Workflow extension support in WSO2 API Manager 1.6

Applies to

Table of contents

1. Introduction
2. Workflow extension plug points
3. Components of a workflow extension
4. How to configure and use it
5. Conclusion
6. References

Introduction

Workflow extension support was a major requirement since the early stages of WSO2 API Manager and we decided to add it to the WSO2 API Manager 1.6 release. With this new feature, users will be able to plug workflow extensions into WSO2 API Manager's key functionalities. In this release (1.6), we introduced workflow extension support for three major operations of WSO2 API Manager. In order to try this, you would need WSO2 API Manager 1.6 or above version and WSO2 Business Process server 3.0.0 or above. We do not expect high level business process workflow and human task design knowledge to try this as we have embedded all necessary workflows and human tasks into product distribution. We have documented details about this feature in the WSO2 API Manager documentation page [1]. In this article, we will discuss WSO2 API Manager's workflow extension design, its main components, configurations, and its uses. We will also describe how we can customize this workflow process according to our requirements.

The enabling of the workflow extension feature in the WSO2 API Manager will disable the processes of complete user sign-up, application creation and subscription. Therefore, we will be maintaining it in an intermediate state and enabling an administrator to approve the said action. With this system, administrators will have some kind of control over user actions. This is how the process works - if a user performs an action, the approval task will be handed over to a business process. If we take user creation as an example, when a new user is created on the system, he/she will not be able to login to the system immediately; instead, the user will receive a message that says "User account creation wait for administrator approval". Only once the administrator approves, the user will be able to login to the system and use the API store's functionalities. What actually happens is that when a new user is created in the system, we will call the external business process with the necessary information and wait for it to call back. We have included the following additional steps before complete user creation (same applies to application creation and subscription).

1. Call BPS workflow web service from WSO2 API Manager once configured
2. Accept workflow request coming from WSO2 API Manager to WSO2 BPS
3. Create human tasks instance in WSO2 BPS
4. User interaction to approve workflow. The user can log in to "Workflow-Admin" jaggery app, which is a default feature in WSO2 API Manager 1.6, and approve process. The URL for "workflow-admin" jaggery application is "http[s]://ip:port/workflow-admin"
5. Call back to WSO2 API Manager post workflow execution
6. Complete action from WSI2 API Manager side

Workflow extension plug points

Next we will discuss 3 plug points and the importance of having these:

User Signup: Whenever a new user registers on the self signing page, this workflow will be triggered (only if you have enabled the user self sign-in feature by editing api-manager.xml). This would be very useful as administrators can review all user registrations before they use the system. When users try to sign up to the API Manager Store, their request for user accounts will go into an intermediary state in which it will remain until it is approved by the administrator. To enable the User Sign Up workflow, you will need to configure UserSign up executor by editing UserSignUpSimpleWorkflowExecutor section of /repository/conf/api-manager.xml file.

API Subscription: Whenever a new subscription is created, this workflow will be executed. You can control how users can add APIs to applications created by them. Administrative users will get authority to control API subscriptions. Once the workflow is engaged in the API subscription scenario, the user's request for a new subscription will go into a temporary 'On Hold' state in which it will remain until approved or rejected by the Workflow Administrator. To enable the API Subscription workflow, you will need to configure theSubscriptionCreation executor by editing "SubscriptionCreationSimpleWorkflowExecutor" section of /repository/conf/api-manager.xml file.

Application Creation: Once the user creates the application and subscribes to APIs, he/she can invoke APIs as required. Therefore, each application created by users should be reviewed and controlled as they are the main entry points to access secured APIs. When users try to create an Application in the API Manager Store, their request will go into an intermediary state in which it will remain until authorized by the workflow authorization administrator. To enable the Application Creation workflow you will need to configure the Application Creation executor by editing "ApplicationCreationSimpleWorkflowExecutor" section of /repository/conf/api-manager.xml file.

Components of a workflow extension

Now let's discuss the main components of workflow extension implementation. There are three main components and these are connected to each other through web service APIs.

Workflow executor is somewhat of a plug point to each process followed by WSO2 API Manager. Let's take API creation, application creation, user sign up, and subscription creation as an example. Each workflow executor in WSO2 API Manager should be an implementation of the org.wso2.carbon.apimgt.impl.workflow.WorkflowExecutor abstract class. The workflow executor class has an execute method and it will create payload according to a pre-defined format. Thereafter, it will create a web service client with the information we configured in api-manager.xml file (with workflow configuration Properties) and call the business process service deployed in WSO2 BPS. Next, let's discuss the function of business process.

A workflow consists of a sequence of connected steps where each step follows. In this case, we create a business process in WSO2 BPS and expose it as a secured web service. Once the workflow executor is triggered, we will find the appropriate workflow for the performed action and do a web service call with all information that has been provided. As mentioned earlier, the external workflow would typically be a secured web service. Therefore, the calling client (the API manager in this case) would need to pass in necessary credentials to invoke the service. The configuration related to executing an external workflow would be as shown in the configuration section of this article. This configuration can be found in the /repository/conf/api-manager.xml file.

Figure 1: Business process

