Create Records and Run Actions

On this page

The API has no direct create, update, or delete: every change is a workflow action. POST / runs a create action, and POST /Object/{objectId}/Action/{actionId} runs an action against an existing object. No route of the public API deletes an object. What an action is, and how it is authored, is covered in Actions.

In the API

How an action call is built

An action is named by its GUID, by its numeric event id, or by its name, tried in that order. A disabled action is refused.

Before any field is touched, four checks must pass:

  • You have view rights on the action's class.
  • For a portal session, the action is of a portal kind.
  • For an action against an existing object, the object exists, is of the action's class, and is one you may view.
  • The action's own conditions and availability rules admit it for that object.

A condition failure and an unavailable action both come back as ordinary failures in the response envelope.

When you run an action against an existing object, the request body is a flat map of field names to values. Only five JSON types are accepted as values there: string, integer, float, boolean, and null. An object or an array fails the request as an invalid body, except for the reserved Attachments array. A create action takes its field values in the Fields map of its body instead, as described under Create a record. An activity field is written with an Activity. prefix, for example Activity.Time_Spent.

A field name is matched against the action's own form first, by field name, its HTML counterpart, its caption, or its label. Only if that fails is it looked up by caption among the object's and the activity's fields. An unmatched name fails with "field is unknown", and so does a matched name whose type cannot be determined. A create action with no form accepts any field of the object's table.

A non-GUID value for a field with a lookup is resolved to an id, by name or by OID, including for fields that reference an object. A category lookup matches either of two name columns. A value that resolves to nothing fails with "object does not exist in database". A boolean field accepts 0/1 and true/yes; any other value counts as false.

Fields you omit are filled from the action form's defaults. A remaining field that is mandatory on the form, or not-null in the underlying table, fails the request with a message that names the field's caption, and so does a submitted but empty value for such a field. On a create action, the object table's own insert defaults are applied first, so your request only needs to carry what differs from them.

An HTML field is always written through its HTML half, even if you name the plain-text field. Under version v1 the value is HTML-encoded on the way in; under version v2 it is stored as you supplied it.

Every value you submit must be legal XML. A value that contains a character XML forbids is rejected, and the error names the field.

Actions that use AI Control

When you create a record or run an action through the API, AI Control on the action form does not run or generate an AI response. The control runs only when the action is performed interactively in the user interface.

The API can return Succeed: true even though AI Control did not run. If the action uses the control's value to update a record field, that field may remain empty.

To run AI processing through the API, call the Ask AI system global workflow function in a separate request. See Global Workflow Functions.

Create a record

POST / runs a create action. The body carries ActionId, Fields (a map of field names to string values), and an optional Attachments array. A body without Fields fails as an invalid body.

{
  "ActionId": "<action GUID, event id, or name>",
  "Fields": {
    "<field name>": "<value>"
  }
}

Sending a task action to this route fails with "Cannot process the request. Requested action event id is of unexpected type."

Incident create actions in a new database

In a new database created with the Default Workflow (see Default Workflow Configuration), Incidents have three enabled technician create actions: New Technical Issue, New Major Incident, and API Incident Creation, whose description reads "Used to create Incidents via API". An upgraded database need not have these actions, and an administrator may have changed them.

Create a Service Request from a Service Catalog Item

A Service Request is created by running the Service Catalog Item's request-submission action, which is reserved and identified by the GUID {3766577B-913E-4988-905E-38FB62BABC1B}. Run it on the update route, POST /Object/{itemId}/Action/{3766577B-913E-4988-905E-38FB62BABC1B}, with the item's GUID or OID as the object id and the request form's fields as the body.

On the update route, the API runs the create action configured for the item instead. When the item or its create action is missing, the call fails with "Requested action is not available." On success, the returned identifiers are the new Service Request's, not the catalog item's. The new Service Request is linked to the catalog item in the URL by default. If the create action's form accepts Service_Catalog_Item_ID, a value passed in the request body takes precedence.

