Cloud Services Catalog API

  • Release version: Xanadu
  • Updated August 1, 2024
  • 26 minutes to read

    • The Cloud Services Catalog API provides methods related to Day-1 (provisioning) and Day-2 (modification) operations available in the Cloud Services Catalog, such as creating cloud service stacks and calling resource operation requests. You can also retrieve information about catalog requests, stacks getting status, and other information.

    This API is included in the now namespace and requires the sn_cmp.cloud_service_user role. The Cloud Services Catalog (CSC) application is available as a separate subscription and requires either the ITOM Enterprise bundle or ITOM Cloud Accelerate product Entitlement.

    The Cloud Services Catalog API features actions you perform during Day 2 operations. In the context of this API, resource catalog items refer to catalog items related to Day 2 operations.

    To use this API, ensure that you have completed the Cloud Services Catalog guided setup process or have a working configuration where provisioning and catalog operations are working in the UI. For more information about these steps, see Cloud Services Catalog.

    Cloud Services Catalog - GET /now/cmp_catalog_api/itemsbyciclass

    Returns a list of resource catalog items based on a given configuration item (CI) class.

    URL format

    Default URL: /api/now/cmp_catalog_api/itemsbyciclass

    Supported request parameters

    Table 1. Path parameters
    Name Description
    None
    Table 2. Query parameters
    Name Description
    ci_class Required. Name of the CI class to get the resource catalog items from (for example, "cmdb_ci_vm_instance"). Located in the Reference CI Type field in the Configuration Item [cmdb_ci] table.

    Data type: String
    display_variables Flag that indicates whether to list catalog item variables associated with each catalog item.
    Valid values:
    • true: Displays list catalog item variables.
    • false: Doesn't display list catalog item variables.

    Data type: Boolean

    Default: False
    operation_name Optional. Name of the operation. Located in the Name column of the resource interface in the OperationSignature [sn_cmp_rb_op_signature] table.
    Note:
    This parameter can query part or whole of the operation. For example, if you want to list all interfaces starting with "Servicenow", you can set the variable as operation_name = Servicenow.

    Default: All catalog items of all operation types are returned.

    Data type: String
    resource_interface Optional. Resource interface that the resource catalog item is hosted on. Located in the Name column of the ResourceInterfaces [sn_cmp_rb_resourceinterface] table.

    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 have not been passed.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    active The active state of the resource operation catalog item.

    Possible values:

    • true: The resource operation catalog item is active.
    • false: The resource operation catalog item is inactive.

    Data type: String
    created_on Time stamp from when the resource operation catalog item was created.

    Format: yyyy-MM-dd HH:mm:ss.

    Data type: String
    display_name Name of the resource interface. Located in the ResourceInterfaces [sn_cmp_rb_resourceinterface] table.

    Data type: String
    id Sys_id of the resource operation catalog item. Located in the Resource Operation Catalog Item [sn_cmp_rsrc_opr_cat_item] table.

    Data type: String
    name Name of the resource operation catalog item. Located in the Resource Operation Catalog Item [sn_cmp_rsrc_opr_cat_item] table.

    Data type: String
    short_description Brief description of the resource operation catalog item. Located in the Resource Operation Catalog Item [sn_cmp_rsrc_opr_cat_item] table.

    Data type: String
    updated_on Time stamp from when the resource operation catalog item was last updated. Required format: yyyy-MM-dd HH:mm:ss.

    Data type: String

    cURL request

    The following example requests and returns the status of the request item.

    curl "https://instance.servicenow.com/api/now/cmp_catalog_api/itemsbyciclass?ci_class=cmdb_ci_vm_instance&resource_interface=Virtual%20Machine%20Store%20Extension%20Interface&operation_name=Execute%20Job%20Template" \
