Naughty Program Manipulator

    roadiejs-flow

    0.0.16 • Public • Published

    roadiejs-flow

    A plugin for RoadieJS

    A BPEL-inspired workflow control solution, featuring human-tasks, parallel flows and an extensible 'activity' architecture.

    Contents

    API

    createFlowFromRequest

    Creates a new flow (based on a flow template) and then goes on to run it, returning once one of these conditions is reached:

    • The finish activity is reached
    • An activity requiring human input is reached
    • An error occurs
    Request

    POST /flows

    {
      "templateId": "roadiejs.hr.newEmployee",
      "params": {
        "managerId": "Walter.White"
      }
    }
    Name Notes
    templateId The name of a flow-template from which the new flow should be generated.
    params Optional. Any values that are required by activities in the flow (e.g. docIds, username, default values etc.)
    Response

    Status 200

    {
      "flowId": "5579d9351872a3070b470e83",
      "flowState": "pending",
      "forHumans": [],
      "immediatePendingActivityId": "showStreetCreateUi",
      "message": "There is currently 1 activity pending"
    }
    Name Notes
    flowId The system-generated flowId
    flowState The current state of the overall flow. Can be pristine, running, pending, failed, dirty, lost or finished
    forHumans An array of human-readable messages
    immediatePendingActivityId On receiving a createFlowFromRequest request, a new flow will be created (based on a flow-template) and run. If during this run, the flow reaches an activity that requires immediate human input, then the id of that pending activity will be available here.
    message A simple string summarising the current state of the freshly created flow.

    stopFlowFromRequest

    Deletes the specified flow.

    Request

    DELETE /flow/:flowId

    Parameter Notes
    flowId The system-generated flowId to delete
    Response

    Status 200


    setDataAndProgress

    Sets the data object of a currently pending activity and then restarts the flow.

    Request

    PUT /flows/:flowId/data

    Parameter Notes
    flowId The system-generated flowId to update
    Response

    Status 200

    {
      "flowId": "5579f6141872a3070b470e86",
      "flowState": "finished",
      "forHumans": [],
      "message": "Flow has reached finished activity"
    }
    Name Notes
    flowId The system-generated flowId
    flowState The current state of the overall flow. Can be pristine, running, pending, failed, dirty, lost or finished
    forHumans An array of human-readable messages
    message A simple string summarising the state of the flow after the update.

    getActivity

    Returns data, config and current status information for the specified activity, along with contextual information about the wider flow.

    Request

    GET /flows/:flowId/:activityId

    Parameter Notes
    flowId An id associated with a currently-running flow.
    activityId An element id which uniquely identifies an activity within a flow.
    Response

    Status 200

    {
      "id":"createEmployeeUi",
      "flowId":"5579d9351872a3070b470e83",
      "state":"pending",
      "data": {
        "employeeNumber":20077,
        "status": "Permanent"
      },
      "type":"showUi",
      "typeConfig":{},
      "audience":[],
      "activityConfig":{
        "uiId":"streetCreateUi"
      },
      "flow":{
        "id":"5579d9351872a3070b470e83",
        "templateId":"roadiejs.hr.newEmployee",
        "state":"pending",
        "namespace":"roadiejs",
        "blueprintName":"hr",
        "blueprintVersion":1,
        "blueprintLocalVersion":0
      },
      "lastStarted":"2015-06-11T18:53:41.490Z",
      "lastCompleted":"2015-06-11T18:53:41.492Z"
    }
    Path Notes
    id The activityId that was requested
    flowId The system-generated flowId that was requested
    state The current state of the activity. Can be pristine, running, pending, dirty, ready, failed or finished
    data An object containing data pertinent to the activity. Can be set by other activities
    type The type of activity
    typeConfig roadie.activities[activity.activityType].properties,
    audience Who is part to this activity?
    activityConfig The config of the activity, as defined in its element
    flow
    flow.id The system-generated flowId that was requested
    flow.templateId The flow-template that originally used to produced the flow
    flow.state The current state of the overall flow. Can be pristine, running, pending, failed, dirty, lost or finished
    flow.namespace The namespace of the blueprint which defines the flow
    flow.blueprintName Name of the blueprint which defines the flow
    flow.blueprintVersion Version of the blueprint which defines the flow
    flow.blueprintLocalVersion The local version of the blueprint which defines the flow
    lastStarted Timestamp of when the activity was last started
    lastCompleted Timestamp of when the activity last completed
    messages A list of messages attached to the activity

    Elements

    category

    Registers a category with which flows can then be associated. Note that categories are registered 'globally' and are not namespaced. This allows multiple blueprints to contribute flows to common categories like 'Administration', 'HR' etc.

    • It's possible multiple blueprints can conflict over registering a categoryId. Currently first-installed-wins.
    Example
    {
      "element": "category",
      "id": "admin",
      "config": {
        "label": "Administration",
        "description": "General administration tasks",
        "less": {
          "base-color": "#5CB85C"
        }
    }
    Config
    Name Type Notes
    label string A short label for the category.
    description string A description of what the category's all about.
    less object Less-style CSS variables for controlling the appearance of the category

    flow

    Registers a new flow for the blueprint.

    Example
    {
      "element": "flow",
      "id": "newTeacher",
      "config": {
        "category": "employees",
        "label": "Create a new teacher",
        "description": "All the necessaries for when a new teacher joins the school",
        "instigators": ["newTab"]
      }
    }
    Config
    Name Type Notes
    category string The id of a category which this flow is best associated.
    label string A short label to identify the flow
    description string A description of what the flow's all about.
    instigators [string] An array of strings which describes how the flow might be started. To be taken from newTab, search.

    activity

    Adds a new activity to a flow (must be a child of a flow element).

    Example
    {
      "element": "activity",
      "id": "saveData",
      "path": "newDepartment",
      "config": {
        "activityType": "saveData",
        "config": {
          "sourceDataActivityId": "showDepartmentUi",
          "method": "post",
          "schema": "departments"
        }
      }
    }
    Config
    Name Type Notes
    activityType string Name of the type of activity to run.
    config object Values to configure the behaviour of the activity once it's reached. The actual values required here will depend on what activityType is defined.

    goto

    Activities are stitched together as a directed graph via goto elements. As such they need to be defined as child elements of an activity element.

    • Because of the state value, it is possible for a single activity element to have multiple gotos.
    Example
    {
      "element": "goto",
      "path": "newDepartment.saveData",
      "config": {
        "state": "finished",
        "targetActivityId": "finish"
      }
    }
    Config
    Name Type Notes
    state string Defines the circumstances of when a goto should be followed. If the associated activity completes without error, flow will follow gotos defined with a finished state. If however an activity fails, then flow will follow a goto with a failed state.
    targetActivityId string The id of an activity defined on the same flow to which flow should transfer to on completion (successful or otherwise) of the activity.

    Activities

    start

    The entry-point of where the flow is to start. If not explicitly supplied, attempts will be made to infer it. Probably best to explicitly define it...

    Example
    {
      "element": "activity",
      "id": "start",
      "path": "maintainTeacherFlow",
      "config": {
        "activityType": "start",
        "config": {}
      }
    }
    Config
    • No config's required.

    finish

    A single end-point that indicates the end of the flow. No need to explicitly define, can be inferred through gotos.

    Example
    {
      "element": "activity",
      "id": "finish",
      "path": "maintainTeacherFlow",
      "config": {
        "activityType": "finish",
        "config": {}
      }
    }
    Config
    • No config's required.

    saveData

    Takes the data stored in the specified activity's data object and then persists it to the defined schema. Will trigger data-tasks as normal.

    Example
    {
      "element": "activity",
      "id": "saveData",
      "path": "maintainTeacher",
      "config": {
        "activityType": "saveData",
        "config": {
          "sourceDataActivityId": "showTeacherUi",
          "method": "put",
          "schema": "teachers",
          "docIdPath": "teacherNumber"
        }
      }
    }
    Config
    Name Type Notes
    sourceDataActivityId string The id of an activity within the current flow, that is storing the data to persist.
    method string Should a new document be created with the data, or should an existing document be updated? One of post, put or patch.
    schema string The id of a schema defined in the blueprint into which the new/updated document is headed.
    docIdPath string Path to a key in the source activity's data object that contains the documents docId. Only used when method is set to either put or patch.

    grabBlueprintData

    Used to find a document from the supplied schema, and set the data object of the target activity.

    Example
    {
      "element": "activity",
      "id": "grabBlueprintData",
      "path": "maintainDepartment",
      "config": {
        "activityType": "grabBlueprintData",
        "config": {
        "targetActivityId": "showDepartmentUi"
        }
      }
    }
    Config
    • No config need be defined in the activity...
    Notes

    This activity is configured via parameters created as part of the flow.

    Name Type Notes
    sourceDocId string A value expected to be found in the key field of the source schema.
    sourceSchema string The schema from where the document should be fetched.

    setDefaults

    Sets default values on an activity's data object. Supports a {{...}} syntax for function-based defaults.

    Example
    {
      "element": "activity",
      "id": "setDefaults",
      "path": "newEmployee",
      "config": {
        "activityType": "setDefaults",
        "config": {
          "targetActivityId": "newEmployeeCreateUi",
          "defaults": {
            "agencyStaff": "No",
            "employementStatus": 1,
            "startDate": "{{DATE(1900-01-01)}}",
            "entryDate": "{{TODAY}}",
          }
        }
      }
    }
    Config
    Name Type Notes
    targetActivityId string Name of an activity in the current flow where default values should be set.
    defaults object Used as a key/value map to set default values. Set literally, unless value is of form {{FUNCTION_NAME}}, whereby a function will be used. Supported functions listed below.
    Default functions

    As above, if the value of the key/value map is of the form {{FUNCTION_NAME}}, then a function will be used to derive the value. Some functions may require a parameter string to be passed in the form {{FUNCTION_NAME(paramStringHere)}}.

    Function name Parameter string Notes
    NOW Sets the value to new Date().
    DATE String to be passed to newDate() Sets the value to the the specified date.
    TODAY Same as NOW, but hours, minutes and milliseconds are set to 0.

    License

    MIT

    Install

    npm i roadiejs-flow

    DownloadsWeekly Downloads

    4

    Version

    0.0.16

    License

    MIT

    Last publish

    Collaborators

    • timneedham