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 .

Configuration Items 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:

/cis/active : List all active configuration items
/cis/inactive : List all inactive configuration items
/cis/supported_by_my_teams : List all configuration items which support team is one of the teams that the API user is a member of

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.

action_status

Optional enum , default: not_required — The Action status field is used to specify what should happen to the configuration item after it has reached a removal-related status. Valid values are:

not_required : Not Required
for_disposal : For Disposal
to_return : To Return
utilized : Utilized
returned : Returned

When the CI status is to_be_removed, the allowed values are:

not_required : Not Required
for_disposal : For Disposal
to_return : To Return

When the CI status is removed, the allowed values are:

not_required : Not Required
utilized : Utilized
returned : Returned

For all other CI status values, action_status is always null.

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.

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. See the action_status field for the values available in this status.
lost_or_stolen : Lost or Stolen
removed : Removed. See the action_status field for the values available in this status.

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.