Forms: Stream Action
A Stream Action carries out the following actions in the following sequence. All of the steps are optional and are only carried out if configured on the appropriate tab.
- Open a Form View to allow the user to provide some parameters for this action.
- Open a File Explorer window to allow the user to navigate to a directory and select one or more files.
- Evaluate a set of Context Parameter expressions configured on the Context Parameters tab. The Context Parameter expressions can refer to any values entered on the Form View using the notation _prompt.<Form Field Name>. The Context Parameters can also refer to any attributes of any records selected on the view or dashboard from which the action was initiated using the notation <View name or alias>.<Attribute name or alias>.
- Evaluate the file upload tag expression. This expression can refer to any values entered on the Form View using the notation _prompt.<Form Field Name>, the values of any Context Parameters using the notation <i>_context</i>.<ContextParameter Name> and any attributes of any records selected on the view or dashboard from which the action was initiated using the notation <View name or alias>.<Attribute name or alias>.
- Upload the selected files and mark them with the evaluated tag value so that they can be retrieved later by suitably configured File Collector.
- Evaluate the validation expression configured on the Validate Action tab. This expression can reference any values entered on the Form, the values of any Context Parameters (using the notation <i>_context</i>.<ContextParameter Name>) and any attributes of any items selected on the view or dashboard from which the action was initiated. If the validation expression generates any error messages (including by using the Error function) then no further action processing will take place.
- Retrieve a set of records from the database for this Stream. The records retrieved will either be based on a filter specified on the Filter tab or, if no filter is specified, the records selected on the view from which the action was initiated. If a filter is specified then any expression on the filter can refer to the Form View fields, Context Parameters or attributes of items selected on the view or dashboard from with the action was initiated. This step will only be carried out if the user has selected either the Update or Delete Action on the Item Updates tab.
- Carry out any stream item updates configured on the Item Updates tab. Update and delete actions will be applied to the records retrieved from the database in the previous step. When carrying out Insert or Update actions each Stream Action Attribute expression will be evaluated in turn to calculate the new value for that attribute. These expressions can refer to the Form View values, the Context Parameters, the values of any attributes of items selected on the view or dashboard from with the action was initiated or, for Updates, the values of attributes from the records retrieved from the database. To refer to values of attributes retrieved from the database simply refer to the attribute name without any prefix. Please note, even where a record retrieved from the database is based on a record selected on a view, the values on the record retrieved from the database may differ from those on the view as the record in the database may have been updated by another user since the view was last refreshed. If any attribute expression fails, or an error message is sent using the Error function, then that record will not be Updated, Deleted or Inserted. However, if multiple records are being updated, a failure of one record will not prevent the others from being updated or deleted.
- Run the configured task plan. Any Context Parameters can be referenced by any expression run during that task plan.
- Open another dashboard. Any filter of any view on that dashboard can reference any Context Parameters set on this action. If the specified dashboard is already open it will be brought to the front and refreshed rather than a second instance of the dashboard opening.
- Close the current dashboard from which the action was initiated.
Once configured, a Stream Action can be dragged and dropped onto Stream Views associated with the Stream on which the Action is configured to create a set of Action Buttons which appear on the top of the Stream View.
The following are the top-level configuration parameters for Stream Actions:
Form: Stream Action Details
The following fields are configured on the Details tab:
...
A Check box to determine whether a Tag Expression field is displayed. The tag expression can refer to any values entered on the Form View using the notation _prompt.<Form Field Name>, the values of any Context Parameters using the notation _context.<ContextParameter Name> and any attributes of any records selected on the view or dashboard from which the action was initiated using the notation <View name or alias>.<Attribute name or alias>.
If a tag expression is provided then when the action is run a file explorer dialog will appear to allow the user to navigate to a directory and select one or more files. These files will be uploaded to the File Upload Directory specified in the System Configuration table and tagged with the evaluated value of this tag expression so that they can be retrieved later by suitably configured File Collector.
List of names of uploaded files can be accessed through <i>_files</i> variable.
...
The following fields are configured on the Context Parameters tab:
...
Step 5. Upload the selected files
Mark them with the evaluated tag value so that they can be retrieved later by a suitably configured File Collector.
Step 6. Evaluate the validation expression
This validate action expression can reference:
- any values entered on the form
- the values of any context parameters
- any attributes of any items selected on the view or dashboard from which the action was initiated.
Do this using the notation:
Code Block |
---|
_context.<ContextParameter Name>
|
The validation expression can also refer to items being dragged or items which are having other items dropped onto them using the notations
Code Block |
---|
_dragSource.<AttributeName>
_dropTarget.<AttributeName> |
respectively.
If the validation expression generates any error messages (including by using the error function) then no further action processing will take place.
Step 7. Retrieve a set of records from the database
Retrieve a set of records for this Stream. The records retrieved will either be based on a filter specified on the Update StreamItems Filter, or, if no filter is specified, the records selected on the view from which the action was initiated.
If a filter is specified then any expression on the filter can refer to the Form View fields, Context Parameters or attributes of items selected on the view or dashboard from with the action was initiated. This step will only be carried out if the user has selected either the Update or Delete Action on the Item Updates tab, and then Filter Type = View Filter or Action Filter.
Step 8. Perform stream item updates
Carry out any stream item updates configured in the Update StreamItems section.
Update and delete actions will be applied to the records retrieved from the database in step 7.
When carrying out Insert or Update actions, each Stream Action Attribute expression will be evaluated in turn to calculate the new value for that attribute. These expressions can refer to the Form View values, the Context Parameters, the values of any attributes of items selected on the view or dashboard from with the action was initiated. Or, for Updates, the values of attributes from the records retrieved from the database.
To refer to values of attributes retrieved from the database simply refer to the attribute name without any prefix. Please note, even where a record retrieved from the database is based on a record selected on a view, the values on the record retrieved from the database may differ from those on the view as the record in the database may have been updated by another user since the view was last refreshed. If any attribute expression fails, or an error message is sent using the error function, then that record will not be updated, deleted or inserted. However, if multiple records are being updated, a failure of one record will not prevent the others from being updated or deleted.
With drag and drop actions, either the items being dropped or the items having other items dropped onto them can be chosen to be updated. In the stream action attribute expressions, you can refer to both _dragSource and _dropTarget.
Step 9. Run task plan
If a task plan has been specified, run this now. Any Context Parameters can be referenced by any expression run during that task plan.
Step 10. Close starting dashboard
If Close Parent Dashboard has been set, close the dashboard from which the action was initiated.
Step 11. Open post-dashboard
If a post dashboard has been specified, open this now. Any filter of any view on that dashboard can reference any Context Parameters set on this action. If the specified dashboard is already open it will be brought to the front and refreshed rather than a second instance of the dashboard opening.
Action Properties
Once configured, a Stream Action can be dragged and dropped onto Stream Views associated with the Stream on which the Action is configured to create a set of Action Buttons which appear on the top of the Stream View. Actions can also be dragged into the menus belonging to an Application.
Insert excerpt _standard_settings _standard_settings nopanel true
The following fields are configured for actions:
Basic Settings
Field | Description |
---|---|
Name | The name of the Stream Action. |
Display Name | The name that will be used to display this action on a Stream View |
Show progress indicator after (ms) | A number of milliseconds which need to pass after the Action is submitted before the progress indicator is shown . |
In Progress Message | The custom message which will be displayed in the progress window. If not specified, the default message is displayed. |
In Progress Popup Message | The additional information about the running Stream Action which will be displayed as a HTML formatted window. |
Context Parameters
Field | Description |
---|---|
Include Previous Context Parameters | If this is ticked, any context parameters sent to the dashboard when it was opened will be included. If the action specifies a new context parameter of the same name, the new context parameter will supersede the previous one. |
Update Parent Context | If this is ticked, any context parameter values will also be sent to the dashboard that initiated the action |
Context parameters | A grid listing the context parameters. Double-click to open the properties for a context parameter |
Confirmation Message
Field | Description |
---|---|
Ask for Confirmation | If this flag is ticked, a message will pop up asking the user if they want to proceed with the action. By default, the message is:
To provide a customised confirmation message, use the next field. |
Confirmation Message | Optionally, enter your own text to display as the confirmation message. Use the toolbar to format the message. |
File Upload
Field | Description | ||||||
---|---|---|---|---|---|---|---|
File Upload | If this flag is ticked, users will be prompted to browse to a file and select it for upload when they run this action. | ||||||
Tag Expr. | An expression that sets the value of the tag for the file. You can use this tag in a file collector to read into PhixFlow files that the action has uploaded. The tag expression can refer to:
List of names of uploaded files can be accessed through |
Action Validation
Field | Description | ||||||
---|---|---|---|---|---|---|---|
Validation Expression | The validation expression is evaluated at the start of any stream item Insert or Update actions. If the validation expression generates any error messages (using the error function) then the action is abandoned. The validation expression is not used to decide whether or not to run the selected Task Plan. The validation expression can include multiple statements by wrapping them in a do() clause. A number of internal variables are available in these expressions:
The usual message functions debug(message), info(message), warning(message), and error(message) are all available to be used in these expressions and will result in messages being written to the system console logs. Be careful when using the error(message) function - this will stop the action from being completed. Example 1 Validate that the sum of the selected record amounts equate to zero before allowing the action to be executed.
Example 2 Validate that the user entered comment is at least 10 characters long, else write a warning to the log.
Using values from other views You can also refer to records selected in other dashboard views by using their dashboard element names. E.g. if the dashboard also contains a view with database element name
|
Stream Item Action Rules
A list of rules related to this action. Double-click a rule to open its properties and specify rule details and attributes: see Stream Item Action Rule. This grid displays the rule's:
- Order: The order in which the rules are evaluated.
- Stream: The backing stream.
- Name: The rule name.
- Expression: If this expression evaluates to true, this action will be run. A blank (null) expression counts as true.
Run Task Plan
Anchor | ||||
---|---|---|---|---|
|
Field | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Run Selected TaskPlan | Tick this flag if you want to run a task plan as part of the action. Any expression evaluated during this task plan can reference any Context Parameter. | ||||||||||||||||||||||||
Task Plan Rules | This section has a toolbar with Common Properties and
The grid contains a list of task plans and their associated expression. The expression is the rule to determine whether the task plan runs. To add a task plan to the list:
To remove a task plan, use the toolbar button
To add an expression, double-click the task plan in the grid to open a task plan rule property tab. The first task plan whose expression evaluates to true will be run. Only this task plan will be run. If none of the expressions evaluates to true, no task plan will be run. Double-click a task plan rule to specify:
See Task Plan Rulefor details. |
Action Completion
Field | Description |
---|---|
Close Parent Dashboard | If you tick this flag, the initiating dashboard will be closed once the action has completed. |
Open Post Dashboard | If you tick this flag, a separate dashboard will be opened once the action has completed. The dashboard to open is determines by the Dashboard Rules. These are only available if you have ticked this flag. Any filter of any view on the post dashboard can reference any Context Parameters set on this action. If the specified dashboard is already open it will be brought to the front and refreshed, rather than a second instance of the dashboard opening. |
URL Expression | A URL which will be opened when the Action has completed. This may be provided as a fixed URL or as an expression evaluating to a plain text string. The expression can reference the Form fields, Context Parameters or attributes of Records selected on the view or dashboard from which the action was initiated |
...
The values returned by the context parameter expressions can be referenced by the Validation expression, the Filter, the Maximum and Minimum Items expressions, any Stream Action Attribute expressions and any dashboard opened by this action.
...
The usual message functions debug(message), info(message), warning(message), and error(message) are all available to be used in these expressions and will result in messages being written to the system console logs.
However special attention should be taken when using the error(message) function as this will also STOP the action from being completed.
...
Field | Description |
---|---|
Validation Expression | The validation expression is evaluated at the start of any stream item Insert or Update actions and if the validation expression generates any error messages (using the error function) then the action is abandoned. The validation expression is not used to decide whether or not to run the selected Task Plan A number of internal variables are available in these expressions:
The usual message functions debug(message), info(message), warning(message), and error(message) are all available to be used in these expressions and will result in messages being written to the system console logs. However special attention should be taken when using the error(message) function as this will also STOP the action from being completed. e.g To validate that the sum of the selected record amounts equate to zero before allowing the action to be executed.if(sum(_this.amount) == 0, info('OK'), error('Not performing Action as the Sum does not equate to zero')) e.g To validate that the user entered comment is at least 10 characters long, else write a warning to the log.if(stringLength(_prompt.UserComment) >= 10, info('OK'), warning('Comment should be at least 10 characters')) Note that you can also reference selected records from other dashboard views by using their view names:- i.e if(sum(ACCTS.amount) == 0, info('OK'), error('Error as ACCTS Sum does not equate to zero')) |
...
Field | Description |
---|---|
Result includes Warnings | If ticked, warning messages generated by the Action in the Console log will be displayed as part of the result message. |
Result includes Errors | If ticked, error messages generated by the Action in the Console log will be displayed as part of the result message. |
Result Message | The Result Message is displayed when the Action has completed and may be used to provide a summary of the Action. The message can contain multiple Expressions inside {} brackets - these Expressions are evaluated in turn before the message is displayed. E.g. Action {_action} failed with {_errors} errors and {_warnings} warnings. A number of internal variables are available in these expressions:
|
The following fields are configured on the Item Updates tab:
...
- None
- Update
- Insert
- Delete
Please be aware that a Deletion action is non-reversible. In some circumstances it may therefore be better to select an Update action to simply mark the records as 'deleted' and then configure an Archive Task to remove records marked as deleted after a certain period of time. This will provide a window of opportunity for these 'deletions' to be reversed manually if they are made by mistake.
...
- Selected Items - Action will only apply to the records selected on the view from which the action was initiated.
- View Filter - Action will only apply to the records shown on the view from which the action was initiated.
- Action Filter - Action will only apply to the records retrieved by the filter defined in the Filter tab.
...
A Grid showing all the associated Stream Action Attributes that form part of this stream action. See the Stream Action Attribute form.
This grid only appears if the Stream Item Action selected is Update or Delete.
The Filter tab allows the user to enter a filter to specify the records against which any Update or Delete actions should be applied. Any expressions on this filter can reference the Form View fields, Context Parameters and any attributes from any record selected on the view or dashboard from which this action was initiated. The tab is visible only if the selected Filter Type (in the Item Updates tab) is the 'Action Filter'.
The following field is configured on the User Groups tab:
Field | Description |
---|---|
User Groups | A list of User Groups permitted to run this Action |
The following field is configured on the Description tab:
Field | Description |
---|---|
Description | Description of the stream action |
Form Icons
The form provides the standard form icons.
Displays the Stream that this action belongs to. |
The form also provides the following icons on the Stream Action Attributes tab:
Deletes the selected object from the list. | |
Adds a new Stream Action Attribute. | |
Shows the list of attributes that can be added as stream action attributes |
See Also
...
. | |
Dashboard Rules available if Open Post Dashboard | This field is only available if the Open Post Dashboard is ticked. A list of dashboards that can be opened after this action, for each one a rule to determine whether this is the dashboard that will be opened. The first dashboard whose expression evaluates to true will be opened. Only this dashboard will be opened. If none of the expressions evaluates to true, no dashboard will be opened. For each dashboard rule define the following fields:
|
Result
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Result includes Warnings | If ticked, warning messages generated by the Action in the Console log will be displayed as part of the result message. | ||||||||||||||||
Result includes Errors | If ticked, error messages generated by the Action in the Console log will be displayed as part of the result message. | ||||||||||||||||
Result Message Timeout (s) | If specified, the result message will disappear after the given number of seconds. | ||||||||||||||||
| Enter the text for a message that PhixFlow will display when the action has completed. Use the toolbar to format the message. You can use the message to notify the user of a summary of the action, or the to provide information about the completed state. You can include expressions within the message by enclosing each expression in curly brackets For result messages that report on the status of the action, you can use the following internal variables in the expressions:
number of You can also use context parameters and values to report different messages. For example if you have a context parameter (called
|
Access Permissions
Field | Description |
---|---|
All Users Can Run Action | If you tick this box, all users can run this Action, provided they have the basic privilege to run stream actions. If you untick this box, then access to the stream action is controlled by associating the action with user groups. |
User Groups | This field only appears if the All Users Can Run Action box is not ticked. This is a list of the User Groups permitted to run this Action. This list provides the button - press this to bring up the list of user groups. Drag user groups into the list as needed. |
Advanced
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Prevent Parallel Processing |
| ||||||||||||||||
Wait for Selection |
| ||||||||||||||||
Form View | You can specify a form view to appear when the user starts the action.They will be able to enter values on this form view, and the values can be used to update selected records for an update action, or populate fields for an insert action. Select a form view from the drop-down list of all forms views in PhixFlow, or by pressing - this brings up the list of streams in PhixFlow; you can select a form view from a stream, and drag it into the form view field. Values entered in the form view are referenced in expressions in the action with the form
For example, if there is a field on the form with the label
If this is an update action, then the form will be pre-populated with the values from the selected record. Where multiple records are selected, then only those values which are common to all the selected records will be displayed. For insert action, when the form pops up all fields will be blank. |
Additional Properties for Update or Delete Actions
Field | Description |
---|---|
Maximum Items Expr. | This field appears if the update action selected is Update or Delete. The expressions entered here must evaluate to a positive whole number. The expression can reference any fields entered on the Form View associated with this action, any attributes of any records selected on the view or dashboard from which the action was initiated and any of the Context Parameters configured for this action. If the number of items selected on the view from which this action is initiated, or retrieved by the filter configured on this action, is greater than this number then an error message will be generated and no updates or deletes will take place. |
Minimum Items Expr. | This field appears if the update action selected is Update or Delete. The expression entered here must evaluate to a positive whole number. The expression can reference any fields entered on the Form View associated with this action, any attributes of any records selected on the view or dashboard from which the action was initiated and any of the Context Parameters configured for this action. If the number of items selected on the view from which this action is initiated, or retrieved by the filter configured on this action, is less than this number then an error message will be generated and no updates or deletes will take place. |