--request GET \ 
--header 'Accept: application/json' \ 
--user 'username':'password'

    Response:

    [
  {
    "display_name": "Virtual Server-Virtual Machine Store Extension Interface-Execute Job Template",
    "id": "01b2341a56789012345d6ddeeff7b89fc",
    "created_on": "2019-04-28 12:58:26",
    "updated_on": "2019-04-28 12:58:26",
    "name": "Virtual Server-Virtual Machine Store Extension Interface-Execute Job Template",
    "short_description": "Catalog item to invoke operation",
    "active": true
  }
]

    Cloud Services Catalog - GET /now/cmp_catalog_api/itemsbyrb

    Returns a list of resource catalog items based on a given resource block.

    URL format

    Default URL: /api/now/cmp_catalog_api/itemsbyrb

    Supported request parameters

    Table 7. Path parameters
    Name Description
    None
    Table 8. Query parameters
    Name Description
    display_variables Flag that indicates whether to list catalog item variables associated with each catalog item.
    Valid values:
    • true: Displays list catalog item variables.
    • false: Doesn't display list catalog item variables.

    Data type: Boolean

    Default: False
    operation_name Optional. Name of the operation. Located in the Name column of the resource interface in the OperationSignature [sn_cmp_rb_op_signature] table.
    Note:
    This parameter can query part or whole of the operation. For example, if you want to list all interfaces starting with "Servicenow", you can set the variable as operation_name = Servicenow.

    Default: All catalog items of all operation types are returned.

    Data type: String
    resource_block Required. The name of the resource block to get its related resource operation catalog items from (for example, Virtual Server). Available in the Resource Block [sn_cmp_rb_resourceblock] table.

    Default: All catalog items of all operation types are returned.

    Data type: String
    resource_interface Optional. Resource interface that the resource catalog item is hosted on. Located in the Name column of the ResourceInterfaces [sn_cmp_rb_resourceinterface] 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. Supported types: application/json or application/xml.

    Default: 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 have not been passed.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    active The active state of the resource operation catalog item.

    Possible values:

    • true: The resource operation catalog item is active.
    • false: The resource operation catalog item is inactive.

    Data type: String
    display_name Name of the resource interface. Located in the ResourceInterfaces [sn_cmp_rb_resourceinterface] table.

    Data type: String
    id Sys_id of the resource operation catalog item. Located in the Resource Operation Catalog Item [sn_cmp_rsrc_opr_cat_item] table.

    Data type: String
    name Name of the resource operation catalog item. Located in the Resource Operation Catalog Item [sn_cmp_rsrc_opr_cat_item] table.

    Data type: String
    short_description Brief description of the resource operation catalog item. Located in the Resource Operation Catalog Item [sn_cmp_rsrc_opr_cat_item] table.

    Data type: String
    variables List of extra details about the resource catalog item. The variables returned in this API vary based on the query parameters that were passed.

    Data type: Array of objects

    "variables": [
  {
    "parameter1": "String",
    "parameter2": "String"
  }
]

    This example list of resource catalog items based on a Virtual Server resource block:

    curl "https://instance.servicenow.com/api/now/cmp_catalog_api/itemsbyrb?resource_interface=Virtual%20Machine%20Store%20Extension%20Interface&operation_name=Execute%20Job%20Template&resource_block=Virtual%20Server" \
--request GET \ 
--header 'Accept: application/json' \ 
--user 'username':'password'

    Response:

    [
  {
    "display_name": "Virtual Server-Virtual Machine Store Extension Interface-Execute Job Template",
    "id": "01b2341a56789012345d6ddeeff7b89fc",
    "created_on": "2019-04-28 12:58:26",
    "updated_on": "2019-04-28 12:58:26",
    "name": "Virtual Server-Virtual Machine Store Extension Interface-Execute Job Template",
    "short_description": "Catalog item to invoke operation",
    "active": true
  }
]

    Cloud Services Catalog - GET /now/cmp_catalog_api/services

    Returns a list of catalog items based on the given blueprint of a Provision or Lifecycle catalog type.

    URL format

    Default URL: /api/now/cmp_catalog_api/services

    Supported request parameters

    Table 13. Path parameters
    Name Description
    None
    Table 14. Query parameters
    Name Description
    catalog_type Optional. Type of catalog item. Accepted values (case-sensitive):
    • Provision - Returns all Blueprint type catalog items.
    • LifeCycle - Returns all Day 2 Operation type catalog items.

    If the input is empty (default), all services of both catalog types are returned.

    Data type: String
    display_variables Flag that indicates whether to list catalog item variables associated with each catalog item.
    Valid values:
    • true: Displays list catalog item variables.
    • false: Doesn't display list catalog item variables.

    Data type: Boolean

    Default: False
    blueprint_name Optional. Name of the blueprint in which to fetch the related catalog items. Located in the Category Item [sn_cmp_bp_cat_item] table.
    Note:
    This parameter can query part or whole of the blueprint name. For example, if you want to list all blueprints starting with "Servicenow", you can set the variable as blueprint_name = Servicenow.

    Default: all services of all blueprints are returned.

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

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

    Default: application/json
    Table 17. 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 18. 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.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    active Flag that indicates whether the catalog is active.
    Possible values:
    • true: Catalog is active.
    • false: Catalog isn't active.

    Data type: String
    blueprint sys_id of the blueprint. Located in the Blueprint [sn_cmp_bp_blueprint] table.

    Data type: String
    blueprint_category sys_id of the blueprint category. Located in the Cloud Service Category [sn_capi_service_category] table.

    Data type: String
    blueprint_category_name Name of the blueprint category. Located in the Cloud Service Category [sn_capi_service_category] table.
    Possible values:
    • Access
    • Analytics
    • Application Services
    • Blockchain
    • Business Productivity
    • Compute
    • Config Management
    • Containers
    • Database
    • Developer Tools
    • Event
    • Hybrid Cloud
    • IOT
    • IPAM
    • Loud Balancer
    • Machine Learning
    • Management Tools
    • Marketplace
    • Mobile
    • Network
    • Productivity
    • Security
    • Shell Access
    • Storage
    • Tools
    • Unknown
    • Virtual Reality

    Data type: String
    blueprint_name Name of the blueprint. Located in the Blueprint [sn_cmp_bp_blueprint] table.

    Data type: String
    blueprint_type Type of blueprint.

    Possible value: Custom Blueprint

    Data type: String
    catalog_name Name of the catalog. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    catalog_type The type of catalog. Possible values:
    • 1: Catalog is of type provision.
    • 2: Catalog is of type lifecycle.

    Data type: String
    catalog_type The type of catalog. Possible values:
    • 1: Catalog is of type provision.
    • 2: Catalog is of type lifecycle.

    Data type: String
    createdOn Time stamp from when the catalog item was created.

    Data type: String
    createdBy User that created the catalog item.

    Data type: String
    id sys_id of the blueprint. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    last_updated_on Time stamp from when the catalog item was last updated.

    Data type: String
    last_updated_by User that last updated the catalog item, such as an admin or the system.

    Data type: String
    operation sys_id of the operation. Available in the OperationSignature [sn_cmp_rb_op_signature] table.
    operation_name Name of the operation. Possible values:
    • Start: Starts the resources that are in an off state.
    • Stop: Stops the resources that are in an on state.
    • ModifySchedule: Modifies the schedule for provisioned resources.
    • Deprovision: Deletes resources with a terminated state and updates resource CMDB tables accordingly.
    • ModifyLease: Modifies the lease operation scheduled on provisioned resources.

    Data type: String
    variables An object containing extra details about the list catalog item. The variables returned in this API vary based on the query parameters that are passed in the request.

    Data type: Object

    
    "variables": [
      {
        "parameter1": "String",
        "parameter2": "String"
      }
    ]

    This example returns all the catalog items of a Lifecycle type blueprint named "classiclb".

    curl "https://instance.servicenow.comapi/now/cmp_catalog_api/services?display_variables=true&catalog_type=LifeCycle&blueprint_name=classiclb" \
