The Application Service API provides endpoints that enable you to create, modify, and update application services.

This API requires that the user have the Application Service administrator [app_service_admin] role.

Important: Starting with the Rome release, the Application Service API is no longer enhanced or supported. For details, see the Deprecation Process [KB0867184] article in the Now Support Knowledge Base.

Application Service - GET /now/cmdb/app_service/{sys_id}/getContent

Retrieves a list of configuration items (CI) in a mapped application service and the relationships between them. Only retrieves content for services that were manually created.

URL format

Default URL: /api/now/cmdb/app_service/{sys_id}/getContent

Supported request parameters

Table 1. Path parameters
Name Description
sys_id Sys_id of the mapped application service. Located in the Mapped Application Service [cmdb_ci_service_discovered] table.

Data type: String
Table 2. Query parameters
Name Description
Mode Amount of relationship data to return.
Valid values:
  • Shallow: Return parent and child relationships between CIs within a service.
  • Full: Return CI attributes and lookup information in addition to the data returned in shallow mode.
The values are not case-sensitive.

Data type: String
Table 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.

Table 4. Request headers
Header Description
Accept Data format of the response body. Supported types: application/json or application/xml.

Default: application/json
Table 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.

Table 6. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or they do not have the app_service_admin role.
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
cmdb List of objects that describe the CIs associated with the specified application service.

Data type: Object

"cmdb": [
  {
    "items": {Object},
    "relations": [Array]
  }
]
cmdb.items CIs within the application service. If the full query parameter was passed in the request, this section includes attributes and lookup information for each CI.

Data type: Array

"items": [
  {
    "className": "String",
    "values": {Object}
  }
]
cmdb.items.className Name of the class that contains the CI.

Data type: String
cmdb.items.values Information to use to locate an associated CI.

Data type: Object

"values": {
  "name": "String",
  "sys_id": "String"
}
cmdb.items.values.name Name of the CI.

Data type: String
cmdb.items.values.sys_id Sys_id of the CI.

Data type: String
cmdb.relations Relationship data for associated CIs, such as hosts and their children.

Data type: Array
service List of services related to the identified service.

Data type: Array

"service": [
  {
    "name": "String",
    "service_relations": [Array],
    "url": "String"
  }
]
service.name Name of the application service.

Data type: String
service.service_relations Hierarchy data for the CIs within the application service. All CIs form pairs with a parent and child CI. The top-level CI, referred to as the entry point of an application service, does not have a parent CI.

Data type: Array

"service_relations": [
  {
    "child": "String",
    "parent": "String"
  }
]
service.service_relations.child Name of a child CI related to the CI.

Data type: String
service.service_relations.parent Name of a parent CI related to the CI.

Data type: String
service.url Relative path to the application service.

Data type: String

Example: Sample cURL request

curl "https://instance.servicenow.com/api/now/cmdb/app_service/2fce42d80a0a0bb4004af34d7e3984c8/getContent?mode=shallow" \
--request GET \
--header "Accept:application/json" \
--user 'username':'password'
{
  "service": {
    "name": "PeopleSoft Portals",
    "url": "/api/now/table/cmdb_ci_service_discovered/2fce42d80a0a0bb4004af34d7e3984c8",
    "service_relations": [
      {
        "parent": "",
        "child": "3a2810c20a0a0bb400268337d6e942ca"
      },
      {
        "parent": "3a27f1520a0a0bb400ecd6ff7afcf036",
        "child": "3a5dd3dbc0a8ce0100655f1ec66ed42c"
      },
      {
        "parent": "3a290cc60a0a0bb400000bdb386af1cf",
        "child": "3a307c930a0a0bb400353965d0b8861f"
      },
      {
        "parent": "3a172e820a0a0bb40034228e9f65f1be",
        "child": "3a27d4370a0a0bb4006316812bf45439"
      },
      {
        "parent": "",
        "child": "3a172e820a0a0bb40034228e9f65f1be"
      },
      {
        "parent": "",
        "child": "3a27f1520a0a0bb400ecd6ff7afcf036"
      },
      {
        "parent": "3a2810c20a0a0bb400268337d6e942ca",
        "child": "3a290cc60a0a0bb400000bdb386af1cf"
      }
    ]
  },
  "cmdb": {
    "relations": [],
    "items": [
      {
        "values": {
          "sys_id": "3a172e820a0a0bb40034228e9f65f1be",
          "name": "PS LoadBal01"
        },
        "className": "cmdb_ci_win_server"
      },
      {
        "values": {
          "sys_id": "3a2810c20a0a0bb400268337d6e942ca",
          "name": "PS Apache03"
        },
        "className": "cmdb_ci_web_server"
      },
      {
        "values": {
          "sys_id": "55b35562c0a8010e01cff22378e0aea9",
          "name": "ny8500-nbxs08"
        },
        "className": "cmdb_ci_netgear"
      },
      {
        "values": {
          "sys_id": "3a27f1520a0a0bb400ecd6ff7afcf036",
          "name": "PS Apache02"
        },
        "className": "cmdb_ci_web_server"
      },
      {
        "values": {
          "sys_id": "3a307c930a0a0bb400353965d0b8861f",
          "name": "PS ORA01"
        },
        "className": "cmdb_ci_database"
      }
    ]
  }
}

Application Service - GET /now/cmdb/csdm/app_service/find_service

Returns basic information about a specified application service and its associated business context.

Note: This endpoint has been deprecated, use SG Services – POST – /sg_services/app_service/find instead.

URL format

Default URL: /api/now/cmdb/csdm/app_service/find_service

Supported request parameters

Table 7. Path parameters
Name Description
None
Table 8. Query parameters
Name Description
name Required, if number is not passed in. Name of the service for which to return information. Located in the Application Service [cmdb_ci_service_auto] table.

Data type: String
number Required, if name is not passed in. Unique number that identifies the application service for which to return information. Located in the Application Service [cmdb_ci_service_auto] table.

Data type: String
Table 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.

Table 10. Request headers
Header Description
Accept Data format of the response body. Only supports application/json.
Table 11. 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.

Table 12. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or they do not have the app_service_admin role.
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
error Describes an encountered error.

Data type: Object

"error": {
  "details": "String",
  "message": "String"
}
error.details Additional information about the error.

Data type: String
error.message Message describing the error.

Data type: String
services Array of objects, each object containing details of services associated with the specified application service.

Data type: Array

"services": [
  {
    "environment": "String",
    "name": "String",
    "number": "String",
    "relationships": {Object},
    "sys_id": "String",
    "version": "String"
  }
]
services.environment Environment in which the application service is deployed, such as "Production" or "Test Lab 2." This can be any value that makes sense to the implementer.

Data type: String

Maximum length: 40

Default: null
services.name Required. Name of the application service. Must be a unique name from all other application services.

Data type: String

Maximum length: 255
services.number Unique number that identifies the application service. This value is initially generated by the endpoint.

Data type: String
services.relationships Service types associated with the application service.

Data type: Object

"relationships": {
  "business_app": [Array],
  "business_service_offering": [Array],
  "technical_service_offering": [Array]
}
services.relationships.business_app List of sys_ids of the business applications related to the application service.

Data type: Array
services.relationships.technical_service_offering List of sys_ids of the business service offerings related to the application service.

Data type: Array
services.relationships.business_service_offering List of sys_ids of the technical service offerings related to the application service.

Data type: Array
services.sys_id Sys_id of the application service.

Data type: String
services.version Application service version number.

Data type: String

Maximum length: 40

Format: User definable

Default: null

Example: Sample cURL request

curl -X GET \
  https://instance.servicenow.com/api/now/cmdb/csdm/app_service/find_service?name=Email_East&number=SNSVC0001018 \
  -H 'Accept: application/json' \
  -u 'username':'password'

{
"result": {
  "services": [
    {
      "name": "Email_East",
      "number": "SNSVC0001018",
      "sys_id": "f809cb60db94101037740f95ca96190f",
      "environment": "Production",
      "version": "1.1.1",
      "relationships": {
        "business_app": [
          "658c7620db54101037740f95ca9619f2"
        ],
        "technical_service_offering": [],
        "business_service_offering": [
          "069c7e20db54101037740f95ca9619bf"
        ]
      }
    }
  ]
 }
}

Application Service - POST /now/cmdb/app_service/create

Creates an application service or update an existing application service.

URL format

Default URL: /api/now/cmdb/app_service/create

Supported request parameters

Table 13. Parameters
Parameter 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.

Table 14. Request 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
Table 15. Response headers
Header Description
None

Status codes

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.

Table 16. Status codes
Status code Description
200 Successful. The request was successfully processed.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or have not been passed.

Request body

The API accepts these JSON elements in the request body. In addition, you can add any field from the Mapped Application Service [cmdb_ci_service_discovered] table to pass data to the application service record. For example, to add content to the Comments field, add "comments": "Passing data to the Comments field" to the JSON request.

Table 17. Elements accepted in the request body
Element Description
name Name of the application service you wish to create or update.
service_relations Information about CIs and the hierarchy they form. All CIs form pairs with a parent CI and a child CI. The top-level CI, referred to as the entry point of an application service, does not have a parent CI.
parent Sys_ id of the CI whose outgoing connection joins this CI with the CI at the lower level in the map hierarchy.
child Sys_ id of the CI whose incoming connection joins this CI with the CI located of the higher level in the map hierarchy.

Response body

The API returns these JSON elements in the response body.

Table 18. Elements returned in the response body
Element Description
URL URL of the standard table REST API for showing the sys_id of an application service record.

This element appears only if the endpoint is successful.

Data type: String
getContentUrl REST API path for getting the application service content.

This element appears only if the endpoint is successful.

Data type: String
info Number of CIs added to the application service.

This element appears only if the endpoint is successful.

Data type: String
error Error message details.

This element appears only if the endpoint fails.

Data type: Object
message Error message describing the nature of the failure.

This element appears only if the endpoint fails.

Data type: String
status States "failure" if the REST API fails.

This element appears only if the endpoint fails.

Data type: String

Example: Sample cURL request

curl "http://<instance.servicenow.com>/api/now/cmdb/app_service/create" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
\"name\": \"myTestAppService\",
\"comments\": \"Passing data to the Comments field\",
\"service_relations\": [
{ \"parent\": \"\",
\"child\": \"3a70f789c0a8ce010091b0ea635b982a\"
},{ \"parent\": \"3a70f789c0a8ce010091b0ea635b982a\",
\"child\": \"b4fd7c8437201000deeabfc8bcbe5dc1\"
},{ \"parent\": \"b4fd7c8437201000deeabfc8bcbe5dc1\",
\"child\": \"53fdbc8437201000deeabfc8bcbe5d10\"
}
]
}" \
--user 'admin':'admin'
{
  "result": {
    "url": "/api/now/table/cmdb_ci_service_discovered/b1cff89fc9e19300964fcbb1ac3059a5",
    "getContentUrl": "/api/now/cmdb/app_service/b1cff89fc9e19300964fcbb1ac3059a5/getContent",
    "info": "3 CIs added to service"
  }
}

Application Service - POST /now/cmdb/csdm/app_service/register_service

Creates an application service record stub in the Application Service [cmdb_ci_service_auto] table and populates it with the passed in information.

Before storing the record, it validates the passed parameters and the uniqueness of the application service name. It also creates upstream relationships which provide business context to the service by associating the specified business applications, business service offerings, and technical service offerings to the service application. It does not create downstream relationships to infrastructure. To define downstream relationships you must call the Application Service - PUT /now/cmdb/csdm/app_service/{service_sys_id}/populate_service endpoint.
Note: This endpoint has been deprecated, use SG Services – POST – /sg_services/app_service/register instead.

URL format

Default URL: /api/now/cmdb/csdm/app_service/register_service

Supported request parameters

Table 19. Path parameters
Name Description
None
Table 20. Query parameters
Name Description
None
Table 21. Request body parameters
Name Description
basic_details Required. Details of the service associated with the specified application service.

Data type: Object

"basic_details": {
  "environment": "String",
  "name": "String",
  "version": "String"
}
basic_details.environment Environment in which the application service is deployed, such as "Production" or "Test Lab 2." This can be any value that makes sense to the implementer.

Data type: String

Maximum length: 40

Default: null
basic_details.name Required. Name of the application service. Must be a unique name from all other application services.

Data type: String

Maximum length: 255
basic_details.version Application service version number.

Data type: String

Maximum length: 40

