how to use workflow

How to Use Workflow ?

Module 1: Scaffold Application with Workflow

Scaffold a new application using oe-cloud-cli
Create an entry in package.json file pointing to oe-workflow github repo as:

{
    ...
    "oe-workflow" : "https://github.com/EdgeVerve/oe-workflow#master"
    ...
}

Create an entry in server/app-list.json including oe-workflow as a dependent application:

{
    ...
    {
	   "path" : "oe-workflow",
	   "enabled" : true
	},
    ...
}

Open a browser and goto Home which opens a login page for the application.
Enter your username , password and select the tenant from dropdown menu.
Once logged in, goto /designer.

Select Workflow Modeler tab from lower bar.

Module 2: Create Approval Workflow

One can open an existing workflow by dragging the bpmn file in the current window. For our guide we are going to create a new workflow by clicking on the highlighted Pencil Icon button.

Workflow Modeler will open with a new start event (cirlce) in the canvas as shown. This is a BPMN Event Flow Object. The right side of the modeler is the Properties Palette and the left side of the modeler is the Component Palette. For more information refer the OE-Workflow modeler guide.

On Left click of the start event, a panel will pop up as shown below. The items on the panel, define what is the next node that can be attached to the existing start event. Select the Append Task item as highlighted.

Once selected, you will see a new rectangular node attached to start event node. This is a BPMN Activity Flow Object. Again select the Append Task item as highlighted.

After the above selection, you will see another rectangular node attached to the previous one. The created flow contains, a start event with two tasks attached. Now select Append EndEvent item as highlighted to create and attach an end event.

We have successfully created a workflow outline with start event, two tasks and an end event. Our next step is to define the properties of all the flowobjects.

Click on the start flowobject and define the Name in the Properties Palette on the right side as highlighted.

Click on the first task node, and select Change Type item from the panel. Once selected, it presents you with a list of task types. Select the User Task option as highlighted.

Define the Name and CandidateUsers for the user task in the Properties Palette. For the guide, we have chosen mandeep and prem as candidate users, delimited by Comma as highlighted.(Users chosen should be a part of AppUser Model).

Click on the second task node, and select Change Type item from the panel. Select the Service Task option as highlighted.

Define the Name for the service task in the properties panel and select the Implementation from the dropdown as Rest Connector. Click on the REST CONNECTOR tab. Fill the URL, Method and Data as given below.

Field	Data
URL	http://localhost:3000/api/WorkflowManagers/endAttachWfRequest?access_token=${accessToken}
METHOD	POST
DATA	_{ "workflowInstanceId" : pv("workflowInstanceId"), "status" : pv("transactionStatus") }

NOTE - A new connector was created which simplifies the above configuration. Please use Finalize Transaction Connector instead of generic REST connector. After selecting the connector, a new tab will appear where we will specify type as ProcessVariables and value as transactionStatus.

Click on the end flowobject and define the Name in the Properties Palette on the right side as highlighted.

Click anywhere on the canvas area to get the Properties Palette for the entire workflow. Define the Name of the workflow in the palette.

Select the top right blue button as highlighted, select the Publish button as highlighted.

A panel pops-up asking for workflow Name and Version Message. For this guide, give the workflow name as MyApprovalWorkflow and version message as FirstAttempt. A pop-up will show the success message saying Published Successfully

Congratulations, you have successfully created and published a workflow.

Understanding the Approval WorkFlow

Background : The business process that we have just created will be attached to a Model. Any transaction involving create, update or delete on that model can be used to trigger the Approval Workflow.

Basically, Workflow will go through these steps -

Start Event - Start Event is there to understand the starting point of execution from the Process Diagram. As it is None Start Event, there is no associated action corresponding to this kind of event, so it will move the process to the next flow object that it is connected to.
User Task - User Task is a waiting task that needs to be completed by some User for it to move proceed further the process, as per BPMN specification. In this node, if we notice we have Candidate Users as mandeep,prem. What that means is that only these users are eligible to complete the task and make the process move forward. And any other user is not authenticated to control the task.

When eligible user logs in and tries to complete the task, he may give his inputs as process variables and message. The system will understand user input as transaction status which will either be approved or rejected and based on this workflow will proceed.

Service Task - We will be using REST connector in Service Task to send the User reponse Approval/Rejection to the WorkflowManager Model. In the REST body we are sending two parameters Workflow Instance Id and status. Workflow Instance Id is used to make a correlation to the instance that needs to be approved and Status field will have either approved or rejected.

Workflow Instance Id is available by default through process variables. Status was set during User Task.

End Event - End event is the exit point for Workflow.

