This was a major requirement since early stages of WSO2 API Manager and we decided to add it to API manager 1.6.0 release. With this new feature users will be able to plug workflow extensions in to APIManager major operations. In this release(1.6.0) we introduced workflow extension support for three major operations of API Manager. In order to try this you need API Manager 1.6.0 or above version and WSO2 Business Process server 3.0.0 or above. We don't expect high level business process workflow and human task design knowledge to try this as we embedded all necessary workflows and human tasks into product distribution. We have documented about this feature in API manager document page(link to document 1.6.0). Here in this article we will discuss about API Manager workflow extensions design, main components, configurations and usages of it. And finally we will see how we can customize this workflow process according to our requirement.
01. Introduction.
This was a major requirement since early stages of WSO2 API Manager and we decided to add it to API manager 1.6.0 release. With this new feature users will be able to plug workflow extensions in to APIManager major functionalities. In this release(1.6.0) we introduced workflow extension support for three major operations of API Manager. In order to try this you need API Manager 1.6.0 or above version and WSO2 Business Process server 3.0.0 or above. We don't expect high level business process workflow and human task design knowledge to try this as we embedded all necessary workflows and human tasks into product distribution. We have documented about this feature in API manager document page(link to document 1.6.0). Here in this article we will discuss about API Manager workflow extensions design, main components, configurations and usages of it. And finally we will see how we can customize this workflow process according to our requirement.
If we enabled Workflow Extension feature then we will not allow to complete user sign-up, application creation and subscription processes. Instead of that we will be keeping in an intermediate state and let some administrator to approve the action. With this new implementation we will be able to get certain actions if users performed any of above mentioned actions. With this system administrators can have some kind of control over user actions. It works like this, if user performed some action then approval task will handover to business process. If we take user creation as an example when new user is created on the system he will not be able to login to the system immediately, instead he will see message saying "User account creation wait for administrator approve". Once administrator approves then only user will be able to login to the system and use API store functionalities. Actually what happened here is, when new user created in the system we will call external business process with necessary information and waiting for call back from it. We have added following additional steps before complete user creation( same applies application creation and subscription).
01. Call BPS workflow web service from API manager once configured event happened.
01. Accept workflow request coming from API manager to BPS.
02. Create human tasks instance in BPS.
03. User interaction to approve workflow. User can log in to "Workflow-Admin" jaggery app which is default ship with API manager 1.6.0 and approve process.The url for "workflow-admin" jaggery application is "http[s]://ip:port/workflow-admin"
04. Call back to API manager after workflow execution.
05. Complete action from API Manager side.
02. Workflow Extension plug points.
Next we will discuss about 3 plug points and importance of having them. These are 3 main plug points
User Signup: Whenever new user registered from self signin page this workflow will trigger (only if you enabled 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 system. When users try to sign up to the API Manager Store, their request for user accounts will go into an intermediary state where in which it will remain until it get approve by administrative. To enable User Sign Up workflow you will need to configure the UserSign up executor by editing UserSignUpSimpleWorkflowExecutor section of <AM_HOME>/repository/conf/api-manager.xml file.
API Subscription: Whenever new subscription created this workflow will get executed. You can control how users can add APIs to applications created by them. Administrative users will get authority to control of API subscriptions. Once the workflow is engaged in the API subscription scenario, user's request for a new subscription will go into a temporary 'On Hold' state where in which it will remain until approved or rejected by the Workflow Administrator. To enable API Subscription workflow you will need to configure theSubscriptionCreation executor by editing "SubscriptionCreationSimpleWorkflowExecutor" section of <AM_HOME>/repository/conf/api-manager.xml file.
Application Creation: Once user created application and subscribe to APIs they can invoke APIs as they need. So each application created by users should be reviewed and controlled as they are main entry point to access secured APIs. When users try to create an Application in the API Manager Store, their request will go into an intermediary state where in which it will remain till authorized by the workflow authorization administrator. To enable the Application Creation workflow you will need to configure the ApplicationCreation executor by editing "ApplicationCreationSimpleWorkflowExecutor" section of <AM_HOME>/repository/conf/api-manager.xml file.
03. Components of Workflow Extension.
Next we will discuss about main components of Workflow Extension implementation. These are the three main components of workflow executor. These components are connected to each other through web services APIs.
01. workflow executor
Workflow executor is kind of a plug point to each process followed by API manager. As an example we can discuss about API creation, Application creation, user sign up and subscription creation. Each workflow executor in the WSO2 API Manager should be an implementation of org.wso2.carbon.apimgt.impl.workflow.WorkflowExecutor abstract class. Workflow executor class is having execute method and it will create payload according to predefined format. Then it will create web service client with the information we configured in api-manager.xml file (with workflow configuration Properties) and call business process service deployed in WSO2 BPS. Next we will see what business process is doing.
02. Business process
A workflow consists of a sequence of connected steps where each step follows. In this case we will create a business process in WSO2 Business Process Server and expose it as a secured web service to outside. So once workflow executor triggered we will find appropriate workflow for performed action and do a web service call with all provided information. As mentioned earlier external workflow would typically be a secured web service. Therefore the calling client (the API Manager in this case) requires to pass in necessary credentials to invoke the service. The configuration related to executing an external workflow would be as shown in configuration section of this article. This configuration can be found in the <AM_HOME>/repository/conf/api-manager.xml file.
[Business process image]
As you can see in this image (design view of workflow from developer studio) we have business process and human task for each workflow. Once this workflow received event from API manager it takes input parameters and create human task instances by calling associated human task web service. Once business process created human task, it will wait till some user approve it manually(human interaction). To approve pending human tasks we will call human tasks API from API manager. Once human task is completed business process will take output from completed human task and call back the API manager. As you can see in the diagram last invoke operation is there to callback API manager. Once callback receiver (at API Manager) received approval it will change the state of application to 'ACTIVE' ( if we considered application approval process. Otherwise it will change user's state or subscription state).
03. Human task
A human task is, quite simply, a unit of work done by a human. Quite often, this task involves the interaction with other services, and thus becomes a task within a larger business goal. If we take user sign up process as example, human task would be evaluate user details and approve user by administrator. Usually this action is performed by system administrator after reviewing information provided by user. For deployment we have used human task deployed in WSO2 BPS and API manager use BPS human task API to do approve pending tasks. Administrator may log into API manager jaggery application and approve pending human tasks.
API manager comes with default java workflow executors and a web service executor to trigger workflow processes for above three functions. These executors can be defined in api-manager.xml file and you can have your own custom implementation for that.If you wish to add your own workflow executor on each of these three processes, you can write your own custom executor and integrate it. Later in this article we will see how we can do it.
<DONE>
Configure workflow execution and use it
In this section we will see how we can configure API Manager with WSO2 Business process server with workflow execution. In order to run this we will assume users running API manager with port offset 0 and Business Process server with port offset 02.
Business Process Server Configurations
Set port offset as 2 in carbon.xml file of Business Process Server 3.0.0. Edit following element of carbon.xml file.
<Offset>2</Offset>
Copy epr folder in to repository/conf folder of Business Process Server.
Then copy human tasks (archived) files to repository/deployment/server/humantasks folder of Business Process Server.
Then copy business process (archived) files to repository/deployment/server/bpel folder of Business Process Server.
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 repository/conf/epr folder.
In addition to that we need to edit human tasks wsdl files as well. We need this because once human task finished it will call back to workflow. So it should aware about exact service location of workflow.
API Manager Configurations
Edit 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 API Manager product.
All work flow related configurations are located inside <WorkFlowExtensions> section. Edit WorkFlowExtensions as follows. Please note that all workflow process services
are running on port 9765 of Business Process Server(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>
</WorkFlowExtensions>
To test this we will start with user creation process. Please go to API Manager store ui(http://127.0.0.1:9763/store). Then click on self signup button available in right top corner. Now you will be able to self sign up your self for API store. Once you provided all information required you will see following pop up window saying "User account waiting administrator approval"
No comments:
Post a Comment