Products API

• List products
• Get a single product
• Create a product
• Update a product
• Fields

List products

List all products for an account:

GET /products

Response

Status: 200 OK

[
  {
    "name": "Adobe Reader",
    "created_at": "2016-03-14T03:10:50-06:00",
    "category": "software/browser_viewer_application",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:50-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": 33
  },
  {
    "name": "APC NetShelter SX 48U Rack",
    "created_at": "2016-03-14T03:10:50-06:00",
    "category": "rack_enclosure",
    "sourceID": null,
    "updated_at": "2016-03-14T03:10:50-06:00",
    "service": {
      "name": "Rack Space",
      "id": 26,
      "provider": {
        "name": "Widget Data Center, External IT",
        "id": 30
      }
    },
    "support_team": {
      "name": "Unix Servers",
      "id": 13
    },
    "id": 34,
    "disabled": true
  },
  "..."
]

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

Predefined Filters

The following predefined filters are available:

• /products/disabled: List all disabled products
• /products/enabled: List all enabled products
• /products/supported_by_my_teams: List all products 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 products:

id sourceID name category 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 name disabled category rule_set support_team service created_at updated_at

Sorting

By default a collection of products is sorted ascending by name.

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

id sourceID name support_team service created_at updated_at

Response

The response is similar to the response in List products

Get a single product

GET /products/:id

Response

Status: 200 OK

{
  "picture_uri": "https://itrp-demo.s3.amazonaws.com/defaults/avatars/products/large/Adobe Reader.png",
  "name": "Adobe Reader",
  "model": null,
  "rule_set": "software",
  "financial_owner": null,
  "brand": "Adobe",
  "remarks": "No license required.",
  "created_at": "2016-03-14T03:10:50-06:00",
  "category": "software/browser_viewer_application",
  "sourceID": null,
  "updated_at": "2016-03-14T03:10:50-06:00",
  "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
  },
  "rate": null,
  "useful_life": null,
  "id": 33,
  "source": null,
  "depreciation_method": "na_cost_is_zero",
  "ui_extension": null,
  "disabled": false
}

The response contains these fields.

Create a product

POST /products

When creating a new product these fields are available.

Response

Status: 201 Created

{
  "brand": "...",
  "...": "..."
}

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

Update a product

PATCH /products/:id

When updating a product these fields are available.

Response

Status: 200 OK

{
  "brand": "...",
  "...": "..."
}

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

Fields

attachments

Readonly aggregated Attachments

brand

Required string (max 128) — The Brand field is used to select a previously entered brand name or to enter a new one. The brand name is typically the name of the product’s manufacturer.

category

Required enum with reference field of Product Categories — The Category field is used to select the appropriate product category for the product.

created_at

Readonly datetime — The date and time at which the product was created.

custom_fields

Optional custom fields — Custom fields provided in JSON format by the UI Extension that is linked to the related product category.

custom_fields_attachments

Writeonly attachments The attachments used in Custom fields.

depreciation_method

Optional enum — The Depreciation method field is used to specify whether or not configuration items that are based on the product are typically depreciated and if so, which depreciation method is normally applied. Valid values are:

• not_depreciated: Not Depreciated
• 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

disabled

Optional boolean, default: false — The Disabled box is checked when the product may no longer be used to register new configuration items.

financial_owner

Optional reference to Organization — The Financial owner field is used to select the internal organization which budget is normally used to obtain the product.

id

Readonly integer — The unique ID of the product.

model

Required string (max 128) — The Model field is used to enter the model of the product.

name

Required string (max 128) — The Name field is used to enter the name of the product. Fill out the Brand, Model, Product ID (optional) and Category fields to automatically generate a name based on the values entered in these fields.

picture_uri

Optional string — The hyperlink to the image file for the product.

productID

Optional string (max 128) — The Product ID field is used to enter the unique identifier of the product that is used by the manufacturer. The concatenation of Brand and Product ID must be unique within a R-Service account.

rate

Optional integer — The Rate field is used to specify the yearly rate that should normally be applied to calculate the depreciation of configuration items that are based on the product using the reducing balance (or diminishing value) method.

recurrence

Optional aggregated — The recurrence settings hash, missing in case the product has no recurrency defined. It contains the fields of a Recurrence, except the following:

start_date end_date next_occurrence_at last_occurrence_at last_occurrence_object last_occurrence_errors ical

remarks

Optional text (max 64KB) — The Remarks field is used to enter any additional information about the product that might prove useful.

remarks_attachments

Writeonly attachments The inline 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 category. Valid values are:

• 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 for the configuration items based on this product 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.

salvage_value_currency

Optional enum — The currency of the Salvage value field value of the configuration items based on this product. For valid values, see the list of currencies in the Currency field of the Account API.

service

Optional reference to Service — The Service field is used to select the Service which Service Instances would typically include the product.

source

Optional string (max 30) - See source

sourceID

Optional string (max 128) - See source

supplier

Optional reference to Organization — The Supplier field is used to select the Organization from which the product is typically obtained. If the product is developed internally, select the internal organization that develops it. Note that a lease company should be selected in this field if the product is normally leased.

support_team

Optional reference to Team — The Support team field is used to select the Team responsible for maintaining the product’s information in the configuration management database (CMDB).

ui_extension

Optional reference to UI Extension — The UI extension field is used to select the UI extension that is to be added to the configuration items that are based on the product.

updated_at

Readonly datetime — The date and time of the last update of the product. If the product 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 configuration items that are based on the product are typically depreciated.

workflow_template

Optional reference to Workflow Template — The workflow template that is used to periodically maintain configuration items created from the product.

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.