Automated Jira Ticketing using OCI Events, Notifications, and Functions

August 31, 2020 | 8 minute read
Mayur Raleraskar
Solutions Architect
Text Size 100%:

Many of the customers I work with use the Oracle Notifications service to alert their developers and DevOps teams about events happening in Oracle Cloud Infrastructure applications. Events can be of different types and for different resources like Compute Instance restarted, Object created in a bucket, etc. The Notifications service already offers out-of-the-box integrations with many services, such as Email, Functions, Slack, and PagerDuty. Many of these customers are also using ticketing systems, such as Atlassian’s Jira, to track these events, and they’ve asked about the best way to automatically file a Jira ticket when an alert happens.

In this blog, I show you how to automatically file a Jira ticket for an event or alert in Oracle Cloud Infrastructure using Oracle Functions and by calling the Jira API directly from the Functions code.

Overview of the Process

To concretely showcase this end-to-end workflow, we use an Autonomous Transaction Processing database maintenance reminder event as an example. The maintenance reminder event is generated when the Autonomous Transaction Processing database has upcoming scheduled maintenance. We can create a Jira ticket for an on-call engineer when this event occurs, notifying them of it. We can also send an email, informing the team at large about the same. For the solution, we use Oracle Cloud Infrastructure Event service, Notification service, and Functions.

The Autonomous Transaction Processing database already automates all the mundane database admin tasks like backup, tuning, and scaling. This solution improves on this automation.

End-to-End Flow

  1. The event rule for the Autonomous Transaction Processing Maintenance Reminder event has Notification as its target action.

  2. This notification has the function and an email as its two subscriptions. Whenever the Autonomous Transaction Processing Maintenance Reminder event occurs, it triggers the notification with CloudEvent JSON (CNCF compliant and open) as an input data to it. Notification then fans it out to all its subscriptions.

  3. The function takes this CloudEvent and signals to Jira Cloud to create the ticket for the on-call engineer responsible for overlooking the ATP during the maintenance window.

The following graphic shows the data flow:


Figure 1: Automated Jira Ticketing Data Flow

Prerequisites

  • Familiarity with serverless functions on Oracle Cloud Infrastructure.

  • Familiarity with Oracle Cloud web Console.

  • Local installation of tools for the development of functions on Oracle Cloud, namely Oracle Cloud CLI, fn CLI, and Docker.

  • Basic familiarity with Java is also recommended but not required.

If you’re new to serverless functions on the Oracle Cloud, refer to the Oracle Cloud Infrastructure Functions section of references.

Overview of Steps

  1. Create vault and secrets in Oracle Cloud Infrastructure to store your Jira credentials.

  2. Develop a Serverless Function code.

  3. Deploy the function in Oracle Cloud with the right Identity and Access Management (IAM) policy.

  4. Test the function.

  5. Create Notification topic and connect it to the function.

  6. Create Cloud Event rule and connect it to the notification.

Detailed Steps

Step 1: Create Vault and Secrets in Oracle Cloud Infrastructure to Store your Jira Credentials

Because our function hits Jira Cloud APIs, we need a way to securely store and retrieve our Jira Cloud credentials. Oracle Cloud Vaults and Secrets help us achieve that with ease. We create a secret in the Console as in the following screenshot:

Figure 2: Creating Secret in Oracle Cloud Infrastructure Web Console

In this example, we use Basic authentication with API token. Ensure that your Jira secret is in the format.


<Your Jira Cloud Login Email>:<Your Jira Cloud Auth Token>

In our function, we securely fetch this secret with Oracle Cloud software development kit (SDK) and calls Jira Cloud API for ticket creation. For this secret, we have at-rest and in-transit encryption. Since we’re also using HTTPS for the Jira API call, we have end-to-end security.

Once the secret is created, keep its OCID handy. We need it at the time of function creation.

If you’re new to Jira Cloud Rest API, refer to the Jira Cloud documentation.

Step 2: Develop a Serverless Function Code

We already have the Java code for this function ready on GitHub. Before diving into code, we need to answer a question: when the function gets invoked by Oracle Cloud Event service, what’s the input to our function?

As mentioned earlier, JSON complies to the CloudEvent format. You can get example JSON for the development from the Event Creation webpage of the Oracle Cloud Console, as shown in the following image.

