# OE-Workflow Modeler

Starting with Modeler

An existing BPMN file can be dropped or a new BPMN can be created by clicking the edit icon at the center or an existing BPMN can be uploaded using the browse button. Image Image

Starting screen

The left side palette of the screen, Component Palette, shows all the BPMN elements and tools to draw . The right side palette of the screen has the Property Palette, showing the properties. The area in between these two is the Canvas Area, to draw the workflow diagrams.

If no flowobject is selected in the canvas area, the Property Palette will show the properties of the complete workflow.

Image

If a flow object is selected in the canvas area the Property Palette will change, showing the properties of that selected flow object.

Image

Adding a BPMN element

A BPMN element can be added to the workflow by dragging and dropping the BPMN icon on the left panel into the workspace.

Image

Naming a BPMN element

Every BPMN element should be given a name and the property associated with the BPMN element should be filled in the panel to the right of the workspace.

All flowobjects should have a unique name across the workflow. Image

Adding next BPMN element

The next BPMN element can be added to the workflow by dragging and dropping the BPMN icon in the left panel or by clicking on the grey boxes that appear next to the existing BPMN element.

Image

Selecting the BPMN element type

A BPMN element can be of many types. Once a BPMN element has been added, the type of the BPMN element can be set by clicking on the setting icon that appear next to the BPMN element. In the figure below, the BPMN icon denotes a Task and its type is Script Task Image

Saving the BPMN

The workflow diagram can be saved or published. “Save” is equivalent of “Draft”, that is the version of the file doesn’t change even if any changes are made.

Image


Adding BPMN elements to create workflow

1. Tasks

1.1 Script Task

A Script Task is executed by a business process engine. The modeler or implementer defines a script in a javascript language that the engine will interpret. When the Task is ready to start, the engine will execute the script. When the script is completed, the Task will also be completed.

Example: In the below example a script task is being utilized for calculation the interest rate Image

	1.1.1	Parameters

    	1.1.1.1	General :  This parameter defines the name of the Task. In the above example the name of the Task is “Calculate Interest rate”
    	
    	1.1.1.2	Details – Script format : This parameter defines the format of the script that needs to be executed. The script format should be javascript. 
    	
    	1.1.1.3	Details – Script Type: This parameter defines the script type. The script type should be inline. 
    	
    	1.1.1.4	Details – Script: The script that needs to be executed has to be entered in  this text box. For the example above the script that was executed is

var principal = _msg.principal
var  irate= _msg.interestRate
var  period = _msg.period
var interest = principal * irate * period
_msg.interest = interest
	    1.1.1.5	Details – Result Variable : The result is stored in the variable entered here. This can be again referenced.

	    1.1.1.6	Description : This is for documentation purpose only and doesn’t have any impact on the workflow. In the example the task has been described as “Interest Calculation for  HNI’s”

Note: There are global variables by the name of Process Variables which will be available throughout the process(even in the subprocess). There are two functions that are internal to oe-workflow engine which are used to deal with Process varaiables:

Process Variables:

1.Every process will have a set of global variables which will be avilable throughout the process(even within the subprocesses).

2.When an user does an operation(create/update/delete), the workflow attached to the process will get instantiated.

3.The process variables of the workflow instance will have all the data of the model instance.

4.A special field called artifactId will have the model instance Id which can accessed using _getPV function as _getPV('artifactId')

Getting the Process Variables :

_getPV(<variable name>) : This function takes a process variable name and returns the value. Example

var modelInstanceId = _getPV('artifactId');
Setting the Process Variables :

_setPV(<variable name>,<value>) : This function is used to create a process variable with a given value.

Example

_setPV('name','John');

Messages :

A JSON Object named _msg is available in a workflow to pass messages from one Node to another. The _msg variable does not retain the message after the next Node.

Example

You can pass a message to a Node as

\\ Inside a REST Call for message field of Workflow Instance
{
	...
	message : {
		"status" : "approved"
	}
	... 
}

