Cloud Services

Enterprise Marketplace

Consume Operations Template
Published On Oct 04, 2024 - 9:29 AM

Consume Operations Template

Create templates for any standard and custom operations.
The Consume Operations Template (COT) simplifies Day2 Operation onboarding in platform. Note that to run an operation on a specific SOC/SOI, you are required to define an operation template that can then be associated with the operation definition. A template is a JSON-formatted text file that describes the steps to run the operation. Additionally, to run a template, the corresponding APIs must be defined and onboarded first to the Provider API Registry.

Types of COT templates

The following types of COT templates are available:
  • Execution Template:
     Every custom operation must have an execution template.
  • Execution Failure Template:
     This template is useful if part of an execution failed and you need to restart the execution. This is an optional template for all operations.
  • Status Template:
     This template is used to check the status of an operation execution. This is a mandatory template for all operations.
For any kind of template, the basic template anatomy remains the same. However, some basic assumptions and rules must be followed for status and failure templates. By default, all the parameters that are defined in the execution template along with the variables (if resolved) are available during failure template execution. Therefore, you can refer to those parameters in the failure template without having to explicitly define them in the parameter sections of the failure template.
The status template can define only a single parameter. The output that you define in the execution template is the input to the status template as parameters. Therefore, the type of parameter of status template must be of type object because the output of any execution template is always a JSON object as it is defined in the output section.

Template anatomy

The template anatomy is composed of several major sections. The only required sections are ResourceOperations and the Output.

ContentVersion (optional)

ContentVersion refers to the COT version that the template conforms to. The current version is 1.0. If not specified, the default version is assumed.

Name (optional)

The Name provides a name for the template to help identify it.

Parameters (optional)

Values to pass to your template at run time (when you run an operation). You can refer to parameters from the ResourceOperation, Variables, and Output sections of the template. Note that to describe the parameters, the name and type of the parameters must be defined. There are three types of parameters:
  • String
  • Number
  • Object
The following example shows two parameters that are being defined: resourceId and requestor. 
"parameters":{
        "resourceId":{
            "type":"string"
        },
        "requestor":{
            "type":"string"

        }
}
For you to access any parameters in the definition of any other section, you must use
${parametername}
. If the type of parameter is an object, you can access any field by using the path of the field, such as
${parametername}.field1
,
${parametername}.field2.child3
, and so on. If you need to extract information from the object by running a complex logic, you can do that with a variable. For more information, see Variables.

Resource Operations

The Resource Operations part of the template specifies the API IDs and its parameters that are needed to run the operation. Running an operation can involve calling multiple APIs. Output of one API might need to be fed as input into another API. However, you are not required to maintain the order of the API IDs defined in here. The template engine can detect if one API has a dependency on another one.
When you declare the resource operations, the API IDs must match with one of the API definitions that were onboarded in the provider API registry. In addition, the parameters of the resource operation must match with the parameters that are declared in the API definition. You can think of the parameters of the API definition as the declaration of parameters for a function definition. The parameters of the resource operation are equivalent to a call to that function. 
"resourceOperations":{
        "vra/vtsStop":{

            "resourceId": "${resourceId}",
            "actionId": "cc4ecb6b-337e-4a9d-ae72-07a12c556283",
            "providerRequestor": "${requestor}"
        }
    }
If you want to refer to the output of the API execution in any other section, variable, or resourceOperation, use
${apiId}
. In the previous example, the output of the API execution can be imported using
${vra/vtsStop}
.

Variables

In the Variables section, you can declare an internal variable for your template to hold a value after it processes some related data. Variables are optional. This section was given limited programming capability when the variable is declared. The variable definition can contain a JavaScript function implementation or proper JavaScript notation to allow the variable to access any internal field of an object. You can declare a variable if you want to process some data received from an API response, from a payload of another API request, or to process the input parameters. Variables can process primitive data as well as JSON data.

Output

The Output section is a mandatory section in the template that describes the values that are returned. The output must declare the output variables into which the output of the template execution is copied. The behavior of output variables is the same as that of normal variables. Therefore, all the capabilities available in normal variables are also present in the output variables. The only difference is that all these variables will be returned after template execution in a wrapped JSON object.
The output variables can be defined as shown in the following example: 
"output":  {
       "tracking": "${vra/vtsStop}",
       "message": "Success"

   }
For that example, the output will be as follows: 
{
 "tracking" : {} // whatever is the end result of processing the variable expression
 "message" : "Success"
}

Examples of COT templates

The following are some examples of COT templates.

Example of string processing

Consider a case where the template has two input parameters of type string. If you want to call an API, you must concatenate the string before it is passed as a parameter value to an API call (resource operation) as shown in the following example: 
"parameters":{
    "paramA":{
       "type": "string"
   },
  "paramB":{
       "type": "string"
   }
}
"resourceOperations":{
   "startVM":{
      "payload": ${concatenatedInput}
   }
}
"variables":{
  "concatenatedInput": ${paramA}+"-"+${paramB}
}

