• ⌂ Web Services
• Services
  • Capabilities
  • Login
  • Logout
  • Get
  • Put
  • Attach
  • Delete
  • Search
  • Process

Put Web Service

Create and/or update one or more objects in the repository.

Request

The request options and data can be sent in cJSON format in the POST request body if the "Content-Type: application/json" request header is sent.  Otherwise the options below must be sent as application/x-www-form-urlencoded or multipart/form-data form parameters.  For information about encoding form parameters, see POST on MDN.

• parent: <OID> | "<UUID>" | "<cPath>" | "<cQL>" - Optional OID, UUID, cPath or cQL query to specify the parent collection the new object(s) should be created under.  The object should resolve to a Folder or collection object field (the collection object field must be specified as the final cPath element or the only field in the cPath or cQL SELECT clause).  The collection must be compatible with the content type of the new objects, in that new objects must equal or extend the field type.
• data - The objects to create/update, in cJSON format, as provided by Content Manager Export and API Export.
  • type - Always "COMAND", which indicates cJSON format. This is required for validation.  In the future, MIME Types may be supported.
  • version - Always "1.0" for now.  Indicates COMAND and cJSON format.  Future version numbers may be introduced if the specification changes.
  • source - Optional URL to the COMAND repository web service or folder that hosts this file and/or objects.  A web service consumer may request additional information from the host at this URL.
  • repository - Optional UUID of the repository (root object).  If a repository is specified, OID and DOID will be used to match on existing content to determine if existing content should be updated (an object with the OID/DOID exists) or new content should be created (an object with the OID/DOID doesn't exist).
  • time - Optional time objects were queried in ISO 8601 "YYYY-MM-DD HH:MM:SS +HHMM" format.
  • title - Optional title for the contents. For informational purposes only.
  • description - Optional summary of the purpose of contents.
  • contents: {} | [] – An object or array of objects with multiple field/value pairs. Each object can contain the following properties.
    • "<field identifier>": true | false | <N> | "<string>" | {type:"<type>", value:"<value>"} | {} | [{}, ...] – An object field and its value. The field identifier is the Identifier of any field defined by the object's content type. The value must be specified in one of the following formats and correspond to the field's type.
      • true | false | <N> | "<string>" – A boolean, number or string that corresponds to the field's data-type.  Binary data may be encoded as a JavaScript string, unless otherwise specified with the binaryFormat property.  When a field corresponds to a single object reference and a number or string value is provided, the following rules will be applied to find a match:
        • A number or string containing only a number will be assumed to be an OID of the object to reference.  This will only work if the source URL matches the destination, where the OIDs can be assumed to match the OIDs in the target repository.  If the OID does not match a valid object, a warning will be logged in the response.
        • A string containing a number immediately followed by a 'D' will be assumed to be a DOID.  Similar to an OID, this will only work if the source URL matches the destination, where the DOIDs can be assumed to match the DOIDs in the target repository.  If the DOID does not match a valid object, a warning will be logged in the response.
        • A string containing a UUID will be assumed to be a UUID.  This will work even if the source URL does not match the destination.  If the UUID does not match a valid object, a warning will be logged in the response.
        • A string containing an object key that is in the scope of the object's field location.  If multiple matches are found, the first will be used and a warning will be logged in the response.
      • {"type": "<type>", "value": "<value>"} – An object containing a single field Data Type value, where the value is interpreted based on one of the following types.
        • string - value is a string that may contain JavaScript string escape codes for non-ascii characters. For example, the string "\u0227" represents the UTF8 text ȧ. This format is automatically decoded by JavaScript, but is not very space efficient (1 to 3 times the size of the raw binary data).
        • base64 - value is a base64 encoded string
        • url - value is a URL to the resource that contains the value.  The URL may reference binary and long text data, and may be relative (to the source URL) or absolute.
        • attachment - value is an ID that correspond to the ID provided in the response to a previous Attach web service request.
      • object – Object or array of objects that follow the same format as the content property itself, including the _attach option.
      • reference – Object or array of objects that must each contain at least one uniquely Identifiable field, like { OID: <OID> }.
    • _MyID: <N> | "<string>" – Optional unique ID for this object, which can be used to reference this object from other object field values in the contents array.  For example, if a "_MyID" value of 1 is specified, that object can be referenced with the field value of {_MyID: 1} in other objects in the contents array to reference this object.  When a _MyID is specified, it will also be included in the corresponding "contents" object information in the response, which can be helpful for associating the new object OID, DOID or UUID back to the original data source.
    • _Dimension: <N> | "<string>" – Optional unique ID to represent this object across dimensions.  This is useful when the Put request includes multi-dimensional object data.  Object data for each dimension is associated with each other when they share the same "_Dimension" value.
    • _VersionNotes: "<string>" – Optional version notes to apply to this specific object addition or update.
    • _attach: <ID> | [<ID>, <ID>, ...] - An ID or array of IDs that correspond to the ID provided in the response to a previous Attach web service request.  All field/value associated with the specified attachments will be applied to this object, as if it were included here directly. Field/value pairs specified directly in this request will override attached field/value pairs.
• saveMethod: "approve" (default) | "save" | "store" – The method to use to create/update each object.  "approve" is the default and will cause the active/approved version of the object to be updated. "save" will cause a new draft version of the content to be added.  "store" will update the working copy version of the content.  An error will be returned if the user is not authorized to create or update the specified object and/or version. For example, a user may not be authorized to approve the specified content, so "approve" would result in an error.
• select: "field1, field2, ..." – Optional comma-separated list of top-level fields to including in the contents property of the response.  If not specified, OID, DOID, UUID, Type and _MyID (if provided in request) will be included.
• versionNotes: "<string>" – Optional version note to apply to all objects that do not override it with their own object-specific _VersionNotes.
• operation: "auto" | "insert" | "update" – Optional type of operation to perform. The default is 'auto', which will perform a create unless the query and object parameters can be used to definitively match an object already in the content repository. If an operation is specified, it will ensure only that type of operation is permitted. If insert is specified and the new object conflicts with an existing object (ie. another object with the same UUID exists), it will fail. If an update is specified and no existing object matches, it will fail.
• asTask: false | true – Perform the request as a background task and respond immediately with the corresponding System Task OID and UUID. This is useful for requests that may take time to process, such as certain format conversions. Use the Get service to monitor progress and retrieve results.
• session: "<session>" – Optional Login session. If it is not specified, the cookie will be checked for the session instead.
• token: "<token>" – Optional User Token.  If it is not specified, the cookie will be checked for the token instead.

Response

The response includes the following properties, in addition to the Common Response Properties.

• contents: [ {}, {}, ... ] - Array of objects that represent select information about each created or updated object.  By default, the OID, DOID, UUID, Type (Identifier) and _MyID (if provided in request) will be included.  However, the information can be customized with the select option.
• created: N – Number of top-level objects created, excluding embedded/referenced objects.
• updated: N – Number of top-level objects updated, excluding embedded/referenced objects.
• totalCreated: N – Number of top-level objects created, excluding embedded/referenced objects.
• totalUpdated: N – Number of top-level objects updated, excluding embedded/referenced objects.

Simple Object Example

$.ajax({
	url: 'https://<account>.webcomand.com/ws/put',
	data: {
        token: "<token>",
        parent: 123,
        data: {
            type: "COMAND",
		    version: "1.0",
		    contents: [
			    {
			    	Type: "Contact",
			    	Name: "John Smith",
			    	Phone: "716-555-5555"
    			}
	    	]
        }
	},
	success: function(data) {
		var object = data.contents[0];
        var op = (object.updated ? 'Updated' : 'Created');
		alert(op + ' Contact: OID=' + object.OID);
	},
	error: function(jqXHR, textStatus, errorThrown) {
		alert(textStatus + ': ' + errorThrown);
	}
});

Object References Example

$.ajax({
	url: 'https://<account>.webcomand.com/ws/put',
	data: {
        token: "<token>",
        parent: 123,
        data: {
            type: "COMAND",
		    version: "1.0",
		    contents: [
			    {
                    _MyID: 1,
			    	Type: {UUID: "e619ec32-1dbd-1e11-7b76-35357616a88b"},
			    	Name: "John Smith",
			    	Phone: "716-555-5555"
    			},
                {
                    _MyID: 2,
                    Type: {UUID: "e619ec32-1dbd-1e11-7b76-35357616a88b"},
                    Name: "Mary Smith",
                    Phone: "716-555-5555",
                    Father: {_MyID: 1}
                } 
	    	]
        }
	},
	success: function(data) {
        for(var i = 0; i < data.contents.length; i++) {
    		var c = data.contents[i];
	    	console.log('Contact OID=' + c.OID + ', _MyID=' + c._MyID);
        }
	},
	error: function(jqXHR, textStatus, errorThrown) {
		alert(textStatus + ': ' + errorThrown);
	}
});

Object Dimensions Example

The following request will create two versions of a single object for different languages, where Language is a Dimension field and the Language property values correspond to the language dimension object keys.

$.ajax({
	url: 'https://<account>.webcomand.com/ws/put',
	data: {
        token: "<token>",
        parent: "/Folder/cPath",
        data: {
            type: "COMAND",
		    version: "1.0",
		    contents: [
			    {
                    _Dimension: 1,
			    	Type: {UUID: "e619ec32-1dbd-1e11-7b76-35357616a88b"},
			    	Title: "Hello",
			    	Language: "en-US"
    			},
                {
                    _Dimension: 1,
                    Type: {UUID: "e619ec32-1dbd-1e11-7b76-35357616a88b"},
                    Title: "Bonjour",
                    Language: "fr-FR"
                } 
	    	]
        }
	},
	success: function(data) {
		var object = data.contents[0];
        var op = (data.created > 0 ? 'Created' : 'Updated');
		alert(op + ' contact: OID=' + object.OID);
	},
	error: function(jqXHR, textStatus, errorThrown) {
		alert(textStatus + ': ' + errorThrown);
	}
});

• < Get
• Attach >