Service Catalog Open API

The Service Catalog Open API provides endpoints to create and retrieve service specifications.

Use this API to manage service catalog information between external systems and the ServiceNow AI Platform. The Service Catalog Open API is a ServiceNow® implementation of the TM Forum Service Catalog API REST specification. This implementation is based on the TMF633 Service Catalog API REST Specification Version 4, October 2020.

This API is included in the Product Catalog Advanced application, which is available on the ServiceNow Store.

This API's endpoints are provided within the sn_tmf-api namespace under the Product Catalog Open API name:

• Create Service Category (POST) - Service Catalog Open - POST /api/sn_tmf_api/catalogmanagement/serviceCategory
• Create Service Specification (POST) - Service Catalog Open - POST /servicespecification
• Delete Service Category (DELETE) - Service Catalog Open - DELETE /api/sn_tmf_api/catalogmanagement/serviceCategory/{id}
• Get Service Category (GET) - Service Catalog Open - GET /api/sn_tmf_api/catalogmanagement/serviceCategory/{id}
• Get Service Specification (GET) - Service Catalog Open - GET /servicespecification/{specificationId}
• List Service Specifications (GET) - Service Catalog Open - GET /servicespecification
• Update Service Category (PATCH) - Service Catalog Open - POST /api/sn_tmf_api/catalogmanagement/serviceCategory

The calling user must have the sn_prd_pm_adv.catalog_integrator role.

This API creates and updates data in the following tables.

• Characteristic [sn_prd_pm_characteristic]
• Characteristic Option [sn_prd_pm_characteristic_option]
• Service Specification [sn_prd_pm_service_specification]
• Specification Relationship [sn_prd_pm_specification_relationship]

Service Catalog Open - DELETE /api/sn_tmf_api/catalogmanagement/serviceCategory/{id}

Deletes the specified service category record in the Specification Category [sn_prd_pm_specification_category] table.

URL format

Default URL: /api/sn_tmf_api/catalogmanagement/serviceCategory/{id}

Supported request parameters

表 : 1. Path parameters

Name	Description
id	Sys_id of the service category to delete. Table: Service category [sn_prd_pm_specification_category] Data type: String

表 : 2. Query parameters

Name	Description
None

表 : 3. Request body parameters (XML or JSON)

Name	Description
None

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.

表 : 4. Request headers

Header	Description
Accept	Data format of the request body. Only supports application/json.

表 : 5. Response headers

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.

表 : 6. Status codes

Status code	Description
204	No content.
400	Bad request. A bad request type or malformed request was detected.

Response body parameters (JSON or XML)

Name	Description
None

cURL request

The following example deletes a service category with ID, a1b23456c7de8a90f0123456gh789ij. Returns a status code with messaging.

curl "https://instance.service-now.com/api/sn_tmf_api/catalogmanagement/serviceCategory/a1b23456c7de8a90f0123456gh789ij" \
  --request DELETE \
  --header "Accept:application/json" \
  --user 'user:password'

Service Catalog Open - GET /api/sn_tmf_api/catalogmanagement/serviceCategory

Retrieves a list of all service category records in the Service Category [sn_prd_pm_specification_category] table.

URL format

Default URL: /api/sn_tmf_api/catalogmanagement/serviceCategory

Supported request parameters

表 : 7. Path parameters

Name	Description
None

表 : 8. Query parameters

Name	Description
fields	List of fields to return in the response. Invalid fields are ignored. Valid fields: href id name Data type: String Default: Returns all fields
id	Filter service categories by specific sys_id(s). Table: Service Category [service_category] Data type: String
limit	Maximum number of records to return. For requests that exceed this number of records, use the offset parameter to paginate record retrieval. Data type: Number Default: 20 Maximum: 100
offset	Starting index at which to begin retrieving records. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. Use this value to paginate record retrieval. Don't use a negative number value. Data type: Number Default: 0

表 : 9. Request body parameters (XML or JSON)

Name	Description
None

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.

表 : 10. Request headers

Header	Description
Accept:application/json

表 : 11. Response headers

Header	Description
Content-Range	Range of content returned in a paginated call. For example, if offset=2 and limit=3, the value of the Content-Range header is items 3-5.
Content-Type	Data format of the response body. Only supports application/json.
Link	Contains the following links to navigate through query results: first last next previous
X-Total-Count	For paginated queries, this header specifies the total number of records available on the server.

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.

表 : 12. Status codes

Status code	Description
200	Request successfully processed. Full resource returned in response (no pagination).
206	Partial resource returned in response (with pagination).
400	Bad request. Possible reasons: Invalid path parameter Invalid URI
404	Record not found. No records matching the query parameters are found in the table.

Response body parameters (JSON or XML)

Name	Description
externalIdentifier	Identifying information for an external system involved in managing categories. Data type: Array of Objects "externalIdentifier": [ { "id": "String", "owner": "String" } ]
externalIdentifier.id	Unique identifier for the service category. This value is determined by an external system. Data type: String Table: Service Category [sn_prd_pm_specification_category], field external_id
externalIdentifier.owner	The system that owns the given external ID. Data type: String
href	Hyperlink to access the service category. Data type: String
id	Sys_id of the service category. Table: Service Category [sn_prd_pm_specification_category] Data type: String
isRoot	Flag that indicates whether the category is a root of categories. Valid values: true: Category is a root of categories. false: Category isn't a root of categories. Data type: Boolean
modelCategory	List of model categories associated with the service category. Data type: Array of Objects "modelCategory": [ { "id": "String", "name": "String" } ]
modelCategory.id	Sys_id of the model category. Table: Model Category [cmdb_model_category] Data type: String
modelCategory.name	Name of the model category. Table: Model Category [cmdb_model_category] Data type: String
name	Name of the service category. Data type: String
serviceCandidate	List of service candidates references associated with this category. Data type: Array of Objects "serviceCandidate": [ { "id": "String", "href": "String", "name": "String", "@referredType": "String", "version": "String" } ]
serviceCandidate.@referredType	Value is always ServiceCategory. Data type: String
serviceCandidate.href	Hyperlink to access the service specification. Data type: String
serviceCandidate.id	Sys_id of the service specification. Table: Service Specification [sn_prd_pm_service_specification] Data type: String
serviceCandidate.version	Version of the service candidate. Data type: String

cURL request

The following example calls the GET operation to return a list of all service category records in theService Category [sn_prd_pm_specification_category] table.

curl "https://instance.service-now.com/api/sn_tmf_api/catalogmanagement/serviceCategory" \
  --request GET \
  --header "Accept:application/json" \
  --user 'user:password'
``

Response body.

