This document describes how to use the Entity series of APIs to work with Custom Forms.
Please see here for the generic details about importing a postman collection. The specific file to import for this tutorial is Vivantio Custom Forms.postman_collection.json.
To work successfully with Custom Forms it's important to distinguish between the following:
- Custom Form Definitions: these are the definitions of custom forms that are created for use with a specific ticket type.
- Custom Form Instances: these are instances of where a custom form has been used by a ticket item and custom form data is associated with that ticket item.
To begin working with custom form definitions you need to determine which ticket type ID (as an integer) you want to work with. The Get All Ticket Types request calls POST api/Configuration/TicketTypeSelectAll which needs no further input to return the details of all the ticket types in your system.
Having determined which ticket type ID you want to work with you need to pass this in to Get Custom Form Definition Master Details For Ticket Type ID which calls POST api/Entity/CustomEntityDefinitionSelectByRecordTypeId. Note that this API requires the ticket type ID to be passed in via the request body:
The results of this API will include the high-level details of all the custom forms associated with the passed in ticket type ID. Each custom form has an ID which can be used to get lower-level details about the form.
Use Get Custom Form Definition Child Details For Master ID to get further details about a custom form. This request calls POST api/Entity/CustomEntityDefinitionSelectById/{id} using the ID of a custom form from the previous request. This value can be passed in either via Query Params or Path Variables (Query Params is illustrated):
The results of this API include the Field Definitions for the custom form.
The Field Definitions for a custom form can be retrieved using Get Custom Field Definition For Definition ID which calls POST api/Entity/CustomEntityFieldDefinitionSelectById/{id} using a field definition ID from the previous request. This value must be passed in as a Path Variables value:
To determine which custom forms are associated with a particular ticket instance use Get Custom Form Definition Master IDs For Ticket Instance ID which calls POST api/Entity/SelectEntityTypeIdsByParentItem. The ticket unique integer reference (ParentId, from the URL) and system area (SystemArea) need to be passed in to the body of the request as above. The JSON should be in the following format:
{
"ParentId": 655984,
"SystemArea": "Ticket"
}To return details of either an instance or all instances of custom forms used by tickets use Get Custom Form Instance For Ticket Instance ID which calls POST api/Entity/CustomEntitySelectByTypeIdAndParent. The request parameters need to be passed in the request body in the following format:
{
"TypeId": 0,
"ParentId": 655984,
"SystemArea": "Ticket"
}If TypeId is 0 then all instances are returned. To restrict to a specific custom form use TypeId to supply the ID of the custom form as returned from Get Custom Form Definition Master Details For Ticket Type ID.
To get just the specific form instance details returned from the previous API use Get Custom Form Instance For Form Instance ID which calls POST api/Entity/CustomEntitySelectById/{id}. Pass in the ticket instance ID as a query parameter.
To return a simplified version of Get Custom Form Instance For Ticket Instance ID use Get Custom Form Instance For Ticket Instance ID Simple which calls POST api/Entity/CustomEntitySimplifiedSelectByTypeIdAndParent using the same JSON body parameters.