States dashboard

The std:dashboard:states feature implements a dashboard which displays counts of processes at each state.

It can be filtered and additional UI added.

EgWorkflow.use("std:dashboard:states", {
    title: "Example task progress",
    path: "/do/example/progress-dashboard",
    columnTag: "department",
    canViewDashboard: function(dashboard, user) {
        return user.isMemberOf(Group.ViewDashboard);
    },
    states: [
        "review_project",
        "wait_reviewer",
        "check_rejection",
        "approved",
        "rejected"
    ]
});

Your plugin is responsible for providing some UI to link to the dashboard at /do/example/progress-dashboard.

Usage

The second argument to use() is the configuration, which has properties:

key title

The name of the dashboard, displayed as the page title.

key layout

The layout for the page. Consider setting to "std:wide" if there are lots of columns.

key path

The path for the generated respond() call on your plugin. The path must be within your plugin’s namespace.

key backLink

The URL for the return link (optional).

key backLinkText

The text for the back button (optional).

key configurationService

If present, the named service will be called with a copy of the specification to apply common configuration to state dashboards.

key canViewDashboard

function(dashboard, user)

A function which returns true when a user is permitted to view the dashboard. The function takes two arguments, the dashboard object and the user.

key states

An array containing the states which should be displayed on the dashboard, in order.

key mergeStates

Optional. A dictionary of state name to an array of other state names. The other states are considered the same when counting and listing workflow instances.

For example, to report "returned", "returned2" and "returned3" as a single line in the dashboard, use something like:

  states: [
    "submitted", "returned", "rejected", "approved"
  ],
  mergeStates: {
    "returned": ["returned2", "returned3"]
  }

When merging states, choose one to act as the state in the list of states for the dashboard, "returned" in this case, and include it in the right place in the states array. Then use mergeStates to list the states which should be merged into that state.

key columnTag

The name of the tag to use to split the instances into columns.

key columnTagToName

function(value)

Returns a user visible heading for the column, given the tag value.

key setup

function(dashboard, E)

A function called to set up the dashboard object for the given Exchange.

Dashboard interface

The feature configuration calls functions with a Dashboard object to allow you to configure it and add extra UI.

function addLinkParameter(key, value)

If you’re providing extra UI, for example, year navigation, you can use this to add parameters to the URL. These will be available within E.parameters in your setup() function.

function addHeaderDeferred(deferred)

Add additional UI in the header, as a deferred render created by deferredRender().

function addQueryFilter(fn)

Add a filter function which will be called to filter the dashboard using the WorkUnitQuery functions to refine the query.

For example:

  setup: function(dashboard, E) {
      var year = O.ref(E.request.parameters.year);
      if(year) {
          dashboard.addQueryFilter(function(query) {
              query.tag("year", year);
          });
      }
  }

function setTitle(title)

Override the default page title, for example, by adding the year.

Text

The dashboard system uses the text system, but interpolation is not used as there is no active instance.

Transition name on dashboard

dashboard-status:STATE
status:STATE