Customizing API Manager – Adding Workflow Extension

API Manager comes with capability to add custom workflows to user signup, application creation, registration and subscription. By default API manager comes with two workflows. Simple Workflow Executor and WS Workflow Executor. Simple workflow executor is the simplest one and it is enabled by default and it executes the default flow.

In WSO2 API Manager documentation, you will find a post regarding creating a custom workflow. In this post I’ll try to show in more details how this workflow process happens. Once you understand the process you could use this feature much more effectively in your own environment.

Workflows can be used to add extra steps in to the processes like self signup, application creation, etc. For example we can use a workflow for user self signup in the store and add extra steps to approve this user before giving him the permission to access the store. (the default process just create the user and grant him the rights to access the store). WS Workflow Executor has implemented this feature. The sample executor in the api manager documentation sends an email during the workflow. So we can do whatever we want. At the moment workflows can be used for only user signup, application creation, registration and subscription.

Following image describes the steps. Knowing the steps would make it easier to implement a custom workflow

When an action occurs (ex user signup, etc) API manager selects the executor to execute for that action. This is defined in the registry workflow-extension.xml file (refer https://docs.wso2.com/display/AM180/Adding+Workflow+Extensions)

Then it execute the execute() method first (please refer to the code example in https://docs.wso2.com/display/AM180/Customizing+a+Workflow+Extension). This method is called by the previous mentioned action. WorkflowDTO object is passed to this method which contains a unique reference id for that workflow (externalWorkflowReference) this reference needs to be there all the time to complete the execution.
All the custom executors should extend the base class WorkflowExecutor.
By calling the parent execute() method, an entry related to this workflow is added to the database with 'Created' as the status.
super.execute(workflowDTO);

Inside this method we could do our additional work. (sending email, etc). WS Workflow Executor which comes with API manager as one of the default executors sends a request to external business process server (WSO2 BPS) for an approval process.

We can also call the complete() method from the execute() method. This way we can finish the workflow from there (Simple Workflow Executor and the sample executor in the documentation use this method).

NOTE: some processes need to change their states in the complete stage. For example in application creation workflow you have to set the status of that application to ‘REJECTED’ or APPROVED in the complete() method (before the execute() method the application state is in ON_HOLD ).

Do not forget to call parent method at the end of the complete method
super.complete(workflowDTO);
API manager has deployed a web service to handle the situations where we call external applications (step 2 and 3). A web service'WorkflowCallbackService' is hosted to accept external requests related to workflows and call the complete() method.

The service endpoint is http://127.0.0.1:8280/services/WorkflowCallbackService and the wsdl file can be viewed using http://127.0.0.1:8280/services/WorkflowCallbackService?wsdl

The reference id I mentioned in the execute() method needs to be sent as workflowReference and status should be APPROVED, REJECTED or REGISTERED

WS Workflow Executor

WS Workflow Executor is one of the default executors in API manager. This can be used to add an approval/rejection process. WSO2 Busines Process Server is used as an external server to handle the approval process. The process is defined in BPL and deployed in WSO2 BPS. Following is the overall picture of how it is used. You could understand it with the previous information