IBM Cloud Orchestrator, Version 2.5.0.2

Launching an offering through Offering REST API

There are two ways of launching an offering. In both cases, you need to know the offering ID of the offering to launch. You can either use the user interface or pass the data directly with the initial request.

An offering can be retrieved by listing the offerings by using a GET request on the offerings:

GET https://<ico_server_fqdn>:443/orchestrator/v2/offerings

The ID attribute on each offering contains the offering ID.

The offering does not require any input data. In this case, you can start the offering by performing a POST request on the offering you want to launch.
```
POST https://<ico_server_fqdn>:443/orchestrator/v2/offerings/<offering-id>/launch
```
The offering does require more input data. In this case, you must decide whether you want to use the IBM® Cloud Orchestrator User Interface to gather that data and start the process, or if you provide the data as part of the launch request.

Using the User Interface

If you want to use the IBM Cloud Orchestrator User Interface you must perform the following steps:

Issue the call to initiate the offering by performing the post request:
```
POST https://<ico_server_fqdn>:443/orchestrator/v2/offerings/<offering-id>/launch
```
with the following header:
```
"Content-Type" : "application/json"
```
and POST body containing the string {} (for an empty JSON object).
In the JSON response of that request find the redirect attribute that contains the path to launch the IBM Cloud Orchestrator User Interface for the offering. For example:
```
"redirect":"\/teamworks\/executeServiceByName?processApp=SCONOVA
&serviceName=Deploy+Single+Virtual+Machine&tw.local.operationContextId=3059"
```
Launch the User Interface (which is the Human Service of the offering) with the URI from the previous step by running the following request (on one line):
```
GET https://<ico_server_fqdn>:443/teamworks/executeServiceByName?processApp=SCONOVA
&serviceName=Deploy+Single+Virtual+Machine&tw.local.operationContextId=3059
```
After the data is filled in, the business process of the offering is started automatically.

Pass the data directly with the initial request

Offerings started this way cannot have a human service configured. If the offering has a human service that is configured, create a new one by using the same process as the original offering, with no human service configured. Creating such an offering can be done in the IBM Cloud Orchestrator Self-Service Configuration User Interface. To start the offering, you must do the same POST request as in the other option for creating an offering:

POST https://<ico_server_fqdn>:443/orchestrator/v2/offerings/<offering-id>/launch

You must also provide a POST body in that request describing the InputParameterObject that is passed into the process. Pass the body a JSON document in this format:

{"parm":{"OperationParameter":
      "<variable type=\"Sample_BusinessObject\">       
<field1 type=\"String\"><![CDATA[Hello]]><\/field1>      
<field2 type=\"String\"><![CDATA[Phone]]><\/field2> <\/variable>"}}

The OperationParameter is the serialized form of the related Business Process Manager business object as returned by the Business Process Managertw.system.serializer.toXML(tw.local.inputParameterObject)

The following methods are some ways of finding out more about the input parameter data type of the process you want to launch. If you need to inspect parameters of the offering workflow, the following methods can be performed:

Use REST interface for IBM Cloud Orchestrator to retrieve details of a registered offering:
```
GET https://<ico_server_fqdn>:443/orchestrator/v2/offerings/<offering-id>
```
In this data you can find:
process

The name of theBusiness Process Manager process that is bound to the offering.

process_app_id

The ID of the Business Process Manager application in which the process is defined.

For details, refer to GET entries for a specific self-service offering.

Use REST Interface for Business Process Manager - related resources to get details about exposed items:

GET https://<ico_server_fqdn>:443/rest/bpm/wle/v1/exposed

