Working with callouts

A callout is a special kind of domain object that enables you to alter the flow of an operation by executing a remote procedure before or after the operation. The remote procedure can be a BMC Atrium Orchestrator workflow or a web service call. A callout can be a precallout, which is executed before the requested operation, or a postcallout, which is executed after the requested operation.

For callouts, CSMRequest XML is an input to BMC Atrium Orchestrator workflows. The output from the workflow is expected to be a CloudObject of Task. For a sample CSMRequest XML file and sample output, see the BMC Communities blog, Nitin's CLM Blog: Demystifying Callouts.

Note

You cannot pass parameters to BMC Cloud Lifecycle Management flow through callouts. Instead, use a CloudObject of Task that mentions the status of the callout (whether it was successful or it failed). Depending upon this status, BMC Cloud Lifecycle Management can determine whether to continue with the execution or to abort and rollback.

This topic describes the steps to perform the following operations from the Administration Console. Currently, you can create only BMC Atruim Orchestrator and HTTP types of callouts from the application. You can add multiple operations for the callout from the console.

The following BMC Communities video (5:26) describes how to use callouts in BMC Cloud Lifecycle Management.

https://youtu.be/33kJzGPiS98

Commonly used classes and operations

Class	Operation	Callout usage example
`ServiceOfferingInstance`	`BULKCREATE`	A precallout for order processing.
`ServiceOfferingInstance`	`CONSTRUCTOR`	A postcallout for updating a third-party CMDB.
`ServiceOfferingInstance`	`applyOptionChoice`	A precallout to perform any processing prior to applying option choices.
`ComputeContainer`	`BULKDECOMMISSION`	A postcallout to perform any cleanup after a server has been decommissioned or rolled back. This callout is applicable for the AWS provider only.
`ComputeContainer`	`CONSTRUCTOR`	A postcallout to register a server (virtual/physical) for monitoring.
`ComputeContainer`	`DESTRUCTOR` and `DECOMMISSION`	A postcallout to perform any cleanup after a server (virtual or physical) has been decommissioned or rolled back.
`ComputeContainer`	`EXECUTE_SCRIPT`	A precallout to perform the logic for a custom operator action (such as create snapshot).
`ComputeContainer`	`START`	A precallout to perform processing before starting a server.
`ComputeContainer`	`STOP`	A precallout to perform processing before stopping a server.
`VirtualGuest`	`CONSTRUCTOR`	A precallout to perform DNS registration for a virtual server.
`VirtualGuest`	`DESTRUCTOR`	A postcallout to perform any cleanup after a decommission or rollback of a virtual server (such as clean up DNS).
`OperatingSystem`	`CONSTRUCTOR`	A precallout to perform DNS registration for a physical server.
`ApplicationSoftware`	`CONSTRUCTOR`	A precallout to perform any specific processing prior to initiating a software install.
`NetworkConnector`	`CONSTRUCTOR`	A precallout to perform any specific processing before CLM acquires NIC information (such as, IP address; network, portgroup, or VLAN information, and so on).
`NetworkConnector`	`DESTRUCTOR`	A postcallout to perform any specific processing after BMC Cloud Lifecycle Management has decommissioned or removed a NIC.

To create Atrium Orchestrator workflow to handle a callout

Create BMC Atrium Orchestrator workflow that accepts XML from BMC Cloud Lifecycle Management Platform Manager and uses the information from the XML to perform the required business action.

Remember the following tips as you create the workflow:

Make sure that the workflow will receive the proper input in XML format.
The XML should contain the full CsmRequest payload. (Click the link below to see sample XML.) For the exact payload, see the csm.log file.
The CsmRequest has many sections, but focus on the operationParameters section, which has all the variables and its value from that request.
Include the necessary logic in BMC Atrium Orchestrator workflow to extract the appropriate parameters from the XML.
Click here to see the sample input.
<?xml version="1.0" encoding="UTF-8"?>
<soa:executeProcess xmlns:soa="http://bmc.com/ao/xsd/2008/09/soa">
    <soa:gridName>GridName</soa:gridName>
    <soa:processName>:moduleName:workflowName</soa:processName>
    <soa:parameters>
        <soa:Input>
            <soa:Parameter>
                
                <soa:Name>input</soa:Name>
                <soa:Value>
                    <soa:XmlDoc>
                        <CsmRequest>
<CloudObject class="User" name="user">
...
                        </CsmRequest>
                  </soa:XmlDoc>
                </soa:Value>
            </soa:Parameter>
        </soa:Input>
    </soa:parameters>
