Although CLM Callouts have been around for quite some time now, I do get questions on these all the time. In this blog post I will try to clarify the Callout concepts, some commonly asked questions and best practices. We will also walk through Callout registration and request processing. So, bear with me as we call out on this small journey!
1. Callouts Overview
As the name suggests, a Callout is essentially a piece of code that CLM can invoke (call out) during a usecase flow. The best way to look at a Callout is to think of influencing CLM's behavior. Yes, "influencing" is a loaded term. It could be as simple as register my VM into the DNS or could be as loaded as work with the Order Fulfillment system to process the order before commencing provisioning. Following are some other common usecases where customers use CLM Callouts
- Have VM/server join a domain
- Notify a 3rdparty application (such as, Backup or Monitoring) about existence of the newly provisioned server
- Perform any prerequisite Security configurations that are required for provisioning
- Update 3rdparty CMDB (non-BMC)
- In releases prior to CLM 4.5, Change Management Integration often used a Callout-based approach.
Note: From CLM 4.5+, please use the new Change Management Provider architecture to integrate with Change Management systems that are not supported out-of-the-box.
Callouts are typically written as BMC Atrium Orchestrator (BAO) workflows. That does not mean the entire code has to be written in BAO. Often customers have scripts they would like to integrate in a callout scenario and other forms of reusable code. So, think of the Callout BAO workflow as the launch pad/integration layer for such scenarios so that it can handle translation of data and response.
Although it is not as commonly known, but Callouts do have types. There are 3 types of Callouts that CLM supports.
- Regular/Standard Callout: Ok, this is not really a type. I just made it up. These Callouts are written in BAO and are the most commonly used Callouts. CLM invokes the Callout and waits for its completion. The Callout returns the result of the processing (typically, success or failure with a message). CLM handles the result and accordingly proceeds with the next steps. In this post I will be focusing on the Standard Callouts only.
- HTTP Callout: These are not commonly used and are typically meant for complex scenarios where the Callout processing is going to take a long time. Now long is relative. But, think of something that will typically run in hours or days (such as, a Purchase Order Processing task that my involve manual steps as well). These Callouts are front-ended by a Java Servlet-style gateway, which receives the Callout invocation and simply informs CLM that the task processing has begun. CLM hibernates the calling task, so that no resources are consumed on the CLM side. Once the Callout has finished the Servlet (or an associated piece of code) can inform CLM about the result of the operation. CLM handles the result and accordingly proceeds with the next steps.
- Notification Callout: These Callouts are fire-and-forget style Callouts. That is, CLM invokes the Callout, but does not wait for its completion. As the name suggests, these are intended to simply notify 3rparty systems.
2. Think Object and not time when thinking about Callouts
In my discussions, this is the biggest challenge/shift that has to be understood to use Callouts effectively. Often when we think of a usecase flow, we think in terms of a sequence of operations and events. So, it is natural to ask how do I know where to "attach my Callout" in a CLM flow? Can someone provide me a list? These are fair questions. But, lets park these for a moment and see if at the end of this section you still have those.
A Callout is always attached to an operation on a CLM object. An object here means an entity like the Service instance, Virtual Machine, Application Software, etc. And operation means an action on that object. A typical example is creation of an object. A Callout can either run before the operation (a.k.a pre-callout) or after the operation (a.k.a. post-callout). For example, if you wanted to do DNS registration of your VM with static IP, a VM create pre-callout would be the most appropriate place.
Lets talk a bit about this "think object and not time" aspect. When thinking of associating Callouts, follow this simple guideline.
- Identify the class for the object of interest. Use CLM's Object Model as reference. In most cases, you should be able to identify the object and its class you are interested in. For example, if you were interested in DNS registration, you are most likely interested in the VM (VirtualGuest) itself. But, if you were doing something at Firewall Rule level, the object of interest would be FirewallRule. Simple! right?
Object model - BMC Cloud Lifecycle Management 4.5 - BMC Documentation
- Determine whether your processing needs to happen before the object comes into existence or after it or before/after its operation. Again the above Object Model reference should help you determine the operation of interest.
- Once you know the class and operation, you can register one or more pre/post Callouts against it and CLM will honor the registration regardless of when that happens in time sequence.
To strike this point home slightly differently, when you start thinking in objects you start taking care of additional usecases that you may not be thinking at the outset. For example, a DNS pre-callout for VM would be useful for provisioning. But, it will also be able to handle any servers added via CLM's auto-scale or additional VMs added via CLM's Add Server capability. So, you see, thinking in object saves you the time and effort to dig into time sequences. Instead, focus on the object of interest and CLM will invoke the Callout whenever that object and operation come into play. Hopefully, it has started to make more sense now.
Having said that, realistically there are a handful of objects and operations that are most commonly used by customers. I am summarizing these here for a quick reference.
|Class||Operation||Callout Usage Example|
A pre-callout for Order Processing.
|ServiceOfferingInstance||CONSTRUCTOR||A post-callout for updating 3rdparty CMDB.|
|ServiceOfferingInstance||applyOptionChoice||A pre-callout for doing any processing prior to applying Option Choice(s).|
|ComputeContainer||CONSTRUCTOR||A post-callout to register a server (virtual/physical) for monitoring.|
|ComputeContainer||DESTRUCTOR and DECOMMISSION||A post-callout to do any clean up after a server (virtual/physical) has been decommissioned or rolled back.|
|ComputeContainer||EXECUTE_SCRIPT||A pre-callout to perform the logic for a Custom Operator Action (such as, create snapshot).|
|ComputeContainer||START||A pre-callout to perform processing before starting a server.|
|ComputeContainer||STOP||A pre-callout to perform processing before stopping a server.|
|VirtualGuest||CONSTRUCTOR||A pre-callout to do DNS registration for a virtual server.|
|VirtualGuest||DESTRUCTOR||A post-callout to do any clean up post decommission/roll back of a virtual server (such as, clean up DNS).|
|OperatingSystem||CONSTRUCTOR||A pre-callout to do DNS registration for a physical server.|
|ApplicationSoftware||CONSTRUCTOR||A pre-callout to do any specific processing prior to initiating software install.|
|NetworkConnector||CONSTRUCTOR||A pre-callout to do any specific processing before CLM acquires NIC information (such as, IP address, network/portgroup/VLAN info, etc.)|
|NetworkConnector||DESTRUCTOR||A post-callout to do any specific processing after CLM has decommissioned/removed a NIC.|
3. Commonly asked questions about Callouts
Q. How long can a Callout take?
A. The short answer is 'forever'. Yes, a Callout can ideally run forever and CLM will wait for its completion. A Callout invocation can even withstand CLM Platform Manager restarts. CLM handles Callout invocation intelligently by hibernating the parent task that invoked the Callout. This is to reduce undue load on the system. The Callout workflow that is invoked by CLM (keeping a Standard Callout in mind) is the one that CLM would wait on. This workflow can choose to call other BAO workflows and utilities/code.
Q. Can a Callout abort further processing? Or can a Callout return status? Can it written an error message that will be shown in CLM Activities results?
A. The short answer is 'Yes' to all of the above questions. A Callout response is well defined. It can return success or failure. In case of failure, it can also return an error message. I have attached some sample Callout response XMLs to this post for reference.
Q. Can I reuse my existing scripts with Callouts?
A. While it is our intent is to promote re-usability with Callouts, the answer to the question really depends on what type of script it is and how reusable it is? BAO provides various adapters for typical integration scenarios like the various command line adapters. It is possible to invoke a script using such an adapter. However, the script should support re-use. Or hopefully it requires minor tweaks. Keep the target platform idiosyncrasies in mind as well. For example, it is fairly well understood in a UNIX style scripting on how to interpret the exit status of a script and how to fetch the error message. However, that may not be true for all platforms. The point being ensure your script is capable of handling the usecase needs and the automation desired.
Q. Can a Callout change the object it is associated with?
A. No. For those familiar with Application Architecture, it is important to know that Callouts do not follow the Decorator pattern, which let you decorate (manipulate) the objects. Callouts are purely meant to influence behavior.
Q. I also see things like Blueprint Post Deployment Actions, Pre/Post Install Actions per Software, Custom Action via Option Choices. How are these different from Callouts and when should I use these over Callouts?
A. It is a loaded question. So, let me try to break these into simpler points.
- Callouts are system-wide and global in nature. That is, anytime CLM invokes the operation on the object for which you have registered one or more Callouts, CLM will invoke the Callout(s). Of course, you can write logic inside a Callout to decide when to do processing and when not to do anything. But, CLM will invoke the Callout if its object and operation are in the path of that usecase flow. Period.
- Blueprint Post Deployment Actions (PDAs) or the ones injected using Service Catalog Option Choices are typically meant for specific usecases only. For example, I may have a PDA to format and partition a newly added disk. But, this does not need to happen for every CLM provisioning flow. Only when the user requested that specific Blueprint or Option Choice. PDAs can also be of type NSH (Bladelogic Server Automation script). Callouts can only be written in BAO (at least the main Callout workflow).
- The Pre/Post Install actions per Software are to invoke that action only for that specific software. On the contrary, if you were to invoke a BAO workflow for every software installed, you could instead consider using an ApplicationSoftware_CONSTRUCTOR pre/post Callout.
- Custom Action via Option Choices are similar to PDAs but work in the context of a given Option Choice. For example, an Add Disk option choice could include a Custom Action to format and partition the disk. Again, Custom Actions can be of type BAO workflow or NSH.
4. How do I register and use Callouts?
We have talked a lot about Callout concepts and hopefully clarified some questions that might have bee on your mind. Lets see these in action now.
Callout registration is a very simple process. Following is a screenshot that demonstrates the process.
- There is a Callout Workspace that is part of the CLM Admin Portal->Configuration.
- You can simply create an entry for a new Callout registration. As you can see the data being asked is very minimal. Mainly, you need to know the Class and Operation and whether you want to invoke Callout before or after the operation. You obviously need to know the main Callout BAO workflow name. Notice that the BAO workflow name is specified in a fully qualified format (starting with a ':'). Don't worry about weight. If you have multiple Callouts for a given operation, you can assign weight to give priority to one Callout over others.
- Once you save this entry, the Callout is active from that point.
Now that we know how a Callout is registered, lets see what data it receives. Remember that a Callout is associated with an object (more accurately, class) and operation. As such, the data it receives is the object representation at that point in time. For example, a pre Callout for the same object may receive less data than the post Callout for the same object because during the operation rest of the object got populated. This may also help you determine a more appropriate place for associating the Callout depending on what data you are looking for. So, it is difficult to generalize what data a Callout would receive. However, there is a standard pattern followed for sending data to Callouts. Lets talk about that.
Following is a sample Callout request data (often referred to as "CSMRequest" or "CSMRequest XML") for a ServiceOfferingInstance_BULKCREATE pre-callout.
- The root is always "CsmRequest".
- Most of the data related to the object would be found under the "operationParameters" section. For example, here you can see the data around the requested Service Offering, selected option choices, the hostname prefix specified by the user, any parameters and data associated with the request, etc.
- The Callout can parse out this data along with any additional lookups and data it needs and use it for its processing.
- Additional metadata about the request is available in other parts of the XML.
Once a Callout has finished processing it should return the status along with any error and associated message to CLM, as appropriate. Note that the Callout responses do not return the object the Callout was associated with because... You got it - because a Callout cannot manipulate the object. It can only influence behavior.
Following is an example of a successful Callout response.
Following is an example of a failure Callout response.
As you can see, Callouts do require a bit of an effort. But, it could be well worth depending on the usecase and what you are trying to accomplish. These are certainly nuggets that are available to you to integrate CLM better in rest of your ecosystem.
If there are other topics you would like me to blog about, please feel free to leave me a comment. I will try my best to respond to the requests.
Have a good day!
Cloud is a journey with milestones and not a destination!