--request GET \ 
--header 'Accept: application/json' \ 
--user 'username':'password'

    Response:

    [
  {
    "catalog_name": "Deprovision",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "active": true,
    "category": "86d85478678232005ca552e457415a79",
    "blueprint_category_name": "Compute",
    "shortDescription": "Are you sure you want to perform this operation?",
    "id": "01b2341a56789012345d6ddeeff7b89fc",
    "variables": [
      {
        "id": "a12d34c5678c91234bf45678912d34e4",
        "name": "StackID",
        "question_text": "StackID",
        "default_value": "Not specified"
      }
    ],
    "last_updated_on": "2024-02-19 07:46:03",
    "last_updated_by": "system",
    "catalog_type": "2",
    "created_on": "2024-02-19 07:46:02",
    "created_by": "user@password.com",
    "operation": "a70d51c0476c46104bf15222516d4375",
    "blueprint_type": "Custom Blueprint",
    "operation_name": "Deprovision"
  },
  {
    "catalog_name": "ModifySchedule",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "active": true,
    "category": "86d85478678232005ca552e457415a79",
    "blueprint_category_name": "Compute",
    "shortDescription": null,
    "id": "361d55c0476c46104bf15222516d4351",
    "variables": [
      {
        "id": "031d55c0476c46104bf15222516d43af",
        "name": "ScheduleProfile",
        "question_text": "ScheduleProfile",
        "default_value": "Not specified"
      },
      {
        "id": "0b1d55c0476c46104bf15222516d43c9",
        "name": "ScheduleTimeZone",
        "question_text": "ScheduleTimeZone",
        "default_value": "Not specified"
      }
    ],
    "last_updated_on": "2024-02-19 07:45:53",
    "last_updated_by": "system",
    "catalog_type": "2",
    "created_on": "2024-02-19 07:45:52",
    "created_by": "user@password.com",
    "operation": "130d51c0476c46104bf15222516d436c",
    "blueprint_type": "Custom Blueprint",
    "operation_name": "ModifySchedule"
  },
  {
    "catalog_name": "Stop",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "active": true,
    "category": "86d85478678232005ca552e457415a79",
    "blueprint_category_name": "Compute",
    "shortDescription": "Are you sure you want to perform this operation?",
    "id": "542dd5c0476c46104bf15222516d43b0",
    "variables": [
      {
        "id": "a02d19c0476c46104bf15222516d4301",
        "name": "StackID",
        "question_text": "StackID",
        "default_value": "Not specified"
      }
    ],
    "last_updated_on": "2024-02-19 07:46:00",
    "last_updated_by": "system",
    "catalog_type": "2",
    "created_on": "2024-02-19 07:45:58",
    "created_by": "user@password.com",
    "operation": "930d51c0476c46104bf15222516d436f",
    "blueprint_type": "Custom Blueprint",
    "operation_name": "Stop"
  },
  {
    "catalog_name": "Cleanup",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "active": true,
    "category": "86d85478678232005ca552e457415a79",
    "blueprint_category_name": "Compute",
    "shortDescription": "Are you sure you want to perform this operation?",
    "id": "712d59c0476c46104bf15222516d435c",
    "variables": [
      {
        "id": "da2d59c0476c46104bf15222516d43dc",
        "name": "resourceId",
        "question_text": "ResourceId",
        "default_value": "Not specified"
      },
      {
        "id": "da2d59c0476c46104bf15222516d43e2",
        "name": "operationName",
        "question_text": "OperationName",
        "default_value": "Not specified"
      }
    ],
    "last_updated_on": "2024-02-19 07:46:06",
    "last_updated_by": "system",
    "catalog_type": "2",
    "created_on": "2024-02-19 07:46:04",
    "created_by": "user@password.com",
    "operation": "ab0d51c0476c46104bf15222516d437b",
    "blueprint_type": "Custom Blueprint",
    "operation_name": "Cleanup"
  },
  {
    "catalog_name": "ModifyLease",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "active": true,
    "category": "86d85478678232005ca552e457415a79",
    "blueprint_category_name": "Compute",
    "shortDescription": null,
    "id": "bb1dd5c0476c46104bf15222516d4301",
    "variables": [
      {
        "id": "142dd5c0476c46104bf15222516d4382",
        "name": "resourceId",
        "question_text": "ResourceId",
        "default_value": "Not specified"
      },
      {
        "id": "d82dd5c0476c46104bf15222516d4394",
        "name": "operationName",
        "question_text": "OperationName",
        "default_value": "Not specified"
      }
    ],
    "last_updated_on": "2024-02-19 07:45:58",
    "last_updated_by": "system",
    "catalog_type": "2",
    "created_on": "2024-02-19 07:45:56",
    "created_by": "user@password.com",
    "operation": "2b0d51c0476c46104bf15222516d4378",
    "blueprint_type": "Custom Blueprint",
    "operation_name": "ModifyLease"
  },
  {
    "catalog_name": "Start",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "active": true,
    "category": "86d85478678232005ca552e457415a79",
    "blueprint_category_name": "Compute",
    "shortDescription": "Are you sure you want to perform this operation?",
    "id": "d71d95c0476c46104bf15222516d4312",
    "variables": [
      {
        "id": "731d95c0476c46104bf15222516d43ae",
        "name": "resourceId",
        "question_text": "ResourceId",
        "default_value": "Not specified"
      },
      {
        "id": "731d95c0476c46104bf15222516d43b4",
        "name": "operationName",
        "question_text": "OperationName",
        "default_value": "Not specified"
      }
    ],
    "last_updated_on": "2024-02-19 07:45:55",
    "last_updated_by": "system",
    "catalog_type": "2",
    "created_on": "2024-02-19 07:45:54",
    "created_by": "user@password.com",
    "operation": "270d51c0476c46104bf15222516d4372",
    "blueprint_type": "Custom Blueprint",
    "operation_name": "Start"
  }
]

    Cloud Services Catalog - GET /now/cmp_catalog_api/stacks

    Returns a list of catalog items based on Provision-type blueprints (also known as stacks).

    URL format

    Default URL: /api/now/cmp_catalog_api/stacks

    Supported request parameters

    Table 19. Path parameters
    Name Description
    None
    Table 20. Query parameters
    Name Description
    blueprint_name Optional. Name of the blueprint in which to fetch the related catalog items. Located in the Category Item [sn_cmp_bp_cat_item] table.
    Note:
    This parameter can query part or whole of the blueprint name. For example, if you want to list all blueprints starting with "Servicenow", you can set the variable as blueprint_name = Servicenow.

    Default: all services of all blueprints are returned.

    Data type: String
    display_variables Flag that indicates whether to list catalog item variables associated with each catalog item.
    Valid values:
    • true: Displays list catalog item variables.
    • false: Doesn't display list catalog item variables.

    Data type: Boolean

    Default: False
    Table 21. 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 22. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: 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
    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.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    active Flag that indicates whether the catalog is active.
    Possible values:
    • true: Catalog is active.
    • false: Catalog isn't active.

    Data type: String
    blueprint sys_id of the blueprint. Located in the Blueprint [sn_cmp_bp_blueprint] table.

    Data type: String
    blueprint_category sys_id of the blueprint category. Located in the Cloud Service Category [sn_capi_service_category] table.

    Data type: String
    blueprint_category_name Name of the blueprint category. Located in the Cloud Service Category [sn_capi_service_category] table.
    Possible values:
    • Access
    • Analytics
    • Application Services
    • Blockchain
    • Business Productivity
    • Compute
    • Config Management
    • Containers
    • Database
    • Developer Tools
    • Event
    • Hybrid Cloud
    • IOT
    • IPAM
    • Loud Balancer
    • Machine Learning
    • Management Tools
    • Marketplace
    • Mobile
    • Network
    • Productivity
    • Security
    • Shell Access
    • Storage
    • Tools
    • Unknown
    • Virtual Reality

    Data type: String
    blueprint_name Name of the blueprint. Located in the Blueprint [sn_cmp_bp_blueprint] table.

    Data type: String
    blueprint_type Type of blueprint.

    Possible value: Custom Blueprint

    Data type: String
    catalog_name Name of the catalog. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    catalog_type The type of catalog. Possible values:
    • 1: Catalog is of type provision.
    • 2: Catalog is of type lifecycle.

    Data type: String
    catalog_type_name The name of the catalog type. Possible values:
    • Provision Operation (Day 1): Catalog type is named provision.
    • LifeCycle Operation (Day 2): Catalog type is named lifecycle.

    Data type: String
    id sys_id of the blueprint. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    lifecycleOperations Object containing the life cycle operation's name and sys_id.

    Date type: Array of objects

    "lifecycleOperations": [
      {
        "id": "String",
        "name": "String"
      }
    lifecycleOperations.id sys_id of the life cycle operation. Available in the OperationSignature [sn_cmp_rb_op_signature] table.
    lifeCycleOperations.name Type of life cycle operations. Possible values:
    1. Deprovision: Deletes resources in a terminated state and updates resource CMDB tables accordingly.
    2. ModifySchedule: Performs business hours scheduling on stacks at the time of provisioning or on existing stacks.
    3. Stop: Stops the resources that are in an on state.
    4. Cleanup: Cleans up resources with a terminated state.
    5. ModifyLease: Modifies the lease operation scheduled on provisioned resources.
    6. Start: Starts the resources that are in an off state.

    Date type: Object
    operation sys_id of the operation. Available in the OperationSignature [sn_cmp_rb_op_signature] table.
    operation_name Name of the operation. Possible values:
    • Start: Starts the resources that are in an off state.
    • Stop: Stops the resources that are in an on state.
    • ModifySchedule: Modifies the schedule for provisioned resources.
    • Deprovision: Deletes resources with a terminated state and updates resource CMDB tables accordingly.
    • ModifyLease: Modifies the lease operation scheduled on provisioned resources.

    Data type: String
    shortDescription A brief description of the catalog.

    Data type: String
    template_name Name of the template. Available in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    template_type sys_id of the template type. Available in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    template_cloud_product_name Name of the product. Available in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    variables An object containing extra details about the list catalog item. The variables returned in this API vary based on the query parameters that are passed in the request.

    Data type: Object

    
    "variables": [
      {
        "parameter1": "String",
        "parameter2": "String"
      }
    ]

    The following example returns all catalog items in the instance with the provision catalog type.

    curl "https://instance.servicenow.com/api/now/cmp_catalog_api/stacks" \
--request GET \ 
--header 'Accept: application/json' \ 
--user 'username':'password'

    Return:

    [
  {
    "catalog_type": "1",
    "catalog_type_name": "Provision Operation (Day 1)",
    "catalog_name": "classiclb",
    "blueprint": "d90d9d80476c46104bf15222516d43b9",
    "blueprint_name": "classiclb",
    "blueprint_category": "57c0dbd9934b22004a9032bfa67ffb79",
    "blueprint_category_name": "Compute",
    "active": true,
    "category": "8641fe260b212200eff7ef9bb4673a3d",
    "shortDescription": null,
    "id": "07cc9580476c46104bf15222516d43c3",
    "last_updated_on": "2024-02-19 07:46:13",
    "last_updated_by": "user@servicenow.com",
    "blueprint_type": "Cloud Template",
    "template_type": "932f81e49f00320048111f80a57fcf6e",
    "template_name": "CloudFormation Template",
    "template_cloud_product": "52cfc4749f00320048111f80a57fcf9a",
    "template_cloud_product_name": "AWS CloudFormation",
    "lifecycleOperations": [
      {
        "id": "1d2d19c0476c46104bf15222516d4392",
        "name": "Deprovision"
      },
      {
        "id": "361d55c0476c46104bf15222516d4351",
        "name": "ModifySchedule"
      },
      {
        "id": "542dd5c0476c46104bf15222516d43b0",
        "name": "Stop"
      },
      {
        "id": "712d59c0476c46104bf15222516d435c",
        "name": "Cleanup"
      },
      {
        "id": "bb1dd5c0476c46104bf15222516d4301",
        "name": "ModifyLease"
      },
      {
        "id": "d71d95c0476c46104bf15222516d4312",
        "name": "Start"
      }
    ],
    "created_on": "2024-02-19 07:44:44",
    "created_by": "user@servicenow.com",
    "operation": "130d51c0476c46104bf15222516d4368",
    "operation_name": "Provision"
  }
]

    Cloud Services Catalog - GET /now/cmp_catalog_api/status

    Returns the status and details of a given catalog RITM (request item).

    Use this method to identify and trace the request's origin and monitor its flow. The response includes the following:
    1. RITM number for the submitted request
    2. The stage the request is in
    3. The users who opened and is assigned the request
    4. The group assigned to the request
    5. When the request was opened
    6. The state the request is in
    7. Submission data

    URL format

    Default URL: /api/now/cmp_catalog_api/status

    Supported request parameters

    Table 25. Path parameters
    Name Description
    None
    Table 26. Query parameters
    Name Description
    req_item Unique request item number in the Requested Item [sc_req_item] table. For example, RITM0000001.

    Data type: String
    Table 27. 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 28. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: 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.
    400 Bad Request. A bad request type or malformed request was detected.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    assignmentGroup The group assigned to the request.

    Data type: String
    assignedTo The user email assigned to the request.

    Data type: String
    catItem sys_id of the catalog item request. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    error A message with details about a returned error. Possible error messages:
    • Record Not Found: The request item doesn't exist.
    • User Not Authenticated: The user's credentials aren't authorized to make this request.

    Data type: String
    number The unique Request Item Number (RITM) given to the new request item. Located in the Request Item [sc_req_item] table.

    Data type: String
    openedAt Time stamp from when the request item was opened.

    Format: yyyy-MM-dd HH:mm:ss.

    Date type: String
    openedBy sys_id of the user who opened the request.

    Data type: String
    stage Current processing stage of the request item.
    Possible values:
    • Task Created for User
    • Deployment Successful
    • Waiting for Provision Approval
    • Resource Limit Exceeded
    • Deployment Failed
    • Deployment Cancelled
    • Retrying Stack Deployment
    • Deploying Stack

    Data type: String
    state The current completion state of the request item.
    Possible values:
    • Open
    • Work in Progress
    • Closed Complete
    • Closed Incomplete
    • Closed Skipped
    • Pending

    Data type: String
    submissionData Information about the request submission, like cloud account, location, application, and cost center data. Submission data varies depending on the request item number passed in the request.

    Data type: Object

    "submissionData": "{\"key1\":\"value\", \"key2\":\"value\"}"
}
    sys_id sys_id of the request item record. Located in the Request Item [sc_req_item] table.

    Data type: String

    cURL request

    The following example returns status information for the request item number, RITM0010076.

    curl "https://instance.servicenow.com/api/now/cmp_catalog_api/statusreq_item=RITM0010076" \
