Adding a workflow to WSO2 APIM when there are port offsets

4 min readDec 21, 2019

Source : https://gravityflow.io/articles/workflow-automation-best-practices/

You may already aware of adding custom workflows to WSO2 APIM. However, I have found that there is a little bit of confusing when there are port offsets for APIM and EI/BPS servers when achieving the same task. So, this blog post will help you to solve that confusion.

Just for the completion, I will also mention all default steps of this integration along with the required additional steps on fulfilling the requirement. And here, I will take adding application creation workflow relates to WSO2 BPS as an example.

First, configure the Business Process Server

Download WSO2 Business Process Server.

2. Set an offset of 4 to the default BPS port in the <BPS_HOME>/repository/conf/carbon.xml file.

<Offset>4</Offset>

By default, this port offset is 2. So, when changing the BPS port offset other than 2, you need to search and replace the value 9765 in all the files ( .epr) inside the <APIM_HOME>/business-processes directory with the new port (ex: 9763 + <port-offset>). Or when running the APIM and BPS servers on different machines, you need to set the hostname to a different value other than the localhost.

3. Open the <BPS_HOME>/repository/conf/humantask.xml file and <BPS_HOME>/repository/conf/b4p-coordination-config.xml file and set the TaskCoordinationEnabled property to true.

<TaskCoordinationEnabled>true</TaskCoordinationEnabled>

4. Copy the following from the <APIM_HOME>/business-processes/epr directory to the <BPS_HOME>/repository/conf/epr directory.
If the <BPS_HOME>/repository/conf/epr directory does not exist, create it.

Make sure to give the correct credentials in the <BPS_HOME>/repository/conf/epr files.

Update the <APIM_HOME>/business-processes/epr/ApplicationCallbackService.epr file according to API Manager (hostname and port). Here I have used APIM server with port offset 1.

<wsa:Address>https://localhost:8244/services/WorkflowCallbackService</wsa:Address>

Update the <APIM_HOME>/business-processes/epr/ApplicationService.epr file according to BPS.

<wsa:Address>http://localhost:9767/services/ApplicationService</wsa:Address>

5. Start the BPS server and sign in to the Management Console (https://<Server Host>:9443+<port-offset>/carbon)

ex:https://<Server Host>:9447/carbon

6. Also, please make sure to search the value 8243, 8280 in all the files (.epr, .wsdl files inside the ZIP archives) inside <APIM_HOME>/business-processes folder and replace respectively with 8244, 8281.

7. Click Add under Processes and upload the <APIM_HOME>/business-processes/application-creation/BPEL/ApplicationApprovalWorkFlowProcess_1.0.0.zip file to BPS.
This is the business process archive file.

8. Select Add under the Human Tasks menu and upload the .<APIM_HOME>/business-processes/application-creation/HumanTask/ApplicationsApprovalTask-1.0.0.zip file to BPS.
This is the human task archived file.

When updating the aforementioned archive file, please make sure to un-deploy the existing BPEL and HumanTask archived files and redeploy the updated <APIM_HOME>/business-processes/application-creation/BPEL/ApplicationApprovalWorkFlowProcess_1.0.0.zip and <APIM_HOME>/business-processes/application-creation/HumanTask/ApplicationsApprovalTask-1.0.0.zip files to BPS server.

Then configure the WSO2 API Manager

Open the <APIM_HOME>/repository/deployment/server/jaggeryapps/admin/site/conf/site.json file and configure “workFlowServerURL”under “ workflows” to point to the BPS server (ex:”workFlowServerURL”: “https://localhost:9447/services/")
Change the port to 9444 (according to the port offset of APIM server) of the following property in WorkflowCallbackService.xml resides in the <APIM_HOME>/repository/deployment/server/synapse-configs/default/proxy-services directory.

<address uri="https://localhost:9444/store/site/blocks/workflow/workflow-listener/ajax/workflow-listener.jag"
                        format="rest"/>

By default, it contains localhost:9443.

When you do not configure the above changes, you will be faced with the below warnings.

WARN {org.apache.synapse.endpoints.EndpointContext} - Endpoint : AnonymousEndpoint with address https://localhost:9443/store/site/blocks/workflow/workflow-listener/ajax/workflow-listener.jag will be marked SUSPENDED as it failed {org.apache.synapse.endpoints.EndpointContext}WARN {org.apache.synapse.endpoints.EndpointContext} - Suspending endpoint : AnonymousEndpoint with address https://localhost:9443/store/site/blocks/workflow/workflow-listener/ajax/workflow-listener.jag - current suspend duration is : 30000ms - Next retry after : Tue Oct 29 11:11:46 CET 2019 {org.apache.synapse.endpoints.EndpointContext}

3. Sign in to WSO2 APIM Management Console (https://<Server-Host>:9444/carbon) and select Browse under Resources.

4. Navigate to the /_system/governance/apimgt/applicationdata/workflow-extensions.xml resource, disable the Simple Workflow Executor, and enable WS Workflow Executor. In addition, specify the service endpoint where the workflow engine is hosted and the credentials required to access the said service via basic authentication (i.e., username/password based authentication).

<WorkFlowExtensions>
…
 <ApplicationCreation executor=”org.wso2.carbon.apimgt.impl.workflow.ApplicationCreationWSWorkflowExecutor”>
 <Property name=”serviceEndpoint”>http://localhost:9767/services/ApplicationApprovalWorkFlowProcess/</Property>
 <Property name=”username”>admin</Property>
 <Property name=”password”>admin</Property>
 <Property name=”callbackURL”>https://localhost:8244/services/WorkflowCallbackService</Property>
 </ApplicationCreation>
… 
</WorkFlowExtensions>

Note: When enabling the workflow features, make sure you import the certificate of the API Manager into the client-truststore located inside the <BPS_HOME>/repository/resources/security directory.

Now, you can test the Application creation flow.

Navigate the API Store, click Applications and create a new application.
Note that the status field of the application states INACTIVE (Waiting for approval).