Figure 3: Web Console Screen for Event Rule Creation

Follow the README.md of the GitHub repo for details of the code, especially the function and Oracle Cloud SDK used for storing and fetching secrets.

Step 3: Deploy the Function in Oracle Cloud Infrastructure with the Right IAM Policy

To use Oracle Cloud Secrets service anywhere in the Oracle Cloud platform, we have to authorize our function as an IAM principal. Since we’re using resource principal authentication in our function to work with the Secrets service, we need to create a dynamic group and the proper policies in place.

First create a dynamic group, for example fn_dg. I like to include all resources of a specific type (in this case, Oracle Functions) within a specific compartment in my dynamic group. The definition looks like the following example:


ALL{resource.type=’fnfunc’, resource.compartment.id=’ocid1.cmpt.x’}

Next, give the proper policies to the dynamic group. You can apply the policies at the tenancy or the compartment level:


allow dynamic-group fn_dg to read secret-family in tenancy

Now, we create and deploy our function in Oracle Cloud Infrastructure using the following fn CLI script. Read through the code, along with the comments. Make changes as indicated in the code, for your specific environment specific to your Oracle Cloud region, compartment, user, and so on.

After the execution of the script, you should see the Function and its application in the Console.

Figure 4: Function Created from the Script

 

Step 4: Test the Function

Since the function is an Oracle Cloud platform-generated event, we can’t generate the event at will for invoking our function at the time of development. Then how do we develop and test the function before production deployment?

There’s a quick and easy way. As already shown in the previous snippet, we can invoke the function from fn CLI with the following dummy event input:


echo -n "$(curl -s $FN_CLOUD_EVENT_JSON_GIST)" |  fn -v invoke fn_app_jira fn-jira-ticket-creation
We can also use JUnit with the code for local testing on the dev box. For testing or development purposes, we don’t need to hook the function with the actual event.

Step 5: Create Notification Topic and Connect It to the Function

Here, we create a topic named topicForDBMaintainanceReminder, along with two subscriptions for it. One is the function fn-jira-ticket-creation, which we developed in the previous step, and another email address of the receiver who would be interested in this notification. Oracle Notification service helps us achieve fanout for an event to multiple subscribers with ease.

Figure 5: Topic and Subscriptions in Oracle Notification Service

Note the Publish Message button. We can easily test and debug our Notification+Function integration from the Console. We already have the sample CloudEvent JSON. We can publish the message to this topic, for this sample JSON.

Figure 6: Sample Message Publishing on the Topic

Upon clicking the Publish button, the function fn-jira-ticket-creation is invoked, and the email is sent.

Step 6: Create Cloud Event Rule and Connect It to the Notification

We have to select the right event type and conditions for creating the event rule. In the condition, we choose the OCID value of the Autonomous Transaction Processing database that we want to create an event for, as resource ID. In the Action drop-down, choose the option of Notification.

Then we choose the right compartment and name of the Notification topic, as shown in the following screenshot.

Figure 7: Event Rule Creation with Notification Topic As Its Action

Now create the Event rule.

Summary

As a result, we now have stitched together this database maintenance event with our Oracle function and email address through Notification Topic. Whenever a reminder for upcoming database maintenance comes from Oracle Cloud Infrastructure, a Jira ticket is created for our on-call engineer.

Figure 8: Jira Task Example

The Notification service also sends an email on the occurrence of the event.

Figure 8: Email sent from Notifications Service

One manual process is streamlined with the help of three easy-to-use building blocks from Oracle Cloud Infrastructure: Events, Notifications, and Functions. We can also easily add Slack and PageDuty as subscriptions to our Notifications topic.

You can easily extend the same solution design for Oracle Cloud Events of other types or Notifications, such as audit events or events related to Compute services. You can also directly connect Events to Functions, but that doesn’t allow for fan-out using the Notifications service.

Feel free to contact me for any queries on my email.

References

Jira Cloud API

Oracle Cloud Infrastructure Functions

Related Articles

Mayur Raleraskar

Solutions Architect

Solutions Architect, Oracle Cloud Infrastructure


Previous Post

Get Started Now with Oracle Cloud VMware Solution

Direak Tan | 3 min read

Next Post


Latest Updates on Oracle Ansible Modules and Comparison with Terraform

Gaurav Jain | 4 min read