--request GET \ 
--header 'Accept: application/json' \ 
--user 'username':'password'

    Response:

    { 
  "catItem": "39737024c390719005091d75e0013115", 
  "stage": "Task Created for User", 
  "sys_id": "ee1197db476cc2904bf15222516d439f", 
  "assignedTo": null, 
  "assignmentGroup": null, 
  "number": "RITM0010072", 
  "openedAt": "2024-02-29 18:32:55", 
  "openedBy": "6816f79cc0a8016401c5a33be04be441", 
  "state": "Open", 
  "submissionData": "{\"CloudAccount\":\"AzureCA\",\"CSC_Azure_Functions_newResourceGroup\":\"test-rg-dnd\",\"CSC_Azure_Functions_runTimeVersion\":\"~18\",\"CSC_Azure_Functions_runTimeEngine\":\"node\",\"CSC_Azure_Functions_os\":\"Windows\",\"CSC_Azure_Functions_functionAppName\":\"sa02291029-fa\",\"LeaseEndDate\":\"2024-05-29 17:29:57\",\"ScheduleProfile\":\"-- No Schedule --\",\"UserGroup\":\"cfcbad03d711110050f5edcb9e61038f\",\"CSC_Azure_Functions_applicationName\":\"function-app\",\"ScheduleTimeZone\":\"America/Los_Angeles\",\"BusinessService\":\"\",\"environment\":\"Production\",\"CostCenter\":\"\",\"UseExistingWorkspace\":false,\"CSC_Azure_Functions_existingResourceGroup\":\"cpg-dnd\",\"CSC_Azure_Functions_isNewResourceGroup\":\"false\",\"CSC_Azure_Functions_storageAccountName\":\"sa02291029fasa\",\"Application\":\"\",\"StackName\":\"sa02291029\",\"Location\":\"Azure Datacenter - eastus\",\"Workspace\":\"\"}" 
}

    Cloud Services Catalog - POST /now/cmp_catalog_api/submitoprequest

    Submits a resource operation request to perform day 2 operations on provisioned resources.

    URL format

    Default URL: /api/now/cmp_catalog_api/submitoprequest

    Supported request parameters

    Table 31. Path parameters
    Name Description
    None
    Table 32. Query parameters
    Name Description
    cat_id Required. sys_id of the cloud catalog item to invoke. Available in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    Table 33. Request body parameters (XML or JSON)
    Name Description
    CloudAccount Required. Name of the cloud account in which to submit the request. Account names are available in the Cloud Account [cmdb_ci_cmp_cloud_account] table.

    Data type: String
    Location Required. Datacenter location in which to provision the resource. For example, us-west-1 or asia-south-2. This value should match the datacenter location of the cloud account's platform provider. Available in the Associated Datacenter [sn_cmp_ca_assc_datacenter] table.

    Data type: String
    StackName Required. Name of the stack. The stack name is dynamic and is reflected in resource management.

    Data type: String
    resourceId Required. The sys_id of the resource where Day 2 operations will be performed. Located in the Stack Items [sn_cmp_stack_item] table.
    resource_block Required. The name of the resource block to get its related resource operation catalog items from (for example, Virtual Server). Available in the Resource Block [sn_cmp_rb_resourceblock] table.

    Default: All catalog items of all operation types are returned.

    Data type: String
    operation_name Optional. Name of the operation. Located in the Name column of the resource interface in the OperationSignature [sn_cmp_rb_op_signature] table. The operation name you enter depends on the value passed in the resourceBlock parameter.
    Note:
    This parameter can query part or whole of the operation. For example, if you want to list all interfaces starting with "Servicenow", you can set the variable as operation_name = Servicenow.
    Default: All catalog items of all operation types are returned.Data type: String
    resourceInterface Required. The name of the resource block to get its related resource operation catalog items from (for example, Virtual Server). Available in the Resource Block [sn_cmp_rb_resourceblock] table. The resource interface you enter depends on the value passed in the resourceBlock and operation_name parameters.

    Default: All catalog items of all operation types are returned.

    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 34. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: 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.
    400 Bad Request. A bad request type or malformed request was detected.
    401 Unauthorized. The user credentials are incorrect or have not been passed.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    assignmentGroup The group assigned to the request.

    Data type: String
    assignedTo The user email assigned to the request.

    Data type: String
    catItem sys_id of the catalog item request. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    number The unique Request Item Number (RITM) given to the new request item. Located in the Request Item [sc_req_item] table.

    Data type: String
    openedAt Time stamp from when the request item was opened.

    Format: yyyy-MM-dd HH:mm:ss.

    Date type: String
    openedBy sys_id of the user who opened the request.

    Data type: String
    stage Current processing stage of the request item.
    Possible values:
    • Task Created for User
    • Deployment Successful
    • Waiting for Provision Approval
    • Resource Limit Exceeded
    • Deployment Failed
    • Deployment Cancelled
    • Retrying Stack Deployment
    • Deploying Stack

    Data type: String
    state The current completion state of the request item.
    Possible values:
    • Open
    • Work in Progress
    • Closed Complete
    • Closed Incomplete
    • Closed Skipped
    • Pending

    Data type: String
    submissionData Information about the request submission, like cloud account, location, application, and cost center data. Submission data varies depending on the request item number passed in the request.

    Data type: Object

    "submissionData": "{\"key1\":\"value\", \"key2\":\"value\"}"
}
    sys_id sys_id of the request item record. Located in the Request Item [sc_req_item] table.

    Data type: String

    The following example creates a Day 2 operation request item.

    curl "https://instance.servicenow.com/api/now/cmp_catalog_api/submitoprequest?cat_id=e44dcd238731e5101126cbb4dabb3506" /
