Manual Instance Actions

(new in Atfinity 17)

Definition

A Manual Instance Action is rule logic that a user runs on demand on a single instance. Like a rule it has a condition and one or more actions, but it is never applied on its own and never waits for a scheduled rule to fire. It runs when a user asks for it, on the instance they are looking at.

Manual Instance Actions can e.g. be used to:

• Correct a client's address after a phone call, and keep a record of who changed it
• Set a classification on a client at the moment a user decides it has to change
• Refresh a client's values from an external system, when a user needs them up to date

Manual Instance Actions are configured under Processes, in the Other Rules section. Every action belongs to one ontology and can assign values, create a lifecycle case, send an email, run an integration and call one of your own API requests. An action can combine several of these, and they all run when the user presses the button.

The condition

The condition is written about the instance the action runs on, so it refers to it as self:

self.status = pending

It holds no declarations, because the ontology of the action already says which instances it applies to.

The condition decides on which instances the action is offered. It is evaluated for the instance the user is looking at, and the action is only shown when it is true, so a user is never offered an action that would not apply. Without a condition, the action is offered on every instance of its ontology.

Input parameters

An action can ask the user for values before it runs, for example the new address a client just gave over the phone. Each of these input parameters is asked for as a field of its own. Only the simple information types can be asked for this way: text, whole and decimal numbers, yes or no, a single or multiple choice from a list, a date and a date with a time.

The fields are independent of each other, so none of them can be shown or hidden based on another. An action can ask for up to 32 values, and all of them have to be filled in before it runs.

The entered values are available in the actions under PARAMETERS, by the key of the parameter, so an Assign Values action can write them onto the instance:

self.first_name := PARAMETERS.first_name
self.last_name := PARAMETERS.last_name

The same references can be used in the input assignments of the other actions, for example to put a value the user entered into the subject of an email.

Where users find an action

Configuring an action does not yet show it anywhere. It is offered only on the pages it has been selected on, in one of two ways:

• On an instance page. The actions selected there are offered on the Actions tab of every matching instance, each with its description next to the button.
• On an instance tree page, as a button in an info list. The button runs the action straight away, so use it for actions that ask for no values, as there is no dialog to enter them in.

Users are offered an action only if their roles have access to it, which is configured in the permissions of the action, the same way the permissions of a tab work.

Running an action

An action that asks for no values is a single button. An action with input parameters opens a dialog that asks for them first, and runs once the dialog is confirmed. While it runs, the button shows that it is working, and finishing is confirmed with a message. If the action created a lifecycle case, that message links to it. If something went wrong, an error message is shown instead.

Values written by an action appear in the History tab of the instance with the name of the action as the reason, so it stays visible who ran what and when.

Example

An action on the ontology Person, titled 'Update address', has this condition:

self.address_confirmed = false

It defines the input parameters street, city and postal_code, and one Assign Values action:

self.street := PARAMETERS.street
self.city := PARAMETERS.city
self.postal_code := PARAMETERS.postal_code
self.address_confirmed := true

Selected on the instance page of the Person ontology, the action is offered on the Actions tab of every instance where address_confirmed is false, and no longer offered once the assignment has set it to true.