{
  "id": "a1b23456c7de8a90f0123456gh789ij",
  "href": "api/sn_tmf_api/service_catalog_api/serviceCategory/a2a68216d9ce2a90f87718429ae503dd",
  "name": "Cloud Services",
  "serviceCandidate": [
    {
      "id": "14fbd5ead902ea90f87718429ae503f7",
      "href": "api/sn_tmf_api/catalogmanagement/serviceSpecification/14fbd5ead902ea90f87718429ae503f7",
      "version": "1",
      "name": "servicenow",
      "@referredType": "ServiceCategory"
    }
  ],
  "modelCategory": [
    {
      "id": "a1d5bc14c3031000b959fd251eba8f5f",
      "name": "Business Service"
    }
  ],
  "externalIdentifier": [
    {
      "id": "1234234312",
      "owner": "TMF200000123233"
    }
  ],
  "isRoot": "true"
}

Service Catalog Open - GET /api/sn_tmf_api/catalogmanagement/serviceCategory/{id}

Retrieves a specific service category record in the Specification Category [sn_prd_pm_specification_category] table.

URL format

Default URL: /api/sn_tmf_api/catalogmanagement/serviceCategory

Supported request parameters

表 : 13. Path parameters

Name	Description
id	Sys_id of the service category to retrieve. Table: Specification Category [sn_prd_pm_specification_category] Data type: String

表 : 14. Query parameters

Name	Description
fields	List of fields to return in the response. Invalid fields are ignored. Valid fields: href id name Data type: String Default: Returns all fields
limit	Maximum number of records to return. For requests that exceed this number of records, use the offset parameter to paginate record retrieval. Data type: Number Default: 20 Maximum: 100
offset	Starting index at which to begin retrieving records. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. Use this value to paginate record retrieval. Don't use a negative number value. Data type: Number Default: 0

表 : 15. Request body parameters (XML or JSON)

Name	Description
None

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.

表 : 16. Request headers

Header	Description
Accept:application/json

表 : 17. Response headers

Header	Description
Content-Range	Range of content returned in a paginated call. For example, if offset=2 and limit=3, the value of the Content-Range header is items 3-5.
Content-Type	Data format of the response body. Only supports application/json.
Link	Contains the following links to navigate through query results: first last next previous
X-Total-Count	For paginated queries, this header specifies the total number of records available on the server.

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.

表 : 18. Status codes

Status code	Description
200	Request successfully processed. Full resource returned in response (no pagination).
206	Partial resource returned in response (with pagination).
400	Bad request. Possible reasons: Invalid path parameter Invalid URI
404	Record not found. No records matching the query parameters are found in the table.

Response body parameters (JSON or XML)

Name	Description
externalIdentifier	Identifying information for an external system involved in managing categories. Data type: Array of objects "externalIdentifier": [ { "id": "String", "owner": "String" } ]
externalIdentifier.id	Unique identifier for the service category. This value is determined by an external system. Data type: String Table: Specification Category [sn_prd_pm_specification_category], Field: external_id
externalIdentifier.owner	The system that owns this ID. Data type: String
href	Hyperlink to access the service category. Data type: string
id	Sys_id of the service category. Table: Specification Category [sn_prd_pm_specification_category] Data type: String
isRoot	Flag that indicates whether the category is a root of categories. Valid values: true: Category is a root of categories. false: Category isn't a root of categories. Data type:Boolean
modelCategory	List of model categories associated with the service category. Data type: Array of objects "modelCategory": [ { "id": "String", "name": "String" } ]
modelCategory.id	Sys_id of the model category. Table: Model Category [cmdb_model_category] Data type: String
modelCategory.name	Name of the model category. Table: Model Category [cmdb_model_category] Data type: String
name	Name of the service category. Data type: String
serviceCandidate	List of service candidates associated with this category. Data type: Array of Objects "serviceCandidate": [ { "id": "String", "href": "String", "name": "String", "@referredType": "String", "version": "String" } ]
serviceCandidate.@referredType	Referred type of the service candidate. Value is always ServiceCategory. Data type: String
serviceCandidate.href	Hyperlink to access the service specification. Data type: String
serviceCandidate.id	Sys_id of the service specification. Table: Service Specification [sn_prd_pm_service_specification] Data type: String
serviceCandidate.version	Version of the service candidate. Data type: String

cURL request

The following example calls the GET operation to return a specific service category record according to a given ID, a2a68216d9ce2a90f87718429ae503dd.

curl "https://instance.service-now.com/api/sn_tmf_api/catalogmanagement/serviceCategory/a1b23456c7de8a90f0123456gh789ij" \
  --request GET \
  --header "Accept:application/json" \
  --user 'user:password'

Response body.

