SG Services API

The SG Services API provides endpoints to create and manage application services and the upstream relationships between them.

Request apps on the Store

Visit the ServiceNow Store website to view all the available apps and for information about submitting requests to the store. For cumulative release notes information for all released apps, see the ServiceNow Store release notes.

This API can only be used when the CMDB Application API and CLI (sn_service_graph) plugin is activated. This API is used within the sn_service_graph namespace.

Using this API does not require details regarding source tables or relationship types.

To script critical operations which support automation across the enterprise, you can leverage APIs or run command line operations that the CMDB Application CLI and API store app provide instead of using the user interface. The CMDB Application CLI and API store app provides a robust framework which consolidates all the APIs that are related to application services and the command lines that let you access the interface to those APIs.

CMDB Application CLI and API commands enable the following tasks:

• Registering and creating an application service and establishing upstream relationships
• Getting details of a given application service and its upstream relationships
• Connecting higher level constructs such as business applications and business service offerings
• Populating an application service with a given population type
• Changing the state of an application service

For the command line solution, see CMDB Application CLI and API available commands.

Parent Topic:REST API reference

SG Services – POST /sg_services/app_service/convert

Converts a manual or empty type application service to a calculated application service. During conversion, the application service record moves into the [cmdb_ci_service_calculated] table with the newly assigned class.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/convert

Default URL: /api/sn_service_graph/sg_services/app_service/convert

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

Supported request parameters

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.

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.

Response body parameters (JSON)

cURL request

The following example shows how to convert an application service type.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/convert" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
 \"name\": \"Test Register\",
 \"environment\": \"Test\",
 \"version\": \"1.0\",
 \"levels\" : 8
}" \
--user 'username':'password'

Results indicating a successful conversion to a calculated application service.

{
  "result": {
  "status": "success"
  }
}

SG Services – POST /sg_services/app_service/delete

Deletes an application service.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/delete

Default URL: /api/sn_service_graph/sg_services/app_service/delete

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

Supported request parameters

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.

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.

Response body parameters (JSON)

cURL request

The following example shows how to delete an application service.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/delete" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
   \"name\": \"Test Register\",
   \"environment\": \"Test\",
   \"version\": \"1.0\"
}" \
--user 'username':'password'

Results indicating a successful removal of an application service.

{
  "result": {
  "status": "success"
  }
}

SG Services – POST /sg_services/app_service/find

Finds the details of a given application service and its upstream relationships.

Users with the app_service_user role can use this API, but results are restricted to application services in Operational status. The app_service_admin role provides unlimited viewing of application services.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/find

Default URL: /api/sn_service_graph/sg_services/app_service/find

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

Supported request parameters

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.

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.

Response body parameters (JSON)

</td></tr><tr><td>

relationships.class\_name

</td><td>

Name of the class that contains the application service.Data type: String

</td></tr><tr><td>

relationships.name

</td><td>

Name of the relationship.Data type: String

</td></tr><tr><td>

relationships.number

</td><td>

Unique number of the relationship.Data type: String

</td></tr><tr><td>

relationships.relationship

</td><td>

The relationship rule.Data type: String

</td></tr><tr><td>

relationships.sys\_id

</td><td>

Sys\_id of the relationship.Data type: String

</td></tr><tr><td>

sys\_id

</td><td>

Sys\_id of the application service listed in the Service Instance \[cmdb\_ci\_service\_auto\] table. Data type: String

</td></tr></tbody>
</table>

### cURL request

The following example shows how to find details of an application service.

The response body includes the application service and relationship information.

## SG Services – POST /sg\_services/app\_service/populate

Populates an application service with a service population method.

The following properties for identifying a CI take precedence as follows:

1.  sys\_id – If sys\_id, the system only uses the sys\_id and ignores any additional values.
2.  number – If provided without the sys\_id, the system only uses the number and ignores any additional values.
3.  <IRE field name> – The system only uses these values if the sys\_id or number are not provided.

### URL format

Versioned URL: `/api/sn_service_graph/{api_version}/sg_services/app_service/populate`

Default URL: `/api/sn_service_graph/sg_services/app_service/populate`

**Note:** Available versions are specified in the [REST API Explorer](../rest-api-explorer/use-REST-API-Explorer.md). For scripted REST APIs there is additional version information on the [Scripted REST Service form](../rest-api-explorer/c_CustomWebServices.md).

### Supported request parameters

<table class="rest_api_path_parameters"><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

api\_version

</td><td id="version-entry-RESTAPI">

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

</td></tr></tbody>
</table>

|Name|Description|
|----|-----------|
|None| |

<table class="rest_api_request_body"><thead><tr><th>

Name

</th><th>

Description

</th></tr></thead><tbody><tr><td>

&lt;IRE field name&gt;

</td><td>

One or more IRE fields identifying the application service. For example, name or version. Data type: String

</td></tr><tr><td>

number

</td><td>

Unique number that identifies the application service. Data type: String

</td></tr><tr><td>

population\_method

</td><td>

