Integrating Launch
HTTP Interface
| Method |
URL |
Description |
| GET |
/mdworkbench/launch |
Provides access to the launch queue, i.e. the ordered list of launches being executed or waiting to execute.
@Since 2.2.0
Request Query Parameters
kind (optional): filters the launches by implementation type of the underlying service.
Value can be RULESET or OPERATION.
If not set, all launches are returned.
@Since 2.3.0
Request Header
Authorization: credentials of an administrator user set as Basic authentication.
It is highly recommended that the server is handling HTTPS only when using this servlet.
Accept (optional): the media type which is acceptable for the response.
Values can either be application/json (default) or application/xml.
Response Status
200: administrator is authenticated and the response body contains launches information.
401: Authorization request header is not present or its content is rejected.
403: the credentials set as Authorization request header is recognized
but does not match an mdw-admin user.
Response Header
Content-Type: the media type of the response content.
Values can either be application/json (default) or application/xml.
Response Body
An list of JSON or XML nodes:
id: id of the launch.uri: uri of the launch (i.e. the request uri).service: id the of the launched service.state: execution state: waiting, running, canceled.requestNumber: number associated with this launch.
This number is intended to facilitate the visual identification of a launch by an administrator.
It is not guaranteed to be unique for the lifetime of the web application.
It is not meant to be used for any programmatic identification nor to be used in web servicesrequestTime: date at which the service execution was requested.
Differs from the actual execution start time, as the launch might be enqueued before its execution is started.
The date format is ISO 8601.startTime: date at which the launch has been started. The date format is ISO 8601.
The launch queue returns only running and waiting launches.
It provides only a summary of launches information.
To get more details on a particular launch, refer to the /mdworkbench/launch/<id> servlet.
|
| GET |
/mdworkbench/launch/<id> |
Provides access to the details of a launched service
Request URL Path
<id>: must be a valid launch identifier.
Developers should not assemble a launch URL but use as-is the Content-Location
information provided by the POST response.
Request Header
Accept (optional): the media type which is acceptable for the response.
Values can either be application/json (default) or application/xml.
Response Status
200: the response body contains launch information.
404: no launch matches the launch identifier set in the URL path.
Response Header
Content-Type: the media type of the response content.
Values can either be application/json (default) or application/xml.
Response Body
A JSON or XML node:
id: id of the launch.uri: uri of the launch (i.e. the request uri).service: id the of the launched service.state: execution state: waiting, running, completed, failed, canceled.requestNumber: number associated with this launch.
This number is intended to facilitate the visual identification of a launch by an administrator.
It is not guaranteed to be unique for the lifetime of the web application.
It is not meant to be used for any programmatic identification nor to be used in web servicesrequestTime: date at which the service execution was requested.
Differs from the actual execution start time, as the launch might be enqueued before its execution is started.
The date format is ISO 8601.startTime: date at which the launch has been started. The date format is ISO 8601.endTime: date at which the launch has been terminated (either cancelled, failed, or succeeded). The date format is ISO 8601.duration: the duration of the launch. The duration format is ISO 8601.arguments: an array of nodes, each one describing an argument of the launched servicestatus: an array of nodes, each one describing a status property.
Each status node has the following attributes:
name - the name of the status property.value - the value of the status property.
logEntries: an array of nodes, each one describing a log message.
Each log node has the following attributes:
kind - the king of log: progress, output, warning, error.message - the logged message.time - date at which the log entry has been created. The date format is ISO 8601.duration - the duration of the launch at the moment this log entry has been created. The duration format is ISO 8601.
result: this node exists if at least one file is generated by the service execution.
The uri attribute provides access to a zip file containing all generated files (see Storage).
The files node contains an array of generated files, each one having those attributes:
path - relative path of the generated fileuri - uri of the generated data (see Storage).
|
| POST |
/mdworkbench/launch |
Requests the execution of a service
Query Parameters
id: if of the service whose execution is requested.
Request Headers
Content-Type: multipart/form-data (fixed)Status-Location (optional): URL of the launch requestor to get a launch status notification.
When the launch is terminated (execution is either canceled, completed or failed),
a POST request is sent to this Status-Location URL.
The content of the POST request is the same as the content of the GET response on the launch.
Request Body
If the service declares parameters, there must be a launch argument set for each service parameter.
The body must be a form data where each form field name must match the corresponding service parameter name.
Note on request headers
Headers might be used to send service parameters instead of putting those as request body.
The name of each header must match the corresponding service parameter name.
In this case, the Content-Type header is not mandatory.
Response Status
200: the launch was successfully created.
503: the server is in maintenance and a launch cannot be created.
Response Headers
Content-Location: the URL that can be used to query the launch details (see GET) or to cancel the execution (see DELETE).
|
| PUT |
/mdworkbench/launch |
Reorders the launch queue
@Since 2.2.0
Query Parameters
id: id of the launch to reorder in the queue.
You might use multiple id parameters if multiple launches are to reorder at once.direction: the direction in which the queue shall be reordered:
top: specified launches are moved to the top of the queue, just right after launches being currently executed.up: specified launches are moved one place up in the queue.down: specified launches are moved one place down in the queue.bottom: specified launches are moved at the bottom of the queue.
Request Header
Authorization: credentials of an administrator user set as Basic authentication.
It is highly recommended that the server is handling HTTPS only when using this servlet.
Response Status
200: administrator is authenticated and the queue has been reordered.
400: the direction parameter is not set or is invalid, or no launch matches the specified launch identifier.
401: Authorization request header is not present or its content is rejected.
403: the credentials set as Authorization request header is recognized
but does not match an mdw-admin user.
|
| DELETE |
/mdworkbench/launch/<id> |
Cancels the execution of a launched service
Request URL Path
<id>: must be a valid launch identifier.
Developers should not assemble a launch URL but use as-is the Content-Location
information provided by the POST response.
Response Status
200: the launch has been canceled.
404: no launch matches the launch identifier set in the URL path.
|
Using the HTTP Interface
Launching a Service Execution
The developer must identify the service that is to be executed.
The id is explicitly declared by the service owner in the corresponding plugin.xml file.
The id is visible using the GET request on Service HTTP interface.
The developer must also identify the service expected arguments,
which are also declared in the plugin.xml file and visible in the Service HTTP GET interface.
The developer must then send a POST request with a "multipart/form-data" Content-Type header.
The POST body must contain a form data where each form field matches a service parameter name
and whose value is used as launch argument.
The POST request replies with a Content-Location header that references the URL of the Launch,
which the developer can then query to get information on the state of the execution.
Refreshing the Service Execution State
The developer shall periodically send a GET request on the executed service URL (obtained when posting a service execution)
to get details on the execution state, as long as the execution is not terminated nor cancelled.
Get Notification when the Launch is Terminated
Instead of querying periodically the launch state using the GET request,
the developer might want to be directly notified when the launch is terminated.
A Status-Location header can be set on the launch POST request.
When the launch is completed (execution is cancelled, completed or failed),
a POST request is automatically sent to this Status-Location URL.
The content of the POST request is the same as the content of the GET response on the launch.
Launch
Service
Storage
Configuring Administration
Administering Launch
Integrating Service
Integrating Storage
Adding a Custom Launch Page