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:
with the following header:POST https://<ico_server_fqdn>:443/orchestrator/v2/offerings/<offering-id>/launch
and POST body containing the string {} (for an empty JSON object)."Content-Type" : "application/json"
- 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):
After the data is filled in, the business process of the offering is started automatically.GET https://<ico_server_fqdn>:443/teamworks/executeServiceByName?processApp=SCONOVA &serviceName=Deploy+Single+Virtual+Machine&tw.local.operationContextId=3059
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:
In this data you can find:GET https://<ico_server_fqdn>:443/orchestrator/v2/offerings/<offering-id>
- 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.
- Use REST Interface for Business Process Manager -
related resources to get details about exposed items:
Find the process with display=process and processAppID=process_app_id.GET https://<ico_server_fqdn>:443/rest/bpm/wle/v1/exposed
For more information, see REST interface for BPD-related resources - Exposed Items Resource in the IBM Business Process Manager Knowledge Center.{"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" }
- Use REST Interface for Business Process Manager-related
resources to get details about the process model:
Use parts=all for more information about the process. Find the process with itemID=process and processAppID=process_app_id:GET https://<ico_server_fqdn>:443/rest/bpm/wle/v1/processModel/{bpdId}?processAppId={string}&parts=dataModel
For more information, see REST interface for BPD-related resources - Process Model Resource - GET Method in the IBM Business Process Manager Knowledge Center.{ "status":"200", "data":{ …, "DataModel":{ …} } }
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]]><\/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",
...
}
}