Widget features

Dynamic evaluation

Web evaluation involves using user input alongside integrator logic. It serves various purposes across multiple components :

• Menus and toolbars

• Schematics

• On-clicks handler on widgets

To evaluate expressions, the web performs theses steps:

1. Find all dynamic expression placeholder (between ${ and }).

2. Replace all ${<dynamic content replacement>} available during evaluation. Missing items are replaced by empty strings. JSON structure can be access through . separator (ie. ${user.username}).

3. Evaluate and retrieve its content for further usage. Should an error occurs, resulting evaluation returns an undefined result.

Evaluation language is JavaScript and supports syntactic sugar such as object?.hypotheticalAccessor.

Menus and toolbars

Menus and toolbars allow integrators to define user interactions. These interactions are various and include, for example:

• Acknowledging an alarm

• Tagging an alarm

• Download PDF linked to a collection

• Updating table filter with selected value

• Open new browser tab with dynamic URL based on mouse click

• and many more

Menus are related to user clicks/long presses while toolbars can be displayed for more complexes widgets. For the rest of this chapter, for simplicity sake, menu refers to both menu and toolbar.

In this section we explain how to structure your menu for widgets and describe user interactions.

For an integrator it is possible to add new features for users simply by adding menu based on requirements.

Structure

Menus and toolbars share the same structure. They can both react conditionally to dynamic evaluation. Both can be setup to be used for multiple widgets (should they offer the feature) and can also be dedicated to only one type of widget.

A menu item consists of:

• A label explaining the interaction for users (label)

• An optional icon showing the interaction (icon)

• List of submenus items (hierarchical structure of menu or toolbar items) (subMenu)

• List of contexts associated with the item (context)

  • Which widget(s) can be associated with the interaction (type)

  • Condition for the menu / toolbar availability given context (condition)

  • What to to when the user interact with the menu / toolbar item (action)

  • For which scope (menu or toolbar) the context is applied (scope)

  • What information the menu receives upon interaction (input)

  • What the menu does after the action has been executed (output)

For more information about structure refer to menu.web schema definition.

Context

Contexts allow definition off what is available during menu evaluation. Whether it is to look for a field in an alarm, to retrieve the value clicked by user or to guide current user in adding a journal entry, contexts enriches menus features.

Contexts can be access in condition, input and output section. They are access through evaluation. Refer to evaluation explanation for more information on how to access context sections.

Depending on widget type, different contexts are available. See widgets definition for specific contexts.

Shared context content is:

• user an object containing Keycloak user information

  {
    "username": "<username>",
    "email": "<user email>",
    "firstName": "<first name>",
    "lastName": "<last name>",
    "attributes": {
      "<keys>": ["values"]
    }
  }
  

• severities containing an array of severity

• defaultSeverity linked to the stack default severity.

Conditions

Conditions state wether a menu is displayed or not. condition can be omitted for menu which need to always be displayed. Condition are evaluated upon:

• User click on an widgets supporting interaction

• Data change

Conditions evaluation must result in a true or false statement. Should an error occur during evaluation, it is handled as false.

Conditions can use context content to evaluate its state. For example, should a menu be displayed when user has clicked on an table row, condition could be: !!${alarms.clicked}. Refer to evaluation explanation for more information on how to access dynamic parts.

Warning

Should you want to use an action for a table with clicked and selected behavior, you should detect both case with ${rows.selected}.length === 0 which is for clicked event and ${rows.selected}.length > 0 for the selected condition. Multiple condition can be evaluated as truthy, be careful with condition evaluation.

Action

When a condition is evaluated as truthy, should the user click on a given cell, it will trigger the related action.

An action is a configuration Item linked to a module. Refer to action.ospp definition to know which actions can be triggered.

Input

Inputs are a way to provide data to actions and or operations (in output) that might be required. They are used by building JSON content by creating keys with fixed or dynamic data.

Static content supports strings, boolean and number but not objects.

Building dynamic data is done through pipeline evaluation with the following steps:

1. Extraction with extract keyword. This allows context value extraction using JSONPath query. Resulting extraction will always be an array of elements. Context parts can be extracted and sent with the extract keyword.

2. Evaluation with expression keyword. This allows JavaScript code evaluation. Returns the evaluation result.

3. Transformation with as keyword into the desired type.

Accepted types (used with as keyword) are :

• timestamp: transform input into a date value as a nanoseconds timestamp. Input for this transformation must be a valid string or number that can satisfy JavaScript Date constructor.

• object: transform input into a JavaScript object. Input must be an instance of Object.

• boolean: transform input into a boolean value. If input is an boolean value, simply returns the value of the input. Otherwise, it returns true if the input is truthy (i.e., it has a “truthy” value such as a non-empty string, a non-zero number, an object, etc.) and false if the input is falsy (i.e., it has a “falsy” value such as false, 0, null, undefined, an empty string, etc.).

