...
...
...
The Context Parameter and Form Mapping expressions can refer to any values entered on the Form View using the notation
Code Block |
---|
_prompt.<Form Field Name> |
The Context Parameters and Form Mappings 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> |
...
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 fields are configured for actions:
...
Action Properties
Insert excerpt | ||||||
---|---|---|---|---|---|---|
|
Basic Settings
Field | Description |
---|---|
Name | Enter the name of the action. |
Display Name | A stream view can have a default action configured. PhixFlow runs the action when the user double-clicks on a record in the stream view. Enter the name for the default action. PhixFlow displays this action name on a Stream View. |
Progress Indicator Settings
Field | Description |
---|---|
Show progress indicator after (ms) | Enter the number of milliseconds which need to pass after the action is submitted before PhixFlow displays a progress indicator. |
In Progress Message | Enter a message that you want the user to see with the progress indicator. If not specified, PhixFlow displays a default progress message. |
In Progress Popup Message | Enter a message to display in a pop-up window. Use the toolbar to format the message text. You can provide additional information to the user to explain what the action is doing. |
Context Parameters
Use context parameters to specify conditions that apply to the action
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Include Previous Context Parameters |
| ||||||||||||||||
Update Parent Context |
...
|
...
. | |
Context parameters | This property has a toolbar with standard buttons. The grid contains a list of |
...
context parameters |
...
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.
...
An expression for the form mapping. The Form Mapping expressions can refer to any values entered on the Form View using the notation
Code Block |
---|
_prompt.<Form Field Name> |
The Form Mappings 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 form mapping from another.
The values returned by the form mapping expressions are used to set default values onto any forms on any dashboards opened by the action. If the name of form mapping matches the name of a field on form, it will have any value replaced by the form mapping
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 form called "new invoice", which will create a new invoice to send to the customer with a date field which will be automatically filled in.
- To do this:
- Add an action button to the 'customers' view, and configure it to open the dashboard containing the 'new invoice' view
- Add a form mapping called 'date' to the action, with the form mapping expression set to (now())
Clicking this button will now open up the dashboard with the "new invoice" form with the "date" field set to today's date
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:
Info |
---|
Please confirm that you want to apply action "Action Name" |
...
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> |
- any attributes of any records selected on the view or dashboard from which the action was initiated using:
Code Block |
---|
<View name or alias>.<Attribute name or alias> |
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. 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.
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.
Code Block |
---|
if(sum(_this.amount) == 0, info('OK'), error('Not performing Action as the Sum does not equate to zero')) |
Example 2
Validate that the user entered comment is at least 10 characters long, else write a warning to the log.
Code Block |
---|
if(stringLength(_prompt.UserComment) >= 10, info('OK'), warning('Comment should be at least 10 characters')) |
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 ACCTS
, you could use the following in your validation expression:
Code Block |
---|
if(sum(ACCTS.amount) == 0, info('OK'), error('Error as ACCTS Sum does not equate to zero')) |
...
- None
- Insert
- Delete
- Update
Please be aware that deleting records with an 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. If you don't want your users to see these deleted records, simply filter them from any views.
...
- Selected Items - Action will only apply to the records selected on the view from which the action was initiated unless the Target View is specified.
- Edited Items - Action will only apply to the updated records on the view from which the action was initiated unless the Target View is specified.
- View Filter - Action will only apply to the records shown on the view from which the action was initiated unless the Target View is specified.
- Action Filter - Action will only apply to the records retrieved by the filter defined in the action.
...
This is only available if you have selected Filter Type = Action Filter.
Create a filter to specify the records that an Update or Delete will apply to. 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. Configure this filter in the same way that you would a pipe filter.
...
This is only available if you have selected Stream Item Action = Insert or Update.
If this flag is ticked, all Stream Item Attributes which are not present on the Action Attributes list below will take their new values from the current form.
...
The list of attributes that will be populated by the action - whether an update or insert.
This section includes the button - this brings up the list of attributes for the stream that you are building the action on. Drag any attributes you want from this list into the action, or add them by pressing .
For each attribute, configure the following fields:
...
The expression used to generate the new attribute value. This is written as a PhixFlow Expression.
- Dashboard Element Name You can reference selected records from other dashboard views by using their dashboard element names within the expression. E.g.
Code Block |
---|
sum(ACCTS.amount) |
will sum up all values in amount
from the records select in the view with dashboard element name ACCTS
.
- No Prefix If you want to refer to the current values of the record you are about to update, then simply refer to the attribute name with no prefix.
- _prompt You can reference fields from any user input form associated with this action by referencing the form field name prefixed by _prompt.
- _form You can reference the current value displayed in a field on the form by using _form as a prefix.
For example: In the screenshot below, the expressions use _form to reference fields that are displayed on the form (Unit Price, Quantity and VAT Percentage).
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 for the current stream item. However, it will not stop the action from updating/ inserting other stream items.
- _out You can also use the prefix _out to reference the current value of an attribute in the action. Note that in the above example, to use the value for the attribute ChargeAmount in VATAmount the expression uses _out.ChargeAmount.
- _context Reference any context variable defined on this Action or passed through to this Action.
- _gridRow When the Filter Type is Edited Items this object contains a recordset pointing to an individual row that had been modified.
- "pipe" Expressions can refer to lookup pipes on the same stream as the action. Note that at version 7.6.0, lookup pipes used in this way can only be driven by $ variables i.e. if the lookup filter or cache lookup needs to be driven by values from the action, then those values nust be passed in by $ variables. The pipe cannot reference _out variables directly.
...
A list of task plans that can be run for this action, for each one a rule to determine whether the task plan is actually run.
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.
For each task plan rule define the following fields:
...
If this expression evaluates to true, this task plan will be run. A blank (null) expression counts as true.
...
Action Completion
...
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.
...
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:
...
The Result Message is displayed when the Action has completed, and can 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.
For example:
Code Block |
---|
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.
...
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
...
If you tick this box, a single user will not be able to run this action more than once at the same time. I.e. if a user has started this action, they will not be able to start it again until the first action has finished.
...
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
Code Block |
---|
_prompt.<form field name> |
For example, if there is a field on the form with the label Name
, then the value entered in that field by the user can be referenced in subsequent expressions as
Code Block |
---|
_prompt.Name |
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.
...
that affect whether or not the action runs. To edit the properties of a context parameter, double-click its name. To add a stream item action to the list, click
To remove a context parameter from the action, select it and click
|
Confirmation Message
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Ask for Confirmation |
To provide a customised confirmation message, use the Confirmation Message property. | ||||||||||||||||
Confirmation Message | Optionally, enter your own text to display as the confirmation message. Use the text formatting toolbar to format the message. The maximum length for a message string is determined by System Configuration → System Tuning → Maximum Bigstring Size. |
File Upload
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
File Upload | Use this property for an action that will upload a file.
| ||||||||
Tag Expr. | Enter 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:
You can return a list of the names of uploaded files using the |
Action Validation
Field | Description | ||||||||
---|---|---|---|---|---|---|---|---|---|
Validation Expression | Enter a validation expression. This expression is evaluated at the start of any 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
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.
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
This property has a toolbar with standard buttons. The grid contains a list of rules that determine whether or not a stream item action runs.
To edit the properties of a context parameter, double-click its name. To add a stream item action to the list, click
Insert excerpt | ||||||
---|---|---|---|---|---|---|
|
To remove a context parameter from the action, select it and click
Insert excerpt | ||||||
---|---|---|---|---|---|---|
|
A stream item action is the CRUD action that can operate on a data record. The rules listed here determine whether or not a stream item action runs.
When the action runs, PhixFlow uses this list of rules to determine which of the listed Stream Item Actions will run.
Double-click a rule to open its properties and specify rule details and attributes: see Stream Item Action Rule. This grid displays:
- 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.
When the action runs, PhixFlow evaluates the action rules in order. For each action rule that evaluates to true, PhixFlow will run that action.
Note | ||||||||
---|---|---|---|---|---|---|---|---|
The action type of the first action rule is overwritten if the button that initiates the action has both an Action Type and an Action; see Layout.
|
Run Task Plan
Anchor | ||||
---|---|---|---|---|
|
Field | Description | ||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Run Selected Task Plan |
| ||||||||||||||||||||||||
Task Plan Rules | This section has a toolbar with standard buttons 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 Plans for 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. |
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 |
| ||||||||||||||||
Result includes Errors |
| ||||||||||||||||
Result Message Timeout (s) | Optionally, specify the number of seconds that the result message is displayed to the user. | ||||||||||||||||
| 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:
You can also use context parameters and values to report different messages. For example if you have a context parameter (called
|
Access Permissions
For details about how to control access to an action, see Common Properties → Access Permissions.
Advanced
Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Prevent Parallel Processing |
| ||||||||||||||||
Wait for Selection |
| ||||||||||||||||
Target view | Enter the name of the stream view to which this action will apply. | ||||||||||||||||
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 either from the drop-down list of all forms views in PhixFlow or click
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 |
...
Form Icons
The form provides the standard form icons. Additional buttons are described above, for the sections or fields that they appear against.
See Also
...
less than this number then an error message will be generated and no updates or deletes will take place. |
...
Minimum Items Expr.
Using Variables in Expressions
In actions, the _form, _grid and _gridRow act on a specific record. The record depends on the structure of layout components on the dashboard.
Action expression variable | Where | ||||
---|---|---|---|---|---|
Stream view directly on a dashboard | form on a dashboard | stream view on a form | form on a card | grid on a card | |
_form acts on the record | currently selected in the view | currently displayed on the form | currently displayed on the form | currently displayed on the card | backing the card |
_grid acts on the record | currently selected in the view | currently selected in the view | |||
_gridRow acts on the record | current record |