msa arch wf dev

The workflow editor is a web based UI tool for designing, developing, testing and releasing automation workflows.

Overview

With the workflow editor, you can create new workflows or edit existing workflows.

This document explains how to use the editor to design workflows and implement them in PHP or in Python.

The Workflow designer and execution engine are located in the architecture layer, between the BPM and the Microservice.

workflow design

Workflow overview

A workflow is a automation entity that can be used to automate all sorts of simple to complex processes.

A workflow is defined by

  • a set of variables that can be used to hold the state of a workflow instance;

  • a set of processes made out of tasks. This is where the execution is coded.

The tasks are scripts that can be implemented either in PHP or in Python.

The lifecycle of a workflow

There are 3 main types of workflow processes:

CREATE

execute an automated process and create a new instance of the workflows.

UPDATE

execute an automated process that will (but it’s not mandatory) update the state of the process.

DELETE

execute an automated process that will also remove the instance of the workflow.

a delete process can be assigned to the trash icon of the workflow instances. By default, the thrash icon action will only delete the workflow instance without executing any specific process.

Execution status

The status a normal process execution is defined by the implementation of the tasks and it’s the responsibility of the developer to handle the termination status. As a developer, you have 3 statuses, defined by constants in PHP or Python, that you can use in your task to define the condition for transiting from a task to the next one.

  • ENDED: the execution was successful, the next task will be executed and if it was the last task, the process will be marked as "Success".

  • WARNING: the execution was successful but some warning were raised, the next task will be executed and if it was the last task, the process status will be displayed as "Warning".

  • FAILED: the execution failed, the process execution will stop at the current task and the process status will be noted as "Failed".

these documentations to get more details and code samples on this topic: PHP SDK and Python SDK

How to persist the state of a workflow instance

The variables are used to define the current state of a workflow instance, this state is maintained in a context which is persisted in the database.

For each workflow instance, the variable and their values are stored in the database in a context. This context is accessible in read-write mode anytime in the process tasks, in order to store a value of a variable or read a value from a variable.

Example:

in Python: read a value from the context

context = Variables.task_call()
my_name = context['name']

set a value in the context

context['name'] = my_name
Example:

in PHP: read a value from the context

$my_name = $context['name'];

set a value in the context

$context['name'] = $my_name;

The context is persisted in the database and its value is updated after each task execution.

This is how variable values can be passed, during the execution of a process, from one task to another.

by default, the variables that are declared a persisted in the context but you can also create local variables in the tasks and store them in the context.

Editor Overview

To create a new workflow, connect to the developer portal and click "+ Create" on the workflow library swimlane.

Workflow information

Provide the information related to the workflow:

  • Workflow Name: the name of the workflow

  • Description: a description of the workflow

  • Delete process: the delete process to associate to the workflow instance trash icon.

  • Workflow variable name: default to service_id (see below for more detail about this field)

  • Workflow language: PHP or PYTHON (this cannot be edited)

Workflow variables

Use "+ Create Variable" to add a variable to this workflow.

A variable can be used to store data in the context of the workflow instance and it can also be used to generate the user input fields when executing a process from the UI.

It is possible to define a variable for "internal" use and decide to keep is hidden from the end-user.

A variable has a name, a type and a display name

This documentation will give you more details on the variables and the various types available.

Workflow processes

A workflow can have as many processes as needed. The processes provide the "public" functions exposed by a workflow either with the UI or the REST API.

To create a process, click on the "+" and provide a name and a type (CREATE, UPDATE or DELETE).

the other types listed in the UI are not supported yet.
A new process

workflow editor new process

Process scheduling

Scheduling of process execution can be authorize when defining a process by checking "Allow scheduling" on the process definition screen.

When scheduling is allowed, the user execute the process either the usual way by clicking "Run" or use "Schedule" to configure the process execution scheduling.

Tasks

The tasks are the smallest execution unit of a workflow.

A process can have as many tasks as needed and although it’s possible to implement a process with a single task, splitting the overall process execution into smaller tasks will ease the code maintenance and the execution monitoring.

Depending on the workflow language selected when creating the workflow, the task should be implemented either in Python or in PHP.

When creating a new task, the UI will populate the code editor with a pre-defined code template that you can use to start coding your tasks.

PHP template
<?php

require_once '/opt/fmc_repository/Process/Reference/Common/common.php';                     (1)

function list_args()                                                                        (2)
{
  create_var_def('var_name', 'String');
  create_var_def('var_name2', 'Integer');
}

check_mandatory_param('var_name');                                                          (3)

/**
 * $context => workflow context variable one per Instance
 * ENTER YOUR CODE HERE
 */
$context['var_name2'] = $context['var_name2'] + 1;                                          (4)

if ($context['var_name2'] % 2 === 0) {                                                      (5)
	$ret = prepare_json_response(FAILED, 'Task Failed', $context, true);
	echo "$ret\n";
	exit;
}

task_success('Task OK');   // or task_error('Task FAILED');                                 (6)
?>
1 include the php SDK libraries.
2 function to list all the parameters required by the task and that should also be rendered as user input field.
3 function to check whether all the mandatory parameters are present in user input.
4 assign a variable with a modified value from another variable.
5 task execution status will depend on the value of a variable
6 end of the task.
Python template
from msa_sdk.variables import Variables		(1)
from msa_sdk.msa_api import MSA_API


dev_var = Variables()
dev_var.add('var_name', var_type='String')			(2)
dev_var.add('var_name2', var_type='Integer')


context = Variables.task_call(dev_var)
context['var_name2'] = int(context['var_name2']) + 1   (3)

ret = MSA_API.process_content('ENDED', 'Task OK', context, True)
print(ret)			(4)
1 include the php SDK libraries.
2 list all the parameters required by the task and that should also be rendered as user input field.
3 update the current context with another value read from the context.
4 end of the task.
Microservice to Task code generation

workflow create ms task

When you create a task you have the possibility to create a simple task pre-coded with on of the template above but you can also choose to create a task from a Microservice call.

If you select the second option, you’ll have the possibility to select a Microservice and one for it’s function to generate a task with all the code to execute this microservice auto-generated.

workflow create ms task

The code of the task is automatically generated.

workflow create ms task code

The variables related to the microservice are added.

workflow create ms task variables

Logging and troubleshooting

You can add debugging information to help you with your development and also provide useful information for troubleshooting task in production.

The log files are generated per workflow instance in the container msa_api under /opt/wildfly/logs/processLog/. The log files are formatted as process-XX.log where XX is the workflow instance ID.

39 is the workflow instance ID

workflow instance id

You can monitor the logs of a process by opening the logs tab in the process execution view.

workflow process exec logs

You can also monitor the logs of a process with the CLI command below

Monitor the process execution logs
docker-compose exec msa-api tail -F  /opt/wildfly/logs/processLog/process-XX.log
Log a message in PHP
require_once '/opt/fmc_repository/Process/Reference/Common/common.php';

logToFile("a message");
Log a message in Python
from msa_sdk.variables import Variables
from msa_sdk import util

dev_var = Variables()

context = Variables.task_call(dev_var)
process_id = context['SERVICEINSTANCEID']

util.log_to_process_file(process_id, 'a message')