Format: User definable

Default: null
relationships Upstream (parent) service types to associate with the application service. These relationships are stored in the CI Relationships [cmdb_rel_ci] table.

Data type: Object

"relationships": {
  "business_app": [Array],
  "business_service_offering": [Array],
  "technical_service_offering": [Array]
}
relationships.business_app List of sys_ids of the business applications to relate to the application service.

Data type: Array
relationships.business_service_offering List of sys_ids of the business service offerings to relate to the application service.

Data type: Array
relationships.technical_service_offering List of sys_ids of the technical service offerings to relate to the application service.

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.

Table 22. 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.
Table 23. 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.

Table 24. Status codes
Status code Description
201 Successful. The application service was successfully registered.
400 Bad Request. A bad request type or malformed request was detected.
401 Unauthorized. The user credentials are incorrect or they do not have the app_service_admin role.
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
error Describes an encountered error.

Data type: Object

"error": {
  "details": "String",
  "message": "String"
}
error.details Additional information about the error.

Data type: String
error.message Message describing the error.

Data type: String
number Unique number that identifies the application service. This number is generated by the endpoint.
service_sys_id Sys_id of the registered application service.

Example: Sample cURL request

curl -X POST \
  https://instance.servicenow.com/api/now/cmdb/csdm/app_service/register_service \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password'
  -d '{
  "basic_details": {
    "environment": "Test Lab 2",
    "name": "Test Lab 2",
    "version": "1.1.1"
  },
  "relationships": {
    "business_app":["f07c7620db54101037740f95ca96199a"],
    "business_service_offering":["069c7e20db54101037740f95ca9619bf"]
  }
}'
{
  "result": {
    "service_sys_id": "80f21bbadbd410103d3a93c3e296199a",
    "number": "SNSVC0001018    
    }
}

Application Service - PUT /now/cmdb/csdm/app_service/{service_sys_id}/populate_service

Populates the specified application service with a specified set of downstream configuration items (CI).

Before calling this endpoint, you must call the POST /now/cmdb/csdm/app_service/register_service endpoint to create the application service.
Note: This endpoint has been deprecated, use SG Services – POST – /sg_services/app_service/populate instead.

URL format

Default URL: /api/now/cmdb/csdm/app_service/{service_sys_id}/populate_service

Supported request parameters

Table 25. Path parameters
Name Description
service_sys_id Sys_id of the application service to populate with the specified CIs. Located in the Application Service [cmdb_ci_service_auto] table.

Data type: String
Table 26. Query parameters
Name Description
None
Table 27. Request body parameters (XML or JSON)
Name Description
population_method CIs to associate with the specified application service. The elements in the populate_method object depend on the type of information being populated; defined by the type parameter.

Data type: Object

For type = cmdb_group_based

{
  "population_method": {
    "group_id": "String",
    "type": "String"
  }
}
For type = discovery
Note: To use this type you must activate the Service Mapping (com.snc.service-mapping) plugin.
{
  "population_method": {
    "attributes": [Array],
    "entry_point_id": "String",
    "type":"String"
  }
}
For type = tag_list
Note: To use this type you must activate the Service Mapping (com.snc.service-mapping) plugin.
{
  "population_method": {
    "tags":[Array],
    "type":"String"  }
}
population_method.attributes List of attributes to associate with the CI, such as host, port, name, and URL.

For additional information on entry points, see Entry point attributes.

Note: You must pass all required attributes.

Data type: Array

{
  "attributes": {
    "name":"String",
    "value":"String"
  }
}
population_method.attributes.name Name of the attribute, such as host, port, name, and URL.

Data type: String
population_method.attributes.value Attribute value.

Data type: String
population_method.entry_point Required if population_method.type = discovery. Entry point into the application service. For additional information on entry points, see Entry point attributes and Create entry point types for Service Mapping.

Data type: String
population_method.group_id Required if population_method.type = cmdb_group_based. Sys_id of the group to associate with the CI. Located in the CMDB Group [cmdb_group] table.

Data type: String
population_method.tags List of tags to associate with the CI. This information is located in the Key Values [cmdb_key_value} table.

Data type: Array

{
  "tags": {
    "tag": "String",
    "value": "String"
  }
}
population_method.tags.tag Name of the tag.