Example of number processing

The following shows a case where you must divide a number before it is sent to an API request: 
"parameters":{
    "paramA":{
       "type": "number"
   },
 }
"resourceOperations":{
   "addDisk":{
      "numberOfDisk": ${dividedBy2}
   }
}
"variables":{
  "dividedBy2": ${paramA}/2
}

Example of object processing

Consider a case where, two consecutive API calls must be made to run an operation. Output of the first API is a JSON object that needs to be processed to extract a sub document that is then fed as a parameter into the next API call. In the following example, you are adding the same type of disk as the ones that are already present. Therefore, the first API call must be made to check the current disk details and then that disk type information is used when you add any additional disks. 
"parameters":{
    "resourceId":{
       "type": "string"
   },
  "size":{
       "type": "number"
   }
}
"resourceOperations":{
   "getDiskDetails":{
      "diskId": ${resourceId}
   },
   "addDisk":{
     "type":"${disktype}",
     "size" :"${size}"
   }
}
"variables":{
  "disktype": "${getDiskDetails}.type"
}

Example of functional processing

The following example is a more complicated version of the previous example. In this case, if the disk type is SSD, you would want to double the size. Otherwise, the system should use the size mentioned in the parameters. 
"parameters":{
    "resourceId":{
       "type": "string"
   },
  "size":{
       "type": "number"
   }
}
"resourceOperations":{
   "getDiskDetails":{
      "diskId": ${resourceId}
   },
   "addDisk":{
     "type":"${disktype}",
     "size" :"${newsize}"
   }
}
"variables":{
   "disktype": "${getDiskDetails}.type",
   "newsize": "function(diskDetails){ if(diskDetails.type==='SDD') {return diskDetails.size*2}else{return ${size}}}(${getDiskDetails})"
}

Provider API Registry

Any API that is referred to by the template must first be onboarded in the Provider API Registry by a user with the System Integrator role. The APIs to onboard the API definition of any provider API are as follows:
  • To accept an array or create an API definition, use
    /apiregistry/providers/<providerId>/<versionId>/apis
     with the method POST.
  • To get the API definition by IDs, run
    /apiregistry/providers/<providerId>/<versionId>/apis?apiIds=["id"]
     using the method GET.
  • To delete a single API definition, run
    /apiregistry/providers/<providerId>/<versionId>/apis/
    using the method DELETE.
  • To update a single API definition, run
    /apiregistry/providers/<providerId>/<versionId>/apis/
     using the method PUT.
  • To deletes all APIs under a provider, run
    /apiregistry/providers/<providerId>/<versionId>
     using the method DELETE.

API Definition Anatomy

In the API definition there are several properties that may be required to be entered. At this time it is possible to provide definition only for REST API over json/xml.
  • schema (optional):
     This is the schema reference of the API definition. It should be similar to .
  • contentVersion (optional):
     This is the version ID of the schema definition.
  • id (mandatory):
     This is the ID of the API definition by which the API can be referred to in the template. The API ID must be unique inside a single provider type. All the APIs are declared with respect to a specific provider account that is in Store.
  • providerTypeId (mandatory):
     This is the ID of the provider type under which the APIs will be listed. This ID must match the provider account ID in Store. The endpoint of the provider must be found in the provider account definition.
  • params (optional):
     Declares the parameters that must be provided by the consumer during runtime.
  • resourcePath (mandatory):
     Declares the relative path of the API to be invoked. The API definition does not hold the actual physical endpoint of the API. Instead, the relative URI must be declared.
  • queryparams (optional):
     Declares any query parameters that will be sent to API to be invoked. In the
    queryparams
    , refer to any parameters declared to be replaced during run time as
    ${parametername}
    .
  • headers (optional):
     Declares the list of headers to be passed to the API (except any security tokens). In the header you can refer to any parameters declared to be replaced during runtime as
    ${parametername}
    .
  • method (mandatory):
     Declares the http method to be used to call the API (POST/PUT/DELETE/GET).
  • body (optional):
     Declares the body/payload to be sent to the API, if any. In the body you can refer to any parameters declared to be replaced during runtime as
    ${parametername}
    .
  • return (optional):
     This is an optional component. If not specified, the result is returned from the API execution that is returned. Otherwise, you can define JSON path on the return value that will be returned to the caller.

Sample JSON payload

The following is a sample JSON payload to create an API definition: 
{
    "$schema":"http://github.kyndryl.net/cb-consume-schema/cs/api.json",
    "contentVersion":"1.0",
    "id":"addDisk",
    "providerTypeId":"vra",
    "params":{
        "disk": {
            "type":"object"
        }
    },
    "resourcepath": "/vra/service/addDisk",
    "queryparams":{},
    "headers":{},
    "method": "POST",
    "body":"${disk}",
    "return":{}
}
Do you have two minutes for a quick survey?
Take Survey