\\ Inside scripting [Script Node]
_msg.status = "approved";

the value status can be accessed from the next node(if needed inside scripting) as follows:

var something = _msg.status;

1.2 Service Task

A Service Task is executed by a business process engine. The modeler or implementer defines a service request by filling the marked forms that the engine will interpret. When the Task is ready to start, the engine will make REST calls with the provided parameters.

Image

1.2.1	Parameters

	1.2.1.1	General - Name : This parameter defines the name of the Task. In the example the name of the Task is “Update application status”.

	1.2.1.2	Details – Implementation : This parameter defines how we are supposed to implement the service task. We are providing two implementation methods as of now : 
	
		1.2.1.2.1	REST Connector : This provides an interface to make REST Calls(GET/POST/PUT)

			1.2.1.2.1.1	URL: We have to provide the URL to which we want to make REST Calls.
								Ex. http://localhost:3000/api/ProcessInstances/access_token=${_getPV("accessToken")}

			1.2.1.2.1.2	METHOD: Type of the REST Call (GET/POST/PUT). Ex.GET(will make a rest call to the api url provided)

			1.2.1.2.1.3	DATA: Data that needs to be passed to the REST Call(accepts only json).

			1.2.1.2.1.4	HEADERS: Provide the headers to the REST Call here if necessary(accepts only json)
			
			1.2.1.2.1.5	Number of Retries: Provide the number of times to retry if the REST Call fails. Default value is 1
			
			1.2.1.2.1.6	Timeout: Provide the time for how much the REST Call should wait for the response.

		1.2.1.2.2	OE Connector : This provides an interface to interact with the internal models of the application. 

			1.2.1.2.2.1	Model : Name of the model that is present in the application to interact.

			1.2.1.2.2.2	Method : Choose from the set of CRUD methods provided. This field will dynamically generate required fields that are to be populated.

		1.2.1.2.3	Finalize Transaction Connector : This provides an interface to finalize workflow dependent Model Instances by ending Attach Workflow request with a final Approved/Rejected status. Refer to Create, Update & Delete Life Cycle during Attach Workflow phase for more information. 

			1.2.1.2.3.1	Type : Type of the variable to choose transaction status from (Process Variable, Message, Static).

			1.2.1.2.3.2	Value : This parameter requires the ProcessVariable name or Message variable name based on the Type chosen to pick the status dynamically.
			
	1.2.1.3	Description :  This does not impact the workflow and is for documentation purposes only. This is to describe what the task is intended to do in the specified workflow.

Note: URL is evaluated, so dynamic variables are allowed while defining URL. A dynamic variable VAR stored in Process Variables should be written as ${pv("VAR")} while variable VAR passed as message to the Service Node should be accesed using ${msg("VAR")} in the URL for it to be evaluated. To use Authentication Token in URL one can directly use ${accessToken}. Sample URL definition -

http://localhost:3000/api/Products/access_token=${accessToken}

Note: DATA field accepts only json objects. Also we can have dynamic variables in the JSON.

{
    "workflowInstanceId" : ${pv("_workflowInstanceId")},
    "status" : "approved"
}

1.3 User Task

This task is used to model work that needs to be done using a human interaction. When the process execution arrives at a user task, a new task is created in the task list of the assigned user or role.

Task assigned to User

Image

Task assigned to Role

Image

1.3.1	General – Name : This parameter defines the name of the User Task. In the example the name of the Task is “Approval for Loan”.

1.3.2	Details : This defines whom we are supposed to assign the User Task to. We are providing two implementation for assigning User task to either User or Role.

	1.3.2.1	CandidateUsers : UserIds seperated by comma to whom the task is supposed to be assigned.
	
	1.3.2.2 ExcludedUsers : UserId seperated by comma to whom the task is not supposed to be assigned.

	1.3.2.3	CandidateRoles : Name of the Role seperated by comma to whom the task is supposed to be assigned.
	
	1.3.2.4	ExcludedRoles : Name of the Role seperated by comma to whom the task is not supposed to be assigned.
	
	1.3.2.5	CandidateGroups : Name of the Group(Department) seperated by comma to whom the task is supposed to be assigned.
	
	1.3.2.6	ExcludedGroups : Name of the Group(Department) seperated by comma to whom the task is not supposed to be assigned.

