Running Step Actions on objects

Description

The API provides the ability to run workflow Step Actions on Alloy Navigator objects.

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/object/<oid>/action/<actionId>

URL parameters

Parameter	Description
`oid`	The object identifier INFO: For more information, see Object identification in Alloy Navigator. NOTE: This HTTP request cannot be used to update objects that belong in the Software Catalog and Stock Room sections of the product.
`actionId`	The Step Action ID. Example: `250`. TIP: You can find the Step Action ID in the Settings App: Workflow and Business Logic > [Module]> [Object Class] > Workflow > Actions > Step Actions.

POST parameters

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

Parameter	Description
<fieldName1> <fieldName2> ...	The fields on the Step Action form. Field names (display labels) TIP: To refer to object 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`. For HTML fields, you must specify text with HTML tags, see Working with HTML fields.

POST body format

{
	"<fieldName1>": "<fieldValue1>",
	"<fieldName2>": "<fieldValue2>",
	...
}

Response Format

On success, the server returns the identifiers of the updated object.

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

Property	Description	Format
`Succeed`	The confirmation that the object record was updated.	Boolean
`ObjectID`	The internal database identifier of the created object.	String
`ObjectOID`	The object identifier. INFO: For more information, see Object identification in Alloy Navigator.	String

In case of a failure, the server returns one of the following errors:

Error message	Description
Authorization has been denied for this request.	The Authorization header is missing, or the token has expired.
You do not have enough permissions to access this item.	The user is not authorized to view the requested Object.
This action cannot be executed because the action's condition is not satisfied.	The user is not authorized to use the Step Action.
Object <OID> not found.	The record with the specified object identifier was not found.
Requested action is not available.	The Step 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 update the Vendor record with OID=V0000006) by calling Step Action #1631 and updating the Activity.Time_Spent and Comment fields.

Request:

(POST) http://www.example.com/api/v2/object/V000006/action/1631

POST Body:

{
	"Activity.Time_Spent": 84,
	"Comment": "Updated with the API"
}

Response:

{
	"success": true,
	"errorCode": 0,
	"errorText": "",
	"responseObject": {
		"Succeed": true,
		"ObjectID": "326624be-4271-46bd-b070-7a47b0f5ee54",
		"ObjectOID": "V000006"
	}
}