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
- Get a single configuration item
- Create a configuration item
- Update a configuration item
- Archive a configuration item
- Trash a configuration item
- Restore a configuration item
- Fields
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.
- assetID
- Optional string (max 50)
- attachments
- Readonly aggregated Attachments
- ci_type
- Readonly enum — Valid values are:
-
software_version
: Software Versionsoftware_license_certificate
: Software License Certificatehardware
: Hardware
-
Deprecated - The
ci_type
field is being phased out. Use therule_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 Licensecpu_license
: CPU Licenseinstalled_user_license
: Installed User Licensenamed_user_license
: Named User Licenseunlimited_user_license
: Unlimited User Licenseother_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 Certificatelogical_asset_with_financial_data
: Logical Asset with Financial Datalogical_asset_without_financial_data
: Logical Asset without Financial Dataphysical_asset
: Physical Assetserver
: Serversoftware
: Softwaresoftware_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 therule_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
: Orderedbeing_built
: Being Builtin_stock
: In Stockreserved
: Reservedin_transit
: In Transitinstalled
: Installedbeing_tested
: Being Testedstandby_for_continuity
: Standby for Continuitylent_out
: Lent Outin_production
: In Productionundergoing_maintenance
: Undergoing Maintenancebroken_down
: Broken Downbeing_repaired
: Being Repairedarchived
: Archivedto_be_removed
: To Be Removedlost_or_stolen
: Lost or Stolenremoved
: 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.