Adding an API State Change Workflow
This section explains how to add a custom workflow to control the API state changes in the API Manager. First see Workflow Extensions for more information on different types of workflow executors. For more details on API states see API Lifecycle.
Configuring the Business Process Server
- Download WSO2 Business Process Server.
Set an offset of 2 to the default BPS port in
<BPS_HOME>/repository/conf/carbon.xml
file. This prevents port conflicts that occur when you start more than one WSO2 product on the same server. Also see Changing the Default Ports with Offset.<Offset>2</Offset>
Tip: If you change the BPS port offset to a value other than 2 or run the API Manager and BPS on different machines (therefore, want to set the
hostname
to a different value thanlocalhost
), you do the following:- Search and replace the value 9765 in all the files (.epr) inside
<APIM_HOME>/business-processes
folder with the new port (9763 + port offset).
- Search and replace the value 9765 in all the files (.epr) inside
Start the BPS server and log in to its management console (
https://<Server Host>:9443+<port offset>/carbon
).If you are using Mac OS with High Sierra, you may encounter following warning when login into the Management console due to a compression issue exists in High Sierra SDK.
WARN {org.owasp.csrfguard.log.JavaLogger} - potential cross-site request forgery (CSRF) attack thwarted (user:<anonymous>, ip:xxx.xxx.xx.xx, method:POST, uri:/carbon/admin/login_action.jsp, error:required token is missing from the request)
To avoid this issue open <BPS_HOME>/repository/conf/tomcat/catalina-server.xml and change the compression="on" to compression="off" in Connector configuration and restart the BPS.
- Select Processes > Add > BPMN and upload the
<APIM_HOME>/business-processes/api-state-change/APIStateChangeApprovalProcess.bar
file to BPS.
Configuring the API Manager
- Open
<APIM_HOME>/repository/conf/api-manager.xm
l and set in<Enabled>
totrue
in the<WorkflowConfigurations>
section. - Change the
<ServerUrl>
if you have configured the BPS to run on a different port offset.
Engaging the WS Workflow Executor in the API Manager
First, enable the API state change workflow.
- Log in to the APIM management console (
https://<Server Host>:9443/carbon
) and select Browse under Resources.
Go to the
/_system/governance/apimgt/applicationdata/workflow-extensions.xml
resource, disable the Simple Workflow Executor and enable WS Workflow Executor.<WorkFlowExtensions> .... <!-- Publisher related workflows --> <!--<APIStateChange executor="org.wso2.carbon.apimgt.impl.workflow.APIStateChangeSimpleWorkflowExecutor" />--> <APIStateChange executor="org.wso2.carbon.apimgt.impl.workflow.APIStateChangeWSWorkflowExecutor"> <Property name="processDefinitionKey">APIStateChangeApprovalProcess</Property> <Property name="stateList">Created:Publish,Published:Block</Property> </APIStateChange> .... </WorkFlowExtensions>
You have now engaged the API WS Workflow. The default configuration is set for Created to Publish and Published to Block state changes. See Advanced Configurations for information on configuring more state changes.
Log in to the API Publisher (
https://<Server Host>:9443/publisher
) and publish an API. See Create and Publish an API. A message related to the publish workflow will be displayed because the workflow is enabled for Created to Publish state change.Note that the Save & Publish button will be disabled until the workflow task is completed or deleted.
You can revoke the state change by clicking Delete Task in the Lifecycle tab.
- Log in to the Admin Portal (
https://<Server Host>:9443/admin
) and click API State Change to see the list of tasks awaiting approval.
Click Assign to Me to approve the task. Select Approve and click Complete to resume and complete the API state change.
Configuring the BPS for tenants
- Log in to the BPS with the credentials of the tenant. Select Processes > Add > BPMN and upload the
<APIM_HOME>/business-processes/api-state-change/APIStateChangeApprovalProcess.bar
file to BPS. - Copy the
<BPS_HOME>/repository/deployment/server/webapps/bpmn.war
web app to<BPS_HOME>/wso2bps-3.6.0/repository/tenants/<tenant_id>/webapps
. - To engage the WS Workflow Executor, log in to the admin console using the credentials of the tenant and repeat step 2 from Engaging the WS Workflow Executor in the API Manager.
Advanced Configurations
Given below are the configurations that can be changed by editing <APIM_HOME>/repository/conf/api-manager.xml
<WorkflowConfigurations> <Enabled>true</Enabled> <ServerUrl>https://localhost:9445/bpmn</ServerUrl> <ServerUser>${admin.username}</ServerUser> <ServerPassword>${admin.password}</ServerPassword> <WorkflowCallbackAPI>https://localhost:${mgt.transport.https.port}/api/am/publisher/v0.10/workflows/update-workflow-status</WorkflowCallbackAPI> <TokenEndPoint>https://localhost:${https.nio.port}/token</TokenEndPoint> <DCREndPoint>https://localhost:${mgt.transport.https.port}/client-registration/v0.10/register</DCREndPoint> <DCREndPointUser>${admin.username}</DCREndPointUser> <DCREndPointPassword>${admin.password}</DCREndPointPassword> </WorkflowConfigurations>
The elements of the above configuration are explained below.
Element name | Description |
---|---|
| Enables the Admin Portal to approve state change tasks. |
| The URL of the BPMN server. |
| User accessing the BPMN REST API. |
| Password of the user accessing the BPMN REST API. |
| The REST API invoked by the BPMN to complete the workflow. |
| The API call to generate the access token is passed to the BPMN process. Once the access token is received, it is used to call the workflow callback API. |
| Endpoint to generate OAuth application. This application is used by the BPMN process to generate the token. |
| Endpoint user. |
| Endpoint password. |
Setting a DCREndPointUser
Create a user with exclusive apim:apiworkflow scope permissions when setting a DCREndPointUser.
Please avoid using super admin credentials. If super admin credentioals are used, the created OAuth application will have all the permissions related to scopes in the other REST APIs. Follow the steps below to create a user with apim:apiworkflow scope permissions:
- Log in to APIM management console (
https://<Server Host>:9443/carbon
) and create a role namedworkflowCallbackRole
. Set create and publisher or subscriber permissions to this role. Go to Resources and click Browse. Go to
/_system/config/apimgt/applicationdata/tenant-conf.json
and update the role related to ‘apim:api_workflow’ scope with the newly created role.... { "Name": "apim:api_workflow", "Roles": "workflowCallbackRole" } ...
- Assign this role to a user.
- Update <DCREndPointUser> and <DCREndPointPassword> with this user's credentials.
For more details on how to create users and roles see managing users and roles.
The configurations that can be changed by editing the /_system/governance/apimgt/applicationdata/workflow-extensions.xml
are given below.
<APIStateChange executor="org.wso2.carbon.apimgt.impl.workflow.APIStateChangeSimpleWorkflowExecutor" />
<APIStateChange executor="org.wso2.carbon.apimgt.impl.workflow.APIStateChangeWSWorkflowExecutor"> <Property name="processDefinitionKey">APIStateChangeApprovalProcess</Property> <Property name="stateList">Created:Publish,Published:Block</Property> </APIStateChange>
The elements of the above configuration are explained below.
Element Name | Mandatory/Optional | Description |
---|---|---|
| Mandatory | BPMN process definition id. BPMN process provided with AM as default has ‘APIStateChangeApprovalProcess’ as the id |
| Mandatory | This is a comma separated list of the current state and intended action. For example, Created:Publish,Published:Block |
| Optional | The URL of the BPMN process engine. This overrides the global |
| Optional | Username for the external BPMN process engine. This overrides |
| Optional | password for the external BPMN process engine. This overrides |