Subscribing an Application to API

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 change theSubscriptionCreation executor from "SubscriptionCreationSimpleWorkflowExecutor" to "SubscriptionCreationWSWorkflowExecutor" in the <AM_HOME>/repository/conf/api-manager.xml (see below).

<!--SubscriptionCreation executor="org.wso2.carbon.apimgt.impl.workflow.SubscriptionCreationSimpleWorkflowExecutor"/-->
<SubscriptionCreation executor="org.wso2.carbon.apimgt.impl.workflow.SubscriptionCreationWSWorkflowExecutor">
     <Property name="serviceEndpoint">https://localhost:9444/services/SubscriptionCreationWorkflow</Property>
     <Property name="username">admin</Property>
     <Property name="password">admin</Property>
     <Property name="callbackURL">https://localhost:8243/services/WorkflowCallbackService</Property>
</SubscriptionCreation>

When making this change you need to specify the service endpoint at which the Workflow Engine is hosted along with the credentials required to access said service via Basic Authentication (i.e. username and password).

Note : If you wish to write your own logic for executing the BPEL workflow, you can do so by extending the WorkflowExecutor abstract class and overriding the execute() and complete() methods. After changing the configs, API Manager needs to be restarted for the changes to take effect.

By default API Manager is shipped with a sample BPEL and HumanTask for subscription-creation process.Additionally a jaggery based web application called 'workflow-admin' also ship with APIManager which provides a GUI for pending human tasks created by the default BPELs and Human Tasks in APIManager. To browse subscription creation based BPEL and Human Task, navigate to {AM_Home}/business-processes/subscription-creation.To get more information on running these BPELs,Human Tasks and the web application 'workflow-admin',follow the readme.txt which can be found from {AM_Home}/business-processes location.

Invoking the Workflow Engine

Once the SubscriptionCreationSimpleWorkflowExecutor is engaged, whenever a user tries to subscribe to an API with an application, in the API Manager Store, a request of the following format will be sent to the Workflow Endpoint (You may refer the wsdl here when implementing your custom Workflow Service) specified under "serviceEndpoint" in the API Manager.xml.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:wor="http://workflow.subscription.apimgt.carbon.wso2.org">
   <soapenv:Header/>
   <soapenv:Body>
      <wor:createSubscription>
         <wor:apiName>sampleAPI</wor:apiName>
         <wor:apiVersion>1.0.0</wor:apiVersion>
         <wor:apiContext>/sample</wor:apiContext>
         <wor:apiProvider>admin</wor:apiProvider>
         <wor:subscriber>subscriber1</wor:subscriber>
         <wor:applicationName>application1</wor:applicationName>
         <wor:tierName>gold</wor:tierName>
         <wor:workflowExternalRef></wor:workflowExternalRef>
         <wor:callBackURL>?</wor:callBackURL>
      </wor:createSubscription>
   </soapenv:Body>
</soapenv:Envelope>

A detailed explanation of each property is as follows.

Property	Description
apiName	Name of the API to which subscription is requested
apiVersion	Version of the API, user wishes to subscribe to
apiContext	Context on which the requested API is to be accessed on
apiProvider	Provider of said API
subscriber	Name of the User requesting the subscription
applicationName	Name of the application through which the user wishes to subscribe to the API
tierName	Thorrtling tier specified for the application
workflowExternalRef	The unique reference against which a workflow will be tracked. This will need to be sent back from the Workflow Engine to API Manager at the time of workflow completion.
callBackURL	At the time of workflow completion, this is URL to which the "Workflow completed" request will be sent to by the Workflow Engine. This property is configured under the "callBackURL" property in the api-manager.xml (Can be either a SOAP or REST endpoint)

In addition to invoking the Workflow Engine, at the time of executing a Workflow an entry will be added to the AM_WORKFLOWS table in the API Manager Database, indicating the workflow status and workflow external reference along with a host of other information. This entry in turn will be used to track the progress of the workflow throughout its lifecycle. At a given time, the status of a workflow can be either 'CREATED', APPROVED' or 'REJECTED'. 'CREATED' is the default status of a workflow, it will get promoted to either 'APPROVED' or 'REJECTED' state based on the response from Workflow Engine.

Note : A user may maintain any number of states/steps for a workflow in between the CREATED and APPROVED / REJECTED states inside the Workflow Engine. API Manager will only acknowledge the CREATED / REJECTED states.