Configuration Items API

Note If you are looking for information on how to integrate a discovery tool with R-Service, 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,
    "rule_set": "software"
  },
  "..."
]

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

Predefined Filters

The following predefined filters are available:

Collection Fields

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

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

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

Filtering

Filtering is available for the following fields:

id source sourceID label name status rule_set support_team created_at updated_at product service systemID assetID serial_nr site financial_owner

The filters on label and serial_nr are not case sensitive.

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

Response

The response is similar to the response in List configuration items

Get a single configuration item

GET /cis/:id

Response

Status: 200 OK
{
  "in_use_since": 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,
  "custom_fields": null
}

The response contains these fields.

Create a configuration item

POST /cis

When creating a new configuration item these fields are available.

Important: To facilitate integrations with discovery tools, the POST is treated as a PATCH in case the provided name or label is already used by an inactive CI in the same account.

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

Archive a configuration item

POST /cis/:id/archive

Moves a given configuration item to the Archive. This action requires the Account Administrator or Directory Administrator role in the account of the configuration item.

Response

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

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

Trash a configuration item

POST /cis/:id/trash

Moves a given configuration item to the Trash. This action requires the Account Administrator or Directory Administrator role in the account of the configuration item.

Response

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

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

Restore a configuration item

POST /cis/:id/restore

Moves a given configuration item from the Archive or the Trash back into the view of “Inactive CIs”. This action requires the Account Administrator or Directory Administrator role in the account of the configuration item.

Response

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

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

Fields

alternate_names
Optional array of strings — Alternate names a software configuration item is also known by.
assetID
Optional string (max 50)
attachments
Readonly aggregated Attachments
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_fields
Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related product.
custom_fields_attachments
Writeonly attachments The attachments used in Custom fields.
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.
in_use_since
Optional date — The In use since 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.
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.
product
Required reference to Product — The Product field can be used to relate the configuration item to a different product.
recurrence
Optional aggregated — The recurrence settings hash, missing in case the configuration item has no recurrency defined. See Recurrence for the fields in the recurrence hash.
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.
remarks_attachments
Writeonly attachments The attachments used in the Remarks field.
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
serial_nr
Optional string (max 50) — The concatenation of Product Brand and Serial Number must be unique within a R-Service account.
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
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
  • in_transit: In Transit
  • 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. Optional when status of CI equals “Removed”, required otherwise.
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.
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.
workflow_template
Optional reference to Workflow Template — The workflow template that is used to periodically maintain the configuration item.
workflow_manager
Optional reference to Person — The person who will be responsible for coordinating the workflows that will be generated automatically in accordance with the recurrence schedule.