App development reference

This page lists the specifications for apps and groups beyond what is already required for .lf state machines.

Ports

The top level state machine for all apps must contain the two ports Success and Error. The choice of ports for all nested states is up to the app developer. Exception: In groups, any child states that are marked as container must also use the ports Success and Error.

Client Data

The following fields of client-data are specific to app development. Required fields are bold

• type "app" | "group"

• name String

• color String

• tags String[]

• image String

• requiredParameters Object[] -- An array of objects which contain source parameters defined by

  • source: The name of the parameter in the source

  • localParameter: The name of the parameter as it is used in the state machine

• contextMenu Script -- The definition of steps to configure the app, refer to Context menus for a detailed explanation

• components Script -- Custom components used in the app, refer to Custom components for more information

• hiddenInLibrary Bool

These fields are only used in apps of type group:

• containers String[][] | Object[]

Caution

The following fields are used for experimental features that may not continue to be supported (also only in groups):

• executionDashboard

Experimental Features

The following group features are experimental and not officially supported:

Wrapper Groups

Groups can be specified to programmatically wrap any of their child apps with another group. To do this, specify the containers property in client data as an array of objects with the schema {String[] path; String wrapper;} The value of the field wrapper must be the name of an existing group.

Example app

WrappingGroup {
  port Success true
  port Error false

  clientData {
    type: "group";
    containers: [{path: ["group_body"]; wrapper: "ChildGroup"}];
    name: "Wrapping Group";
    color: "darkgray";
    }@;
  }

  [...]
}

Behavior

• When an app is inserted into a group's container that has a wrapper specified the app automatically appears with the specified wrapper around it. This also applies to the case where the app is nested inside of other groups within the wrapping group.

• This wrapper cannot be manually (re)moved, however clicking on it will open the context menu to configure parameters.

• If the wrapped skill is deleted or moved outside of the wrapping group, the wrapper automatically disappears again.

Execution Dashboard

The execution dashboard is an experimental feature that allows app developers to show live information during task execution in desk. To implement an execution dashboard, add the optional field executionDashboard to your group app's clientData structure. Just like the contextMenu field, the contents must be HTML markup and can embed the resources that are declared in the components field. Analogously to how the contents of the context menu must be wrapped in <step> tags, the contents of the the execution dashboard must be wrapped in a <execution-dashboard> tag.

Example app

DashboardGroup {
  port Success true
  port Error false

  clientData {
    type: "group";
    containers: [["group_body"]];
    name: "Dashboard Group";
    color: "darkgray";
    components: @{
      <component name="test-component">
        <template src="groupy/test.html"></template>
        <script src="groupy/test.js"></script>
      </component>
    }@;
    executionDashboard: @{
      <execution-dashboard id="test-dashboard" name="My Dashboard">
          <test-component></test-component>
      </execution-dashboard>
    }@;
  }

  [...]
}

Behavior

• When a task is executed that contains a group with an execution dashboard specified, an execution dashboard panel will appear in the location otherwise occupied by the library drawer.

• At any given time, only the execution dashboards of direct parents of the currently executing app can be shown in the panel.

• By default the bottom-most group's dashboard will be focused. By clicking on the tab labels, the operator can switch to a different one. This selection will be remembered as long as that dashboard is in execution scope.

• Focus switches automatically to track the execution.

• It is possible to add a name attribute to your <execution-dashboard> tag in order to customize the label that appears on the tabs. This may be useful for distinguishing between multiple dashboards of a single group. Otherwise the group name appears.

• The height of the dashboard is fixed, and if the contents are larger there will be a scroll bar.