Item Endpoint

1. Create Item

createItem (String itemTypeId, HashMap fieldValues) (since 6.5)
createItem (String itemTypeId, String ownerCustomerId, HashMap fieldValues)

Parameters

  • itemTypeId The unique Item Type ID of the Item Type
  • ownerCustomerId The unique Customer ID to assign to this Item
  • fieldValues A HashMap of field values

Description

Use this function to enter a new Configuration Item (CI). Enter the Item Type ID, a Customer ID, and a set of Item Type field values.

The fieldValues HashMap is a Map of Strings to Strings. The keys represent HEAT LiveTime data fields called custom1 through to custom20. These map to the category field definitions within the CMS. Other keys include itemNumber which allow the item to be created with a given item number (provided the Edit Item Numbers admin privilege is enabled).

The function returns a HashMap containing the Configuration Item ID and a success or failure message.

2. Delete Item

deleteItem (String itemNumber)

Parameters

  • itemNumber The unique Item Number

Description

This function flags an Item as deleted so that it is no longer available for new requests.

3. Undelete Item

undeleteItem (String itemNumber)

Parameters

  • itemNumber The unique Item Number

Description

This function re-instates a previously deleted Item so that it is available for all future requests.

4. Update Item

updateItem (String itemNumber, HashMap fieldValues)

Parameters

  • itemNumber The unique Item Number
  • fieldValues A HashMap of field values for this Item

Description

This function updates and Item with new field values from the supplied hash map.

The fieldValues HashMap is a map of Strings to Strings. The keys represent HEAT LiveTime data fields called custom1 through to custom20. Other keys include itemstatus and itemNumber for changes to the item status and item number fields respectively. These map to the Category field definitions within the CMDB.

5. Get Items

getItems ()
 getItems (String customerId) (since 5.5)
 getItems (String customerId, String pageNdx) (since 5.5)
 getItems (String customerId, String itemNumber, HashMap fieldValues) (since 6.5)

Parameters

  • customerId The unique Customer Id
  • itemNumber The unique Item Number to retrieve. If this value is set then fieldValues will be ignored.
  • fieldValues A hash map of field names and values used to search for an appropriate CI. This will be ignored if the Item Number has already been set.

Description

The ‘getItems’ methods return a list of the item numbers that are either global or owned by the logged in Customer (or the Customer specified if using the customerId function). The response is in the form of a HashMap that uses the list of Item Numbers as field names. Each field has as its value a String containing the name of the Item Type that the Item represents.

In the event that no Items are found for the logged in Customer, only the ‘message’ field will be present and will contain a text message explaining that no Items were found.

The function returns a HashMap containing a list of string values detailing the Item Number(s) and description(s). This will only return the first 100 items. Use getItems(customerId, pageNdx) to page through larger result sets.

6. Get All Items

getAllItems (String pageNdx) (since 5.5)

Parameters

  • pageNdx The page index is required to return 100 entries ordered by Item Number.

Description

The ‘getAllItems’ function returns a list of Item Numbers for all the Items in the system. A page index is required to specify the ‘page’ required. Each page contains 100 entries, ordered by Item Number. The response is in the form of a HashMap that uses the list of Item Numbers as field names. Each field has as its value as a String containing the id of the Item Type that the Item represents. Note: Before version 7, this each field had as its value a String containing the name of the Item Type that the Item represents.

7. Get Specific Item

getSpecificItem (String itemNumber) (since 5.5)

Parameters

  • itemNumber The unique ItemNumber of the Item to retrieve.

Description

The ‘getSpecificItem’ function returns the Item Type of the supplied Item Number. This method exists solely to provide a quick means to verify that a certain Item Number is defined in the system, without requiring heavy data exchange of Item attributes.

8. Customer Items

customerItems (String customerId, String pagesize, String pagenumber, String sortNdx)
 customerItems (String pagesize, String pagenumber, String sortNdx)

Parameters

  • customerId The unique Customer Id
  • pagesize The maximum number of items that can be returned per query
  • pagenumber In situations where there are more items than can fit on a page size, this number specifies the next set of items to be retrieved.
  • sortNdx The index of the column to sort on

Description

The ‘customerItems’ function returns a list of the item numbers that are either owned by the customer or are global. The response is in the form of a HashMap that uses the list of item numbers as field names. Each field has as its value a String containing the name of the Item Type that the Item represents.

In the argument (customerId) enter the ID of a Customer, i.e. this is assigned to the Customer when it is created via the createCustomer function.

Possible values for sortNdx are:
1 – Item Number
2 – Item Category
3 – Item Type
7 – Item Status
8 – Purchase Date
9 – Incident Team

In Service Manager, you can also specify:
10 – Problem Team
11 – Change Team
12 – Service Request Team

In the event that no Items are found for the Customer, only the ‘message’ field will be present and will contain a text message explaining that no Items were found.

The function returns a HashMap containing a list of string values detailing the Item Number(s) and description(s), being the corresponding Item Types.

9. Org Unit Items

orgUnitItems (String orgUnitId, String pagesize, String pagenumber, String sortNdx)
 orgUnitItems (String pagesize, String pagenumber, String sortNdx)

Parameters

  • orgUnitId A unique Org Unit ID
  • pagesize The maximum number of items that can be returned per query. The page size must be between 10 and 100.
  • pagenumber In situations where there are more items than can fit on a pagesize, this number specifies the next set of items to be retrieved. The page number must be at least 0.
  • sortNdx The index of the column to sort on.

Description

Use this function to search for Items owned by the logged in User’s Org Unit or the Org Unit ID specified.

The function returns a HashMap of HashMaps. The keys of the first map are the Item Numbers. Each Item Number has its own HashMap representing the values that represent Item attributes as name-value pairs.

Possible values for sortNdx are:
1 – Item Number
2 – Item Category
3 – Item Type
7 – Item Status
8 – Purchase Date
9 – Incident Team

In Service Manager, you can also specify:
11 – Problem Team
12 – Change Team