{
  "id": "a2a68216d9ce2a90f87718429ae503dd",
  "href": "api/sn_tmf_api/service_catalog_api/serviceCategory/a1b23456c7de8a90f0123456gh789ij",
  "name": "Cloud Services",
  "serviceCandidate": [
    {
      "id": "a1b23456c7de8a90f0123456gh789ij",
      "href": "api/sn_tmf_api/catalogmanagement/serviceSpecification/a1b23456c7de8a90f0123456gh789ij",
      "version": "1",
      "name": "servicenow",
     

Service Catalog Open - GET /servicespecification

Retrieves a list of all service specifications.

URL format

Default URL: /api/sn_prd_pm_adv/catalogmanagement/servicespecification

Supported request parameters

表 : 19. Path parameters

Name	Description
None

表 : 20. Query parameters

Name	Description
fields	List of fields to return in the response. Invalid fields are ignored. If this parameter is not used, all fields are returned. Data type: String
limit	Maximum number of records to return. For requests that exceed this number of records, use the offset parameter to paginate record retrieval. Data type: Number Default: 20 Maximum: 100
offset	Starting index at which to begin retrieving records. Use this value to paginate record retrieval. This functionality enables the retrieval of all records, regardless of the number of records, in small manageable chunks. Data type: Number Default: 0
state	Filter service specifications by state. Only specifications with a state matching the value of this parameter are returned in the response. Data type: String

表 : 21. Request body parameters (JSON)

Name	Description
None

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.

表 : 22. Request headers

Header	Description
None

表 : 23. Response headers

Header	Description
Content-Range	Range of content returned in a paginated call. For example, if offset=2 and limit=3, the value of the Content-Range header is items 3-5.
Content-Type	Data format of the response body. Only supports application/json.
Link	Contains the following links to navigate through query results. first last next previous
X-Total-Count	For paginated queries, this header specifies the total number of records available on the server.

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.

表 : 24. Status codes

Status code	Description
200	Request successfully processed. Full resource returned in response (no pagination).
206	Partial resource returned in response (with pagination).
400	Bad request. Possible reasons: Invalid path parameter Invalid URI
404	Record not found. No records matching the query parameters are found in the table.

Response body parameters (JSON)

Name	Description
@type	Type of specification. Data type: String
description	Description of the specification. Data type: String
externalId	External ID of the service specification. Data type: String Table: In the external_id field of the Service Specification [sn_prd_pm_service_specification] table.
externalSystem	External system of the service specification, appended with TMF633. For example, if the external system is ABC then enter the value in externalSystem as ABC-TMF633. Data Type: String
externalSystem	Third-party or non-native platform that interacts with the service catalog. Value is always appended with TMF633. For example, if the external system is ABC then the value in the external source should be ABC-TMF633. Data type: String
id	Initial version or external ID of the service specification. Data type: String Table: In the initial_version or external_id field of the Service Specification [sn_prd_pm_service_specification] table.
internalId	Initial version of the service specification. Data type: String Table: In the initial_version field of the Service Specification [sn_prd_pm_service_specification] table.
internalVersion	Version of the service specification. Data type: String Table: In the version field of the Service Specification [sn_prd_pm_service_specification] table.
lastUpdate	Date the specification was last updated. Data type: String
name	Name of the specification. Data type: String
resourceSpecification	Resource specifications for this service specification. Data type: Array of Objects "resourceSpecification": [ { "id": "String", "internalId": "String", "internalVersion": "String", "name": "String", "version": "String" } ]
resourceSpecification.id	The initial_version or external_id of the resource specification. Data type: String
resourceSpecification.internalId	The initial_version of the resource specification. Data type: String
resourceSpecification.internalVersion	The external_version of the resource specification. Data type: String
resourceSpecification.name	Name of the resource specification. Data type: String
resourceSpecification.version	Version of the resource specification. Data type: String
serviceSpecificationRelationship	This specification's relationships to other service specifications. Data type: Array of Objects "serviceSpecificationRelationship": [ { "id": "String", "internalId": "String", "internalVersion": "String", "relationshipType": "String", "validFor": {Object}, "version": "String" } ]
serviceSpecificationRelationship.id	The initial_version or external_id of the related specification. Data type: String
serviceSpecificationRelationship.internalId	The initial_version of the related specification. Data type: String
serviceSpecificationRelationship.internalVersion	Version of the related specification. Data type: String
serviceSpecificationRelationship.relationshipType	Type of relationship. Data type: String
serviceSpecificationRelationship.validFor	Date range the relationship is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
serviceSpecificationRelationship.validFor.endDateTime	End date of the relationship. Data type: String
serviceSpecificationRelationship.validFor.startDateTime	Start date of the relationship. Data type: String
serviceSpecificationRelationship.version	The external_version of the related specification. Data type: String
specCharacteristic	Specification characteristic. Data type: Array of Objects "specCharacteristic": [ { "characteristicValueSpecification": [Array], "description": "String", "name": "String", "validFor": {Object}, "valueType": "String" } ]
specCharacteristic.characteristicValueSpecification	List of possible values of the characteristic. Data type: Array of Objects "characteristicValueSpecification": [ { "value": "String" } ]
specCharacteristic.characteristicValueSpecification.value	Value of the characteristic. Data type: String
specCharacteristic.description	Description of the characteristic. Data type: String
specCharacteristic.name	Name of the characteristic. Data type: String
specCharacteristic.validFor	Date range the characteristic is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
specCharacteristic.validFor.endDateTime	End date of the characteristic. Data type: String
specCharacteristic.validFor.startDateTime	Start date of the characteristic. Data type: String
specCharacteristic.valueType	Value type of the characteristic, such as choice or email. Can be a simple or complex characteristic. Possible values: Date,Address Integer,Date/Time Array.Integer Array.Single Line Test Single Line Text Array.Obect Array.Date Array.Decimal Yes/No Object Array.Datetime Checkbox Email Choice Data type: String
validFor	Date range the specification is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
validFor.endDateTime	End date of the specification. Data type: String
validFor.startDateTime	Start date of the specification. Data type: String
version	External version of the service specification. Data type: String Table: In the external_version field of the Service Specification [sn_prd_pm_service_specification] table.

cURL request

This example retrieves all service specifications.

curl --location --request GET "https://instance.servicenow.com/api/sn_prd_pm_adv/catalogmanagement/servicespecification" \
--user 'username':'password'

Response body.

[
   {
      "id": "16d79ec3532520103b6bddeeff7b12a6",
      "name": "SD WAN Optimization Service",
       "externalSystem": "Salesforce - TMF633",
      "description": "SD WAN Optimization Service",
      "lastUpdate": "2022-01-23 22:48:55",
      "validFor": {
         "startDateTime": "2022-01-12",
         "endDateTime": "2027-02-11"
      },
      "serviceSpecificationRelationship": [
         {
            "id": "a1f5fe981bb420106ba59acf034bcb4f",
            "name": "Deduplication and Compression",
            "version": "1",
            "type": "rfs",
            "validFor": {
               "startDateTime": "2021-02-11",
               "endDateTime": "2027-02-11"
            }
         }
      ],
      "resourceSpecification": [],
      "serviceSpecCharacteristic": [
         {
            "name": "SSL Optimization",
            "description": "SSL Optimization",
            "valueType": "choice",
            "validFor": {
               "startDatetime": "2022-01-14 07:47:57"
            },
            "productSpecCharacteristicValue": [
               {
                  "value": "False",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "True",
                  "validFor": {
                     "startDateTime": ""
                  }
               }
            ]
         },
         {
            "name": "CIFS Optimization",
            "description": "CIFS Optimization Protocol",
            "valueType": "choice",
            "validFor": {
               "startDatetime": "2022-01-14 07:49:09"
            },
            "productSpecCharacteristicValue": [
               {
                  "value": "SMB1",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "SMB2",
                  "validFor": {
                     "startDateTime": ""
                  }
               }
            ]
         }
      ]
      "externalSource": "ABC-TMF633"
   },
   {
      "id": "31c5caff07266010a7955b7e0ad3006b",
      "name": "Firewall Administration",
      "description": "Firewall Administration",
      "lastUpdate": "2022-01-23 11:46:48",
      "validFor": {
         "startDateTime": "2021-11-22",
         "endDateTime": ""
      },
      "serviceSpecificationRelationship": [],
      "resourceSpecification": [
         {
            "id": "3546463307666010a7955b7e0ad3005d",
            "name": "Cisco Firewall Management system",
            "version": "1"
         }
      ],
      "serviceSpecCharacteristic": [
         {
            "name": "Firewall Administration CPE Model",
            "description": "Firewall Administration CPE Model",
            "valueType": "choice",
            "validFor": {
               "startDatetime": "2022-02-20 00:55:37"
            },
            "productSpecCharacteristicValue": [
               {
                  "value": "2100 series",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "4100 series",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "7300 series",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "9300 series",
                  "validFor": {
                     "startDateTime": ""
                  }
               }
            ]
    "externalSource": "ABC-TMF633"
         },
         {
            "name": "Firewall Administration CPE Type",
            "description": "Firewall Administration CPE Type",
            "valueType": "choice",
            "validFor": {
               "startDatetime": "2022-02-20 00:53:45"
            },
            "productSpecCharacteristicValue": [
               {
                  "value": "Physical",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "Virtual",
                  "validFor": {
                     "startDateTime": ""
                  }
               }
            ]
         },
         {
            "name": "Configuration and Policy backup",
            "description": "Configuration and Policy backup",
            "valueType": "choice",
            "validFor": {
               "startDatetime": "2022-01-21 10:46:02"
            },
            "productSpecCharacteristicValue": [
               {
                  "value": "Weekly",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "Monthly",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "Daily",
                  "validFor": {
                     "startDateTime": ""
                  }
               }
            ]
         },
         {
            "name": "Remote CLI troubleshoot support",
            "description": "Remote CLI troubleshoot support",
            "valueType": "choice",
            "validFor": {
               "startDatetime": "2022-01-21 10:45:38"
            },
            "productSpecCharacteristicValue": [
               {
                  "value": "Standard support",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "Premium support",
                  "validFor": {
                     "startDateTime": ""
                  }
               },
               {
                  "value": "Basic support",
                  "validFor": {
                     "startDateTime": ""
                  }
               }
            ]
         },
         {
            "name": "Firewall Administration CPE ID",
            "description": "Firewall Administration CPE ID",
            "valueType": "single_line_text",
            "validFor": {
               "startDatetime": "2022-02-20 00:57:50"
            },
            "productSpecCharacteristicValue": []
         }
      ]
   }
]

Service Catalog Open - GET /servicespecification/{specificationId}

Retrieves a service specification.

URL format

Default URL: /api/sn_prd_pm_adv/catalogmanagement/servicespecification/{specificationId}

Supported request parameters

表 : 25. Path parameters

Name	Description
specificationId	Sys_id of the service specification to retrieve. Data type: String Table: Service Specification [sn_prd_pm_service_specification]

表 : 26. Query parameters

Name	Description
fields	List of fields to return in the response. Invalid fields are ignored. If this parameter is not used, all fields are returned. Data type: String
state	Filter service specifications by state. Only specifications with a state matching the value of this parameter are returned in the response. Data type: String

表 : 27. Request body parameters (JSON)

Name	Description
None

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.

表 : 28. Request headers

Header	Description
None

表 : 29. Response headers

Header	Description
Content-Type	Data format of the response body. Only supports application/json.

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.

表 : 30. Status codes

Status code	Description
200	Request successfully processed.
400	Bad Request. Could be any of the following reasons: Invalid path parameter Invalid URI
404	Record not found. Record associated with the ID is not found in the table.

Response body parameters (JSON)

Name	Description
@type	Type of specification. Data type: String
description	Description of the specification. Data type: String
externalId	External ID of the service specification. Data type: String Table: In the external_id field of the Service Specification [sn_prd_pm_service_specification] table.
externalSystem	External system of the service specification, appended with TMF633. For example, if the external system is ABC then enter the value in externalSystem as ABC-TMF633. Data Type: String
externalSystem	Third-party or non-native platform that interacts with the service catalog. Value is always appended with TMF633. For example, if the external system is ABC then the value in the external source should be ABC-TMF633. Data type: String
id	Initial version or external ID of the service specification. Data type: String Table: In the initial_version or external_id field of the Service Specification [sn_prd_pm_service_specification] table.
internalId	Initial version of the service specification. Data type: String Table: In the initial_version field of the Service Specification [sn_prd_pm_service_specification] table.
internalVersion	Version of the service specification. Data type: String Table: In the version field of the Service Specification [sn_prd_pm_service_specification] table.
lastUpdate	Date the specification was last updated. Data type: String
name	Name of the specification. Data type: String
resourceSpecification	Resource specifications for this service specification. Data type: Array of Objects "resourceSpecification": [ { "id": "String", "internalId": "String", "internalVersion": "String", "name": "String", "version": "String" } ]
resourceSpecification.id	The initial_version or external_id of the resource specification. Data type: String
resourceSpecification.internalId	The initial_version of the resource specification. Data type: String
resourceSpecification.internalVersion	The external_version of the resource specification. Data type: String
resourceSpecification.name	Name of the resource specification. Data type: String
resourceSpecification.version	Version of the resource specification. Data type: String
serviceSpecificationRelationship	This specification's relationships to other service specifications. Data type: Array of Objects "serviceSpecificationRelationship": [ { "id": "String", "internalId": "String", "internalVersion": "String", "relationshipType": "String", "validFor": {Object}, "version": "String" } ]
serviceSpecificationRelationship.id	The initial_version or external_id of the related specification. Data type: String
serviceSpecificationRelationship.internalId	The initial_version of the related specification. Data type: String
serviceSpecificationRelationship.internalVersion	Version of the related specification. Data type: String
serviceSpecificationRelationship.relationshipType	Type of relationship. Data type: String
serviceSpecificationRelationship.validFor	Date range the relationship is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
serviceSpecificationRelationship.validFor.endDateTime	End date of the relationship. Data type: String
serviceSpecificationRelationship.validFor.startDateTime	Start date of the relationship. Data type: String
serviceSpecificationRelationship.version	The external_version of the related specification. Data type: String
specCharacteristic	Specification characteristic. Data type: Array of Objects "specCharacteristic": [ { "characteristicValueSpecification": [Array], "description": "String", "name": "String", "validFor": {Object}, "valueType": "String" } ]
specCharacteristic.characteristicValueSpecification	List of possible values of the characteristic. Data type: Array of Objects "characteristicValueSpecification": [ { "value": "String" } ]
specCharacteristic.characteristicValueSpecification.value	Value of the characteristic. Data type: String
specCharacteristic.description	Description of the characteristic. Data type: String
specCharacteristic.name	Name of the characteristic. Data type: String
specCharacteristic.validFor	Date range the characteristic is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
specCharacteristic.validFor.endDateTime	End date of the characteristic. Data type: String
specCharacteristic.validFor.startDateTime	Start date of the characteristic. Data type: String
specCharacteristic.valueType	Value type of the characteristic, such as choice or email. Can be a simple or complex characteristic. Possible values: Date,Address Integer,Date/Time Array.Integer Array.Single Line Test Single Line Text Array.Obect Array.Date Array.Decimal Yes/No Object Array.Datetime Checkbox Email Choice Data type: String
validFor	Date range the specification is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
validFor.endDateTime	End date of the specification. Data type: String
validFor.startDateTime	Start date of the specification. Data type: String
version	External version of the service specification. Data type: String Table: In the external_version field of the Service Specification [sn_prd_pm_service_specification] table.

cURL request

This example retrieves a service specification for a firewall service.

curl --location --request GET "https://instance.servicenow.com/api/sn_prd_pm_adv/catalogmanagement/servicespecification/31c5caff07266010a7955b7e0ad3006b" \
--user 'username':'password'

Response body.

{
   "id": "31c5caff07266010a7955b7e0ad3006b",
   "name": "Firewall Administration",
   "description": "Firewall Administration",
   "externalSystem": "Salesforce - TMF633",
   "lastUpdate": "2022-01-23 11:46:48",
   "validFor": {
      "startDateTime": "2021-11-22",
      "endDateTime": ""
   },
   "serviceSpecificationRelationship": [],
   "resourceSpecification": [
      {
         "id": "3546463307666010a7955b7e0ad3005d",
         "name": "Cisco Firewall Management system",
         "version": "1"
      }
   ],
   "serviceSpecCharacteristic": [
      {
         "name": "Firewall Administration CPE Model",
         "description": "Firewall Administration CPE Model",
         "valueType": "choice",
         "validFor": {
            "startDatetime": "2022-02-20 00:55:37"
         },
         "productSpecCharacteristicValue": [
            { "value": "2100 series", "validFor": { "startDateTime": "" } },
            { "value": "4100 series", "validFor": { "startDateTime": "" } },
            { "value": "7300 series", "validFor": { "startDateTime": "" } },
            { "value": "9300 series", "validFor": { "startDateTime": "" } }
         ]
      },
      {
         "name": "Firewall Administration CPE Type",
         "description": "Firewall Administration CPE Type",
         "valueType": "choice",
         "validFor": {
            "startDatetime": "2022-02-20 00:53:45"
         },
         "productSpecCharacteristicValue": [
            { "value": "Physical", "validFor": { "startDateTime": "" } },
            { "value": "Virtual", "validFor": { "startDateTime": "" } }
         ]
      },
      {
         "name": "Configuration and Policy backup",
         "description": "Configuration and Policy backup",
         "valueType": "choice",
         "validFor": {
            "startDatetime": "2022-01-21 10:46:02"
         },
         "productSpecCharacteristicValue": [
            { "value": "Weekly", "validFor": { "startDateTime": "" } },
            { "value": "Monthly", "validFor": { "startDateTime": "" } },
            { "value": "Daily", "validFor": { "startDateTime": "" } }
         ]
      },
      {
         "name": "Remote CLI troubleshoot support",
         "description": "Remote CLI troubleshoot support",
         "valueType": "choice",
         "validFor": {
            "startDatetime": "2022-01-21 10:45:38"
         },
         "productSpecCharacteristicValue": [
            { "value": "Standard support", "validFor": { "startDateTime": "" } },
            { "value": "Premium support", "validFor": { "startDateTime": "" } },
            { "value": "Basic support", "validFor": { "startDateTime": "" } }
         ]
      },
      {
         "name": "Firewall Administration CPE ID",
         "description": "Firewall Administration CPE ID",
         "valueType": "single_line_text",
         "validFor": {
            "startDatetime": "2022-02-20 00:57:50"
         },
         "productSpecCharacteristicValue": []
      }
   ],
   "externalSource": "ABC-TMF633"
}

Service Category Open - PATCH /api/sn_tmf_api/catalogmanagement/serviceCategory/{id}

Updates a specified record in the Specification Category [sn_prd_pm_specification_category] table.

URL format

Default URL: /api/sn_tmf_api/catalogmanagement/serviceCategory/ {id}

Supported request parameters

表 : 31. Path parameters

Name	Description
id	Sys_id of the service category table. Table: Specification Category [sn_prd_pm_specification_category] Data type: String

表 : 32. Query parameters

Name	Description
None

表 : 33. Request body parameters (XML or JSON)

Name	Description
externalIdentifier	Identifying information for an external system involved in managing categories. Data type: Array of Objects "externalIdentifier": [ { "id": "String", "owner": "String" } ]
externalIdentifier.id	Unique identifier for the service category. This value is determined by an external system. Table: Specification Category [sn_prd_pm_specification_category], Field: external_id Data type: String
externalIdentifier.owner	The system that owns this ID. Data type: String
href	Hyperlink to access the service category. Data type: String
id	Sys_id of the service category. Table: Specification Category [sn_prd_pm_specification_category] Data type: String
isRoot	Flag that indicates whether the category is a root of categories. Valid values: true: Category is a root of categories. false: Category isn't a root of categories. Data type: Boolean
modelCategory	List of model categories associated with the service category. Data type: Array of Objects "modelCategory": [ { "id": "String", "name": "String" } ]
modelCategory.id	Sys_id of the model category. Table: Model Category [cmdb_model_category] Data type: String
modelCategory.name	Name of the model category. Table: Model Category [cmdb_model_category] Data type: String
name	Name of the service category. Data type: String
serviceCandidate	List of service candidates associated with this category. Data type: Array of objects "serviceCandidate": [ { "@referredType": "String", "href": "String", "id": "String", "name": "String", "version": "String" } ]
serviceCandidate.@referredType	Value is always ServiceCategory. Data type: String
serviceCandidate.href	Hyperlink to access the service specification. Data type: String
serviceCandidate.id	Sys_id of the service specification. Table: Service Specification [sn_prd_pm_service_specification] Data type: String
serviceCandidate.version	Version of the service candidate. Data type: String

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.

表 : 34. Request headers

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

表 : 35. Response headers

Header	Description
None

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.

表 : 36. Request headers

Header	Description
Accept	Data format of the request body. Only supports application/json.
Content-Type	Data format of the request body. Only supports application/json.

表 : 37. Response headers

Header	Description
Content-Type	Data format of the response body. Only supports application/json.

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.

表 : 38. Status codes

Status code	Description
201	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected for one or more of the following reasons: Empty payload. Invalid payload. Mandatory field missing.

Response body parameters (JSON or XML)

Name	Description
externalIdentifier	Identifying information for an external system involved in managing categories. Data type: Array of objects "externalIdentifier": [ { "id": "String", "owner": "String" } ]
externalIdentifier.id	Unique identifier for the service category. This value is determined by an external system. Data type: String Table: Specification Category [sn_prd_pm_specification_category], Field: external_id
externalIdentifier.owner	The system that owns this ID. Data type: String
href	Hyperlink to access the service category. Data type: string
id	Sys_id of the service category. Table: Specification Category [sn_prd_pm_specification_category] Data type: String
isRoot	Flag that indicates whether the category is a root of categories. Valid values: true: Category is a root of categories. false: Category isn't a root of categories. Data type:Boolean
modelCategory	List of model categories associated with the service category. Data type: Array of objects "modelCategory": [ { "id": "String", "name": "String" } ]
modelCategory.id	Sys_id of the model category. Table: Model Category [cmdb_model_category] Data type: String
modelCategory.name	Name of the model category. Table: Model Category [cmdb_model_category] Data type: String
name	Name of the service category. Data type: string
serviceCandidate	List of service candidates associated with this category. Data type: Array of objects "serviceCandidate": [ { "@referredType": "String", "href": "String", "id": "String", "name": "String", "version": "String" } ]
serviceCandidate.@referredType	Value is always ServiceCategory. Data type: String
serviceCandidate.href	Hyperlink to access the service specification. Data type: String
serviceCandidate.id	Sys_id of the service specification. Table: Service Specification [sn_prd_pm_service_specification] Data type: String
serviceCandidate.version	Version of the service candidate. Data type: String

cURL request

The following example updates the service category's name, version, service candidate, model category, and external identifier information.

curl "https://instance.service-now.com/api/sn_tmf_api/catalogmanagement/serviceCategory/a1b23456c7de8a90f0123456gh789ij" \
  --request PATCH \
  --header "Accept:application/json" \
  --header "Content-Type:application/json" \
  --data '{
    "name": "Cloud Services",
    "version": "1.0",
    "serviceCandidate": [
      {
        "id": "a1b23456c7de8a90f0123456gh789ij",
        "href": "https://mycsp.com:8080/tmf-api/serviceCatalogManagement/v4/serviceCategory/5980",
        "version": "3.2",
        "name": "Cloud Services",
        "@referredType": "ServiceCategory"
      }
    ],
    "modelCategory": [
      {
        "id": "b2d5bc14c3031000b959fd251eba8f96",
        "name": "model"
      }
    ],
    "externalIdentifier": {
      "id": "1234234312",
      "owner": "TMF200000123233"
    },
    "isRoot": true
  }' \
  --user 'user:password

Response body.

{
  "name": "Cloud Services",
  "version": "1.0",
  "serviceCandidate": [
    {
      "id": "a1b23456c7de8a90f0123456gh789ij",
      "href": "https://mycsp.com:8080/tmf-api/serviceCatalogManagement/v4/serviceCategory/5980",
      "version": "3.2",
      "name": "Cloud Services",
      "@referredType": "ServiceCategory"
    }
  ],
  "modelCategory": [
    {
      "id": "b2d5bc14c3031000b959fd251eba8f96",
      "name": "model"
    }
  ],
  "externalIdentifier": {
    "id": "1234234312",
    "owner": "TMF200000123233"
  },
  "isRoot": true,
  "id": "8138241b1caaaa10f87703c075c809fe",
  "href": "api/sn_tmf_api/catalogmanagement/serviceCategory/8138241b1caaaa10f87703c075c809fe"
}

Service Catalog Open - POST /api/sn_tmf_api/catalogmanagement/serviceCategory

Creates a new service category record in the Specification Category [sn_prd_pm_specification_category] table.

URL format

Default URL: /api/sn_tmf_api/catalogmanagement/serviceCategory

Supported request parameters

表 : 39. Path parameters

Name	Description
None

表 : 40. Query parameters

Name	Description
None

表 : 41. Request body parameters (XML or JSON)

Name	Description
externalIdentifier	Identifying information for an external system involved in managing categories. Data type: Array of Objects "externalIdentifier": [ { "id": "String", "owner": "String" } ]
externalIdentifier.id	Unique identifier for the service category. This value is determined by an external system. Table: Specification Category [sn_prd_pm_specification_category], Field: external_id Data type: String
externalIdentifier.owner	The system that owns this ID. Data type: String
href	Hyperlink to access the service category. Data type: String
id	Sys_id of the service category. Table: Specification Category [sn_prd_pm_specification_category] Data type: String
isRoot	Flag that indicates whether the category is a root of categories. Valid values: true: Category is a root of categories. false: Category isn't a root of categories. Data type: Boolean
modelCategory	List of model categories associated with the service category. Data type: Array of Objects "modelCategory": [ { "id": "String", "name": "String" } ]
modelCategory.id	Sys_id of the model category. Table: Model Category [cmdb_model_category] Data type: String
modelCategory.name	Name of the model category. Table: Model Category [cmdb_model_category] Data type: String
name	Name of the service category. Data type: String
serviceCandidate	List of service candidates associated with this category. Data type: Array of objects "serviceCandidate": [ { "id": "String", "href": "String", "name": "String", "@referredType": "String", "version": "String" } ]
serviceCandidate.@referredType	Value is always ServiceCategory. Data type: String
serviceCandidate.href	Hyperlink to access the service specification. Data type: String
serviceCandidate.id	Sys_id of the service specification. Table: Service Specification [sn_prd_pm_service_specification] Data type: String
serviceCandidate.version	Version of the service candidate. Data type: String

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.

表 : 42. Request headers

Header	Description
Accept	Data format of the request body. Only supports application/json.
Content-Type	Data format of the request body. Only supports application/json.

表 : 43. Response headers

Header	Description
Content-Type	Data format of the response body. Only supports application/json.

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.

表 : 44. Status codes

Status code	Description
201	Successful. The request was successfully processed.
400	Bad Request. A bad request type or malformed request was detected for one or more of the following reasons: Empty payload. Invalid payload. Mandatory field missing.

Response body parameters (JSON or XML)

Name	Description
externalIdentifier	Identifying information for an external system involved in managing categories. Data type: Array of objects "externalIdentifier": [ { "id": "String", "owner": "String" } ]
externalIdentifier.id	Unique identifier for the service category. This value is determined by an external system. Data type: String Table: Specification Category [sn_prd_pm_specification_category], Field: external_id
externalIdentifier.owner	The system that owns this ID. Data type: String
href	Hyperlink to access the service category. Data type: string
id	Sys_id of the service category. Table: Specification Category [sn_prd_pm_specification_category] Data type: String
isRoot	Flag that indicates whether the category is a root of categories. Valid values: true: Category is a root of categories. false: Category isn't a root of categories. Data type:Boolean
modelCategory	List of model categories associated with the service category. Data type: Array of objects "modelCategory": [ { "id": "String", "name": "String" } ]
modelCategory.id	Sys_id of the model category. Table: Model Category [cmdb_model_category] Data type: String
modelCategory.name	Name of the model category. Table: Model Category [cmdb_model_category] Data type: String
name	Name of the service category. Data type: string
serviceCandidate	List of service candidates associated with this category. Data type: Array of objects "serviceCandidate": [ { "id": "String", "href": "String", "name": "String", "@referredType": "String", "version": "String" } ]
serviceCandidate.@referredType	Value is always ServiceCategory. Data type: String
serviceCandidate.href	Hyperlink to access the service specification. Data type: String
serviceCandidate.id	Sys_id of the service specification. Table: Service Specification [sn_prd_pm_service_specification] Data type: String
serviceCandidate.version	Version of the service candidate. Data type: String

cURL request

The following example calls POST to create a new service category record according to details provided in the request body.

curl "https://instance.service-now.com/api/sn_tmf_api/catalogmanagement/serviceCategory" \
  --request POST \
  --header "Accept:application/json" \
  --header "Content-Type:application/json" \
  --user 'user:password' \
  --data '{
    "name": "Cloud Services",
    "version": "1.0",
    "serviceCandidate": [
      {
        "id": "a1b23456c7de8a90f0123456gh789ij",
        "href": "https://mycsp.com:8080/tmf-api/serviceCatalogManagement/v4/serviceCategory/5980",
        "version": "3.2",
        "name": "Cloud Services",
        "@referredType": "ServiceCategory"
      }
    ],
    "modelCategory": [
      {
        "id": "b2d5bc14c3031000b959fd251eba8f96",
        "name": "model"
      }
    ],
    "externalIdentifier": {
      "id": "1234234312",
      "owner": "TMF200000123233"
    },
    "isRoot": true
  }'

Response body.

{
  "name": "Cloud Services",
  "version": "1.0",
  "serviceCandidate": [
    {
      "id": "a1b23456c7de8a90f0123456gh789ij",
      "href": "https://mycsp.com:8080/tmf-api/serviceCatalogManagement/v4/serviceCategory/5980",
      "version": "3.2",
      "name": "Cloud Services",
      "@referredType": "ServiceCategory"
    }
  ],
  "modelCategory": [
    {
      "id": "b2d5bc14c3031000b959fd251eba8f96",
      "name": "model"
    }
  ],
  "externalIdentifier": {
    "id": "1234234312",
    "owner": "TMF200000123233"
  },
  "isRoot": true,
  "id": "8138241b1caaaa10f87703c075c809fe",
  "href": "api/sn_tmf_api/service_catalog_api/serviceCategory/8138241b1caaaa10f87703c075c809fe"
}

Service Catalog Open - POST /servicespecification

Creates a service specification.

URL format

Default URL: /api/sn_prd_pm_adv/catalogmanagement/servicespecification

Supported request parameters

表 : 45. Path parameters

Name	Description
None

表 : 46. Query parameters

Name	Description
None

表 : 47. Request body parameters (JSON)

Name	Description
description	Required. Description of the specification. Data type: String
externalId	External ID of the service specification. If both externalId and id are provided, they must refer to the same specification. Data type: String Default: Blank string Table: Service Specification [sn_prd_pm_service_specification]
externalSystem	Third-party or non-native platform that interacts with the service catalog. Value is always appended with TMF633. For example, if the external system is ABC then the value in the external source should be ABC-TMF633. Data type: String
id	The initial_version or external_id of the service specification. If id is not provided, this endpoint creates a new specification with version=1. If id is provided, this endpoint creates a new version of the given specification. If both externalId and id are provided, they must refer to the same specification. Data type: String Default: Blank string
internalVersion	Version of the service specification. Data type: String Default: Blank string Table: Service Specification [sn_prd_pm_service_specification]
lastUpdate	Date the specification was last updated. Data type: String Default: Blank string
name	Required. Name of the specification. Data type: String
resourceSpecification	Required. Resource specifications for this service specification. Data type: Array of Objects "resourceSpecification": [ { "id": "String", "internalVersion": "String", "name": "String", "version": "String" } ]
resourceSpecification.id	Required. The initial_version or external_id of the resource specification. Data type: String
resourceSpecification.internalVersion	The external_version of the resource specification. Data type: String Default: Blank string
resourceSpecification.name	Name of the resource specification. Data type: String Default: Blank string
resourceSpecification.version	Version of the resource specification. Data type: String Default: Blank string
serviceSpecificationRelationship	Details of the specification's relationships to other service specifications. Data type: Array of Objects "serviceSpecificationRelationship": [ { "id": "String", "internalVersion": "String", "relationshipType": "String", "validFor": {Object}, "version": "String" } ]
serviceSpecificationRelationship.id	Required if using the serviceSpecificationRelationship parameter. Initial_version or external_id of the related specification. Data type: String
serviceSpecificationRelationship.internalVersion	Version of the related specification. Data type: String Default: Blank string
serviceSpecificationRelationship.relationshipType	Required if using the serviceSpecificationRelationship parameter. Type of relationship. Valid values: bundles composed_of Data type: String
serviceSpecificationRelationship.validFor	Date range the relationship is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
serviceSpecificationRelationship.validFor.endDateTime	End date of the relationship. Data type: String Default: Blank string
serviceSpecificationRelationship.validFor.startDateTime	Start date of the relationship. Data type: String Default: Blank string
serviceSpecificationRelationship.version	The external_version of the related specification. Data type: String Default: Blank string
specCharacteristic	Specification characteristic. Data type: Array of Objects "specCharacteristic": [ { "characteristicValueSpecification": [Array], "description": "String", "name": "String", "validFor": {Object}, "valueType": "String" } ]
specCharacteristic.characteristicValueSpecification	Required. Possible values of the characteristic. Data type: Array of Objects "characteristicValueSpecification": [ { "value": "String" } ]
specCharacteristic.characteristicValueSpecification.value	Required. Value of the characteristic. Data type: String
specCharacteristic.description	Description of the characteristic. Data type: String Default: Blank string
specCharacteristic.name	Required. Name of the characteristic. Data type: String
specCharacteristic.validFor	Date range the characteristic is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
specCharacteristic.validFor.endDateTime	End date of the characteristic. Data type: String Default: Blank string
specCharacteristic.validFor.startDateTime	Start date of the characteristic. Data type: String Default: Blank string
specCharacteristic.valueType	Value type of the characteristic, such as choice or email. Can be a simple or complex characteristic. Possible values: Date,Address Integer,Date/Time Array.Integer Array.Single Line Test Single Line Text Array.Obect Array.Date Array.Decimal Yes/No Object Array.Datetime Checkbox Email Choice Data type: String
validFor	Required. Date range the specification is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
validFor.endDateTime	End date of the specification. Data type: String Default: Blank string
validFor.startDateTime	Start date of the specification. Data type: String Default: Blank string
version	External version of the service specification. Version must be unique for the given version chain. Data type: String Default: Blank string Table: In the external_version field of the Service Specification [sn_prd_pm_service_specification] table.
@type	Required. Type of specification. Valid values: CustomerFacingServiceSpecification ResourceFacingServiceSpecification Data type: String

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.

表 : 48. Request headers

Header	Description
Accept	Data format of the response body. Only supports application/json.
Content-Type	Data format of the request body. Only supports application/json.

表 : 49. Response headers

Header	Description
Content-Type	Data format of the response body. Only supports application/json.

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.

表 : 50. Status codes

Status code	Description
201	Request successfully processed.
400	Bad Request. Could be any of the following reasons: Empty payload. Invalid payload. Mandatory field missing: <field name>

Response body parameters (JSON)

Name	Description
@type	Type of specification. Data type: String
description	Description of the specification. Data type: String
externalId	External ID of the service specification. Data type: String Table: In the external_id field of the Service Specification [sn_prd_pm_service_specification] table.
externalSystem	External system of the service specification, appended with TMF633. For example, if the external system is ABC then enter the value in externalSystem as ABC-TMF633. Data Type: String
externalSystem	Third-party or non-native platform that interacts with the service catalog. Value is always appended with TMF633. For example, if the external system is ABC then the value in the external source should be ABC-TMF633. Data type: String
id	Initial version or external ID of the service specification. Data type: String Table: In the initial_version or external_id field of the Service Specification [sn_prd_pm_service_specification] table.
internalId	Initial version of the service specification. Data type: String Table: In the initial_version field of the Service Specification [sn_prd_pm_service_specification] table.
internalVersion	Version of the service specification. Data type: String Table: In the version field of the Service Specification [sn_prd_pm_service_specification] table.
lastUpdate	Date the specification was last updated. Data type: String
name	Name of the specification. Data type: String
resourceSpecification	Resource specifications for this service specification. Data type: Array of Objects "resourceSpecification": [ { "id": "String", "internalId": "String", "internalVersion": "String", "name": "String", "version": "String" } ]
resourceSpecification.id	The initial_version or external_id of the resource specification. Data type: String
resourceSpecification.internalId	The initial_version of the resource specification. Data type: String
resourceSpecification.internalVersion	The external_version of the resource specification. Data type: String
resourceSpecification.name	Name of the resource specification. Data type: String
resourceSpecification.version	Version of the resource specification. Data type: String
serviceSpecificationRelationship	This specification's relationships to other service specifications. Data type: Array of Objects "serviceSpecificationRelationship": [ { "id": "String", "internalId": "String", "internalVersion": "String", "relationshipType": "String", "validFor": {Object}, "version": "String" } ]
serviceSpecificationRelationship.id	The initial_version or external_id of the related specification. Data type: String
serviceSpecificationRelationship.internalId	The initial_version of the related specification. Data type: String
serviceSpecificationRelationship.internalVersion	Version of the related specification. Data type: String
serviceSpecificationRelationship.relationshipType	Type of relationship. Data type: String
serviceSpecificationRelationship.validFor	Date range the relationship is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
serviceSpecificationRelationship.validFor.endDateTime	End date of the relationship. Data type: String
serviceSpecificationRelationship.validFor.startDateTime	Start date of the relationship. Data type: String
serviceSpecificationRelationship.version	The external_version of the related specification. Data type: String
specCharacteristic	Specification characteristic. Data type: Array of Objects "specCharacteristic": [ { "characteristicValueSpecification": [Array], "description": "String", "name": "String", "validFor": {Object}, "valueType": "String" } ]
specCharacteristic.characteristicValueSpecification	List of possible values of the characteristic. Data type: Array of Objects "characteristicValueSpecification": [ { "value": "String" } ]
specCharacteristic.characteristicValueSpecification.value	Value of the characteristic. Data type: String
specCharacteristic.description	Description of the characteristic. Data type: String
specCharacteristic.name	Name of the characteristic. Data type: String
specCharacteristic.validFor	Date range the characteristic is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
specCharacteristic.validFor.endDateTime	End date of the characteristic. Data type: String
specCharacteristic.validFor.startDateTime	Start date of the characteristic. Data type: String
specCharacteristic.valueType	Value type of the characteristic, such as choice or email. Can be a simple or complex characteristic. Possible values: Date,Address Integer,Date/Time Array.Integer Array.Single Line Test Single Line Text Array.Obect Array.Date Array.Decimal Yes/No Object Array.Datetime Checkbox Email Choice Data type: String
validFor	Date range the specification is valid for. Data type: Object "validFor": { "endDateTime": "String", "startDateTime": "String" }
validFor.endDateTime	End date of the specification. Data type: String
validFor.startDateTime	Start date of the specification. Data type: String
version	External version of the service specification. Data type: String Table: In the external_version field of the Service Specification [sn_prd_pm_service_specification] table.

cURL request

This example creates a service specification for a firewall service.

curl "https://instance.servicenow.com/api/sn_prd_pm_adv/catalogmanagement/servicespecification" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"externalId\": \"7655\",
   \"name\": \"Firewall Service\",
   \"description\": \"This service specification describes a firewall service that can be deployed in customer-premises equipment.\",
   \"validFor\": {
      \"startDateTime\": \"2017-08-23T00:00\",
      \"endDateTime\": \"2021-03-25T00:00\"
   },
   \"lastUpdate\": \"2020-08-15T00:00\",
   \"externalSource\": \"ABC-TMF633\",
   \"resourceSpecification\": [
      {
         \"id\": \"af66e551c32f10105252716b7d40dd52\",
         \"name\": \"Firewall\"
      }
   ],
   \"specCharacteristic\": [
      {
         \"name\": \"Edge\",
         \"description\": \"This characteristic describes the operating system run by the service\",
         \"valueType\": \"choice\",
         \"validFor\": {
            \"startDateTime\": \"2017-08-12T00:00\",
            \"endDateTime\": \"2021-03-07T00:00\"
         },
         \"characteristicValueSpecification\": [
            {
               \"value\": \"Android KitKat\"
            }
         ]
      }
   ],
   \"serviceSpecRelationship\": [
      {
         \"relationshipType\": \"composed_of\",
         \"id\": \"65033023ebdb30107ee5302698522849\",
         \"validFor\": {
            \"startDateTime\": \"2017-08-25T00:00\",
            \"endDateTime\": \"2021-03-25T00:00\"
         }
      }
   ],
   \"@type\": \"ResourceFacingServiceSpecification\"
}" \
--user 'username':'password'