Required. Identifies the population method and its accompanying property to identify the content for population.Only one accompanying object is valid per type.

 Data type: Object

</td></tr><tr><td>

population\_method.group\_id

</td><td>

Group ID of the CMDB group configured with the cmdb\_group population type.Data type: "String"

 ```
"population_method": {
  "group_id": "String",
  "type": "cmdb_group"
}

 Associated population type: dynamic\_service

 Default: 3 if no level value is set for the sys\_property

</td></tr><tr><td>

population\_method.service\_candidate

</td><td>

Unique identifier of the service candidate.

 Data type: String

 ```
"population_method": {
  "service_candidate": "String",
  "type": "tag_based_service_family"
}

 Associated population type: service\_hierarchy

</td></tr><tr><td>

population\_method.service\_relations.child

</td><td>

Name of a child CI related to the CI.Data type: String

</td></tr><tr><td>

population\_method.service\_relations.parent

</td><td>

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

</td></tr><tr><td>

population\_method.tags

</td><td>

List of objects containing tags to associate with the CI. This information is located in the Key Values \[cmdb\_key\_value\] table.Data type: Array

 ```
"population_method": {

  "tags": [
     {
      "tag": "String",
      "value": "String"
     }
  ],

  "type": "tag_list"  
}

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.

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.

Response body parameters (JSON)

cURL request

The following example shows how to populate an application service with a dynamic_service type.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/populate" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"name\": \"Test Register\",
  \"environment\": \"Test\",
  \"version\": \"1.0\",

 \"population_method\": {
   \"type\": \"dynamic_service\",
   \"levels\" : 8
  }
}" \
--user 'username':'password'

Results indicating a successful population of an application service.

{
  "result": {
  "status": "success"
  }
}

SG Services – POST /sg_services/app_service/register

Creates an application service, tags and constructs upstream relationships such as business applications, business service offerings, and other application services.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/register

Default URL: /api/sn_service_graph/sg_services/app_service/register

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

Supported request parameters

 Maximum number of relationships is 25.

</td></tr><tr><td>

relationships.business\_app

</td><td>

List of objects representing Business Application relationship types. These values can be defined using one of the following items as key-value pairs.

-   &lt;IRE field name&gt;
-   number
-   sys\_id

 Data type: Array

</td></tr><tr><td>

relationships.business\_service\_offering

</td><td>

List of objects representing Business Service Offering relationship types. These values can be defined using the following items as key-value pairs.

-   &lt;IRE field name&gt;
-   number
-   sys\_id

 Data type: Array

</td></tr><tr><td>

relationships.parent\_app\_service

</td><td>

List of objects representing Application Service relationship types. These values can be defined using the following items as key-value pairs.

-   &lt;IRE field name&gt;
-   number
-   sys\_id

 Data type: Array

</td></tr><tr><td>

relationships.technical\_service\_offering

</td><td>

List of objects representing technology management offering \(formerly technical service offering\)relationship types. These values can be defined using the following items as key-value pairs.

-   &lt;IRE field name&gt;
-   number
-   sys\_id

 Data type: Array

</td></tr><tr><td>

sys\_id

</td><td>

Sys\_id of the application service listed in the Service Instance \[cmdb\_ci\_service\_auto\] table. Data type: String

</td></tr><tr><td>

tags

</td><td>

List of objects containing tag definitions as key-value pairs.

 Data type: Array

</td></tr><tr><td>

tags.key

</td><td>

Tag category name.Data type: String

</td></tr><tr><td>

tags.value

</td><td>

Tag value.Data type: String

</td></tr></tbody>
</table>

### 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](../rest-api-explorer/c_RESTAPI.md).

|Header|Description|
|------|-----------|
|Accept|Data format of the response body. Only supports **application/json**.|

|cHeader|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](../rest-api-explorer/c_RESTAPI.md).

|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 the user does 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\)

<table><thead><tr><th>

cHeader

</th><th>

Description

</th></tr></thead><tbody><tr><td>

app\_service

</td><td>

Application service details.Data type: Object

 ```
"app_service": {
  "name": "String",
  "number": "String",
  "sys_id": "String"
}

cURL request

The following example shows how to register an application service.

curl "instance.service-now.com/api/sn_service_graph/sg_services/app_service/register" \--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"name\": \"Test Register\",
  \"environment\": \"Test\",
  \"version\": \"1.0\",
  \"number\": \" SNSVC0001014\",
  \"relationships\": {
    \"business_application\": [
      {
        \"sys_id\": \"0250a94040697410f87713b656474250\"
      },
      {
        \"number\": \"APM0001002\"
      },
      {
        \"name\": \"Test Biz App1\"
      }
    ],
    \"business_service_offering\": [
      {
        \"sys_id\": \"ed32e98040697410f87713b656474259\"
      }
    ],
    \"technical_service_offering\": [
      {
        \"sys_id\": \"80e12d8040697410f87713b65647421c\"
      },
      {
        \"number\": \"BSN0001005\"
      },
      {
        \"name\": \"Tech Service Offering2\"
      }
    ],
    \"parent_app_service\": [
      {
        \"sys_id\": \"a2f0618040697410f87713b656474255\"
      }
    ]
  },
  \"tags\": [
    {
      \"key\": \"key1\",
      \"value\": \"value1\"
    },
    {
      \"key\": \"key2\",
      \"value\": \"value2\"
    }
  ]
}" \
--user 'username':'password'