--request POST\ 
--header 'Accept: application/json' \ 
--user 'username':'password'

//Request body:
{"StackName":"sa02292143","CloudAccount":"AWS","Location":"AWS Datacenter - us-east-1","resourceId":"df8c61e3eb2cc210d298fbbdbad0cd74","operationName":"Deprovision","resourceInterface":"S3 Interface","resourceBlock":"S3"}

    Response body:

    { 
  "number": "RITM0010078", 
  "catItem": "e44dcd238731e5101126cbb4dabb3506", 
  "stage": "request_approved", 
  "sys_id": "9bf5cab3c3594610bc89b33605013190", 
  "assignedTo": null, 
  "assignmentGroup": null, 
  "openedAt": "2024-04-08 09:08:47", 
  "openedBy": "6816f79cc0a8016401c5a33be04be441", 
  "state": "Open", 
  "submissionData": "{\"StackName\":\"sa02292143\",\"CloudAccount\":\"AWS\",\"Location\":\"AWS Datacenter - us-east-1\",\"resourceId\":\"df8c61e3eb2cc210d298fbbdbad0cd74\",\"operationName\":\"Deprovision\",\"resourceInterface\":\"S3 Interface\",\"resourceBlock\":\"S3\"}" 
} 
 
Sample Request Body for CSC S3 Bucket Catalog Order: 
 
