Workflow Service

Entities in stack9 can have a workflow definition with actions and steps, in order to manipulate the workflow, the service WorkflowService can be used.

Stack9-core

The service WorkflowService implements IWorkflowService which has the following actions available:

• hasWorkflow: Check if the workflow_definition is defined in the entity.

    /**
    * @param entityName = entity name
    */
    hasWorkflow(entityName: string): Promise<boolean>
  

• availableSteps: If the entity has a valid workflow and the workflow doesn't have an outcome (Approved | Rejected) then it will return a WorkflowInformation with available steps for the entity. If the entity has a workflow outcome defined, available steps will be an empty array.

    /**
    * @param entityName = entity name
    * @param id = entity ID
    */
    availableSteps(entityName: string, id: number): Promise<WorkflowInformation>
  
    // return
    class WorkflowInformation {
      availableSteps?: { key: string; name: string }[]; // Array of steps if workflow doesn't have outcome
      currentStep?: number; // Current step of the workflow
      ownerName?: string; // Owner of the workflow
      outcome?: WorkFlowOutcome; // Workflow outcome if exists (Approved | Rejected)
      outcomeReason?: string; // Workflow outcome reason if exists
      historyGrouped?: any[]; // Workflow history
      definition: WorkflowDefinition; // Workflow definition of the entity
    }
  

• move: If the workflow doesn't have outcome defined, it will check the step to specified in the action that has the actionKey informed.

    /**
    * @param entityName = entity name
    * @param id = entity ID
    * @param actionKey = key defined in the actions
    * @param data = entity data to be updated
    */
    move(
      entityName: string,
      id: number,
      actionKey: string,
      data: any,
    ): Promise<void>;
  
    // COMMOM ERRORS
    `Workflow has outcome defined. Cannot be changed` // Workflow with outcome defined cannot be changed.
    `Workflow cannot be moved from {step A} to {step B}` // Action in workflowDefinition doens't allow workflow to be moved to the requested action
    `"outcome_reason" is required to reject step.` // outcome_reason is required to reject the workflow
    `System could not find destination step for action '{actionKey}' in workflow definition.` // invalid action key
  

  The data object passed as parameter in this function will be used to execute an entity update.

• takeOwnership: Set the workflow owner to the workflow_owner passed in the data parameter, where workflow_owner is the user ID.

    /**
    * @param entityName = entity name
    * @param id = entity ID
    * @param data = entity data to be updated
    */
    takeOwnership(entityName: string, id: number, data: any): Promise<void>;
  
    // COMMOM ERRORS
    `Workflow has outcome defined. Cannot be changed` // Workflow with outcome defined cannot be changed.
  

  The data object passed as parameter in this function will be used to execute an entity update.

Usage

Check if an entity has workflow definition

const hasWorflow = await this.services.workflow.hasWorkflow(
  "product"
);
console.log(hasWorflow); // true

Get availables steps

await services.workflow.availableSteps(
  "event", // entity name
  7 // entity id
);

// sample return
{
  "availableSteps": [
    {
      "key": "takeOwnership",
      "name": "Take responsibility of this step",
      "to": { "takeOwnership": true }
    },
    {
      "key": "reject",
      "name": "Reject Event",
      "from": ["ALL"],
      "to": { "outcome": 2 }
    }
  ],
  "currentStep": 1,
  "outcome": null,
  "outcomeReason": null,
  "ownerName": null,
  "historyGrouped": [
    {
      "uniqueIndex": 1,
      "stepName": "Pending",
      "approvedStep": false,
      "rejectedStep": false,
      "date": "2021-07-06T06:34:53.851Z",
      "items": [
        {
          "id": 7,
          "ownerName": null,
          "created_by": "Test",
          "workflow_step": 1,
          "workflow_action": "create",
          "outcome": null,
          "outcome_reason": null,
          "date": "2021-07-06T06:34:53.851Z"
        },
        // history items...
      ]
    }
  ],
  "definition": {
    "actions": [
      // actions...
    ],
    "steps": [
      // steps...
    ],
    "outcome": {
      // outcome... 
    }
  }
}

Move workflow

await services.workflow.move(
  "product", // entity name
  7, // entity id
  "tolisting", // action key
  {
    // data : fields to be updated
    processing_message: `Updated to listed`,
    processed_date: this.started_date,
  }
);

Take workflow ownership

await services.workflow.takeOwnership(
  "product", // entity name
  7, // entity id
  {
    workflow_owner: 1  // user id to be set as owner of the workflow
  }
);