Standard Plugins » Workflow » Definitions » Standard features » Entity replacements

Entity replacements

This feature builds on top of the Entities system to allow you to specify alternatives to those entities. This provides per-instance customisation for workflows, giving some extra flexibility where required.

Usually this functionality will not be required, as the Entities system will be sufficient. It’s worth avoiding the extra layer of abstraction if possible.

Using replacement entities

myWorkflow.use("std:entities:entity_replacement", {
    replacements: {
        // replacement entity definitions
        "editorOrNominee": {
            entity: "editor",
            assignableWhen: {flags: ["canAssignReplacements"]},
            replacementTypes: [T.Researcher]
        },
        "adminOrNominee": {
            entity: "admin",
            assignableWhen: {flags: ["canAssignReplacements"]},
            selectableWhen: {flags: ["canAssignReplacements", "adminNotApproved"]}, // optional
            listAll: true,  // optional
            replacementTypes: [T.Staff]
        }
        onRenderUI: function(M, ui) {
            ui.addSidebarButton("/do/example-path");
            ui.addDeferredRender(deferredRenderObject);
        }
    }
});

In use throughout the consuming workflow plugin, the usage is the same as any non-replaced entity (so from the above definition, using M.entities.editorOrNominee_ref is valid).

Replacements are stored as one-to-one mappings between object Refs, so replacement is performed by a simple lookup operation.

If no replacement is specified, the original entity is returned.

Configuring entity replacements

use() the std:entities:entity_replacement feature, passing in the specification object, which has keys:

key replacements

This is an object, specifying a mapping from new entity name to an object specifying which entity to replace, when the replacement can be specified, and what type of object can be used as a replacement.

The entity string must be an entity that is already defined for the workflow.

assignableWhen is a Selector specifying when the nominees for that role can be changed.

selectableWhen is an optional Selector which allows the user to choose whether that entity is selected for this workflow. This sets a flag on the workflow instance object M, which follows the naming pattern entity-selected_ENTITYNAME_ORIGINALREF. The ref used is that of the original entity, not the replacement, for uniqueness.

These flags can then be used for any custom logic the consuming workflow requires. If selectableWhen is not used then the entity is always selected.

listAll is an optional boolean. When true the underlying entity _list is used, allowing a replacement to be chosen for each of those entities, if required.

replacementTypes is an array of schema types. The replacement StoreObject must have one of these types.

function onRenderUI

Optional. Passes in an object containing functions to add custom UI into the entity replacements overview page. The functions implemented are:

addDeferredRender(deferred)

Adds the deferredRender() object passed in to be rendered at the bottom of the entity replacement page.

addSidebarButton(link, label, indicator)

Uses the url passed in as link as the path for an action button rendered into the right-hand sidebar. label and indicator are optional, and have sensible default values.

User interface

The feature supplies a full functional user interface for viewing and selecting the replacement entities for a workflow. A link is added to the workflow object’s Action Panel, linking to the Overview page.

An entityReplacementUserInterfaceURL() method (taking no arguments) is added to the M workflow object if the ui is needed to be accessed from elsewhere.

Overview

This gives a table of the entities that have been changed, their original value, and the replacement. If the assignableWhen selector is true, then a set or change link will be displayed to the user.

Form

A very simple form page, displaying the original entity and a lookup field for replacing it. The lookup is restricted to suggesting objects of the replacement’s replacementTypes.

Text

The text for use in the ui should be added to the workflow Text interface.

The following names are searched:

Displayable entity names

• entity-replacement:display-name:editorOrNominee
• entity-replacement:display-name

Either a generic displayable value can be given, or a user-readable name supplied for each of your replacement entities

Page titles

• entity-replacement:page-title:overview
• entity-replacement:page-title:form
• entity-replacement:page-title

These are optional, with sensible defaults used if left undefined