Interactions

Interactions provide a straightforward way to interact with UI fields and control their behavior within views through scripts. They enable dynamic user interface responses based on user interactions and field changes.

Overview #

An interaction belongs to a specific view and allows you to define scripts that modifies the UI fields. Multiple interactions can be configured for a single view, enabling complex dynamic behaviors.

Interaction settings #

Label #

This is the human-readable name of the interaction, which will be displayed in the UI.

Name #

The name serves as the internal identifier for the interaction. The name must consist only of letters and numbers, without special characters or spaces.

Visible #

This option controls the visibility of the interaction. If set to Never, even if the interaction is present in the view, it will remain hidden. This feature spares you the need to manually remove the interaction from each view.

Keep in mind that this is solely a UI setting.

The Visible options are:

• Always: The interaction is always visible (default option).

• Expression: The interaction becomes visible if the specified expression evaluates to true. Refer to the documentation for Expressions for more information.

• Script: The action’s visibility depends on the return value of a script. If the script returns true, the interaction is visible; otherwise, it’s hidden. Here’s the script context:

  ---

  Parameters #

  Name	Type	Description
  record	sys.data.Record	The record where the interaction will be executed.
  interaction	sys.data.Interaction	The interaction object itself.

  Returns #

  boolean - true if conditions are met, false otherwise.

  Samples #

  // make the interaction visible if the type is 'a'
  return record.field('type').val() == 'a';
  

  
  

  ---

• Never: the interaction will be hidden.

Ask for confirmation #

This boolean flag allows to prompt user before executing the interaction.

Style #

This pertains to the visual style of the interaction when presented as a button in the UI.

Icon #

This specifies the icon to represent the interaction when displayed in the UI.

Modal size #

Since interactions always opens in a modal, this switcher allows to choose the size of the modal to be rendered.

The options are:

• Automatic (default option).
• Small
• Medium
• Large
• Extra large

Interaction script #

The script runs when the interaction is executed in the UI (when the interaction’s execution is confirmed), and it is the place where the interaction’s intended operations should be carried out.

Parameters #

Samples #

// updates some values in the record
var newValue = interaction.field('param1') * 10;
record.field('field').val(newValue);

Custom validations #

Custom validations for interactions enable more intricate validations that span across all fields within the interaction. These validations can utilize external services or functionalities that aren’t accessible through field rules.

For instance, consider an external endpoint for address validation that you can integrate to validate addresses. Alternatively, you might want to enforce a requirement that when a specific option is chosen in one field of the record or the interaction, another field’s value must adhere to a specific pattern.

Here is the script context for these custom validations:

Parameters #

Returns #

object - You should return an array of errors, something like this:

[
  {
    path: 'addressLine', 
    code: 'invalid', 
    message: 'Not a valid address when running this interaction'
  },
  {
    path: 'zipCode', 
    code: 'invalid', 
    message: 'Wrong zip code'
  }
]

Where path is the path to the field experiencing issues. For nested fields, the full path should be provided, such as address.zipCode. For multi-valued fields, the index should be indicated, like addresses[1].zipCode.

The code is an error code that you can define according to your needs.

Finally, the message is what will be displayed in the UI and will also be included in the response along with the code.

Samples #

// validates the zip code using an external service
var errors = [];
var zipCode = interaction.field('address.zipCode').val();
if (!app.endpoints.addressValidator.isValidZipCode(zipCode)) {
  errors.push({
    path: 'address.zipCode',
    code: 'invalid',
    message: 'Wrong zip code'
  });
}
return errors;

Parameters #

Parameters are fields that will be prompted for when the interaction is executed. For instance, when executing the interaction from the UI, a popup will appear asking the user to input values for the parameters configured in the interaction.

For more information on configuring parameters, please refer to the Fields documentation.

Permissions #

Permissions dictate which groups are granted the authority to execute the interaction.

Upon adding a new interaction to a view, if a group has permissions for all the interactions in that view, the interaction is automatically granted the Allowed permission.

Permissions for parameters can be configured within each parameter or at the group level.

Upon adding a new parameter to an interaction, if a group has permissions for the interaction, read-write permission is automatically assigned to that parameter within the group.

For more details on permissions, please consult the Groups documentation.

Events #

Before show #

The before show script is evaluated prior to interaction execution. In the UI, it is triggered before presenting the user with the interaction popup. This enables adjustments to parameters based on specific conditions.

Parameters #

Samples #

// sets the default value as the email of the current user
interaction.field('sendTo').val(sys.context.getCurrentUser().email());

On interaction change #

The On Interaction Change script is executed whenever a view parameter changes its value. This enables making adjustments to the parameters based on specific conditions.

You can identify the parameter that triggered the event by utilizing the modifiedParameter parameter within the script.

Parameters #

Samples #

// sets the value as the email of the current user only if the field 'sendTo' has changed and is empty
if (modifiedParameter == 'sendTo' && interaction.field('sendTo').isEmpty()) {
  interaction.field('sendTo').val(sys.context.getCurrentUser().email());
}

After interaction executed #

The After Interaction Executed script is executed immediately after the user confirms the execution of the interaction.

Parameters #

Samples #

// after interaction is executed log something
sys.logs.info("Interaction: [" + interaction.name() + "] executed")