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, determine the url for the Call Create action, create a properly formatted Call object, serialize the object in JSON format and submit the object using HTTP POST.​

Finally, the created Call may need to be submitted before it becomes visible to other system users.

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:v1/ipk-status-stream-to-type or api:v1/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:v1/ipk-status/$metadata",
"_self": "api:v1/ipk-status/1"
},
"IpkStream": {
"Name": "Standard",
"_context": "api:v1/ipk-stream/$metadata",
"_self": "api:v1/ipk-stream/0"
},
"_context": "api:v1/ipk-status-stream-to-type/$metadata",
"_self": "api:v1/ipk-status-stream-to-type?$select=IpkStatus,IpkStream&$filter=(IpkStatus%3d%3d1%26%26IpkStream%3d%3d0%26%26InfraEntityType%3d%3d7)",
"_actions": {
"Create": [
{
"_self": "api:v1/incident/$Create",
"href": "api:v1/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."
}
]
}
}

Note that "_actions" contains a reference to a Create action. The Create action includes a hypermedia link to itself and a "href".​ This "href" is the link to use if you want to Create a Call of this type.

Note also the additional information in "description".

In this example, we would choose to create a call using api:v1/incident.

​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:v1/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:v1/call-template/$metadata",
"_self": "api:v1/call-template/96",
"_actions": {
"Create": [
{
"_self": "api:v1/call/$Create",
"href": "api:v1/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:v1/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.

  1. Download an attachment from the API, example: 

alemba.api/api/v2/asset/624/attachment-download/1159

  1. To get the list of attachments:

alemba.api/api/v2/asset/624/attachment?$select=Ref,Name

If you are authenticated to ASM the above links should work, otherwise if you are doing this programatically then you will need to authenticate as normal.

Call 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:v1/call/$metadata",
"_self": "api:v1/call/$Create",
"href": "api:v1/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:v1/call/$metadata",
"_self": "api:v1/call/10056",
"_actions": {
"Submit": [
{
"_self": "api:v1/call/$Submit",
"href": "api:v1/call/10056/submit"
}
],
"Update": [
{
"_self": "api:v1/call/$Update",
"href": "api:v1/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:v1/service-order/$create

For each service action in the order:

  1. A Service Order Item linked to the Service Order must be created 

api:v1/service-order-item/$create

2. 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.

The entity called Order is used for transactions that are part of Asset Management, and is not used for Service Orders.

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.