1.3.3	Description: This does not impact the workflow and is for documentation purposes only. This is to describe what the task is intended to do in the specified workflow.

1.4 Manual Task

This task has no impact on the workflow execution. It is used as a notification task for the users to do a task outside the system.

Image

1.4.1	General – Name : This parameter defines the name of the Task. In the example the name of the Task is “Send Documents”.

1.4.2	Description: This does not impact the workflow and is for documentation purposes only. This is to describe what the task is intended to do in the specified workflow.

1.5 Call Activity

A call activity allows us to integrate external bpmn files(workflows) within the current workflow as a module. This is something similar to a sub process. But a sub-process needs to be defined within the workflow where it is being used. A call activity can be any external bpmn file that has been already deployed.

The property panel on the right side of the diagram editor, will have a field called “Called Element” which is a dropdown and will list all the deployed workflows. It will allow you to pick a particular workflow from the list or if a Custom Workflow is selected, it allows for custom input through a text box. This custom text box is for dynamic call activity configuration, which will be evaluated at run time.

2 Gateways

Gateways are used to control how Sequence Flows interact as they converge and diverge within a Process. Gateways can define all the types of Business Process Sequence Flow behavior.

2.1 Exclusive Gateway

An exclusive gateway evaluates the state of the business process and—based on the condition—breaks the flow into one of the two or more mutually exclusive paths. Remember that the exclusive in “exclusive gateway” stands for mutually exclusive. In the example below, an exclusive gateway requires that the mode of transportation be evaluated.

Image

	2.1.1	General-Name: This parameter defines the name of the gateway. In the example the name of the gateway is “gateway”.
	
	2.1.2	In the outgoing sequence flows give the condition based on which the path has to be choose. In the example one sequence flow “flow1” will respond if input.count >5 and other will respond to the else case

Image

2.2 Inclusive Gateway

An inclusive gateway breaks the process flow into one or more flows. An example of an inclusive gateway is business actions taken based on survey results. For the current workflow engine this gateway is in development stage only and it will not work.

2.3 Parallel Gateway

A parallel gateway is very different than the previous gateways because you aren’t evaluating any condition or event. Instead, parallel gateways are used to represent two concurrent tasks in a business flow.

Image

	2.3.1	General-Name: This parameter defines the name of the gateway. In the example the name of the Gateways are “PG1” and “PG2”.

	2.3.2	In the above example both the sequence flows will execute in parallel and will synchronize at PG2

2.4 Event-Based Gateway

An event-based gateway is similar to an exclusive gateway because both involve one path in the flow. In the case of an event-based gateway, however, you are evaluating which event has occurred, not which condition is being met.

Image

	2.4.1	General-Name: This parameter defines the name of the gateway. In the example the name of the Gateway is EBG1
	
	2.4.2	In the example the gateway EBG1 will register all the catching events attached to it and will wait for the some throw event to trigger the event. Based on this the rest of the events will be interrupted and the flow will continue.

3 Events

3.1 Start Event

Start events define where a Process or Sub Process starts. The engine requires at least one start event to instantiate a process.

Image

3.1.1	General-Name: This parameter defines the name of the start event. In the example the name of the start event is “start”

3.1.2	Details-Initiator: This will be used to set custom values for initiation the workflow. Currently this is deprecated and is optional. initiator attribute can be set for any start event except for start events inside of sub processes

3.1.3	Description: This field is to provide description for the start event and it is optional.

3.2 End Event

End events describe how a process ends. Often, the end of one process can initiate other behaviors within a business process.

Image

3.2.1	General-Name: This parameter defines the name of the end event. In the example the name of the end event is “done”

3.2.2	Description: This is an optional field used to provide the description of the end event.