Initiate a Work Order

Description:

This API method provides a way to initiate a new work order for a given workflow. If the call is successful, a work order ID is returned . The work order ID can be used to subsequently track the execution status of that work order. Note that if this workflow has sub-workflows, they can not be monitored using the API as only the parent work order ID is returned.

The request can be either asynchronous or synchronous. If asynchronous, it will return as soon as the work order is created. If synchronous, it will return after a specified step in the workflow is executed. The response can be in either XML or JSON format.

Note: The account specified in the login section of the URL must be part of the Orchestrator Operator group and the account must have run permission on the workflow.
If the workflow has run-time inputs, they can be specified in the URL with the following notation:
external_parameters[name_of run-time input-n]=value of run-time input-n
Usage for an asynchronous request with an XML response:
http://Orchestrator_IP_address/aspera/orchestrator/api/initiate/xml?login=admin&password=aspera&work_order[workflow_id]=workflow_id&external_parameters[name_of run-time input1]=value of run-time input1&external_parameters[name_of run-time input-n]=value of run-time input-n
The required input parameter is the following:
work_order[workflow_id]=integer
Indicates that the work order is launched with a dedicated worker process.
The optional input parameters are the following:
work_order[higherPriority]=on
Specifies the workflow ID as can be obtained in Orchestrator workflow editor.
preemptive_level=integer
Indicates a preemptive priority with the specified integer as the level of preemption (lowest goes first).
work_order[priority]=integer from 1 → low to 3 → high
Specifies the priority level for that work order.
work_order[name]=string
Specifies a name for the work order replacing the generated default name that is based on the workflow name.
external_parameters[param_name]=string
Specifies a name for a parameter to be passed as runtime input to the workflow. The name entered for param_name must match the name defined in the workflow as runtime input. Multiple external parameters can be passed, each one separated by the character "&".
For example:
http://localhost/aspera/orchestrator/api/initiate/xml?login=admin&password=aspera&work_order[workflow_id]=1
Response example (XML):
<?xml version="1.0"?>
<work_order time="2014-11-25 13:24:01 UTC" action="initiate" id="8464" workflow_id="1">
   <work_order_id>8464</work_order_id>
   <name>create file</name>
   <workflow id="1" revision_id="14">create file</workflow>
   <status state="Created">WorkOrder created at Tue Nov 25 07:24:01 CST 2014</status>
   <comments/>
   <parameters></parameters>
   <ownership>
      <initiated_by>admin</initiated_by>
      <running_as>system</running_as>
      <launched_by>admin</launched_by>
   </ownership>
   <priority dedicated_worker="false"/>
   <work_steps></work_steps>
</work_order>
Note: The error code 400 Bad Request is returned if a mandatory input parameter is absent from the initiate work order request.

If an HTTP POST method is issued, the body can be any user-defined XML data. In this case, the workflow must expect the XML payload with a run-time input defined as Raw_post_body and the first step must be the one parsing the data. For example:



Usage for an asynchronous request with JSON response:
http://Orchestrator_IP_address/aspera/orchestrator/api/initiate/workflow_id.json?login=admin&password=aspera&external_parameters[name_of run-time input1]=value of run-time input1&external_parameters[name_of run-time input2]=value of run-time input2
For example:
http://localhost/aspera/orchestrator/api/initiate/1.json?login=admin&password=aspera&external_parameters[foo]=bar
Sample returned JSON:
{
   "work_order":    {
      "workflow_revision_id": 14,
      "name": "create file",
      "initiate_date": null,
      "forkedAt": null,
      "derivedFrom": null,
      "workflowName": "create file",
      "created_at": "2014-11-25T13:25:18Z",
      "cleanup_after_days": null,
      "monitor_id": null,
      "comments": null,
      "updated_at": "2014-11-25T13:25:18Z",
      "priority": null,
      "max_running": 0,
      "master_id": 8465,
      "launched_by": 1,
      "initiatedBy": 1,
      "branchedFrom": null,
      "statusDetails": "WorkOrder created at Tue Nov 25 07:25:18 CST 2014",
      "purge_after_days": null,
      "id": 8465,
      "workflow_id": 1,
      "branchedFromOrder": null,
      "higherPriority": null,
      "completion_date": null,
      "status": "Created",
      "running_as": 2
   },
   "parameters": [],
   "work_steps": []
}

Usage for a synchronous request with XML response:

This call will create a work order. A variable name can be specified to get an output variable value. Only the variable value is returned in the output, without the long-form XML wrapper around the variable.
http://Orchestrator_IP_address/aspera/orchestrator/api/initiate/xml?login=admin&password=aspera&work_order[workflow_id]=workflow id&external_parameters[name_of run-time input1]=value of run-time input1&external_parameters[name_of run-time input-n]=value of run-time input-n&synchronous=true&explicit_output_step=step_name&explicit_output_variable=variable_name
For example:
http://localhost/aspera/orchestrator/api/initiate/xml?login=admin&password=aspera&work_order[workflow_id]=1&external_parameters[foo]=bar&synchronous=true&explicit_output_step=create xml content&explicit_output_variable=Generated_file_content
Sample returned value:
hello