</soa:executeProcess>
Make sure that the BMC Atrium Orchestrator output is blank (if the operation was successful) or returns a CloudError message if there is an issue.
See the attached sample ROAR file to understand how you can implement callouts.

Make sure that the BMC Atrium Orchestrator workflow output XML in the format provided below.
- For provisioning-related callouts, if BMC Atrium Orchestrator workflow returns a failure (in XML format), BMC Cloud Lifecycle Management rolls back the changes automatically.
- For callouts on other actions (such as start or stop), if BMC Atrium Orchestrator workflow outputs a failure (in XML format), the operation is aborted.
  - The state of the resources are untouched if it is a pre-callout.
  - The state of resources remain changed even if the post-callout failed.
Click here to see the sample output in case of success.
<list>
   <CloudObject class="Task">
      <entry>
         <string>creationTime</string>
         <string>[epoch time]</string>
      </entry>
      <entry>
         <string>completionTime</string>
         <string>[epoch time]</string>
      </entry>
      <entry>
         <string>isCallout</string>
         <boolean>true</boolean>
      </entry>
      <entry>
         <string>isSuccess</string>
         <boolean>true</boolean>
      </entry>
      <entry>
         <string>isError</string>
         <boolean>false</boolean>
      </entry>
   </CloudObject>
</list>
Click here to see the sample output in case of failure.
First type of response
<list>
   <CloudObject class="Task">
      <entry>
         <string>creationTime</string>
         <string />
      </entry>
      <entry>
         <string>completionTime</string>
         <string />
      </entry>
      <entry>
         <string>isCallout</string>
         <boolean>true</boolean>
      </entry>
      <entry>
         <string>isSuccess</string>
         <boolean>false</boolean>
      </entry>
      <entry>
         <string>isError</string>
         <boolean>true</boolean>
      </entry>
   </CloudObject>
</list>
Second type of response
<list>
   <CloudObject class="Task">
      <entry>
         <string>creationTime</string>
         <string />
      </entry>
      <entry>
         <string>completionTime</string>
         <string />
      </entry>
      <entry>
         <string>isCallout</string>
         <boolean>true</boolean>
      </entry>
      <entry>
         <string>isSuccess</string>
         <boolean>false</boolean>
      </entry>
      <entry>
         <string>isError</string>
         <boolean>true</boolean>
      </entry>
      <entry>
         <string>errors</string>
         <list>
            <CloudObject class="CloudError">
               <entry>
                  <string>errorCause</string>
                  <string>Error in the AO Callout induced manually in the workflow.</string>
               </entry>
               <entry>
                  <string>errorAction</string>
                  <string>The AO workflow failed to execute. Check the AO process logs for details.</string>
               </entry>
               <entry>
                  <string>errorTrace</string>
                  <string>This is a sample error.</string>
               </entry>
               <entry>
                  <string>severity</string>
                  <ErrorSeverity>CRITICAL</ErrorSeverity>
               </entry>
               <entry>
                  <string>errorID</string>
                  <string>BMC-CLMT-11155555</string>
               </entry>
            </CloudObject>
         </list>
      </entry>
   </CloudObject>
</list>
To debug callouts, add a debug category level in Cloudservices.json file. Set the category to GENERIC_PROVIDER=debug.

To create an HTTP endpoint to handle a callout

You can create an HTTP endpoint in any language (for example, Java, Node.JS, Python, Ruby On Rails, and so on). It will be a typical HTTP server process. If you want to invoke BMC Cloud Lifecycle Management functionality as part of callout logic, Python language is recommended so that you can use the CLM Python SDK.

Remember the following tips as you create the HTTP endpoint:

Make sure a background process starts and keeps listening for HTTP requests.
Make sure the HTTP request returns JSON output in this format.
Click here to see the sample output in case of success
RESPONSE BODY :
[{
"cloudClass" : "com.bmc.cloud.model.beans.Task",
"description" : "Callout Task Success",
"guid" : "3c68d4c9-a2ac-437c-b76a-f279e5705d16",
"isCallout" : true,
"isError" : false,
"isSuccess" : true,
"isWarning" : false,
"name" : "CALLOUT",
"parentTaskInternalUUID" : "adaa3123-488e-4384-a60c-be50548d18f6",
"taskState" : "COMPLETED_PRECALLOUT"
}]
Click here to see the sample output in case of failure
RESPONSE BODY :
[{
"cloudClass" : "com.bmc.cloud.model.beans.Task",
"description" : "Callout Task Failure",
"guid" : "3c68d4c9-a2ac-437c-b76a-f279e5705d16",
"isCallout" : true,
"isError" : true,
"isSuccess" : false,
"isWarning" : false,
"name" : "CALLOUT",
"parentTaskInternalUUID" : "adaa3123-488e-4384-a60c-be50548d18f6",
"taskState" : "CALLOUT_FAILED"
}]
For provisioning-related callouts, if HTTP endpoint logic returns a failure (in XML format), BMC Cloud Lifecycle Management rolls back the changes automatically.
For callouts on other actions (such as start or stop), if the HTTP endpoint logic returns failure (in XML format), the operation is aborted.
- The state of the resources are untouched if it is a pre-callout.
- The state of resources remain changed even if the post-callout failed.
Make sure that the process provides enough infrastructure resources such as CPU, memory, and disks in the production deployment so that the process can handle up to 250 requests per hour, for example.
Make sure that HTTP endpoint logic is written so that it can handle multiple requests concurrently.