Module 3: Attaching Workflow to a Model (Using Explorer)

Open the brower and goto http://localhost:3000/explorer and POST the below data to Model Definition to create a Product model.

{
    "name": "Product",
    "base": "BaseEntity",
    "strict": false,
    "plural": "Products",
    "idInjection": true,
    "options": {
        "validateUpsert": true
    },
    "properties": {
        "code": {
            "type": "string"
        },
        "name": {
            "type": "string"
        },
        "category": {
            "type": "string"
        },
        "price": {
            "type": "number"
        },
        "offeredSince": {
            "type": "date"
        },
        "active": {
            "type": "boolean"
        },
        "description": {
            "type": "string"
        }
    }
}

Refresh the page to see the Product Model.

Use AttachWorkflow API of Workflow Manager to attach the created MyApprovalWorkflow workflow to Product Model by posting the below data in the corresponding fields: To understand more about these parameters refer to Workflow-Integration guide.

    { 
        "modelName"     :   "Product",
        "workflowBody"  :   { "workflowDefinitionName":"MyApprovalWorkflow" },
        "operation"     :   "create",
        "wfDependent"   :   true
    }

Congratulations, we have successfully attached a workflow to a Model.

Module 4: Posting Data to the Model

Goto the Product Model and POST the below data.

    {
        "code": "HC1001",
        "name": "Caffe Latte",
        "description": "Strong Blend Espresso filled up with...",
        "category": "",
        "price": 1.23,
        "offeredSince": "01-01-2012"
    }

You will see a similar response as below:

    {
      "id": "58b0111b317319fc3ad4131a",
      "code": "HC1001",
      "name": "Caffe Latte",
      "category": "",
      "price": 1.23,
      "offeredSince": "2011-12-31T18:30:00.000Z",
      "description": "Strong Blend Espresso filled up with..."
      "_version": "f6a60252-d044-434c-ba83-f66e8a8c8bf2",
      "_type": "Product",
      "_createdBy": "mandeep",
      "_modifiedBy": "mandeep",
      "_createdOn": "2017-02-24T10:55:23.880Z",
      "_modifiedOn": "2017-02-24T10:55:23.880Z",
      "_isDeleted": false,
      "_transactionType": "create",
      "_status": "private"
    }

Try to fetch the instance using GET of the Product model.

    [{
      "id": "58b0111b317319fc3ad4131a",
      "_version": "f6a60252-d044-434c-ba83-f66e8a8c8bf2",
      "_type": "Product",
      "_createdBy": "mandeep",
      "_modifiedBy": "mandeep",
      "_createdOn": "2017-02-24T10:55:23.880Z",
      "_modifiedOn": "2017-02-24T10:55:23.880Z",
      "_isDeleted": false,
      "_transactionType": "create",
      "_status": "private"
    }]

Note: To get all the workflows attached to a model instance, we can use the API provided for all models /modelName/{id}/workflows, where {id} is the id of the model Instance.

Module 5: Approving the user task and Completing workflow.

Use the workflowInstanceId from the Product instance fetched using \Products\{id}\workflows, to get the workflowInstance using GET APIof the WorkflowInstance model. This verifies that on create, a workflow Instance was successfully created. The status of the workflowInstance will be pending because workflow will be waiting on user task.
Now login as one of the CandidateUsers mentioned in the user task when the workflow was created. Only the candiadte users can complete the user task assigned to them.
Use TASK model to fetch all the tasks API. You will find your user task created during workflow process. Get the Id of the task.
Complete the user task using by posting the below message data to the Task/{id}/complete. The id will be the task id fetched in the previous step.The message can be left empty. Post below data

{
    "pv" : {
        "transactionStatus" : "approved"
    }
}

The final data can be fetched from Product model just like in Step 1 using API. The final data will be as below.

    {
      "id": "58b0111b317319fc3ad4131a",
      "_version": "f6a60252-d044-434c-ba83-f66e8a8c8bf3",
      "_type": "Product",
      "_createdBy": "mandeep",
      "_modifiedBy": "mandeep",
      "_createdOn": "2017-02-24T10:55:23.880Z",
      "_modifiedOn": "2017-02-24T10:57:23.880Z",
      "_isDeleted": false,
      "code": "HC1001",
      "name": "Caffe Latte",
      "category": "",
      "price": 1.23,
      "offeredSince": "2011-12-31T18:30:00.000Z",
      "description": "Strong Blend Espresso filled up with...",
      "_status": "public"
    }

Observation: _status changed to "public".

Summary

Congratulations! You have successfully created a simple app based on oe-cloud, which triggers a workflow in the oe-workflow engine.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly