Configuration Items API

If you are looking for information on how to integrate a discovery tool with ITRP, please refer to the Discovery Tools page of the Import API.

List configuration items

List all configuration items for an account:

GET /cis

Response

Status: 200 OK
[
  {
    "name": "Adobe Reader 9.1.0",
    "label": "Adobe Reader 9.1.0",
    "created_at": "2016-03-14T03:11:22-06:00",
    "sourceID": null,
    "updated_at": "2016-03-14T03:11:22-06:00",
    "service": {
      "name": "Personal Computing",
      "id": 22,
      "provider": {
        "name": "Widget Data Center, Internal IT",
        "id": 32
      }
    },
    "support_team": {
      "name": "End-User Support, Houston",
      "id": 9
    },
    "id": 711,
    "product": {
      "name": "Adobe Reader",
      "brand": "Adobe",
      "category": "software/browser_viewer_application",
      "id": 33
    },
    "status": "in_production",
    "software": true,
    "ci_type": "software_version"
  },
  "..."
]

The response contains these fields by default. Filtering and pagination are available to reduce/limit the collection of configuration items.

States

The following states are available:

Collection Fields

By default the following fields will appear in collections of configuration items:

id sourceID software label name status product ci_type support_team service created_at updated_at

Obtain a different set of fields using the ?fields= parameter.

Sorting

By default a collection of configuration items is sorted ascending by label.

The following fields are accepted by the ?sort= parameter:

id sourceID label name status support_team created_at updated_at

List configuration items relevant for API user

List all configuration items which support team is one of the teams that the API user is a member of:

GET /cis/supported_by_my_teams

Response

The response is similar to the response in List configuration items

Get a single configuration item

GET /cis/:id

Response

Status: 200 OK
{
  "start_date": null,
  "site_license": null,
  "name": "Adobe Reader 9.1.0",
  "label": "Adobe Reader 9.1.0",
  "rule_set": "software",
  "financial_owner": null,
  "assetID": null,
  "remarks": "No license required.",
  "location": "Room 202, Software Safe",
  "created_at": "2016-03-14T03:11:22-06:00",
  "sourceID": null,
  "nr_of_licenses": null,
  "license_type": null,
  "updated_at": "2016-03-14T03:11:22-06:00",
  "systemID": null,
  "supplier": null,
  "service": {
    "name": "Personal Computing",
    "id": 22,
    "provider": {
      "name": "Widget Data Center, Internal IT",
      "id": 32
    }
  },
  "support_team": {
    "name": "End-User Support, Houston",
    "id": 9
  },
  "serial_nr": null,
  "rate": null,
  "po_nr": null,
  "warranty_expiry_date": null,
  "useful_life": null,
  "salvage_value": null,
  "id": 711,
  "product": {
    "name": "Adobe Reader",
    "brand": "Adobe",
    "category": "software/browser_viewer_application",
    "id": 33
  },
  "license_expiry_date": null,
  "site": {
    "name": "Widget Data Center",
    "id": 13
  },
  "nr_of_processors": null,
  "temporary_license": null,
  "purchase_value": null,
  "status": "in_production",
  "source": null,
  "software": true,
  "nr_of_cores": null,
  "depreciation_method": null,
  "ci_type": "software_version",
  "custom_data": null
}

The response contains these fields.

Create a configuration item

POST /cis

When creating a new configuration item these fields are available.

Response

Status: 201 Created
{
  "assetID": "...",
  "...": "..."
}

The response contains all fields of the created configuration item and is similar to the response in Get a single configuration item

Update a configuration item

PATCH /cis/:id

When updating a configuration item these fields are available.

Response

Status: 200 OK
{
  "assetID": "...",
  "...": "..."
}

The response contains all fields of the updated configuration item and is similar to the response in Get a single configuration item

Fields

assetID
Optional string (max 50)
ci_type
Readonly enum — Valid values are:
  • software_version: Software Version
  • software_license_certificate: Software License Certificate
  • hardware: Hardware

Deprecated - The ci_type field is being phased out. Use the rule_set field instead.

created_at
Readonly datetime — The date and time at which the configuration item was created.
custom_data
Optional hash — Custom data provided in JSON format by the UI Extension that is linked to the related product.
depreciation_method
Optional enum, default: na_cost_is_zero — The Depreciation method field is used to specify whether or not the configuration item should be depreciated and if so, which depreciation method is to be applied. When creating a new CI and a value is not specified for this field, it is set to the depreciation method of the CI’s product. Valid values are:
  • na_cost_is_zero: N/A - Cost is Zero/Included in Other CI or Service
  • na_not_capitalized: N/A - Not Capitalized
  • na_leased: N/A - Leased
  • double_declining_balance: Double Declining Balance
  • reducing_balance: Reducing Balance (or Diminishing Value)
  • straight_line: Straight Line (or Prime Cost)
  • sum_of_the_years_digits: Sum of the Year’s Digits
financial_owner
Optional reference to Organization — The Financial owner field is used to select the internal organization which budget is used to pay for the configuration item. If the CI is leased or rented, the organization that pays the lease or rent is selected in this field. When creating a new CI and a value is not specified for this field, it is set to the financial owner of the CI’s product.
id
Readonly integer — The unique ID of the configuration item.
label
Optional string (max 160) — The Label field is used to specify the label that is attached to the configuration item (CI). A label is automatically generated using the same prefix of other CIs of the same product category, followed by the next available number as the suffix.
license_expiry_date
Optional date — The License expiry date field is used to specify the date through which the temporary software license certificate is valid. The license certificate expires at the end of this day.
license_type
Optional enum — The License type field is used to select the type of license that the license certificate covers. Valid values are:
  • concurrent_user_license: Concurrent User License
  • cpu_license: CPU License
  • installed_user_license: Installed User License
  • named_user_license: Named User License
  • unlimited_user_license: Unlimited User License
  • other_type_of_license: Other Type of License
location
Optional string (max 128) — The Location field is used to enter the name or number of the room in which the CI is located, if it concerns a hardware CI.
name
Optional string (max 160), default: Adobe Reader — The Name field is used to enter the name of the configuration item (CI). When creating a new CI and a value is not specified for this field, it is set to the name of the CI’s product.
nr_of_cores
Optional integer — The Nr. of cores field is used to enter the total number of processor cores that are installed in the server.
nr_of_licenses
Optional integer — The Nr. of licenses field is used to enter the number of licenses that the license certificate covers.
nr_of_processors
Optional integer — The Nr. of processors field is used to enter the number of processors that are installed in the server.
po_nr
Optional string (max 50)
product
Required reference to Product — The Product field can be used to relate the configuration item to a different product.
purchase_value
Optional decimal — The Purchase value field is used to enter the amount that was paid for the configuration item (this is normally equal to the invoice amount).
rate
Optional float — The Rate field is used to specify the yearly rate that should be applied to calculate the depreciation of the configuration item (CI) using the reducing balance (or diminishing value) method. When creating a new CI and a value is not specified for this field, it is set to the rate of the CI’s product.
remarks
Optional text (max 64KB), default: No license required. — The Remarks field is used to add any additional information about the configuration item that might prove useful. When creating a new CI and a value is not specified for this field, it is set to the remarks of the CI’s product.
rule_set
Readonly enum — The Rule set field is automatically set to the rule set of the related product’s product category, except when the CI is a license certificate, in which case the rule set is license_certificate. Valid values are:
  • license_certificate: License Certificate
  • logical_asset_with_financial_data: Logical Asset with Financial Data
  • logical_asset_without_financial_data: Logical Asset without Financial Data
  • physical_asset: Physical Asset
  • server: Server
  • software: Software
  • software_distribution_package: Software Distribution Package
salvage_value
Optional decimal — The Salvage value field is used to enter the value of this configuration item at the end of its useful life (i.e. at the end of its depreciation period). When a value is not specified for this field, it is set to zero.
serial_nr
Optional string (max 50)
service
Optional reference to Service — The Service field is used to select the Service which service instance(s) the configuration item is, or will be, a part of. When creating a new CI and a value is not specified for this field, it is set to the service of the CI’s product.
site
Optional reference to Site — The Site field is used to select the Site at which the CI is located, if it concerns a hardware CI.
site_license
Optional boolean — The Site license box is checked for license certificates that may only be used at one or more specific locations.
software
Readonly boolean, default: false

Deprecated - The software field is being phased out. Use the rule_set field instead.

source
Optional string (max 30) - See source
sourceID
Optional string (max 128) - See source
start_date
Optional date — The Start date field is used to specify the date on which the expense for the configuration item (CI) was incurred or, if the CI is depreciated over time, the date on which the depreciation was started. This is typically the invoice date.
status
Required enum — The Status field is used to select the appropriate status for the configuration item (CI). Valid values are:
  • ordered: Ordered
  • being_built: Being Built
  • in_stock: In Stock
  • reserved: Reserved
  • installed: Installed
  • being_tested: Being Tested
  • standby_for_continuity: Standby for Continuity
  • lent_out: Lent Out
  • in_production: In Production
  • undergoing_maintenance: Undergoing Maintenance
  • broken_down: Broken Down
  • being_repaired: Being Repaired
  • archived: Archived
  • to_be_removed: To Be Removed
  • lost_or_stolen: Lost or Stolen
  • removed: Removed
supplier
Optional reference to Organization — The Supplier field is used to select the supplier from which the configuration item (CI) has been obtained. When creating a new CI and a value is not specified for this field, it is set to the supplier of the CI’s product.
support_team
Optional reference to Team — The Support team field is used to select the Team responsible for supporting the configuration item and maintaining its information in the configuration management database (CMDB). When creating a new CI and a value is not specified for this field, it is set to the support team of the CI’s product.
systemID
Optional string (max 255)
temporary_license
Optional boolean — The Temporary license box is checked for license certificates that are not valid indefinitely.
updated_at
Readonly datetime — The date and time of the last update of the configuration item. If the configuration item has no updates it contains the created_at value.
useful_life
Optional integer — The Useful life field is used to enter the number of years within which the configuration item is to be depreciated. When creating a new CI and a value is not specified for this field, it is set to the useful life of the CI’s product.
warranty_expiry_date
Optional date — The Warranty expiry date field is used to specify the date through which the warranty coverage for the configuration item is valid. The warranty expires at the end of this day.