• string: transform input into a string value.

In the following example, the dynamic-evaluation field is filled with extracting content from context.field.dynamic. Since extraction result is an array, we transform it with as transformer. The static field will be filled with this is static content.

{
  "input": {
    "dynamic-evaluation": {
      "extraction": "context.field.dynamic",
      "as": "string"
    },
    "static": "this is static content"
  }
}

User prompt to input data

Input can also take the form of user prompts letting them set the content of the input. Prompts have different types that changes the components inside. This components should be selected in relation with the type of the input you want to set.

• SEVERITY: prompt that shows a select component letting you choose between the severities defined in your system (i.e., to change an alarm severity).

• INPUT: prompt with a component to set a string value.

• COMBO: prompt with a component letting you choose from a list of values. Theses values must be given as a prompt parameter named items. Items supports both array of strings or result from an extraction (for example alarms.all[*].tags[*] will retrieve all tags from all alarms in an alarm table widget).

• DATE, DATETIME, and TIME: prompt with a date/time selector to pick a date. The value is then transformed into a millisecond representation of the date/time.

• FORM: prompt with a form. Load a form defined in the configuration to retrieve an object when the user submit the form.

You can define the labels displayed on the prompt by setting the parameter labels:

• title: title displayed on top of the prompt.

• message: message displayed on top of the components, at the center of the prompt.

• save: text for the save option.

• cancel: text for the cancel option.

• placeholder: placeholder text shown in the prompt components

Form prompts

Form input prompts take different options. Some of them are always mandatory in order to load the desired form, while other are mandatory when we want to interact with values or collections.

The following options define the form behavior:

• formId: id of the desired form.web

• formSave: If set to true, when the user submit the form, the data are saved according to the form submit parameters. If the form submit destination is Value or Mixed, values bounded to the form are updated with the form new data. Otherwise, when using Request as a destination, an entry is created/update inside the collection associated to the form (defined by the schema of the form). The id of the new entry is added to the data as collectionId.

• collectionId: if given, the collection entry associated with this id will be retrieved and the form will be loaded with the result. Submitting the form while formSave and collectionId are enabled and provided will update the collection. This can be evaluated from the context (i.e. from an alarm data in an Alarm table).

• initialData: provide a initialData object to set the initial values of the form properties. This can be evaluated from the context.

Look at a full example of this here.

Output

Outputs provide a way to call actions or operations after the rest of the actions are finished. Outputs require an input as well to define the action/operation data. The work as describe in the Input section.

In addition to context available, outputs have access to result and input objects which contains result from input execution as well as all input content provided. The result object contains:

{
    "success": "<true|false>",
    "message": "string"
}

Warning

When multiple outputs are defined for the same menu item, the outputs are executed in parallel, which means that there is no guarantee on the order of the outputs. You can change the order of execution to make them be executed one after the oder by setting outputExecution as Sequential.

Different operations types can be used to different outcomes:

• url: open a new browser tab with an url that must be specified:

  • address: field to point browser tab to

• navigate: navigate to an url that must be specified as an input:

  • to: field to navigate to

• evaluate: JavaScript evaluation of code passed as an input (i.e., set an alarm table widget context, like adding a filter)

• modal: open a modal to display a message that must be specified as an input:

  • component: which component to display as modal. Supported: WebView or TitleText, defaults to TitleText

  • title: field to set dialog title

  • message: field to set dialog message

  • close: field to customize close label

  • disableCopy: field to disable the modal to show icon to copy content

  • width: field to set modal size (xs, sm, md, lg, xl), defaults to lg

  • height: field to set modal height (CSS format), defaults to 100%

  • src: field to set WebView source to display

• snackbar: display as a snackbar notification a message that must be specified as an input:

  • message: field to set snackbar message

  • variant: field to set snackbar color type (success, default, error, warning, info)

• download: download a file by giving the file content in base 64 as an input:

  • content: field to set base 64 content to download

  • format: field to set format (pdf, csv), defaults to text/plain when none is given

  • filename: field to set filename when downloading

• open: open a file in a new browser tab by giving the file content in base64 as an input:

  • content: field to set base 64 content to open

• preview: open a modal with PDF content in base64 as an input:

  • content: field to set base 64 PDF preview

  • format: field to set format (pdf, csv), defaults to text/plain when none is given

  • filename: field to set filename when downloading preview

  • width: field to set modal size (xs, sm, md, lg, xl), defaults to lg

• form: open a modal with a form and his content as an input:

  • formId: Id of the desired form.web.

  • collectionId: Array of collections entries id. For each id, the form is loaded with the corresponding entry. If more than one id is given, then we have the ability to navigate between the different entries.

  • data: content of the form. Will be overridden if at least one collectionId is passed as well.