To register a BMC Atrium Orchestrator callout

Go to BMC Cloud Lifecycle Management — Administration Console and from the vertical Workspaces menu, click Configuration.
Click the Callouts tab.
Click Register Callout.
In the Register Callout dialog box, enter the requested information.
Fields marked with an asterisk (*) are mandatory.
1. In the Callout Type list, select AO.
2. In the Name field, enter a name for the callout.
  BMC recommends that you use a unique name to distinguish between callouts.
3. In the Workflow Name field, enter the name of the workflow in the :module:path:workflowName format.
  Example: :CSM_Customization:My_Services_Portal:Actions:Create Instance Snapshot
4. Use the controls in the Weight field to select the weight to be assigned to the callout.
5. Select the Is Notification check box if it is a notification-style callout.
6. From the Class Selection list, select the operation that you want to run by using this callout.
  The options in the Provided Operation and the Provider Selection lists are populated based on the Class Selection list.
  For example, from the Class Selection list, select ComputeContainer and then from the Provided Operation list, select ComputeContainer_START.
  In the Provider Selection list, the available providers are displayed.
7. From the Type list, select whether the callout is a precallout or a postcallout.
8. Click Add Operation to add the operation to the callout.
  The button is disabled until you select the operation type.
Click Submit.

_{Back to top}

To register an HTTP callout

Go to BMC Cloud Lifecycle Management — Administration Console and from the vertical Workspaces menu, click Configuration.
Click the Callouts tab.
Click Register Callout.
On the Register Callout dialog box, enter the requested information.
Fields marked with an asterisk (*) are mandatory.
1. In the Callout Type list, select HTTP.
2. In the Name field, enter a name for the callout.
3. In the URL field, enter the URL for the web service to be used by the callout.
  Example: http://pcsm-fqa-psrvm1:9091
4. In the Data field, enter the relevant data.
5. Use the controls in the Weight field to select the weight to be assigned to the callout.
  The weight is useful in determining the sequence of the callouts if multiple callouts are being called for a given operation.
6. Select the Is Notification check box if it is a notification-style callout. For details about notification-style callouts, see Callouts.
7. From the Class Selection list, select the operation that you want to run by using this callout.
  The options in the Provided Operation and the Provider Selection lists are populated based on the Class Selection list.
  For example, from the Class Selection list, select ComputeContainer and then from the Provided Operation list, select ComputeContainer_START.
  In the Provider Selection list, the available providers are displayed.
8. From the Operation Type list, select whether the callout is a precallout or a postcallout.
9. Click Add Operation to add the operation to the callout.
  The button is disabled until you select the operation type.
Click Submit.

_{Back to top}

To edit a callout

You cannot edit a callout type or callout name after it is created. You can edit the rest of the fields.

Go to BMC Cloud Lifecycle Management — Administration Console and from the vertical Workspaces menu, click Configuration.
Click the Callouts tab.
From the list of callouts, select the callout that you want to modify, and click Edit.
You can change all the fields except the Callout Type and the Name.
Click Submit.

_{Back to top}

To delete a callout

Go to BMC Cloud Lifecycle Management — Administration Console and from the vertical Workspaces menu, click Configuration.
Click the Callouts tab.
From the list of callouts, select the callout that you want to delete and click Delete.
The following message is displayed: Do you want to delete the selected callout?
Click Yes.

_{Back to top}

Working with callouts

Commonly used classes and operations

To create Atrium Orchestrator workflow to handle a callout

To create an HTTP endpoint to handle a callout

To register a BMC Atrium Orchestrator callout

To register an HTTP callout

To edit a callout

To delete a callout

Related topics

Comments