Table-Action

This page is for application designers who need to configure functionality. It explains the properties you can set for table-actions.

Overview

For applications created in version 9.0 or later, use actionflows instead of table-actions; see Creating Actionflows

In PhixFlow version 8.3 or earlier use:

Table-actions are usually associated with a table. In the repository, they are listed under the table name → Table Action section.

Table-actions can also provide functionality that is not related to data, such as opening a screen. Table-actions that are not bound to a table are listed in the repository under Table Action.

Property Pane Toolbar

For information about the toolbar options, see the Common Properties page, Toolbars and Controls section.

 Properties Tab

Parent Details

If this item is within or belongs to another, it's parent name is shown here. See the Common Properties page, Parent Details section for more details.

Basic Settings

FieldDescription
NameEnter the name of the table-actions.
Display Name

A view can have a default table-action configured. PhixFlow runs the action when the user double-clicks on a record in the view.

Enter the name for the default table-actions. PhixFlow displays this name on a view.

Progress Indicator Settings

FieldDescription
Show progress indicator after (ms)Enter the number of milliseconds which need to pass after the table-actions is submitted before PhixFlow displays a progress indicator.
In Progress MessageEnter 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 MessageEnter a message to display in a popup window. Use the toolbar to format the message text. You can provide additional information to the user to explain what the table-actions is doing.

Context Parameters

Use context parameters to specify conditions that apply to the action/table-action.

FieldDescription
Include Previous Context Parameters

 Untick ignore any context parameter that were sent to the screen when it was opened.

 Tick to include the context parameters that were sent to the screen when it was opened. If the action/table-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 screen that initiated the action/table-action.

 Tick to send context parameter values to the screen that initiated the action/table-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/table-action runs. 

To edit the properties of a context parameter, double-click its name. To add a record-action to the list, click   Create New. PhixFlow opens the Context Parameter properties tab.

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

Confirmation Message

FieldDescription
Ask for Confirmation

 Untick to run an action/table-action without requesting user confirmation.

 Tick when a user triggers an action/table-action, PhixFlow displays a popup 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 MessageOptionally, 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

FieldDescription
File Upload

Use this property for an action/table-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 table-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 screen from which the table-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

FieldDescription
Validation Expression

Enter a validation expression. This expression is evaluated at the start of any Insert or Update table-actions or record-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 table-action.
  • _prompt: a reference to all the user prompted table-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/table-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/table-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 views by using their screen zone names. E.g. if the screen also contains a screen zone name ACCTS that is bound to a view, 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'))

Record-Action Rules

This property has a toolbar with standard buttons. The grid contains a list of rules that determine whether or not a record-action runs. 

To edit the properties of a context parameter, double-click its name. To add a record-action to the list, click   Create New. PhixFlow opens the Context Parameter properties tab.

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

A record-action is the CRUD action that can operate on a data record. The rules listed here determine whether or not a record-action runs.

When the record-action runs, PhixFlow uses this list of rules to determine which of the listed record-actions; see Record-Action and Record-Action Rule.

Double-click a rule to open its properties and specify rule details and attributes. This grid displays:

  • Order: The order in which the rules are evaluated.
  • Table: The backing table.
  • Name: The rule name.
  • Expression: If this expression evaluates to true, this record-action will be run. A blank (null) expression counts as true.

When the record-action runs, PhixFlow evaluates the record-action rules in order. For each record-action rule that evaluates to true, PhixFlow will run that record-action. 

The action type of the first record-action rule is overwritten if the button that initiates the action has both an Action Type and an Action; see Component.

Run Task Plan 

FieldDescription
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:

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

To remove a task plan, use the toolbar button  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

FieldDescription
Close Parent ScreenIf you tick this flag, the initiating screen will be closed once the action/table-action has completed.
Open Post Screen

If you tick this flag, a separate screen will be opened once the action/table-action has completed. The screen to open is determines by the screen rules. These are only available if you have ticked this flag.

Any filter of any view on the post screen can reference any context parameters set on this action/table-action. If the specified screen is already open it will be brought to the front and refreshed, rather than a second instance of the screen opening.

URL ExpressionA URL which will be opened when the action/table-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 screen from which the action/table-action was initiated.
Screen Rules available if Open Post Screen

This field is only available if the Open Post Screen is ticked.

A list of screen that can be opened after this action/table-action, for each one a rule to determine whether this is the screen that will be opened.

The first screen whose expression evaluates to true will be opened. Only this screen will be opened. If none of the expressions evaluates to true, no screen will be opened.

For each screen rule define the following fields:

  • Order: The order in which the rules are evaluated.
  • Screen: The screen that will be opened if the accompanying expression evaluates to true.
  • Expression: If this expression evaluates to true, this screen will be opened once the action/table-action has completed. A blank (null) expression counts as true.

Result

FieldDescription
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/table-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/table-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/table-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/table-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/table-action ran (may be null)
  • _runId: The runId of any table data generated by this action/table-action (may be null).
  • _action: The name of the action/table-action.
  • _file: Details of files processed (imported or exported) by the action/table-action.
  • _fileCount: The number of files processed by the action/table-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")}

Advanced

FieldDescription
Prevent Parallel Processing

 Untick so that a user can run this action/table-action multiple times, even if the previous run has not completed.

 Tick so that a single user cannot run this action/table-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/table-action has finished.

Wait for Selection

 Untick so that the action/table-action can run immediately. Only untick this check box if your action does not depend on any data or context parameters from the screen.

 Tick so that PhixFlow runs the action/table-action after completing any outstanding screen refresh. This check box is ticked by default to make sure that the action/table-action uses the data or context parameters related to the data record selected by the application user.

Target viewEnter the name of the view to which this action/table-action will apply.
Form View

You can specify a form view to appear when the user starts the action/table-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 Table to open the repository showing all the tables. From the repository, drag a form view from the table into this field.

Values entered in the form view are referenced in expressions in the table-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 table-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 table-action, when the form pops up all fields will be blank.

Additional Properties for Update or Delete Table-Actions

FieldDescription

Maximum Items Expr.

This field appears if the update table-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 table-action, any attributes of any records selected on the view or screen from which the table-action was initiated and any of the context parameters configured for this table-action.

If the number of items selected on the view from which this table-action is initiated, or retrieved by the filter configured on this table-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 table-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 table-action, any attributes of any records selected on the view or screen from which the table-action was initiated and any of the Context Parameters configured for this table-action.

If the number of items selected on the view from which this table-action is initiated, or retrieved by the filter configured on this table-action, is less than this number then an error message will be generated and no updates or deletes will take place.

Description

We recommend that you always enter a description to explain the purpose of this item.

 Security Tab

Access Permissions

See the Common Properties page, Access Permissions section.

 Audit Tab

Audit Summary

See the Common Properties page, Audit Summary section.

Using Variables in Expressions

In table-actions, the _form, _grid and _gridRow act on a specific record. The record depends on the structure of layout components on the screen.

Table-Action expression variableWhere
View directly on a screenForm on a screenView on a formForm on a cardGrid on a card
_form   acts on the record


currently selected in the view


currently displayed on the form

currently displayed on the formcurrently displayed on the card

backing the card
_grid  acts on the recordcurrently selected in the viewcurrently selected in the view
_gridRow  acts on the recordcurrent record


Sections on this page

Learn More

For links to all pages in this topic, see Using Table-Actions.


Terminology changes in progress

As part of the redesign of PhixFlow, we are changing the following terms:

dashboard → screen   
stream → table
stream attributes → attributes
stream item → record
stream set → recordset
stream view → view
stream item action → record-action 
stream action → table-action
driver class → database driver