Menus and toolbars

Capabilities

Capability	Support	Comment
Use custom menu inside a table
Use dynamic evaluation		The dynamic evaluation can be used to express complex configuration.
Re-use elements multiples times
Use icon from material UI		See Material UI Icons (version 6) for the complete list of available icons and ensure to use snake_case naming.
Display/hide menu		A menu can be hidden or displayed based on conditions
Execute any action on click		An action can be triggered on click menu action
Execute post-event actions		An action can be triggered after the initial one; see Post-Event Action. The system supports either a single post-event action or multiple post-event actions executed in parallel (like A then B AND C). However, sequential execution is not supported (like A then B then C).

Concept

Menus and toolbars enable integrators to define various user interactions, including but not limited to:

• Acknowledging an alarm

• Tagging an alarm

• Downloading a PDF linked to a collection

• Updating a table filter with a selected value

• Opening a new browser tab with a dynamic URL based on a mouse click

• And more

The term toolbar refers to a menu within an element (such as a table like collection or alarm table). In contrast, a menu is specifically associated with user clicks.

For simplicity, throughout this chapter, the term menu will be used to refer to both menus and toolbars.

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 do 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 of 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.

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.

Hide/Display menu

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.

Execute action on click

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.

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.

• integer: transform input into an integer value. Return NaN if cannot be parsed.

• decimal: transform input into an floating point number value. Return NaN if cannot be parsed.

• number: transform input into number (float or integer) value. Return NaN if cannot be parsed.

User prompt to input data

Warning

This feature is currently in beta. It may change in a future version without prior notice. See the Beta Features page for the full list of beta features and their planned release. If you’re using this feature, we encourage you to share your feedback to help with the evaluation process.

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

• GROUPS: prompt that shows a select component letting you choose between the alarm groups currently existing in your system (i.e., to add an alarm into a group).

• 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).

• data: provide a data object to set the initial values of the form properties. This can be evaluated from the context. Look here to see some examples on how to properly extract lists and maps of key values: dynamic evaluation.

Look at a full example of this here.

Combo prompts

Combo input prompts allow a choice between a list of options.

The following options define the form behavior:

• items: List of the options as strings.

"prompt": {
    "type": "COMBO",
    "items": [
        "Sanitaire",
        "Ventilation",
        "Chauffage",
        "Électrique"
    ]
}

Upload files prompts

Open a prompt to allow to upload files into a storage point determined by the upload configuration given as an option. Files dropped into this prompt will be stored into the system. As a result, this returns the list of identifiers for every uploaded file.

The following options define the prompt behavior:

• uploadId: Id of the upload configuration which describes how and where the files are uploaded.

• showPreview: Determine if a preview for each file is shown or not upon a successful upload. The preview only works for images, videos and PDF files. If you want to upload any other type of file, you should disable this option (activated by default).

Look at the Use menus to upload file as attachments on alarms example to get a better understanding on how to use these prompt.

Post-Event Action

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

  • code: code to evaluate

• 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.

• attachments: open a modal to display a list of attachment files:

  • uploadId: Id of the upload configuration from which the files were uploaded.

  • attachments: Array of string identifiers representing the ids of the attachments.

  • previewBehavior: display the list with previews of every attachments in the modal (SHOW_ALL) or display only the current entry (SHOW_ONLY_SELECTED).

  • previewShowNavigation: display or not the navigation component that allow to navigate between entries.

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

  • content: value to copy to the clipboard. Either directly a string value or, if anything else is provided, a JSON stringify of the provided value.

• json: open a modal displaying a JSON payload with the same collapsible, theme-aware viewer as the Json widget:

  • content: the JSON value to display (object, array or scalar).

  • title: field to set the modal title.

  • options: viewer display options. See the Json widget display options.

  • style: viewer appearance, as a map of CSS variables with optional light / dark overrides. See the Json widget appearance.

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

  • height: field to set modal height (CSS format).

Output example

Navigate to google.com

"output": [
    {
        "operation": "navigate",
        "input": {
            "to": "https://www.google.com"
        }
    }
]