• ⌂ Web Services
• Access
• Authentication
• Services
• Common Response Properties
• Response Event Log
• Services
  • Capabilities
  • Login
  • Logout
  • Get
  • Put
  • Attach
  • Delete
  • Search
  • Process

COMAND Web Services

COMAND Web Services provide programmatic access to a COMAND Repository over the web.  Requests and responses use JSON.

Access

If enabled, COMAND Web Services are accessed from a base URL like:

https://<account>.webcomand.com/io_comand_webservice/

An alias is typically also available at a URL like:

https://<account>.webcomand.com/ws/

If enabled, requests to URLs like the ones above should produce the following response.

{
    "type": "COMAND",
    "version": "1.0",
    "time": "2016-06-04T12:00:00-04:00",
    "source": "https://<account>.webcomand.com/ws/",
    "status": false,
    "log": [{
        "timestamp": "2016-06-04 12:00:00",
        "type": "Error",
        "message": "An internal error has occurred: No web service specified."
    }]
}

To access a web service, add the service name to the end of the URL.  For example:

https://<account>.webcomand.com/ws/capabilities

In addition to the service name, most web services also require authentication.

Authentication

Websites and applications can authenticate using one of these methods.

• User Token
• Login Web Service
• OAuth

User Token

A User Token is the simplest way to authenticate a web service request.  A User Token is basically an additional password associated with a User, which may be restricted to a specific period of time and easily revoked or updated without affecting or revealing the User's login password.  A User Token can be created manually in webCOMAND, or programmatically with the API.  To create a User Token in webCOMAND:

• Launch Content Manager
• Click "System" or another desired folder in the folder tree on the left
• Click the New menu () in the collection bar on the right
• Select "User Token"
• Select a User with appropriate authorizations
• Enter a valid Token (32-64 letters and numbers, preferably randomly generated)
• Optionally, enter a Valid Start and/or Valid End time
• Check Active
• Click Approve

Once a valid User Token is created, an HTTP request can pass the token with each web service request using any of the following methods.

• HTTP Authorization Header - Authorization: Token <token>
• HTTP Cookie Header - Cookie: token=<token>
• POST Data - token=<token>
• JSON Top-Level Key/Value - "token": "<token>" (see cJSON)
• GET Query Parameter - https://<account>.webcomand.com/ws/get?token=<token>

For example, the following URL will authenticate against a User Token "W5IhFMzXfY9VAmeJ2MN9":

https://<account>.webcomand.com/ws/get?token=W5IhFMzXfY9VAmeJ2MN9

Services

The following Web Services are typically available, and may be specified after the base URL.

• Capabilities – Get the server version and available services.
• Login – Establish a session as a specific user, which is used to determine authorizations. A session ID (and optional browser cookie) is returned for use with subsequent requests.
• Logout – End/invalidate a session previously established with the Login service. An error will be returned for subsequent requests that reference the invalidated session.
• Get – Retrieve objects and their field values from the repository.
• Put – Create and/or update one or more objects in the repository.
• Attach – Define an object field value for a Put transaction. Useful for building a set of field values over a series of requests, and to "attach" files and other binary field values to a Put request.
• Delete – Remove one or more existing objects from the repository.
• Search – Retrieve objects from the repository based on a keyword search.
• Process – Process cScript code on the server and return the result(s).

Common Response Properties

Most Web Service responses share the following common properties, in addition to the service-specific properties documented for each service listed above.

• type: 'COMAND' – Indicates a COMAND Web Service response.
• version: '3.0.0' – Indicates the COMAND Web Service version.
• time: 'YYYY-MM-DDTHH:MM:SS-ZZ:ZZ' – Timestamp response was created.
• source: 'URL' – URL of the web service that produced the response.
• request: 'query string' – Portion of the web service request URL that came after the source URL, including query string.  This property may not be in the response if no query string was provided.
• status: true | 'error' – true = success, string = error message
• log - Array of event log objects with the properties below.  If no events are returned, this property will not be defined.
  • time: '<timestamp>' – Timestamp that represents when the message was produced, in a format that can be passed to JavaScript's Date constructor.
  • type: 'Error' | 'Warning' | 'Note' | 'Text' – Type of message.
  • text: '<string>' – Text message as a plain-text string.
• session: '<session>' – The session ID to use for a subsequent request. If the session was obtained from a cookie, the response may also update the session ID in the cookie with a Set-Cookie header.  Changing session IDs improves security and awareness of man-in-the-middle attacks.

asTask

Responses to requests that set the optional asTask property to true will include the following properties.  A system task will be started to perform the request and the response will be returned immediately with the OID and UUID for the system task, so it can be monitored with the Get service.

• task_oid: oid – OID of the System Task object that represents the process started by the request.
• task_uuid: 'uuid' – UUID, in string format, of the System Task object that represents the process started by the request.

Debug

Responses to requests that set the optional debug property to true will include the following properties.

• title: '<service>' – Name of the web service that produced the response.
• description: '<description>' – Description of the web service that produced the response.
• executionTime: <seconds> – Decimal number representing the number of seconds taken to process the request on the server after the request was received and before the response was sent (ie. excluding transfer time, which can be determined on the client-side).
• eventLog: {eventLog} – eventLog object will contain the properties below.
  • numErrors: n – Total number of error messages in this log.
  • numWarnings: n – Total number of warning messages in this log.
  • numNotes: n – Total number of note messages in this log.
  • numText: n – Total number of text messages in this log.
  • messages[] – An array of messageObjects with the properties below.
    • time: '<timestamp>' – Timestamp that represents when the message was produced, in a format that can be passed to JavaScript's Date constructor.
    • type: 'Error' | 'Warning' | 'Note' | 'Text' – Type of message.
    • text: '<string>' – Text message as a plain-text string.
    • messages[] – An array of messageObjects under this message.

Response Event Log

The response object's eventLog property can be displayed as an HTML bullet hierarchy (similar to how they are displayed in the webCOMAND alert bar and publish reports) with the following JavaScript.

function log_to_html(log) {
	var output = '';
	var type = ({}).toString.call(log).match(/\s([a-zA-Z]+)/)[1].toLowerCase();
	if(type == 'array') {
		output += '<ul>';
		for(var i in log) {
			var msg = log[i];
			output += '<li>[' + msg.time + '] <span class="' + msg.type + '">' + msg.type + ':</span> ' + msg.text + (msg.messages ? log_to_html(msg.messages) : '') + '</li>';
		}
		output += '</ul>';
	} else if(type == 'object') {
		output += log_to_html(log.messages) + 'Totals: ' + log.numErrors + ' Errors, ' + log.numWarnings + ' Warnings, ' + log.numNotes + ' Notes';
	} else {
		output = 'Invalid response log.';
	}
	return output;
}

• < API Reference
• Capabilities >