Workflow: API Subscription

Usecases of the API subscription workflow:

To enable throttling tiers to an API that consumers cannot choose at the time of subscribing. Only admins can set these tiers to APIs.
To restrict API consumers to only subscribe to sandbox, and then go through an approval process to go to the next level of subscription.

Two types of workflow executors come with the API Manager by default:

Simple Workflow Executor : Subscribes to an application without an approval (default option).
WS Workflow Executor :
- Invokes an external Web service when subscribing to an API and the subscription process completes based on the output of the Web service.
- When an API subscription workflow is engaged, user requests for new subscriptions go into a temporary On Hold state where they remain until approved or rejected by the workflow administrator.

Enabling and engaging WS Workflow Executor

First, enable the API subscription workflow.

Log in to APIM admin console (https://<Server Host>:9443/carbon) and select Browse under Resources.

Go to /_system/governance/apimgt/applicationdata/workflow-extensions.xml resource and edit the file as follows to disable the Simple Workflow Executor and enable WS Workflow Executor of SubscriptionCreation executor:

<!--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>

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).
To write your own logic for executing the BPEL workflow,
- Extend the WorkflowExecutor class and override the execute() and complete() methods
- Restart server to apply the changes
By default, API Manager comes with,
- A sample BPEL and Human Task for subscription-creation workflow
- A Jaggery-based Web application named workflow-admin to provide a GUI for pending Human Tasks that are created by the default BPELs and Human Tasks.
To browse the application creation workflows that are based on BPEL and Human Task, go to <AM_HOME>/business-processes/subscription-creation. Also see <AM_HOME>/business-processes/readme.txt for more information.

After the subscription creation WS Workflow Executor is engaged, whenever a user tries to subscribe to an API with an application, a request of the following format is sent to the workflow endpoint:

See the WSDL here when implementing a custom workflow service.

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

Elements of the above configuration are described below:

Element	Description
apiName	Name of the API to which subscription is requested.
apiVersion	Version of the API the user subscribes to.
apiContext	Context in which the requested API is to be accessed.
apiProvider	Provider of the API.
subscriber	Name of the user requesting subscription.
applicationName	Name of the application through which the user subscribes to the API.
tierName	Throttling tiers specified for the application.
workflowExternalRef	The unique reference against which a workflow is tracked. This needs to be sent back from the workflow engine to the API Manager at the time of workflow completion.
callBackURL	The URL to which the Workflow completion request is sent to by the workflow engine, at the time of workflow completion. This property is configured under the callBackURL property in the api-manager.xml (Can be either a SOAP or REST endpoint)

Also, when executing a workflow, an entry is added to the AM_WORKFLOWS table in the API Manager Database, indicating the workflow status and workflow external reference along with other information. This entry is used to track the progress of the workflow throughout its lifecycle. At a given time, the status of a workflow can be CREATED, APPROVED or REJECTED. CREATED is the default status of a workflow. It gets promoted to APPROVED or REJECTED, based on the response from the workflow engine.

You can maintain any number of states/steps for a workflow in between the CREATED and APPROVED/REJECTED states inside the workflow engine. The API Manager only acknowledges the CREATED/REJECTED states.