Recipes
Creating Calls
Developers may choose to take a trial and error approach to call creation.
Call Creation Checklist
To summarize, the actions to perform are as follows:
To create a call, you must choose a Call type, create a properly formatted Call object, serialize the object in JSON format and create the object using a HTTP POST request on api:v2/call
Finally, the created Call must be submitted with the submit action to be visible by using a HTTP PUT request on api:v2/call/{call ref}/submit
For example, submitting an empty IPK Stream or Status will likely result in a validation error like the following:
{
"Message": "The request is invalid",
"Type": "FieldValidationException",
"Errors": {
"IpkStatus": [
"Required: IpkStatus must be set when Template is null"
],
"IpkStream": [
"Required: IpkStream must be set when Template is null"
],
"Partition": [
"Required"
]
}
}The exact error is entirely dependent upon the configuration of the system.
Choosing a Call type
Each Call Type may be associated with its own extension fields.
These extension fields may not all be visible on all call types, so the recommended approach to choosing a call type is to derive this from ITIL IPK Tiers or Call Templates - if these are enabled.
IPK Statuses and Streams
In the Core application, users choose a type of call to log by choosing a screen set. This is often determined by selecting an IPK Status and then an IPK Stream, which in turn are mapped to a Screen Set. It is also possible to link Screen Set to a combination of IPK Status, IPK Stream add Call Problem Type .
These Call Type mappings are accessible through either api:v2/ipk-status-stream-to-type or api:v2/ipk-status-stream-type-to-type. Only one of these endpoints will be enabled. The enabled one will allow searching ,and the other will respond with HTTP Status code 404. To programmatically determine which to use, each endpoint can be queried using $options on the end of the query string.
Search the enabled call type mapping entity and choose one according to IPK Status, Stream and/or Call Problem Type.
The search results from each include the usual hypermedia links, and also include "_actions".
For example
{
"IpkStatus": {
"Name": "Incident",
"_context": "api:v2/ipk-status/$metadata",
"_self": "api:v2/ipk-status/1"
},
"IpkStream": {
"Name": "Standard",
"_context": "api:v2/ipk-stream/$metadata",
"_self": "api:v2/ipk-stream/0"
},
"_context": "api:v2/ipk-status-stream-to-type/$metadata",
"_self": "api:v2/ipk-status-stream-to-type?$select=IpkStatus,IpkStream&$filter=(IpkStatus%3d%3d1%26%26IpkStream%3d%3d0%26%26InfraEntityType%3d%3d7)",
"_actions": {
"Create": [
{
"_self": "api:v2/incident/$Create",
"href": "api:v2/incident",
"description": "The resource that should be used to create a call of this type. IpkStatus and IpkStream from this result should be set in the new call."
}
]
}
}Call Templates
In the Self Service Portal, users choose a call template, which in turn is associated with a type of call. Call Templates can be searched using the api:v2/call-template resource and the results will contain references to the appropriate Create action in the hypermedia links for each search result.
{
"Ref": 96,
"Name": "Default",
"_context": "api:v2/call-template/$metadata",
"_self": "api:v2/call-template/96",
"_actions": {
"Create": [
{
"_self": "api:v2/call/$Create",
"href": "api:v2/call",
"description": "The resource that should be used to create a call of this type. The Template property in the new call should be set to the Ref of this result."
}
]
}
}In this example, we would choose to create a call using api:v2/call.
When choosing a Call type using the API, either of these approaches can be used for any type of user, or you can define your own mechanism. For example, your user could choose from a list of Call types directly (instead of templates or IPK Tiers).
Creating a Call Object
You can upload and download attachments from the API.
Download an attachment from the API, example:
alemba.api/api/v2/asset/624/attachment-download/1159To get the list of attachments:
alemba.api/api/v2/asset/624/attachment?$select=Ref,NameCall Create Metadata
The metadata for the Call entity describes all of the actions that are available and all of the properties of that entity. Each action may also contain a description of the allowed inputs for that action.
The Call Create action is no exception and does define applicable inputs and the associated validation rules.
Some fields may be required or readonly depending upon the system configuration. This configuration is described in the action metadata and is validated by the server.
For example
{
"_context": "api:v2/call/$metadata",
"_self": "api:v2/call/$Create",
"href": "api:v2/call",
"methods": [
"POST"
],
"inputs": [
{
"property": "ConfigurationItem"
},
{
"property": "User"
},
{
"property": "Priority",
"readonly": true
},
{
"property": "Description",
"relations": [
{
"behaviors": [
{
"type": 11,
"scope": 1
}
],
"source": "Description",
"target": "DescriptionHtml"
}
]
},
{
"property": "DescriptionHtml",
"relations": [
{
"behaviors": [
{
"type": 14,
"scope": 1
}
],
"source": "DescriptionHtml",
"target": "Description"
}
]
},
{
"property": "Type"
},
{
"property": "Organization"
},
{
"property": "Template",
"relations": [
{
"behaviors": [
{
"type": 16,
"scope": 2
},
{
"type": 17,
"scope": 2
}
],
"source": "Template",
"target": "IpkStatus"
},
{
"behaviors": [
{
"type": 16,
"scope": 2
},
{
"type": 17,
"scope": 2
}
],
"source": "Template",
"target": "IpkStream"
},
{
"behaviors": [
{
"type": 16,
"scope": 2
}
],
"source": "Template",
"target": "Name"
}
]
},
{
"property": "IpkStatus",
"relations": [
{
"behaviors": [
{
"type": 14,
"scope": 2
}
],
"source": "IpkStatus",
"target": "IpkStream"
}
]
},
{
"property": "IpkStream",
"relations": [
{
"behaviors": [
{
"type": 14,
"scope": 2
}
],
"source": "IpkStream",
"target": "IpkStatus"
}
]
},
{
"property": "Partition",
"required": true,
"relations": [
{
"behaviors": [
{
"type": 15
}
],
"source": "Partition",
"target": "ConfigurationItem"
},
{
"behaviors": [
{
"type": 15
}
],
"source": "Partition",
"target": "User"
},
{
"behaviors": [
{
"type": 15
}
],
"source": "Partition",
"target": "Priority"
},
]
}
],
"description": "Create a new record of this type",
"status": "GA"
}The metadata for each action may include _context, _self, href, description and status.
It may also include "methods", which defines the HTTP Methods/Verbs that can be used for the action.
The action metadata may also define and array of "inputs"
Each input may include the following properties:
property
The path of the input value. This may be a reference to the name of a property for the current entity "_context" (see API Metadata or may be a dot separated path)
This defines the structure of the object that must be sent in the request body when the action is invoked.
e.g $action.CallActionType describes the following JSON structure
{ "$action": { "CallActionType": value } }
When the "property" path does not refer to an entity property name, all other relevant property values will also be defined e.g. type, displayType, etc.
required
A boolean value indicating that the input is required. Omitted unless it is true
readonly
A boolean value indicating that the input is readonly. Omitted unless it is true
relations
An array of relationships between input fields
Each relation includes "source" and "target" which reference "property" paths within the "inputs" array.
Each relation will also include an array of "behaviours". These define validation level rules.
The behaviors are used in server side validation and transformation rules and are provided so that the client can understand
input requirements without needing to rely upon server side validation.
Behaviors may include the following properties
phase
This indicates when the behavior will be applied.
1 indicates that the behavior will be applied after the record has been updated (but before it is committed to the database)
0 indicates that the behavior will be applied before, and therefore will apply to the input only.
type
This indicates the type of relation and may be one of the following
11 (CalculateHtmlTextIfNull): Indicates that the HTML text value of the target input should be set. When processed on the server.
12 (RequiredIfTrue): Indicates that the target input is required when the source input is true
13 (ZeroIfNotNull): Indicates that the target input must be set to zero when the source input has a value
14 (RequiredIfNotNull): Indicates that the target input is required when the source input has a value
15 (Dependency): Indicates that the target input is dependent upon the value of the source input. This typically applies to partitioned inputs.
16 (ReadonlyIfNotNull): Indicates that the target input is readonly when the source input has a value
17 (RequiredIfNull): Indicates that the target input is required when the source input does not have a value
18 (ReadonlyIfNull): Indicates that the target input is readonly when the source input does not have a value
scope
This indicates where the behavior should be interpreted.
0 indicates that the behavior should be implemented by the client and will be ignored by the server
1 indicates that the behavior can be implemented by the client and will be implemented by the server
2 indicates that the behavior should be implemented by the client and will be implemented by the server
Using the Call Create action metadata, we can easily determine which fields are required, and analyze the more complex relationships between fields.
For the example of creating a Call from a Template, the following ajax call could succeed
var create = $.ajax({
url: metadata.href.replace(/^api:/, "alemba.api/api"),
data: {
Template: 96
},
method: metadata.methods[0],
contentType: 'application/json',
headers: {
'Authorization': "Bearer " + access_token
}
});Call Create Response
When successful, the Call Create action will respond with HTTP Status Code 201.
The response body will include the actual changes to the Call record and hypermedia links to the currently applicable actions.
For example
// S{
"ActualLogDate": "2017-01-23T12:12:41.0000000Z",
"Template": 96,
"Ref": 10056,
"_context": "api:v2/call/$metadata",
"_self": "api:v2/call/10056",
"_actions": {
"Submit": [
{
"_self": "api:v2/call/$Submit",
"href": "api:v2/call/10056/submit"
}
],
"Update": [
{
"_self": "api:v2/call/$Update",
"href": "api:v2/call/10056"
}
]
}
}The _actions property in the response indicates the actions which are applicable to the created Call in its current state.
A Call will only be visible to the creator until it has been submitted, therefore if the "Submit" action is listed in the Create response, this action should be invoked before relinquishing responsibility for the Call.
Replicating behavior of Self Service
If a call is logged in Self Service, fixed rules are applied after saving, to populate certain fields. This has not been replicated in the API, as we will be making such rules configurable in the future. If you wish to replicate the current logic, you need to programmatically do so, following the rules below:
If Location is not set, Location is set to the current User’s Location Ref (if they have one)
If Organization is not set, Organization is set to the current User’s Organzation Ref (if they have one)
If the Location is still not set, this is set to the first valid Location of: the selected User or Service or CI or Organization of the call.
If the Organzation is still not set, this is set to the first valid Organzation from: the selected User or Service or CI of the call.
Impact of data on post-creation rules
Almost any property of a call may be used by IPK Workflow Rules, and each may have a different impact, according how the rules are set up in your system. The API user should be fully conversant with how these rules are configured, so as to achieve the desired assignment, notification and workflow creation.
Creating Requests
The templates retrieved are subject to several security and configuration settings, including:
partitioning Request Screen Sets and Workflow Templates
Workflow Management Settings
login's Workflow Management Role's Template Security settings
Calls and Requests – Determining Initial Assignment
In the WCF API, it is possible to specify the Officer and/or Group to which Calls and Requests are forwarded on creation. These are specified as parameters rather than properties to update. They are ignored if IPK or Workflow rules are in place to set this.
In the RESTful API, it is possible to set these values on the Defer action, rather than the Create, so API users should use both actions, one after the other, to achieve the same thing.
Calls and Requests – Recording Actions
In the WCF API, the transactions to create and update calls include the ability to record “Action and Solution” information, which is largely recorded as an associated history record. In the RESTful API, this can be achieved using the Defer action. This may include some of the following parameters:
$action.Description.Description$action.Description.DescriptionHtml$action.Description.Title$action.ActionType
Creating a Service Order
The items that need to be created for a valid service order are:
Service Order
Service Order Items
A Call or Request per Service Order Item (if you want those items immediately submitted)
Required inputs are:
one or more service actions and/or service bundles
a quantity for each
To create a new Service Order, a new service order record must first be created
api:v2/service-order/$createFor each service action in the order:
A Service Order Item linked to the Service Order must be created
api:v2/service-order-item/$create2. A Call or Request must be created which is linked to the Service Order Item.
3. The type of Call or Request to create is indicated in the metadata links for each service action.
4. Finally, the Service Order must be Submitted (using the Submit action), which will automatically calculate the Order Total and Submit the linked Tickets.
The new dynamic service bundle type is not supported in this version of the API.
The creation of a request will automatically create the necessary tasks and initiate the workflow.
Closing Calls
The process of closing a call in Core is subject to a number of configurable rules, settings and privileges. Some of these are handled by the rules engine and will be automatically invoked after calling the Close method, others need to be considered by the API user in determining what to pass to the Close method, and whether to call additional methods.
Last updated
Was this helpful?