com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links' is unknown.

Configuring Workflows for Tenants

Owned by Former user (Deleted)
Last updated: Mar 06, 2015
6 min read

Using the API Manager, you can configure custom workflows that get invoked at the event of a user signup, application creation, registration, subscription etc. You do these configurations in the api-manager.xml as described in the previous sections.

However, in a multi-tenant API Manager setup, not all tenants have access to the file system and not all tenants want to use the same workflow that the super admin has configured in the api-manager.xml file. For example, different departments in an enterprise can act as different tenants using the same API Manager instance and they can have different workflows. Also, an enterprise can combine WSO2 API Manager and WSO2 Business Process Server (BPS) to provide API Management As a Service to its clients. In this case, each client is a separate enterprise represented by a separate tenant. In both cases, the authority to approve business operations (workflows) resides within a tenant's space.

To allow different tenants to define their own custom workflows without editing configuration files, the API Manager provides configuration in tenant-specific locations in the registry, which you can access through the UI.

The topics below explain how to deploy a BPEL/human task using WSO2 BPS and how to point them to services deployed in the tenant spaces in the API Manager.

Deploying a BPEL and a HumanTask for a tenant

Only the users registered in the BPS can deploy BPELs and human tasks in it. Registration adds you to the user store in the BPS. In this guide, the API Manager and BPS use the same user store and all the users present in the BPS are visible to the API Manager as well. This is depicted by the diagram below:

Figure: API Manager and BPS share the same user and permission store

Follow the steps below to deploy a BPEL and a human task for a tenant in the API Manager:

Sharing the user/permission stores with the BPS and API Manager

  1. Create a database for the shared user store as follows:

    mysql> create database workflow_ustore;
Query OK, 1 row affected (0.00 sec)

    Tip: Copy the database driver (in this case, the MySql driver) to the /repository/components/lib folder before starting each server.

  2. Open the <APIM_HOME>repository/conf/datasources/master-datasources.xml and create a datasource pointing to the newly created database. For example,

    <datasource>
    <name>USTORE</name>
    <description>The datasource used for API Manager database</description>
    <jndiConfig>
        <name>jdbc/ustore</name>
    </jndiConfig>
    <definition type="RDBMS">
        <configuration>
            <url>jdbc:mysql://127.0.0.1:3306/workflow_ustore?autoReconnect=true&amp;relaxAutoCommit=true</url>
            <username>root</username>
            <password>root</password>
            <driverClassName>com.mysql.jdbc.Driver</driverClassName>
            <maxActive>50</maxActive>
            <maxWait>60000</maxWait>
            <testOnBorrow>true</testOnBorrow>
            <validationQuery>SELECT 1</validationQuery>
            <validationInterval>30000</validationInterval>
        </configuration>
    </definition>
</datasource>
  3. Repeat step 2 for the BPS as well.

  4. Point the datasource name in <APIM_HOME>repository/conf/user-mgt.xml to the new datasource. (note that the user store is configured using the <UserStoreManager> element).

    In the following example, the same JDBC user store (that is shared by both the API Manager and the BPS) is used as the permission store as well:

    <Configuration>
    <AddAdmin>true</AddAdmin>
    <AdminRole>admin</AdminRole>
        <AdminUser>
            <UserName>admin</UserName>
            <Password>admin</Password>
        </AdminUser>
    <EveryOneRoleName>everyone</EveryOneRoleName> <!-- By default users in this role sees the registry root -->
    <Property name="dataSource">jdbc/ustore</Property>
</Configuration>
  5. Repeat step 4 for the BPS as well.

Sharing the data in the registry with the BPS and API Manager

To deploy BPELs in an API Manager tenant space, the tenant space should be accessible by both the BPS and API Manager and certain tenant specific data such as key stores needs to be shared with both products. Follow the steps below to create a registry mount to share the data stored in the registry:

  1. Create a separate database for the registry:

    mysql> create database workflow_regdb;
Query OK, 1 row affected (0.00 sec)

  2. Create a new datasource in <APIM_HOME>repository/conf/datasources/master-datasources.xml as done before:

    <datasource>
    <name>REG_DB</name>
    <description>The datasource used for API Manager database</description>
    <jndiConfig>
        <name>jdbc/regdb</name>
    </jndiConfig>
    <definition type="RDBMS">
        <configuration>
            <url>jdbc:mysql://127.0.0.1:3306/workflow_regdb?autoReconnect=true&amp;relaxAutoCommit=true</url>
            <username>root</username>
            <password>root</password>
            <driverClassName>com.mysql.jdbc.Driver</driverClassName>
            <maxActive>50</maxActive>
            <maxWait>60000</maxWait>
            <testOnBorrow>true</testOnBorrow>
            <validationQuery>SELECT 1</validationQuery>
            <validationInterval>30000</validationInterval>
        </configuration>
    </definition>
</datasource>

  3. Add the following entries to <APIM_HOME>/repository/conf/registry.xml:

    <dbConfig name="sharedregistry">
    <dataSource>jdbc/regdb</dataSource>
</dbConfig>
 
