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
  • stopFlowFromRequest
  • setDataAndProgress
  • getActivity
• Elements
  • category
  • flow
  • activity
  • goto
• Activities
  • start
  • finish
  • saveData
  • grabBlueprintData
  • setDefaults
• License

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