Deep Dive Into Workflows in WSO2 API Manager
What is a Workflow Anyways ?
When you are thinking about api manager workflows, you must be wondering , “what is a workflow in the first place ?”. Well, Wikipedia defines a workflow as an “orchestrated and repeatable pattern of activity that transforms materials”.
Let us break it down a bit, a workflow in its simplest terms can be said as sequence of tasks which processes a set of data from the start to finish. Workflows can be said as a number of sub-tasks which needs to be completed in order to finish a certain “main” task.
Workflows in WSO2 API Manager
Above we briefly looked into what workflows are, in general. Now lets look into what exactly a workflow is in the context of WSO2 API Manager.
As you already know there are various api-management-related operations which are enabled by default in the WSO2 API Manager, like creating applications, subscribing to APIs using applications, generating access tokens for applications, signing up new users etc.
The normal flow of these operations is that when you prompt any of these operations, the API Manager instance does the needful and executes your task. But imagine that if you need to add additional functionality to the midst of a certain operation we mentioned before or it could be simple as getting the admin user to approve those operations so that the users of WSO2 APIM should wait till the admin user approves those tasks.
For an example lets take subscribing to a certain API using an Application in the APIM DevPortal. The normal procedure is creating an application and subscribing to a certain API, simple ! But if you want you could an approval workflow to this process, so that when a user subscribes to an API, there is an additional step which should be approved by the APIM Admin.
APIM internally uses WorkFlows for this purpose.
APIM Workflows
Now lets dig into workflows a bit more. In this passage, I will use an API Subscription process (Application subscribing to an API from the DevPortal) as an example.
In APIM two main classes are used to represent the concept of a workflow. A WorkFlowDTO class to store general information the workkflow and the relevant entity. A WorkFlowExecutor class which is used to implement the execution logic of the workflow process.
There are two main types of WorkFlows included in the APIM package by default. Namely SimpleWorkflow and ApprovalWorkflow. The simple workflow is by default activated in the APIM and it does not add any additional steps to a certain process. But if the ApprovalWorkflow is activated, an extra approval step is added to a certain task. In our case, when an application subscribes to an API from the DevPortal, the Application status changes to ON HOLD in the subscription window instead of directly subscribing to the API. And a new entry appears in the Admin Portal as below. Only when this entry is approved, the subscription is done and finalized.
To see which workflows are activated by default and change them, you can visit the APIM Management Console,
https://<Server Host>:9443/carbonand in resources-browse go to
/_system/governance/apimgt/applicationdata/workflow-extensions.xmlIn here inside the tag <WorkFlowExtensions> you could see the activated workflows for the given tasks. If you take a fresh pack of APIM, you’ll see that SubscriptionCreationSimpleWorkflowExecutor is there by default and SubscriptionCreationApprovalWorkflowExecutor is commented out. If you need to change it to the ApprovalWorkflow you could comment out the SimpleWorkFlow and uncomment the Approval workflow. After that if you try to subscribe to an Application you will encounter the above mentioned process.
WSO2 APIM includes several workflow enabled operations by default such as ApplicationCreation, UserSignUp, SubscriptionDeletion and ApplicationDeletion etc.
Digging Deeper Into WorkFlows
As I said earlier, there are two important classes inside APIM code base we need to talk about if we need to dig deeper into WorkFlows.
WorkFlowDTO is the class which is used to store the workflow related information, this information will be stored inside the AM_WORKFLOWS table in the APIM database. In the WorkFlowDTO class, there are 3 important variables which needs addressing.
- workflowReference — Used to reference the entity which is bind to a certain workflow. This is different for each workflow type. For example, for SubcriptionWorkflow types, this is used to hold the relevant subscriptionId.
- status — The status of the workflow. Could be CREATED/APPROVED/REJECTED or REGISTERED
- externalWorkFlowReference — Holds the workflow reference Id. A unique identifier used to reference a certain workflow.
The WorkFlowDTO class has several subclasses representing the different WorkFlow types. ApplicationWorkflowDTO, SubscriptionWorkFlowDTO etc.
The next and the most important class of all is the WorkFlowExecuter. This contains all the core methods which will be called in the WorkFlowLife cycle. For the different type of WorkFlows, a different implementation of this class exists. There are 3 essential methods we need to talk about here.
- execute() — Starting the WorkFlow process, modifieng the relavant WorkFlowDTO and persisting it. This creates the WorkFlow entry in the database. Invoked during the initial stage of the workflow process.
- complete() — Completes the workflow process. WorkFlow completion logic is included here. Normally, until this method is invoked, the relavant entity is in ON_HOLD state. In our case this is called when the admin approves the subscription request from the admin console.
- cleanUpPendingTask() — Cleans-up pending workflows when the original entity related to the workflow is deleted. In our case, if an un-approved subscription is deleted, this method is called.
Apart from SimpleWorkflows and ApprovalWorkflows which are provided by default in the APIM, you could also create your custom workflows pretty easily by implementing the above mentioned classes and methods. So as you can see, it is a very flexible method to incorporate your own business requirements to the API Manager process.
In this article, I have provided a brief introduction to working and understanding the workflows in WSO2 API Manager. You could explore the code base to gain more insight about different types of WorkFlows and how they are used throughout the application.
Thanks for the read :)