<remoteInstance url="https://localhost:9443/registry">
    <id>mount</id>
    <dbConfig>sharedregistry</dbConfig>
    <readOnly>false</readOnly>
    <enableCache>true</enableCache>
    <registryRoot>/</registryRoot>
</remoteInstance>

<!-- This defines the mount configuration to be used with the remote instance and the target path for the mount -->
<mount path="/_system/config" overwrite="true">
    <instanceId>mount</instanceId>
    <targetPath>/_system/nodes</targetPath>
</mount>

<mount path="/_system/governance" overwrite="true">
    <instanceId>mount</instanceId>
    <targetPath>/_system/governance</targetPath>
</mount>

<mount path="/_system/governance/repository/security" overwrite="true">
    <instanceId>mountInstance</instanceId>
    <targetPath>/_system/governance/repository/security</targetPath>
</mount>

  4. Repeat the above three steps for the BPS as well.

Creating a BPEL

In this section, you create a BPEL that has service endpoints pointing to services hosted in the tenant's space. This example uses the Application Creation Workflow.

  1. Set a port offset of 2 to the BPS using the <BPS_HOME>/repository/conf/carbon.xml file. This prevents any port conflicts when you start more than one WSO2 products on the same server.

  2. Log in to the API Manager's management console (https://localhost:9443/carbon) and create a tenant using the Configure -> Multitenancy menu.

  3. Create a copy of the BPEL located in <APIM_HOME>/business-processes/application-creation/BPEL.

  4. Extract the contents of the new BPEL archive.

  5. Copy the ApplicationService.epr and ApplicationCallbackService.epr to the extracted folder and rename them as ApplicationService-Tenant.epr and ApplicationCallbackService-Tenant.epr respectively.

  6. Open ApplicationService-Tenant.epr and change the wsa:Address to http://localhost:9765/services/t/<tenant domain>/ApplicationService.

  7. Point the deploy.xml file to the new .epr files provided in the BPEL archive. For example,

    <invoke partnerLink="AAPL">
   <service name="applications:ApplicationService" port="ApplicationPort">
      <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="ApplicationService-Tenant.epr"></endpoint>
   </service>
</invoke>

<invoke partnerLink="CBPL">
   <service name="callback.workflow.apimgt.carbon.wso2.org:WorkflowCallbackService" port="WorkflowCallbackServiceHttpsSoap11Endpoint">
      <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="ApplicationCallbackService-Tenant.epr"></endpoint>
   </service>
</invoke>

  8. Zip the content and create a BPEL archive in the following format:

    ApplicationApprovalWorkFlowProcess_1.0.0-Tenant.zip
     |_ApplicationApprovalWorkFlowProcess.bpel 
     |_ApplicationApprovalWorkFlowProcessArtifacts.wsdl 
     |_ApplicationCallbackService-Tenant.epr
     |_ApplicationService-Tenant.epr
     |_ApplicationsApprovalTaskService.wsdl 
     |_SecuredService-service.xml
     |_WorkflowCallbackService.wsdl 
     |_deploy.xml
  9. Log into the BPS as the tenant admin and upload the BPEL.

Creating a human task

Similar to creating a BPEL, create a HumaTask that has service endpoints pointing to services hosted in the tenant's space.

  1. Create a copy of the HumanTask archive in <APIM_HOME>/business-processes/application-creation/HumanTask and extract its contents.

  2. Edit the following section in ApplicationApprovalTaskService.wsdl:

    <invoke partnerLink="AAPL">
   <service name="applications:ApplicationService" port="ApplicationPort">
         <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="ApplicationService-Tenant.epr"></endpoint>
   </service>
</invoke>
   
<invoke partnerLink="CBPL">
   <service name="callback.workflow.apimgt.carbon.wso2.org:WorkflowCallbackService" port="WorkflowCallbackServiceHttpsSoap11Endpoint">
         <endpoint xmlns="http://wso2.org/bps/bpel/endpoint/config" endpointReference="ApplicationCallbackService-Tenant.epr"></endpoint>
   </service>
</invoke>

  3. Create the HumanTask archive by zipping all the extracted files.

  4. Log into the BPS as the tenant admin and upload the HumanTask.

  5. Log into the API Manager's management console as the tenant admin and select Resources > Browse menu.

  6. Go to the /_system/governance/apimgt/applicationdata/workflow-extensions.xml in the registry and change the service URL and the credentials of the ApplicationCreationWSWorkflowExecutor. For example,

    Be sure to disable the SimpleWorkflowExecutor and enable the ApplicationCreationWSWorkflowExecutor.

Testing the workflow

You have now completed configuring the Application Creation workflow for a tenant. Whenever a tenant user logs in to the tenant store and create an application, the workflow will be invoked. You log in to the Workflow Admin Web application (https://<Server Host>:9443/workflow-admin) as the tenant admin and browse Application Creation menu to see all approval tasks have been created for newly created applications. For example,

com.atlassian.confluence.content.render.xhtml.migration.exceptions.UnknownMacroMigrationException: The macro 'next_previous_links2' is unknown.