Find the process with display=process and processAppID=process_app_id.

  {"status":"200", "data":{ "exposedItemsList":[ { "type":"process", 
    "itemID":"25.8403dd37-e049-46f5-8952-b7a46f0d198f", 
    "processAppID":"2066.931b0053-02bd-4f47-ac72-4eb527457383", 
    "snapshotID":"2064.73dd1d1a-b533-46ef-ba79-c94cb3b0de87", 
    "snapshotName":"version 2.8.1", 
    "display":"HR Open New Position", "ID":"2015.204" }

For more information, see REST interface for BPD-related resources - Exposed Items Resource in the IBM Business Process Manager Knowledge Center.

Use REST Interface for Business Process Manager-related resources to get details about the process model:
```
GET  https://<ico_server_fqdn>:443/rest/bpm/wle/v1/processModel/{bpdId}?processAppId={string}&parts=dataModel
```
Use parts=all for more information about the process. Find the process with itemID=process and processAppID=process_app_id:
```
{ "status":"200", "data":{ …, "DataModel":{ …} } }
```
For more information, see REST interface for BPD-related resources - Process Model Resource - GET Method in the IBM Business Process Manager Knowledge Center.

Sample Output:

Getting the type of the inputParameterObject. Getting the type detailed information, here the parameters to that service are two string parameters that are named field1 and field2.

{  "status" : "200",
  "data" : {
  "DataModel" : {
  "properties" : {  "message" : { "type" : "String", "isList" : false },
  "returnFromRest" : { "type" : "String", "isList" : false }
  },
  "inputs" : {
  "operationContext" : { "type" : "OperationContext", "isList" : false },
  "inputParameterObject" : { "type" : "Sample_BusinessObject", "isList" : false }
  },
  …
  "Sample_BusinessObject" : {
  "properties" : { "field1" : { "isList" : false, "type" : "String“ },
                   "field2" : { "isList" : false, "type" : "String“ }
  },
  “type" : "object",
  "ID" : "12.2c079fa7-89a0-426c-a3c1-079be08930ac",
  "isShared" : false
  },

Getting an example for the input parameter payload

To get an example of the input parameter payload, trigger a request through the IBM Cloud Orchestrator and query the input parameters of the request. It might either be still running or finished. You must retrieve the request ID and retrieve the input parameters for that request.

To get the request ID, select the triggered request in REQUESTS and note the request ID as listed in the address bar.
Using the REST call to retrieve details about the request, use:
```
GET https://<ico_server_fqdn>:443/kernel/tasks/{request-id}
```

Within the response, search for Operation Parameter. The following is a sample excerpt:

"OperationParameter" : "<variable type=\"MyRequest\"
 <vpmoNumber type=\"Integer\"><![CDATA[116560]]><\/vpmoNumber>
 <appId type=\"Integer\"><![CDATA[19073]]><\/appId>
 <attuidNo type=\"String\"><![CDATA[dw945f]]><\/attuidNo>
 <serverType type=\"NameValuePair\">
 <name type=\"String\"><![CDATA[Test]]<\/name>
 <value type=\"String\"><![CDATA[T]]&gt;<\/value>
 <\/serverType>

Getting information on a request

Once a request is started the IBM Cloud Orchestrator system can be queried for the actual status of that request. This is done by using the REST call:

GET https://<ico_server_fqdn>:443/kernel/tasks/{id}

The response contains information about the status of the request. For details on possible values, refer to GET entries for a specific task. Sample response (excerpt) from

REST GET https://<ico_server_fqdn>:443/kernel/tasks/{id}

{
  "updated_iso" : "2014-02-19T17:54:15+0100",
  "description_message" : "PROCESS_COMPLETE",
  "domain" : "Default",
  "created" : 1392828461580,
  "error" : { ... },
  "serviceInstance" : {
  "virtualMachines" : [{
  "memory" : 4096,
  "hypervisorid" : "\/resources\/hypervisors\/PM-1",
  "hostname" : "SC-192-168-0-103.RegionOne.example.com",
  ....
  }
  ],
  ....
  },
  "user" : "admin",
  "parm" : {
  "startPlanByPlugpointEventHandler" : "done",
  "CUSTOM_PARM1": "abc",
  "CUSTOM_PARM2": "xyz",
  "OperationParameter" : "<variable ...<\/variable>",
 "serviceInstanceId" : "282",
  "plan" : { ... },
  "processId" : "1356"
  },
  "created_iso" : "2014-02-19T17:47:41+0100",
  "status_localized" : "TASKSTATUS_COMPLETED",
  "error_message" : "BPM_PROCESS_COMPLETE",
  "status" : "COMPLETED",
  "eventTopic" :  "com\/ibm\/orchestrator\/serviceinstance\/plan\/ibm_bpm_process",
  "delayInSeconds" : 30,
  "project" : "admin",
  ...
  }
  }