Versions Compared

Old Version 4

changes.mady.by.user Former user

Saved on

compared with

New Version 5

changes.mady.by.user Former user

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: https://wso2.org/jira/browse/DOCUMENTATION-4365

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 workflow-extensions.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 the 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:
Image Removed
Figure: API Manager and BPS share the same user and permission store

Warning

If you are using WSO2 BPS 3.2.0, please copy the <APIM_HOME>/repository/components/patches/patch0009 folder to the <BPS_HOME>/repository/components/patches folder and restart the BPS server for the patch to be applied. This patch has a fix to a bug that causes the workflow configurations to fail in multi-tenant environments.

This patch is built into the BPS version 3.5.0 onwards.

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

Table of Contents
maxLevel4
minLevel4
printablefalse

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

...

Create a database for the shared user and permission store as follows:

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

Make sure you copy the database driver (in this case, mysql driver) to the /repository/components/lib folder before starting each server.

...

Run the <APIM_HOME>/dbscripts/mysql.sql script (the script may vary depending on your database type) on the database to create the required tables.

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

...

languagexml

...

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 workflow-extensions.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 the 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:
Image Added
Figure: API Manager and BPS share the same user and permission store

Warning

If you are using WSO2 BPS 3.2.0, please copy the <APIM_HOME>/repository/components/patches/patch0009 folder to the <BPS_HOME>/repository/components/patches folder and restart the BPS server for the patch to be applied. This patch has a fix to a bug that causes the workflow configurations to fail in multi-tenant environments.

This patch is built into the BPS version 3.5.0 onwards.

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

Table of Contents
maxLevel4
minLevel4
printablefalse

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

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

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

    Make sure you copy the database driver (in this case, mysql driver) to the /repository/components/lib folder before starting each server.

  2. Run the <APIM_HOME>/dbscripts/mysql.sql script (the script may vary depending on your database type) on the database to create the required tables.

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

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

  7. 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).

    Tip

    If you already have a user store such as the lDAP in your environment, you can point to it from the user-mgt.xml file, instead of the user store that we created in step1.

    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:

    Code Block
    languagexml
    <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>
  8. Repeat step 5 in the BPS as well.

...

  1. Create a separate database for the registry:

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

  2. Run the <APIM_HOME>/dbscripts/mysql.sql script (the script may vary depending on your database type) on the database to create the required tables.

    Note

    From WSO2 Carbon Kernel 4.4.6 onwards there are two MySQL DB scripts available in the product distribution. Click here to identify as to which version of the MySQL script to use.

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

    Code Block
    languagexml
    <datasource> <name>REG_DB</name> <description>The datasource used for API Manager database</description> <jndiConfig>

  3. script to use.

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

    Code Block
    languagexml
    <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>
            <name>jdbc<maxActive>50</regdb</name>maxActive>
    </jndiConfig>     <definition type="RDBMS">  <maxWait>60000</maxWait>
      <configuration>      <testOnBorrow>true</testOnBorrow>
      <url>jdbc:mysql://127.0.0.1:3306/workflow_regdb?autoReconnect=true&amp;relaxAutoCommit=true</url>      <validationQuery>SELECT 1</validationQuery>
     <username>root</username>        <validationInterval>30000</validationInterval>
    <password>root</password>    </configuration>
    </definition>
</datasource>

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

    Code Block
    languagexml
     <dbConfig  <driverClassName>com.mysql.jdbc.Driver</driverClassName>name="sharedregistry">
         <dataSource>jdbc/regdb</dataSource>
   <maxActive>50<</maxActive>dbConfig>
 
 <remoteInstance url="https://localhost:9443/registry">
        <maxWait>60000<<id>mount</maxWait>id>
        <dbConfig>sharedregistry</dbConfig>
   <testOnBorrow>true</testOnBorrow>     <readOnly>false</readOnly>
       <validationQuery>SELECT 1<<enableCache>true</validationQuery>enableCache>
        <registryRoot>/</registryRoot>
    <validationInterval>30000<</validationInterval>remoteInstance>
    <!-- This defines the </configuration>mount configuration to be used </definition>
</datasource>

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

    Code Block
    languagexml
     <dbConfig name="sharedregistry">
        <dataSource>jdbc/regdb</dataSource>
 </dbConfig>
 
 <remoteInstance url="https://localhost:9443/registrywith the remote instance and the target path for the mount -->
    <mount path="/_system/config" overwrite="true">
        <id>mount<<instanceId>mount</id>instanceId>
        <dbConfig>sharedregistry</dbConfig><targetPath>/_system/nodes</targetPath>
    </mount>
  <mount path="/_system/governance" overwrite="true">
    <readOnly>false</readOnly>         <enableCache>true</enableCache><instanceId>mount</instanceId>
        <registryRoot>/</registryRoot><targetPath>/_system/governance</targetPath>
    </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>

  6. Repeat the above three steps in 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.
    Image Removed

  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 ApplicationService.epr and ApplicationCallbackService.epr from <APIM_HOME>/business-processes/epr folder to the folder extracted before. Then, rename the two files 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 of the extracted folder to the new .epr files provided in the BPEL archive. For example,

    Code Block
    languagexml
    <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:

    Code Block
    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.
    Image Removed
    /mount>

  10. Repeat the above three steps in 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.
    Image Added

  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 ApplicationService.epr and ApplicationCallbackService.epr from <APIM_HOME>/business-processes/epr folder to the folder extracted before. Then, rename the two files 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 of the extracted folder to the new .epr files provided in the BPEL archive. For example,

    Code Block
    languagexml
    <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:

    Code Block
    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.
    Image Added

Creating a Tenant for Authentication

Step 1: Create a registry resource in the tenant's configuration registry
  1. Start the BPS server If it is not started already.
  2. Navigate to Registry>Browse in the Main menu of the management console and click on /_system/config.
    Image Added

  3. Click on Entries>Add Resource and fill the form using the values listed below for guidance. See Adding a Resource for more information. 

    MethodNameMedia Type
    Create Text ContentTaskCoordinationtext/plain
  4. Click Add to finish adding the resource.
    Image Added
Step 2: Create username and password registry properties and define credentials

  1.  Click on the registry resource you created (Task Coordination) found under the Entries section. 

    Image Added

  2. Add two new registry properties for the resource called "Username" and "Password", and define the tenant coordination user credentials. To do this, click Properties>Add New Property and enter the following values. See Managing Properties for more information. 

    Username PropertyPassword Property
    Name: usernameName: password
    Value: (username value)Value: (password value)

    Image Added

  3. Click Add to finish adding the property.

Image Added

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.

...

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 Admin Portal (https://<Server Host>:9443/admin) as the tenant admin and browse Application Creation menu to see all approval tasks have been created for newly created applications. 

Image RemovedImage Added