As illustrated in Figure 1 (design view of workflow from developer studio), we have a business process and a human task for each workflow. Once this workflow receives an event from WSO2 API Manager, it takes input parameters and creates human task instances by calling the associated human task web service. Once the business process creates the human task, it will wait until some user approves it manually (human interaction). To approve pending human tasks, we will call human tasks API from the API manager. Once the human task is completed, the business process will take the output from the completed human task and call back the API manager. As shown in Figure 1, the last invoke operation is there to callback the API manager. Once the callback receiver (at API manager) receives approval, it will change the state of application to 'ACTIVE' (if you have considered the application approval process; otherwise it will change the user's state or subscription state).

A human task is, quite simply, a unit of work done by a human. Quite often, this task involves interaction with other services, and thus becomes a task within a larger business goal. If we take the user sign up process as example, the human task would evaluate user details and approve the user through the administrator. Usually, this action is performed by the systems administrator after reviewing information provided by the user. For deployment, we have used human task deployed in WSO2 BPS and WSO2 API Manager uses BPS human task API to approve pending tasks. The administrator may log into the WSO2 API Manager Jaggery application and approve pending human tasks.

WSO2 API Manager comes with default java workflow executors and a web service executor to trigger workflow processes for the above three functions. These executors can be defined in the api-manager.xml file and you can have your own custom implementation for this purpose. If you wish to add your own workflow executor for each of these three processes, you can write your own custom executor and integrate it. This will be discussed in detail later in this article.

How to configure and use it

In this section, we will see how we can configure WSO2 API Manager with WSO2 BPS with workflow execution. In order to run this, we will assume that users running API manager with port offset 0 and BPS with port offset 02. Download WSO2 API Manager from the product homepage [1] and BPS from its product home page [3]. Unzip both archived files.

Set port offset as 2 in carbon.xml file of BPS 3.0.0. Edit the following element of carbon.xml file. 2

All the required resources can be found in wso2am-1.6.0/business-processes directory API manager product distribution. Now we need to copy some artifacts from that directory to BPS.

Copy the epr folder into repository/conf folder of BPS. Here /epr means /epr directory found in wso2am-1.6.0/business-processes/epr directory. You need to copy it (epr directory) to the repository/conf folder of Business Process Server.

Then copy human tasks (archived) files to repository/deployment/server/humantasks folder of the BPS. Here, human tasks (archived) means files available in the HumanTask directory are found in each business-processes directory (application-creation, subscription-creation or user-signup folders found in wso2am-1.6.0/business-processes). You need to copy it to the repository/deployment/server/humantasks folder of the BPS.

Then copy the business process (archived) files to the repository/deployment/server/bpel folder of the BPS. Here, business process (archived) means files available in the BPEL directory found in each business-processes directory (application-creation, subscription-creation or user-signup folders found in wso2am-1.6.0/business-processes). You need to copy it to the repository/deployment/server/bpel folder of the BPS.

Then start server.

If you wish to change port, offset to some other value or set hostname to a different value than localhost [when running BPS and AM in different machines], then you will need to edit wsa:Address in all .epr files inside the repository/conf/epr folder.

In addition, we need to edit human tasks wsdl files as well. We need this because once the human task is completed, it will call back to workflow. Hence, it should be aware of the exact service location of the workflow.

Edit the API manager configuration file to enable web service-based workflow execution. For this, we need to edit api-manager.xml located inside repository/conf of the WSO2 API Manager product.

All work flow-related configurations are located inside the section. Edit WorkFlowExtensions as follows. Please note that all workflow process services are running on port 9765 of BPS (as it is running with port offset2).

<ApplicationCreation executor="org.wso2.carbon.apimgt.impl.workflow.ApplicationCreationWSWorkflowExecutor">
           <Property name="serviceEndpoint">http://localhost:9765/services/ApplicationApprovalWorkFlowProcess</Property>
           <Property name="username">admin</Property>
           <Property name="password">admin</Property>
           <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
      </ApplicationCreation>
    
      <SubscriptionCreation executor="org.wso2.carbon.apimgt.impl.workflow.SubscriptionCreationWSWorkflowExecutor">
           <Property name="serviceEndpoint">http://localhost:9765/services/SubscriptionApprovalWorkFlowProcess</Property>
           <Property name="username">admin</Property>
           <Property name="password">admin</Property>
           <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
      </SubscriptionCreation>
      
      <UserSignUp executor="org.wso2.carbon.apimgt.impl.workflow.UserSignUpWSWorkflowExecutor">
           <Property name="serviceEndpoint">http://localhost:9765/services/UserSignupProcess</Property>
           <Property name="username">admin</Property>
           <Property name="password">admin</Property>
           <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
      </UserSignUp>

To test this, we will start with a user creation process. Go to the WSO2 API Manager store UI (https://127.0.0.1:9763/store). Then click on the self signup button available in the top right corner. Now you will be able to self sign up yourself to the API store. Once you have provided all the information required, you will see the following pop up window that says "User account awaiting administrator approval".

Figure 2: User creation message

Figure 3: Subscription creation message

Then you need to visit workflow admin jaggery app(https://10.100.1.65:9443/workflow-admin/) to view pending approval requests. Then you need to log in as admin user and approve pending approval requests.

Figure 4: Workflow admin UI image

After approving user creation requests, those users will be able to login and use WSO2 API Manager. The same applies to application and subscription creation as well. With this feature, administrative users will be able to control some of the critical operations in WSO2 API Manager. There will be multiple plug-point places in future releases of WSO2 API Manager and users will be able to have more control over user actions.

Conclusion

With this new feature, users will be able to plug workflow extensions into WSO2 API Manager's major functionalities. This would be very useful in cases of deployment with external users and systems as we can govern certain actions performed. In the future, we might need to add workflow extensions for all basic operations performed by users as well. Basically, this feature will be very useful for production deployments. In the next article we will see how we can customize this workflow process to meet our requirements.

References

[1] https://docs.wso2.org/display/AM160/WSO2+API+Manager+Documentation

[2] https://wso2.com/products/api-manager/

[3] https://wso2.com/products/business-process-server/