This page is for application designers. It explains the properties you can set for actions.

Overview

Action Concepts

A stream has a set of Stream Item Actions. These specify an operation that can happen to a record in the stream. Stream item actions can create, read, update or delete a record, so are called CRUD actions.

You can configure an Action to perform several operations on the data in different streams. This is because the action contains a list of stream item actions that can come from different streams.

The action can potentially run any of the actions in its list. To decide which stream item action to run, the action has a rule associated with each stream item action. When a Stream Item Action Rule evaluates to true, the action runs the action and therefore makes a change to the data in the stream.

Creating Actions

You can create an action that is not associated with any stream. This is useful for actions that do not operate on stream data. For example you may want a button-click to open a different dashboard.

Expand the repository branch for your application
Right-click on Actions and select Add.

Actions created this way appear in the repository under Actions. You can also export this type of action.

You can also create an action that belongs to a stream. This option is available for backwards compatibility with applications designed with earlier versions of PhixFlow, that did not have stream item actions.

Expand the repository branch for your application.
Expand the stream on which the action will operate.
Right-click on Actions and select Add to open a new action properties tab.

You can create actions on layout components, such as buttons. You can also create actions in grid cells that contain:

strings
numbers
dates or date-times
boolean true/false.

You can drag an action onto a stream view 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.

See also Configuring Actions for related pages.

Sections on this page

Action Properties

For information about the properties toolbar, and about the sections Parent Details, Analysis Models, Description and Audit Summary, see Common Properties. For a full list of all the PhixFlow property tabs and windows, see Property Tabs.

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	Untick ignore any context parameter that were sent to the dashboard when it was opened. Tick to include the context parameters that were sent to the dashboard when it was opened. If the action specifies a new context parameter of the same name, the new context parameter will supersede the previous one.
Update Parent Context	Untick to not send any context parameter values to the dashboard that initiated the action. Tick to send context parameter values to the dashboard that initiated the action.
Context parameters	This property has a toolbar with standard buttons. The grid contains a list of context parameters 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 Add. PhixFlow opens the Context Parameter properties tab. To remove a context parameter from the action, select it and click Permanently Delete in the toolbar.

Confirmation Message

Field	Description
Ask for Confirmation	Untick to run an action without requesting user confirmation. Tick when a user triggers an action, PhixFlow displays a pop-up message asking them to confirm. By default, the message is: `Please confirm that you want to apply action Action Name` 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.

Tick to prompt the user to browse to and select the file they want to upload.

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:

any values entered on the Form View using: _prompt.<Form Field Name>

the values of any Context Parameters using: _context.<ContextParameter Name>

any attributes of any records selected on the view or dashboard from which the action was initiated using: <View name or alias>.<Attribute name or alias>

You can return a list of the names of uploaded files using the _files variable.

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 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. When the action generates an error message it stops running, so does not complete.

Example 1

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'))

Example 2

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'))

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:

if(sum(ACCTS.amount) == 0, info('OK'), error('Error as ACCTS Sum does not equate to zero'))

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 Add. PhixFlow opens the Context Parameter properties tab.

To remove a context parameter from the action, select it and click Permanently Delete in the toolbar.

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.

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.

We recommend that you use either an Action Type or an Action, not both. If you specify both, the Action Type overwrites the type of the first stream item action rule that is configured in the action properties. The rest of the stream item action rule configuration remains the same.

For example:

A button Action Type is Update.
Its Action has 3 stream item action rules, to:
1. insert
2. insert
3. update.

When the user clicks the button, PhixFlow runs the stream item action rules in turn, but runs the actions

update
insert
update

Only the first insert stream item action rule type is replaced by the update type specified in the Action Type.

Run Task Plan

Field

Description

Run Selected Task Plan

Tick 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 standard buttons and Show Task Plans

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:

Click Show Task Plans to list all the task plans in the repository.
Drag task plans into this list.

To remove a task plan, use the toolbar button Permanently Delete.

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:

Order: The order in which the rules are evaluated.
Task Plan: The task plan that will be run if the accompanying expression evaluates to true.
Expression: If this expression evaluates to true, this task plan will be run. A blank (null) expression counts as true.

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: Order: The order in which the rules are evaluated. Dashboard: The dashboard that will be opened if the accompanying expression evaluates to true. Expression: If this expression evaluates to true, this dashboard will be opened once the action has completed. A blank (null) expression counts as true.

Result

Field	Description
Result includes Warnings	Untick to report the result in a message without any information about warnings. You can view the warnings in the console. Tick to include warning messages generated by the action to be listed in the result message.
Result includes Errors	Untick to report the result in a message without including any information about errors. You can view error messages in the console. Tick to include error messages generated by the action to be listed in the result message.
Result Message Timeout (s)	Optionally, specify the number of seconds that the result message is displayed to the user.
Result Message	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 `{ }` . PhixFlow evaluates each expression in turn before displaying the message. For result messages that report on the status of the action, you can use the following internal variables in the 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. Example message showing the number of errors and warnings Action {_action} failed with {_errors} errors and {_warnings} warnings. You can also use context parameters and values to report different messages. For example if you have a context parameter (called `balance`) that calculates the outstanding balance, you can use an expression that reports different messages depending on the calculated value. Example of different messages around a threshold value {if(_context.balance < 0,"Money still owed", "Balance paid")}

Access Permissions

For details about how to control access to an action, see Common Properties → Access Permissions.

Advanced

Field	Description
Prevent Parallel Processing	Untick so that a user can run this action multiple times, even if the previous run has not completed. Tick so that a single user cannot run this action more than once at the same time. For example, if a user has started this action, they will not be able to start it again until the first action has finished.
Wait for Selection	Untick so that the action can run immediately. Only untick this check box if your action does not depend on any data or context parameters from the dashboard. Tick so that PhixFlow runs the action after completing any outstanding dashboard refresh. This check box is ticked by default to make sure that the action uses the data or context parameters related to the data record selected by the application user.
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 Show Streams to open the repository showing all the streams. From the repository, drag a form view from the stream into this field. Values entered in the form view are referenced in expressions in the action with the form. _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 _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.

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.

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
Action expression variable	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 displayed on the form	currently selected in the view	currently displayed on the card	currently selected in the view
`_gridRow` acts on the record	current record