The response body includes ID and status information.

{
  "result": {
    "app_service": {
      "sys_id": "5780cb604061f410f87713b656474271",
      "name": "Test Register",
      "number": " SNSVC0001014"
    },
    "message": "Service registered successfully",
    "status": "INSERT"
  }
}

SG Services – POST /sg_services/app_service/relationship/create

Constructs upstream relations such as business applications, business service offerings, and other application services.

This API creates a relationship, taking input with a single parent and a corresponding child object.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/relationship/create

Default URL: /api/sn_service_graph/sg_services/app_service/relationship/create

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

Supported request parameters

"child": {
  "<service_app_identifier>": "String"
}

"parent": {
  "<service_app_identifier>": "String",
  "class_name": "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.

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.

Response body parameters (JSON)

cURL request

The following example shows how create a relationship from an application service.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/relationship/create" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"child\": {
   \"name\": \"wdfsdf\",
   \"environment\": \"Test\",
   \"version\": \"1.0\"
   },
  \"parent\": {
   \"sys_id\": \"abcdefg\",
   \"name\": \"business App1\",
   \"class_name\": \"service_offering\"
  }
}" \
--user 'username':'password'

Results indicating a successful creation of an application service relationship.

{
  "result": {
  "status": "success"
  }
}

SG Services – POST /sg_services/app_service/relationship/delete

Deletes an application service upstream relationship.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/relationship/delete

Default URL: /api/sn_service_graph/sg_services/app_service/relationship/delete

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

Supported request parameters

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.

</td></tr><tr><td>

child.&lt;IRE field name&gt;

</td><td>

One or more IRE fields identifying the child application service. For example, name or version.Data type: String

</td></tr><tr><td>

child.number

</td><td>

Unique number that identifies the child application service.Data type: String

</td></tr><tr><td>

child.sys\_id

</td><td>

Sys\_id of the child application service listed in the Service Instance \[cmdb\_ci\_service\_auto\].Data type: String

</td></tr><tr><td>

parent

</td><td>

Details identifying the parent application service from which to remove a relationship.Data type: Object

 ```
"parent": {
  "<IRE field name>": "String",
  "number": "String",
  "sys_id": "String",
  "class_name": "String"
}

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.

Response body parameters (JSON)

cURL request

The following example shows how to remove a relationship from an application service.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/relationship/delete" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  \"child\": {
  \"name\": \"Test Register\",
  \"environment\": \"Test\",
  \"version\": \"1.0\"

  },
  \"parent\": {
   \"sys_id\": \"abcdefg\",
   \"name\": \"business App1\",
   \"class_name\": \"service_offering\"
     }
 }" \
--user 'username':'password'

Results indicating a successful removal of an application service relationship.

{
  "result": {
  "status": "success"
  }
}

SG Services – POST /sg_services/app_service/state

Changes the application service lifecycle state to activate, deactivate, or retire.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/state

Default URL: /api/sn_service_graph/sg_services/app_service/state

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

Supported request parameters

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.

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.

Response body parameters (JSON)

cURL request

The following example shows how to change an application service lifecycle state to activate.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/state" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  {
  \"name\": \"Test Register\",
  \"environment\": \"Test\",
  \"version\": \"1.0\",
  \"state\": \"activate\"
  }
}" \
--user 'username':'password'

Results indicating a successful operation.

{
  "result": {
  "status": "success"
  }
}

SG Services – POST /sg_services/app_service/update

Updates an existing application service provided and creates tags for the given application service.

The following properties for identifying a CI take precedence as follows:

1. sys_id – If sys_id, the system only uses the sys_id and ignores any additional values.
2. number – If provided without the sys_id, the system only uses the number and ignores any additional values.
3. <IRE field name> – The system only uses these values if the sys_id or number are not provided.

URL format

Versioned URL: /api/sn_service_graph/{api_version}/sg_services/app_service/update

Default URL: /api/sn_service_graph/sg_services/app_service/update

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

Supported request parameters

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.

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.

Response body parameters (JSON)

cURL request

The following example shows how to update an application service, using name as an IRE field.

curl "https://instance.service-now.com/api/sn_service_graph/sg_services/app_service/update" \
--request POST \
--header "Accept:application/json" \
--header "Content-Type:application/json" \
--data "{
  {
   \"name\": \"Test Register\",
   \"environment\": \"Test\",
   \"version\": \"1.0\"
  }
}" \
--user 'username':'password'

Response includes application service identification information and updated fields.

{
  "result": {
  "sys_id": "123456",
  "number": "SVCKji0w9e",
  "name": "Test Register",
  "environment": "Test",
  "version": "1.0"
  }
}