SAM-Software Usage Data Integration API

The SAM-Software Usage Data Integration API provides endpoints to create and update records in the Software Usage [samp_sw_usage] table.

This API requires activation of the Software Asset Management Professional (com.snc.samp) plugin. It also requires that you have either the sam_admin or sam_developer role to access the endpoint.

Parent Topic:REST API reference

SAM-Software Usage Data Integration - POST /sam_software_usage_integration/createOrUpdate

Creates or updates a specified record in the Software Usage [samp_sw_usage] table.

You can create/update one or more software usage records in a single call.

URL format

Versioned URL: /api/now/{api_version}/sam_software_usage_integration/createOrUpdate

Default URL: /api/now/sam_software_usage_integration/createOrUpdate

Note: Available versions are specified in the REST API Explorer. For scripted REST APIs there is additional version information on the Scripted REST Service form.

Supported request parameters

Name	Description
api\_version	Optional. Version of the endpoint to access. For example, `v1` or `v2`. Only specify this value to use an endpoint version other than the latest. Data type: String

Name	Description
None

Name

Description

items

List of column names and values for each field to store in the software usage record.The column information that you must pass depends on the value you specify for reclamation_type (which is a required field):

Possible reclamation_type values and the column information that must be passed:

total_usage:
configuration_item
last_used_time
month_used
norm_product
year
last_used_date:
configuration_item
norm_product

The combination of these fields uniquely identify a record. If the record is not found in the table, a new record with the specified fields is created; otherwise the existing record is updated.

Data type: Array

Headers

The following request and response headers apply to this HTTP action only, or apply to this action in a distinct way. For a list of general headers used in the REST API, see Supported REST API headers.

Header	Description
Accept	Data format of the response body. Supported types: application/json or application/xml. Default: application/json
Content-Type	Data format of the request body. Supported types: application/json or application/xml. Default: application/json

Header	Description
None

Status codes

The following status codes apply to this HTTP action. For a list of possible status codes used in the REST API, see REST API HTTP response codes.

Status code	Description
200	Successful. The request was successfully processed.
401	Unauthorized. The user credentials are incorrect or have not been passed.
404	Not found. The requested item wasn't found.
405	Invalid method. The functionality is disabled.
500	Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

Response body parameters (JSON or XML)

Name	Description
items	Name-value pair list of all fields in the software usage record.Data type: Array \(content varies\)

cURL request

The following example illustrates how to create a new software usage record.

curl -X POST "https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{'items': [\
  {
    'configuration_item':'eaa9604d3790200044e0bfc8bcbe5dc1',\
    'month_used':2,\
    'norm_product':'40209c060b3022002d6c650d37673a89',\
    'norm_publisher':'24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type':'total_usage',\
    'usage_count': 13,\
    'total_usage_time':13,\
    'year':2020
  }\
]}"

{
  "result": {
    "reply": {
      "items": [
        {
          "configuration_item": "eaa9604d3790200044e0bfc8bcbe5dc1",
          "month_used": 2,
          "norm_product": "40209c060b3022002d6c650d37673a89",
          "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
          "reclamation_type": "total_usage",
          "usage_count": 13,
          "total_usage_time": 13,
          "year": 2020,
          "sysId": "13d15fe59d511010f8772c637e39afe5",
          "status": "INSERT"
        }
      ]
    },
    "message": "Ok"
  }
}

The following example illustrates how to update multiple software usage records in a single call.

curl -X POST "https://instance.servicenow/api/now/sam_software_usage_integration/createOrUpdate" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d "{'items': [\
  {\
    'configuration_item': 'eaa9604d3790200044e0bfc8bcbe5dc1',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 13,\
    'total_usage_time': 13,\
    'year': 2020
  },
  {\
    'configuration_item': '0aa9e80d3790200044e0bfc8bcbe5da0',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 19,\
    'total_usage_time': 19,\
    'year': 2020
  },
  {\
    'configuration_item': 'a0a9a80d3790200044e0bfc8bcbe5d3c',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 7,\
    'total_usage_time': 7,\
    'year': 2020},
  {\
    'configuration_item': '48a9280d3790200044e0bfc8bcbe5d55',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 1,\
    'total_usage_time': 1,\
    'year': 2020},
  {\
    'configuration_item': '61a9680d3790200044e0bfc8bcbe5d11',\
    'month_used': 2,\
    'norm_product': '40209c060b3022002d6c650d37673a89',\
    'norm_publisher': '24dcccc20b3022002d6c650d37673ab3',\
    'reclamation_type': 'total_usage',\
    'usage_count': 18,\
    'total_usage_time': 18,\
    'year': 2020}
]}"

{
  "result": {
    "reply": {
      "items": [
        {
          "configuration_item": "eaa9604d3790200044e0bfc8bcbe5dc1",
          "month_used": 2,
          "norm_product": "40209c060b3022002d6c650d37673a89",
          "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
          "reclamation_type": "total_usage",
          "usage_count": 13,
          "total_usage_time": 13,
          "year": 2020,
          "sysId": "13d15fe59d511010f8772c637e39afe5",
          "status": "INSERT"
        },
        {
          "configuration_item": "0aa9e80d3790200044e0bfc8bcbe5da0",
          "month_used": 2,
          "norm_product": "40209c060b3022002d6c650d37673a89",
          "norm_publisher": "24dcccc20b3022002d6c650d37673ab3",
          "reclamation_type": "total_usage",
          "usage_count": 19,
          "total_usage_time": 19,
          "year": 2020,
          "sysId": "2cd15fe59d521010f9772c637e39aff4",
          "status": "UPDATE"
        },
        {
          ...
        },
      ]
    },
    "message": "Ok"
  }
}