API User's Guide

Creating objects

Description

The API provides the ability to create new Alloy Navigator object records via workflow Create Actions.

IMPORTANT: The API does not support Create Actions for Service Requests. To create Service Requests, use the "Submit Request" #131 Step Action, available for Service Catalog Items.

NOTE: Submitting an action form via an API request may feel different compared to what you'd normally expect in other modules of the product. The API supports only the default value and mandatory options of form fields. In some cases, the API will not return an error when you submit an action form with a mandatory field not filled. It happens if the field on the form is pre-populated with either a default value or its current value in the Object's record.

HTTP method

POST

API URL 
http://www.example.com/api/v2
POST parameters

POST parameters should be specified in the request’s body, in JSON format.

Parameter Description

ActionId

The ID of a workflow Create Action.

IMPORTANT: You can find Create Action IDs and Action Form fields in the desktop Settings App. In your Settings, go to Workflow and Business Logic > [Module]> [Object Class] > Workflow > Actions > Create Actions.

Fields

The fields from the Action Form the specified Create Action uses.

IMPORTANT: You can find Action Form fields in the desktop Settings App. In your Settings, go to Workflow and Business Logic > [Module]> [Object Class] > Workflow > Actions > Create Actions.

<fieldName1>

<fieldName2>

Field names (display labels)

IMPORTANT: To refer to fields, use their display labels. For details, see How to refer to object fields when creating and updating objects.

Field values

  • For reference fields, you must specify the identifier of the referenced object (example: PN000017), or its name (example: Angelina Reyes).

  • For classification fields (e.g. Priority or Impact), you must specify the element’s display value (example: Immediate or Multiple People).

  • For boolean fields, you must specify true/false or 1/0.

INFO: For HTML fields, you must specify text with HTML tags, see Working with HTML fields.
POST body format
{
	"ActionId": "<actionId>",
	"Fields":{
		"<fieldName1>": "<fieldValue1>",
		"<fieldName2>": "<fieldValue2>",
		...
	}
}
Response Format

On success, the server returns the identifiers of the newly created object. 

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Succeed": true/false,
		"ObjectID": "<Object ID>",
		"ObjectOID": "<Object OID>"
	}
}
Property Description Format

Succeed

New object record was created.

Boolean

ObjectID

Internal database identifier of the created object.

String

ObjectOID

OID of the created object.

INFO: For more information, see Object identification in Alloy Navigator.

String

In case of a failure the server returns an error message. The following errors may appear:

Error message Description

Authorization has been denied for this request.

The Authorization header is missing or the token has expired.

This action cannot be executed because the action's condition is not satisfied.

The user is not authorized to use theworkflow Create Action.

Requested action is not available.

The Create Action with the specified ActionID was not found.

Field <name> is unknown.

The field with the specified name was not found.
Example

Here is an example of how you can create a new Asset. Call the Create Action #388 and set values for Name, Description, Type, and Associated.

Request:

(POST) http://www.example.com/api/v2

POST Body

{
	"ActionId": 388,  //"Create new asset"
	"Fields":{
		"Name":"Asset API",
		"Description":"Asset for API test",
		"Type":"Non-Physical", //classification field
		"Associated":"PC00092" // reference field
	}
}

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Succeed": true,
		"ObjectID": "6a469d7d-4bb1-4896-befb-10027f1f0c61",
		"ObjectOID": "A000124"
	}
}