Oracle Integration Cloud (OIC) is often used to connect to SaaS apps such as Salesforce and ERP. In my case, that app is a ServiceNow developer instance. Common integration patterns involve sending data between SaaS apps, whether in a one-to-one or multi-pronged approach. However, it is also possible to set up integration with Oracle Cloud Infrastructure (OCI) services that emit events. This is commonly done through the use of Oracle Functions, a "serverless platform that lets developers create, run, and scale applications without managing any infrastructure." The general structure of such an approach is the following:
Use case: manage cloud compute networks using ServiceNow tables. A customer wanted to manage the virtual machines (VMs) that they created in various clouds using their ServiceNow account, which they were already familiar with. The idea here is that their ServiceNow tables would automatically sync with their cloud environments to reflect the state of all the VMs in their cloud networks. Here is an example: suppose I have three Oracle VMs and one GCP VM. One of the Oracle VMs is terminating, and another Oracle VM is stopped. On my ServiceNow table, I will see four entries: one online Oracle VM, one offline Oracle VM, one terminated Oracle VM, and one online GCP VM. Now, suppose I provisioned a new GCP VM and restarted the offline Oracle VM. The ServiceNow table should automatically update to show two online Oracle VMs, one terminated Oracle VM, and two online GCP VMs. Finally, if I were to drill down into one of these entries, I would be able to view some basic information such as date of creation, VM shape/image, CPU count, etc.
The example workflow below is what was built for the customer. Here, the cloud event is "launch instance end" (i.e. whenever a compute instance has finished provisioning), but one can easily swap out the event for others. For instance, to complete the use case above, one would need to define additional events for the "update instance" and "terminate instance end" events, triggering the same function and integration*.
*these integrations would need to update entries in the ServiceNow tables, rather than creating new entries as they are defined in the instructions.
Here are the important components of the integration:
Since the integration is only supposed to be triggered by an event (when a compute instance is created), it must be app-driven. Oracle Functions is able to trigger integrations via REST (see How to create a function in the helpful links below). The simplest way to pass information about the compute instance to the integration is to have the function "forward" the event payload to integration cloud. A response is not needed, as the function does not use the response for anything (however it might be useful to include a response for testing with Postman).
The event payload does not return these pieces of information about the compute instance; rather it contains only information relevant to the creation of the compute instance. These are artifacts such as the compartment OCID, instance OCID, instance name, image ID, and more. However, these artifacts -- namely, the compartment and instance OCIDs -- are sufficient to query other information about the compute instance. The private IP address and image/shape details are such examples of information that should be stored in ServiceNow to allow for effective compute instance management. Retrieving these data require calling the OCI REST API, which itself requires a special form of authentication that is very difficult to reproduce locally. It is simply easier to configure a REST connection in OIC rather than building the payload from scratch within the Oracle Function*. After making the OCI REST call, there may be additional data processing steps. For example, retrieving the private IP first required listing all the VNIC attachments, then going through each of them to find the specific VNIC associated with the VM that was just created, and finally making one additional REST call to get the private IP.
*discussion: To get additional information about the VM, such as the private IP, you need to call the OCI REST API. There are two ways to do this: using a REST connection in OIC, or calling the REST endpoint in the function. Configuring the REST connection requires you to input five pieces of information, and OIC does the rest (building the payload). The function, which is more or less a python/java code file, needs to build the payload from scratch using those five pieces of information, which involves nested encryptions and specific timestamps and more. Needless to say, I chose the less complex route for this POC
Using the ServiceNow connection closely resembles using other SaaS connectors (especially the Oracle ERP adapter). One defines an action to take on a table, then selects the table in question, and finally performs the data mapping using the spawned mapper. Before using the ServiceNow connection, the ServiceNow instance must be active, which requires you to log in to your ServiceNow developer account (this in turn automatically wakes your instance, which takes about 1-2 minutes). Here, there are two invocations, one for each of the two tables being updated.
Here is a link to the step-by-step instructions of setting up the system above. To do so, you must meet the prerequisites stated in the instructions. Any files mentioned in the instructions will be in the same Github repository as the instructions.
Preparing your ServiceNow account for use by OIC - you do not need to create a new user, using the admin user is fine; also you only need to modify the tables in your ServiceNow instance to have all the permissions listed (CRUD ops), after that if you test a ServiceNow connection in OIC and it works then you are good to go