{"StackName":"sa02292143","CloudAccount":"AWS","Location":"AWS Datacenter - us-east-1","resourceId":"df8c61e3eb2cc210d298fbbdbad0cd74","operationName":"Deprovision","resourceInterface":"S3 Interface","resourceBlock":"S3"}

    Cloud Services Catalog - POST /now/cmp_catalog_api/submitrequest

    Submits a cloud services request. This method accepts provisioned requests for both day 2 operations and stacks or resource operation catalog items.

    URL format

    Default URL: /api/now/cmp_catalog_api/submitrequest

    Supported request parameters

    Table 37. Path parameters
    Name Description
    None
    Table 38. Query parameters
    Name Description
    cat_id Required. sys_id of the cloud catalog item to invoke. Available in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    Table 39. Request body parameters (XML or JSON)
    Name Description
    CloudAccount Required. Name of the cloud account in which to submit the request. Account names are available in the Cloud Account [cmdb_ci_cmp_cloud_account] table.

    Data type: String
    Location Required. Datacenter location in which to provision the resource. For example, us-west-1 or asia-south-2. This value should match the datacenter location of the cloud account's platform provider. Available in the Associated Datacenter [sn_cmp_ca_assc_datacenter] table.

    Data type: String
    StackName Required. Name of the stack. The stack name is dynamic and is reflected in resource management.

    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 40. Request headers
    Header Description
    Accept Data format of the response body. Supported types: application/json or application/xml.

    Default: application/json
    Table 41. 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 42. 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.
    403 Forbidden. The user doesn't have access rights to the specified record.
    404 Not found. The requested item wasn't found.
    405 Invalid method. The functionality is disabled.
    500 Internal server error. An unexpected error occurred while processing the request. The response contains additional information about the error.

    Response body parameters (JSON or XML)

    Name Description
    assignmentGroup The group assigned to the request.

    Data type: String
    assignedTo The user email assigned to the request.

    Data type: String
    catItem sys_id of the catalog item request. Located in the Cloud Catalog Item [sn_cmp_bp_cat_item] table.

    Data type: String
    number The unique Request Item Number (RITM) given to the new request item. Located in the Request Item [sc_req_item] table.

    Data type: String
    openedAt Time stamp from when the request item was opened.

    Format: yyyy-MM-dd HH:mm:ss.

    Date type: String
    openedBy sys_id of the user who opened the request.

    Data type: String
    stage Current processing stage of the request item.
    Possible values:
    • Task Created for User
    • Deployment Successful
    • Waiting for Provision Approval
    • Resource Limit Exceeded
    • Deployment Failed
    • Deployment Cancelled
    • Retrying Stack Deployment
    • Deploying Stack

    Data type: String
    state The current completion state of the request item.
    Possible values:
    • Open
    • Work in Progress
    • Closed Complete
    • Closed Incomplete
    • Closed Skipped
    • Pending

    Data type: String
    submissionData Information about the request submission, like cloud account, location, application, and cost center data. Submission data varies depending on the request item number passed in the request.

    Data type: Object

    "submissionData": "{\"key1\":\"value\", \"key2\":\"value\"}"
}
    sys_id sys_id of the request item record. Located in the Request Item [sc_req_item] table.

    Data type: String

    The following example submits a cloud resource request in the instance's AWS Cloud Account.

    curl "https://instance.servicenow.com/api/now/cmp_catalog_api/submitrequest?cat_id=022e3deec3122910a769f44ed40131b9" /
--request POST \ 
--header 'Accept: application/json' \ 
--user 'username':'password'

//Request body:
{"CloudAccount":"AWS","Location":"us-east-1","StackName":"ss"}

    Response:

    { 
  "number": "RITM0010001", 
  "catItem": "022e3deec3122910a769f44ed40131b9", 
  "stage": "check_permissions", 
  "sys_id": "86d34233c3594610bc89b336050131dd", 
  "assignedTo": null, 
  "assignmentGroup": null, 
  "openedAt": "2024-04-08 08:59:25", 
  "openedBy": "6816f79cc0a8016401c5a33be04be441", 
  "state": "Open", 
  "submissionData": "{\"CloudAccount\":\"AWS\",\"Location\":\"us-east-1\",\"StackName\":\"ss\"}" 
}