Response body.

{
   "id": "21a7ee64c32310105253716b8d40dd60",
   "name": "Firewall Service",
   "description": "This service specification describes a firewall service that can be deployed in customer-premises equipment.",
   "validFor": {
      "startDateTime": "2017-08-23T00:00",
      "endDateTime": "2021-03-25T00:00"
   },
   "lastUpdate": "2020-08-15T00:00",
   "externalSource": "ABC-TMF633",
   "resourceSpecification": [
      {
         "id": "af66e551c32f10105252716b7d40dd52",
         "name": "Firewall"
      }
   ],
   "specCharacteristic": [
      {
         "name": "Edge",
         "description": "This characteristic describes the operating system run by the service",
         "valueType": "choice",
         "validFor": {
            "startDateTime": "2017-08-12T00:00",
            "endDateTime": "2021-03-07T00:00"
         },
         "characteristicValueSpecification": [
            {
               "value": "Android KitKat"
            }
         ]
      }
   ],
   "serviceSpecRelationship": [
      {
         "relationshipType": "composed_of",
         "id": "65033023ebdb30107ee5302698522849",
         "validFor": {
            "startDateTime": "2017-08-25T00:00",
            "endDateTime": "2021-03-25T00:00"
         }
      }
   ],
   "@type": "ResourceFacingServiceSpecification"
}