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 asPOST /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'sresponseObjectis{Fields, Data}:FieldsdeclaresClassName,ObjClassName,Caption,ID,ClassID, andHint, and each row inDataalso carriesGroupName,GroupSorter, andItemSorter.IDis the action's GUID, whichPOST /accepts asActionId. 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:
SucceedObjectID, the object's GUID, which is always a GUID string and never nullObjectOID, the object's OID, as a stringMessageList, 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.
One-click action links
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.
Related topics
- Actions - what a workflow action is and how it is authored.
- One-Click Action Links - authoring one-click links used in notifications.
- Attachments