Data type: String
population_method.tags.value Tag value.

Data type: String
population_method.type Required. Type of CI to populate.
Valid values:
  • cmdb_group_based
  • discovery
  • tag_list

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.

Table 28. 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.
Table 29. 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.

Table 30. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or they do not have the app_service_admin role.
500 Internal server error. An unexpected error occurred while processing the request.

Response body parameters (JSON or XML)

Name Description
error Describes an encountered error.

Data type: Object

"error": {
  "details": "String",
  "message": "String"
}
error.details Additional information about the error.

Data type: String
error.message Message describing the error.

Data type: String

Example: Sample cURL request

The following code example shows how to populate an application service when the CI type is cmdb_group_based.

curl -X PUT \
  https://instance.servicenow.com/api/now/cmdb/csdm/app_service/f809cb60db94101037740f95ca96190f/populate_service \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
  "population_method": {
    "type":"cmdb_group_based",
    "group_id": "e809cf60db94101037640f95ca961932"
  }
}'
{
    "result": {}
}

The following code example shows how to populate a discovery application service.

curl -X PUT \
  https://instance.servicenow.com/api/now/cmdb/csdm/app_service/f809cb60db94101037740f95ca96190f/populate_service \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
  "population_method": {
    "type":"discovery",
    "entry_point_id":"cmdb_ci_endpoint_ad_forest",
    "attributes": [
      {
        "name":"host",
        "value":"test1.com"
      },
      {
        "name":"port",
        "value":"500"
      },
      {
        "name":"protocol",
        "value":"ssh"
      }
    ]
  }
}'
{
    "result": {}
}

Application Service - PUT /now/cmdb/csdm/app_service/{service_sys_id}/service_details

Updates the specified application service with the passed in basic information.

It also validates the uniqueness of the application service by checking the passed in information against the Identification and Reconciliation engine (IRE) rules defined on the application service class.
Note: This endpoint has been deprecated, use SG Services – POST – /sg_services/app_service/update instead.

URL format

Default URL: /api/now/cmdb/csdm/app_service/{service_sys_id}/service_details

Supported request parameters

Table 31. Path parameters
Name Description
service_sys_id Sys_id of the application service to updated. Located in the Application Service [cmdb_ci_service_auto] table.

Data type: String
Table 32. Query parameters
Name Description
None
Table 33. Request body parameters (XML or JSON)
Name Description
basic_details Details of the service associated with the specified application service.

Data type: Object

"basic_details": {
  "environment": "String",
  "name": "String"
}
basic_details.environment Environment in which the application service is deployed, such as "Production" or "Test Lab 2." This can be any value that makes sense to the implementer.

Data type: String

Maximum length: 40

Default: null
basic_details.name Required. Name of the application service. Must be a unique name from all other application services.

Data type: String

Maximum length: 255
relationships Service types to associate with the application service. Located in the CI Relationships [cmdb_rel_ci] table.

Data type: Object

"relationships": {
  "business_app": [Array],
  "business_service_offering": [Array],
  "technical_service_offering": [Array]
}
relationships.business_app List of sys_ids of the business applications to relate to the application service.

Data type: Array
relationships.business_service_offering List of sys_ids of the business service offerings to relate to the application service.

Data type: Array
relationships.technical_service_offering List of sys_ids of the technical service offerings to relate to the application service.

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.

Table 34. 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.
Table 35. 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.

Table 36. Status codes
Status code Description
200 Successful. The request was successfully processed.
401 Unauthorized. The user credentials are incorrect or they do not have the app_service_admin role.

Response body parameters (JSON or XML)

Name Description
error Describes an encountered error.

Data type: Object

"error": {
  "details": "String",
  "message": "String"
}
error.details Additional information about the error.

Data type: String
error.message Message describing the error.

Data type: String

Example: Sample cURL request

curl -X PUT \
  https://instance.servicenow.com/api/now/cmdb/csdm/app_service/f809cb60db94101037740f95ca96190f/service_details \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -u 'username':'password' \
  -d '{
  "basic_details": {
    "environment": "Test Lab 2"
  },  "relationships": {
    "business_app" :["f07c7620db54101037740f95ca96199a"]
  }
}'
{
    "result": {}
}