A Stream Action carries out the following steps, in the following sequence. All of the steps are optional and are only carried out if configured in the action.
...
Insert excerpt | ||||||||
---|---|---|---|---|---|---|---|---|
|
...
...
...
...
...
...
...
...
...
...
This expression can refer to:
- any values entered on the Form View using the notation:
Code Block |
---|
_prompt.<Form Field Name> |
- the values of any Context Parameters using the notation:
Code Block |
---|
_context.<ContextParameter Name> |
- any attributes of any records selected on the view or dashboard from which the action was initiated using the notation:
Code Block |
---|
<View name or alias>.<Attribute name or alias> |
...
This validate action expression can reference any values entered on the Form, the values of any Context Parameters, using the notation
Code Block |
---|
_context.<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 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.
...
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.
...
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.
The following are the top-level configuration parameters for Stream Actions:
The following fields are configured for actions:
...
An expression for the context parameter. The Context Parameter expressions can refer to any values entered on the Form View using the notation
Code Block |
---|
_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
Code Block |
---|
<View name or alias>.<Attribute name or alias> |
It is not possible to refer to one context parameter from another.
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 context values are referenced using the syntax
Code Block |
---|
_context.<context parameter name> |
Example
- For example, you have a view called 'customers' which shows a list of customers including the account id, name and other account details.
- You want to create an action button to open up another dashboard, containing a view called 'invoices', which will show the invoices for the customer selected on the 'customers' view.
- To do this:
- Add an action button to the 'customers' view, and configure it to open the dashboard containing the 'invoices' view
- Add a context parameter called 'account' to the action, with the context parameter expression set to
customers.account_id
- On the background filter of the 'invoices' view, set the filter to only select those invoices whose account_id is equal to
_context.account
Unlike stream action attribute expressions, context parameter expressions can evaluate to a list of values as well as single values.
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.
...
If this flag is ticked, a message will pop up asking the user if they want to proceed with the action. By default (i.e. if you do not enter a value in the field Confirmation Message), the message will have the format:
HELPDEVTODO - what is default message format?
...
If this flag is ticked, users will be prompted to browse to a file and select it for upload when they run this action.
...
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:
- any values entered on the Form View using:
Code Block |
---|
_prompt.<Form Field Name> |
- the values of any Context Parameters using:
Code Block |
---|
_context.<ContextParameter Name> |
Code Block |
---|
<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 _files
variable.
...
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.
The validation expression can include multiple statements by wrapping them in a do() clause. A number of internal variables are available in these expressions:
- _this: A reference to all the selected records within the view to perform the action on.
- _prompt: A reference to all the user prompted action attributes.
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.
...
if(sum(_this.amount) == 0, info('OK'), error('Not performing Action as the Sum does not equate to zero'))
...
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'))
...
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:
- _error: Details of the error messages generated.
- _errors: The number of error messages generated.
- _warning: Details of the warning messages generated.
- _warnings: The number of warning messages generated.
- _messages: The number of warning messages generated.
- _taskPlan: The name of the Task Plan that the Action ran (may be null)
- _runId: The runId of any Stream data generated by this Action (may be null).
- _action: The name of the Action.
- _file: Details of files processed (imported or exported) by the Action.
- _fileCount: The number of files processed by the Action.
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:
...
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
...