--- sourceDocument: Yokohama IT Operations Management sourceDocumentLink: https://servicenow-prod.fluidtopics.net/r/yokohama/it-operations-management Release : - yokohama ft:locale : - en-US ft:publication_title : - Yokohama IT Operations Management ft:clusterId : - itom bundleId : - itom workflow : - Technology --- # Cloud API (CAPI) # Cloud API (CAPI) {#ariaid-title1} * Release version: Yokohama * * Updated January 30, 2025 * * ![](https://www.servicenow.com/docs/portal-asset/ico-clock) 7 minutes to read Summarize ![AI sparkle icon](https://servicenow.com/docs/portal-asset/ai-sparkle-icon) Summarized using AI This content was generated using new OpenAI-powered functionality. Results are provided on an as is basis and are not guaranteed to be accurate or complete. ## Summary of Cloud API (CAPI) The Cloud API (CAPI) enables ServiceNow customers to integrate Cloud Provisioning and Governance with various cloud providers via REST APIs. It facilitates communication with cloud providers like AWS, Azure, and VMware to manage cloud resources directly from your ServiceNow instance. CAPI components provide a structured framework for making REST calls (PUT, GET, POST, DELETE) that create, update, or delete cloud resources, which are then reflected as Configuration Items (CIs) in the CMDB. Show full answer Show less ## Key Features * **Providers and Products:** Pre-configured cloud providers (e.g., AWS, Azure) contain products with specific resource types mapped to CMDB CI types, such as virtual machines. * **Interfaces:** Define reusable REST call structures and operations (methods) with required parameters, standardizing how cloud APIs are called. * **CAPI APIs:** Link products to interfaces and include method mappers implemented as MID Server script includes that execute REST calls to cloud providers. API Config Overrides store credentials and important parameters securely to enable authenticated API calls. * **Resource Blocks:** Represent cloud resources in ServiceNow and use operational steps to invoke CAPI APIs. They process cloud provider responses to update CMDB records, maintaining accurate cloud asset data. * **CMDB Integration:** Cloud resources map to CI classes based on the Virtual Machine Object class. Customers can create new CI classes and identification/relationship rules to support custom or unsupported cloud resource types. * **MID Server Script Includes:** These run on the MID Server to perform REST calls through JavaScript, enabling flexible customization of cloud operations. ## How CAPI Works in Practice When provisioning a cloud resource (e.g., an Azure virtual machine), CAPI uses the provider's product and resource type linked to a CI class, the relevant interface defining methods like *CreateNode*, and a CAPI API with MID Server script includes that execute the REST calls. Credentials and parameters are securely passed via API Config Overrides. Responses from cloud providers update the CMDB to keep resource data current. ## Practical Use and Customization * ServiceNow customers can extend providers by adding new products or resource types, creating custom CI classes, and defining identification and relationship rules to preserve CMDB data integrity. * Custom CAPI APIs and MID Server script includes can be developed to implement new or extended cloud provider operations, leveraging base classes like *CloudAPIBase* and *CloudRESTAPIInvoker*. * Understanding cloud provider REST APIs (e.g., Azure's REST API Reference) is essential for creating custom integrations and ensuring correct operation parameters. * Out-of-the-box CAPI APIs for common cloud providers can be reviewed and used as templates or reference implementations for customization. ## Getting Started * Review provided CAPI APIs and classes included with Cloud Provisioning and Governance. * Explore provisioning workflows for Azure and AWS virtual machines to understand component interactions. * Add new products or resource types to existing providers as needed. * Create or extend CAPI interfaces and APIs, including custom MID Server script includes to implement REST calls. The Cloud API (CAPI) enables you to integrate Cloud Provisioning and Governance with cloud providers using REST APIs. ## CAPI components {#cloud-management-api__section_phl_yt4_x2b} Integration with cloud providers is performed through REST calls, such as PUT, GET, POST, and DELETE. CAPI provides the framework for you to integrate a cloud vendors REST API so that your instance can communicate with the cloud provider to manage cloud resources. See [Browse APIs by product](https://www.servicenow.com/docs/access?context=api-product-type&version=yokohama&pubname=yokohama-api-reference&ft:locale=en-US) to learn more. CAPI contains these components: Figure 1. CAPI overview Providers : Cloud providers are the clouds that you can connect to. By default, Cloud Provisioning and Governance includes the most commonly used providers, such as AWS, Azure, and VMware. Each provider has many products, each of which provide resource types. Each resource type maps to a single CI type. For example, the AWS provider includes the AWS Elastic Compute Cloud product, which includes the AWS::EC2::Instance resource type. This resource type is one of the most common cloud resources that you can create. It maps directly to the Virtual Machine Instance \[cmdb_ci_vm_instance\] CI type, where virtual machines are saved in the CMDB. Interfaces : Interfaces define the framework that the system needs to structure the REST calls that the cloud provider APIs expect. Interfaces define operations, also called methods, and the parameters that each method requires. Interfaces are reusable. If you extend CAPI to include new products and APIs, you can use existing interfaces to make the same REST calls. APIs : CAPI APIs are the core component of CAPI that ties a product and interface together. The APIs include the actual code that the system executes. Each CAPI API includes these components: * CAPI Method Mappers provide the methods that are mapped to the operations defined in the interface. From CAPI method mappers, you create MID Server script includes in JavaScript to tell the cloud provider exactly what to do. It is through the script includes that the connection to the cloud provider occurs. Note: If you create custom CAPI APIs, the system provides an empty script include for you to customize. You can also modify existing script includes on method mappers if necessary. However, many of the default APIs that come with the Cloud Provisioning and Governance application do not use modifiable script includes. The connections are hard-coded in Java. You can still use these APIs in new resource blocks that you create, but you cannot modify the APIs. * API Config Overrides contain the identity, such as a key, and credentials, such as the secret key, and other important parameters required by the cloud provider. These parameters help the cloud provider perform the operations in the CAPI Method Mappers related list. API Config Overrides are necessary because, when the system calls the cloud provider API via REST, credential data is not included. Resource blocks use the parameters and values that you define in the API Config Overrides to query the credential store. When your API executes, the attributes are made available to all method calls in your script includes. The overrides are scoped only for this API. The overrides do not override anything in other APIs. {#cloud-management-api__ul_ynn_zbp_x2b} Because you can define multiple versions of a CAPI API with slight variations, you can extend (without overwriting) an existing API while retaining desired functionality. This image illustrates the components of CAPI that are used when you provision an Azure virtual machine using the default CAPI settings provided with Cloud Provisioning and Governance:Figure 2. CAPI Azure In this example, the Microsoft.Compute product is contained in the Azure provider. Azure uses the Microsoft.Compute product for virtual machines. In your instance, the Microsoft.Compute product maps to the Microsoft.Compute/virtualMachines resource type, which is associated to the Virtual Machine Instance CI type in the CMDB. The Compute interface contains definitions for methods like CreateNode, which defines how to create the actual virtual machine. Of the many parameters that CreateNode uses, Location captures the datacenter where the virtual machine resides. The Azure Compute API pulls together the Microsoft.Compute product and the structure defined in the Compute interface. The implementation of the CreateNode method calls the azure-compute-1.0-CreateNode MID Server script include, which calls the AzureComputeVirtualMachine MID Server script include. The script includes make the actual calls to the Azure API. To access the Azure account, the SecretKey, ClientID, TenantID, and other methods are passed in Config Overrides. ## How CAPI integrates with the instance {#cloud-management-api__section_oj2_dw4_x2b} CAPI integrates these components in your instance: Cloud Provisioning and Governance resource blocks : A resource block represents a single cloud resource, such as a virtual server, virtual server storage, or a datacenter. You can also think of it as a CI type in the CMDB. You put many resource blocks together in a blueprint, which appears as a catalog item (also called a stack) to your users in the Cloud Catalog. In the system, each resource block is like a container that references CAPI, and links responses from the cloud provider to a specific CI. Resource blocks use: * Operational steps that call CAPI for each operation, such as the provision operation, and pass along necessary parameter values that the cloud provider needs to execute the operation. * Response processors that process and parse the REST response from the provider and update records in the CMDB. {#cloud-management-api__ul_gfn_frq_x2b} The CMDB : Each resource block is based on a CI type from the CMDB. For Cloud Provisioning and Governance, all cloud-related CI types are based on the Virtual Machine Object CI class, which provides all the attributes that you need for all the cloud resources supported by default. If a CI type for a cloud resource does not exist in the base system, you must create a new CI class and add the necessary attributes. If you do create a new CI class, you must also create: * A CI class for each of the resources that are available to your users. All CI classes are based on the virtual machine object class. * An identification rule that specifies an Object ID. Whenever components of Cloud Management refer to a specific cloud resource in the CMDB, they need the Object ID to find the correct cloud resource. * A relationship rule that specifies how the CI class for the resource is related to other CI classes. For example, a virtual server CI must have a Hosted on::Hosts relationship with a datacenter CI. These relationship rules are necessary for CI uniqueness when processed by the Identification and Reconciliation Engine (IRE). The combination of the service account, the object ID of the resource, and the datacenter (or location) where the resource is located determines the uniqueness. {#cloud-management-api__ul_vll_zgq_x2b} MID Server script include : Each operation in the CAPI API has a MID Server script include that you configure. The script include calls the JavaScript classes that are already in other script includes in the system, or JavaScript classes that you create. Eventually, the invoker class is called to trigger the REST call. MID Server script includes are configured on your ServiceNow instance, but run on the MID Server. This image illustrates how the components work together when a user provisions a resource from the Cloud User Portal: ## REST calls to the cloud provider {#cloud-management-api__section_sys_p4j_hfb} REST calls to the cloud provider are triggered from the MID Server script includes that are referenced from scripted CAPI Method Mappers inside CAPI API records. To create your own CAPI APIs, or to create custom MID Server script includes (which are part of CAPI Method Mappers), you must understand: * The classes that are available for you to call in MID Server script includes. See [CAPI classes in MID Server script includes](https://servicenow-prod.fluidtopics.net/dbxHPAoxs8tRDstTwTPJIA "Cloud Provisioning and Governance provides several JavaScript classes that make REST calls to cloud providers. These classes are called from MID Server script includes (for Azure by default) or from Java calls in the system (for AWS by default). If you create custom providers, interfaces, or CAPI APIs (for any cloud provider), you can use MID Server script includes to call the classes."). * How the cloud provider implements REST. See: * [Azure REST API Reference](https://docs.microsoft.com/en-us/rest/api/azure/) * [AWS Guides and API References](https://docs.aws.amazon.com/index.html#lang/en_us) {#cloud-management-api__ul_ax3_fsj_hfb} {#cloud-management-api__ul_ysk_trj_hfb} For example, to learn how to make a REST call to Azure to create a resource group, review this Azure topic: [Resource Groups - Create Or Update](https://docs.microsoft.com/en-us/rest/api/resources/resourcegroups/createorupdate). You can find the endpoint, parameters, and request body that Azure requires, and the responses it provides. You can see that: * The endpoint is `management.azure.com` * The method to call with a PUT operation is `subscriptions/{subscriptionId}/resourcegroups/{resourceGroupName}?api-version=2018-02-01`, where you specify the subscription ID, the resource group name, and the API version. {#cloud-management-api__ul_y12_kwj_hfb} Remember that the REST API calls take place inside the MID Server script includes that are associated with CAPI API method mappers. Call the methods that CAPI already makes available for you by using the classes extended from CloudAPIBase and CloudRESTAPIInvoker. You can also create more script includes to extend these base classes and create your own classes. Familiarize yourself with these base classes and the methods available within them. ## Get started here {#cloud-management-api__section_odh_vlh_n2b} 1. [Review CAPI APIs that are provided with Cloud Provisioning and Governance by default](https://servicenow-prod.fluidtopics.net/RolLhhB8~VeKVVapQD94rg "Several CAPI APIs are provided by default with the Cloud Provisioning and Governance application."). 2. [Review the CAPI classes that are provided by default](https://servicenow-prod.fluidtopics.net/dbxHPAoxs8tRDstTwTPJIA "Cloud Provisioning and Governance provides several JavaScript classes that make REST calls to cloud providers. These classes are called from MID Server script includes (for Azure by default) or from Java calls in the system (for AWS by default). If you create custom providers, interfaces, or CAPI APIs (for any cloud provider), you can use MID Server script includes to call the classes."). These classes can be called from the MID Server script includes in your CAPI API operations. 3. Walk through the provisioning of an [Azure virtual machine](https://servicenow-prod.fluidtopics.net/8WnsTG9SAAzmGSOmmoVHOw "This example walks you through the components of Cloud Provisioning and Governance that function during the provisioning of a virtual machine in an Azure datacenter. Topics covered include blueprints, resource blocks, the Cloud API (CAPI), and MID Server script includes.") and an [AWS virtual machine](https://servicenow-prod.fluidtopics.net/XsJcdnMCEBTyhLxGPteFKw "This example walks you through the components of Cloud Provisioning and Governance that function during the provisioning of a virtual machine in an AWS datacenter. Topics covered include blueprints, resource blocks, the Cloud API (CAPI), and MID Server script includes.") to see how the components work together. The Azure walkthrough uses a MID Server script include so you can see the various CAPI classes used in the provision operation. The AWS walkthrough does not use a MID Server script include. 4. [Add a product to an existing provider in CAPI](https://servicenow-prod.fluidtopics.net/cDmru5rlrhJZ_79w79DH7w "The Cloud Provisioning and Governance Cloud API (CAPI) offers many providers, such as AWS and Azure, and products, such as EC2 instances. However, you can add products to existing providers for new types of cloud resources."). 5. [Create a CI class for a virtual cloud resource](https://servicenow-prod.fluidtopics.net/AncR85at9DOKMZf2_kB_CA "If the base system does not provide a CI type for cloud-based virtual resources, you can create a CI class based on the virtual machine object class."). 6. [Create or extend a CAPI interface](https://servicenow-prod.fluidtopics.net/M_qbUXdy3YyTSG2jb8zr5Q "You can create a new CAPI interface or extend an existing one by adding new operations."). 7. [Create a CAPI API](https://servicenow-prod.fluidtopics.net/uTxEhJSV5DXMWx5odnGzMw "If the existing CAPI APIs do not integrate with the CAPI interface for a provider, you can create an API. The steps in resource blocks can call your API methods when operations are executed."), and a custom MID Server script include that makes the REST calls to the cloud provider. An empty MID Server script include is always generated for new CAPI APIs. Modify it with the calls to other JavaScript classes and methods, such as the methods in the Invoker class. {#cloud-management-api__ol_zdd_yby_2fb}