In a new database created with the Default Workflow (see Default Workflow Configuration), the reserved action is the Service Catalog Item's task action Submit Request, and the URL can name it by that name instead of the GUID. Because it is a task action there, sending it to POST / fails with the "is of unexpected type" message: the kind check runs before the API replaces the action with the item's create action.

Run an action on an existing record

POST /Object/{objectId}/Action/{actionId} runs a task action against that object. The body is the flat field map, with an optional Attachments array. Sending a create action to this route fails with the same "is of unexpected type" message.

{
  "<field name>": "<value>"
}

Each field value is passed to the action as a string: a JSON true, for example, arrives as True.

List create actions and an object's actions

No public API route lists a class's actions. The technician profile of the API has two list routes whose only requirement is an authenticated caller:

  • POST /App/GetCreateActions (also routed as POST /App/GetNewTicketActions), with the body {"Value": "<class GUID>"}, lists that class's create actions that your security roles allow, leaving out the actions whose conditions fail and the actions with no form. The answer's responseObject is {Fields, Data}: Fields declares ClassName, ObjClassName, Caption, ID, ClassID, and Hint, and each row in Data also carries GroupName, GroupSorter, and ItemSorter. ID is the action's GUID, which POST / accepts as ActionId. For Incidents, the class GUID is {F4703FE3-DE2C-46B4-9F57-668F420EF04A}.
  • POST /App/GetObjectActions, with an object's GUID in the same body shape, lists that object's task actions.

Read the result

A successful call, whether it created or updated a record, returns the affected object's identity, not the object itself. The responseObject has exactly four members:

  • Succeed
  • ObjectID, the object's GUID, which is always a GUID string and never null
  • ObjectOID, the object's OID, as a string
  • MessageList, the workflow messages

On a create, the two identifiers are the new object's. The create route returns no Location header and no echo of the submitted body, so these members are the only way you learn the key of a record you just created. To see the object's new state, read the object back.

When the workflow aborts while the action runs and leaves at least one message, the envelope reports success: false with the last message as errorText; the full list stays in responseObject.MessageList. If that last message is empty, success stays true. An abort that leaves no message keeps success: true, with only responseObject.Succeed false. A refusal before the action runs (an unavailable action, a kind mismatch, a missing object, a failed condition, or an unknown or mandatory field) comes back as a failure with a null responseObject and no message list.

Check whether an action is available

GET /Object/{objectId}/Action/{actionId}/Check runs the same resolution and checks as running the action, including the action's own conditions, but stops before anything is executed. Nothing is written.

The outcome is reported as {"Result": <boolean>} in responseObject while the envelope is successful. A failed check that carries messages comes back as a failure envelope instead, with the last message as errorText and a null responseObject. {"Result": false} appears only for a failure without messages.

GET /V1/ExecuteAction runs the action of a one-click link. The route answers an HTML page rather than the JSON envelope. The page reports success unless the action raises an error. A workflow abort while the action runs does not raise one: the route does not read the action's result, so an aborted run still shows the success page. The success page shows the link's success message (empty when the link has none). A link that is missing one of its required parts renders the error page with "Invalid Link", an expired link renders "The link has expired.", and any other error renders the error's message.

The two pages are the HTML files ExecuteActionSuccessTemplate.html and ExecuteActionErrorTemplate.html in the HtmlTemplates folder of the API's application folder. The message replaces the {ActionResultMessage} placeholder. The files are read each time a result is rendered, so editing them on the server changes the pages without a rebuild. The shipped success page, titled "Execute action sample template", shows the image htmltemplates/images/logo.jpg; the API serves the files of the HtmlTemplates folder as static files under the /htmltemplates path.

How a one-click link is authored, and where it is used in notifications, is covered in One-Click Action Links.

In the Settings App

Find a create action's id

The id of a create action to pass as ActionId is also found in the Settings App under Workflow and Business Logic > module > object class > Workflow > Actions > Create Actions.