Scenario C: File Jira Tickets for Reminders

This topic explains how to file automatic Jira tickets whenever maintenance reminder events occur. In this scenario, whenever a reminder for upcoming database maintenance comes from Oracle Cloud Infrastructure, a Jira ticket is created for your on-call engineer.

This scenario involves writing a function to file Jira tickets (and creating a secret to store your Jira credentials), adding that function and optional email as subscriptions  to a topic , and creating a rule that sends messages to that topic when maintenance reminder events occur (see Database Service: Autonomous Container Database Event Types). The message fans out to the topic's subscriptions, which includes a group email address in addition to the function. The function is invoked on receipt of the message.

Everything but the function can be set up in the Console. Alternatively, you can use the Oracle Cloud Infrastructure CLI or API, which lets you execute the individual operations yourself.

Note

The Notifications service has no information about a function after it's invoked. For more details, see the troubleshooting information at Function not invoked or run.

This image shows Notifications in the context of a scenario that uses a function to file Jira tickets when reminder events occur.

For more information about this scenario, see Automated Jira Ticketing using OCI Events, Notifications, and Functions and the associated GitHub repository.

Required IAM Policy

To use Oracle Cloud Infrastructure, you must be granted security access in a policy  by an administrator. This access is required whether you're using the Console or the REST API with an SDK, CLI, or other tool. If you get a message that you don’t have permission or are unauthorized, verify with your administrator what type of access you have and which compartment  to work in.

If you're a member of the Administrators group, you already have the required access to execute this scenario. Otherwise, you need access to Events, Notifications, and Functions. You must have FN_INVOCATION permission against the function to be able to add the function as a subscription to a topic. To access your Jira credentials, the function must be authorized to read secrets. This scenario walks through steps to provide this authorization.

Task 1: Store your Jira credentials in a secret

You can create a secret in the Console, CLI, or API. You'll reference this secret later, when creating your function.

Using the Console

To create the secret for your Jira credentials
  1. Open the navigation menu, click Identity & Security, and then click Vault.
  2. Under List Scope, in the Compartment list, click the name of the compartment where you want to create a secret.
  3. From the list of vaults in the compartment, do one of the following:

    • Click the name of the vault where you want to create a secret.

    • Create a new vault for the secret by following the instructions in To create a new vault, and then click the name of the vault.

  4. Click Secrets, and then click Create Secret.
  5. In the Create Secret dialog box, choose a compartment from the Create in Compartment list. (Secrets can exist outside the compartment the vault is in.)
  6. Click Name, and then enter a name to identify the secret. Avoid entering confidential information.

    Example name: jira_auth_plain_text

  7. Click Description, and then enter a brief description of the secret to help identify it. Avoid entering any confidential information in this field.

    Example description: jira_auth_plain_text

  8. Choose the master encryption key that you want to use to encrypt the secret contents while they're imported to the vault. (The key must belong to the same vault.)
  9. For Secret Type Template, select Plain-Text.
  10. Click Secret Contents, and then enter your Jira credentials in the following format, with a colon separating your login email from your auth token:

    <your-jira-cloud-login-email>:<your-jira-cloud-auth-token>

  11. Click Create Secret.
  12. Note the secret OCID  for use in your function code to securely fetch the secret.

For more information about creating secrets using the Vault service, see To create a new secret.

Using the CLI

To create the secret using the CLI

Create a secret storing your Jira credentials: Open a command prompt and run the oci vault secret create-base64 command: 

oci vault secret create-base64 --compartment-id <compartment_OCID> --secret-name <secret_name> --vault-id <vault_OCID> --description <secret_description_text> --key-id <encryption_key_OCID> --secret-content-content <base64_encoded_secret_content> --secret-content-name <unique_content_name>

Avoid entering confidential information.

For more information about managing secrets using the CLI, see Using the Command Line Interface (CLI).

Using the API

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the CreateSecret operation.

Example CreateSecret request
POST /20180608/secrets
Host: <managementEndpoint>
<authorization and other headers>
{
  "vaultId": "<vault_OCID>",
  "compartmentId": "<compartment_OCID>",
  "secretName": "jira_auth_plain_text",
  "description": "jira_auth_plain_text",
  "keyId": "<key_OCID>",
  "secretContent": 
    {
      "content": "<base64_encoded_secret_contents>",
      "contentType": "BASE64"
    }
}

For more information about managing secrets using the API, see Using the API.

Task 2: Create the function

This section provides the code sample for creating your function and covers steps to authorize the function to access your Jira credentials in the secret created using the Vault service.

Function code sample

The following code sample is for a function to file Jira tickets.

Add your secret OCID in the line that includes getSecretForOcid.

For instructions on creating and deploying functions, see Creating and Deploying Functions.

public String handleRequest(CloudEvent cloudEvent) {
 
    // Json body of Cloud event from Oracle Event Service in serialized into cloudEvent object by Fn SDK implicitly
    System.err.println("Inside Java jira function with input as " + cloudEvent.getEventType() + "  " + cloudEvent.getData().getResourceName());
 
    String response = jiraCreateTicket(cloudEvent);
 
    if (response != null) return response;
 
    return null;
}
 
private String jiraCreateTicket(CloudEvent cloudEvent) {
 
    try {
        //create jira ticket body as per CloudEvent
        String jsonBodyJira = getJiraApiBody(cloudEvent);
 
        String jiraCloudEndpoint = System.getenv().get("JIRA_CLOUD_URL");
        String ocidForSecretForJiraAuthToken = System.getenv().get("JIRA_CLOUD_SECRET_OCID");
        String jiraAuthToken= getSecretForOcid(ocidForSecretForJiraAuthToken); // base64 encoded form of <YourJiraUsername:YourJiraAuthToken>
 
        // actual REST call to JIRA cloud
        OkHttpClient client = new OkHttpClient().newBuilder()
                .build();
        MediaType mediaType = MediaType.parse("application/json");
        RequestBody body = RequestBody.create(mediaType, jsonBodyJira);
        Request request = new Request.Builder()
                .url(jiraCloudEndpoint)
                .method("POST", body)
                .addHeader("Accept", "application/json")
                .addHeader("Content-Type", "application/json")
                .addHeader("Authorization", "Basic "+ jiraAuthToken)
                .build();
        Response response = client.newCall(request).execute();
        return response.body().string();
 
    } catch (JsonProcessingException e) {
        e.printStackTrace();
    } catch (IOException e) {
        e.printStackTrace();
    }
    return null;
}
Authorize your function to access secrets

Use a dynamic group  to grant your function the ability to read secrets. Your function must have this authorization to access your Jira credentials, which are stored in the secret you created earlier.

To authorize your function to access secrets (Console)
  1. Find and note your function OCID  (format is ocid1.fnfunc.oc1.iad.exampleuniqueID).
  2. Include your function in a dynamic group: In the relevant dynamic group , specify the following rule:
    resource.id = '<function-ocid>'

    Alternatively, you can create a dynamic group that includes all functions:

    ALL{resource.type=’fnfunc’, resource.compartment.id=’<compartment_OCID>’}
  3. Grant the dynamic group access to secrets: Add the following policy  :
    allow dynamic-group <dynamic-group-name> to read secret-family in tenancy

To authorize your function for access to other Oracle Cloud Infrastructure resources, such as compute instances, include the function in a dynamic group  and create a policy to grant the dynamic group access to those resources. For more information, see Accessing Other Oracle Cloud Infrastructure Resources from Running Functions.

For more information about dynamic groups, see Managing Dynamic Groups.

Task 3: Create the topic, subscriptions, and rule

This section walks through creating a topic, adding your function and optional email as subscriptions, and creating the rule that sends a message whenever the Database service emits an event for a database maintenance reminder. Your function must be deployed.

Everything can be set up in the Console. Alternatively, you can use the Oracle Cloud Infrastructure CLI or API, which lets you execute the individual operations yourself.

For more information about managing topics and subscriptions, see Managing Topics and Subscriptions. For more information about managing rules, see Managing Rules for Events.

Using the Console

To create the topic

This section walks through creating the topic you'll use for the subscriptions and rule.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Click Create Topic at the top of the topic list.
  3. In the Create Topic dialog box, configure your topic.

    • Name: Required. Specify a friendly name for the topic. It must be unique across the tenancy; validation is case-sensitive. Avoid entering confidential information.

      Example: Maintenance Topic

    • Description: Optional. Enter a description for the topic. Avoid entering confidential information.
  4. Click Create.

For help with troubleshooting, see Troubleshooting Notifications.

To create the function subscription

This section walks through adding your function as a subscription to the topic. Your function must be deployed.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Click the name of the topic that you want to add the subscription to.

    Example: "Maintenance Topic" (assuming you used the suggested topic name when creating the topic).

  3. On the topic detail page, click Create Subscription.
  4. In the Create Subscription dialog box, configure your function subscription: 
    Note

    The function must be deployed. You must have FN_INVOCATION permission against the function to be able to add the function as a subscription to a topic.

    The Notifications service has no information about a function after it's invoked. For more details, see the troubleshooting information at Function not invoked or run.

    Confirmation is not required for function subscriptions.

    • Subscription protocol: Select Function.
    • Function Compartment: Select the compartment containing your function.
    • Function Application: Select the application containing your function.
    • Function: Select your function.
  5. Click Create.

    The subscription has been created.

For help with troubleshooting, see Troubleshooting Notifications.

To create an email subscription

This section walks through adding an optional email subscription to your topic.

  1. Open the navigation menu and click Developer Services. Under Application Integration, click Notifications.
  2. Click the name of the topic that you want to add the subscription to.

    Example: "Maintenance Topic" (assuming you used the suggested topic name when creating the topic).

  3. On the topic detail page, click Create Subscription.
  4. In the Create Subscription dialog box, set up your email subscription:

    • Protocol: Select Email.
    • Email: Type an email address.
  5. Click Create.

    The email subscription has been created and a subscription confirmation URL is sent to the specified email address. The subscription remains in "Pending" status until it has been confirmed.

  6. To confirm your new email subscription, open your email and navigate to the confirmation URL.

    For more information, see To confirm a subscription.

For help with troubleshooting, see Troubleshooting Notifications.

To create the rule

This section walks through creating the rule that sends a message to the topic whenever the Database service emits an event for a database maintenance reminder.

  1. Open the navigation menu and click Observability & Management. Under Events Service, click Rules.
  2. Choose a Compartment you have permission to work in, and then click Create Rule.

    Events compares the rules you create in this compartment to event messages emitted from resources in this compartment and any child compartments.

  3. Enter the following.
    • Display Name: Specify a friendly name for the rule. You can change this name later. Avoid entering confidential information.

      Example: Maintenance Reminder

    • Description: Specify a description of what the rule does. You can change this description later. Avoid entering confidential information.

      Example: Sends messages to Maintenance Topic

  4. In Rule Conditions, create a filter for database reminder events: 
    • For Service Name, select Database.
    • In Event type, select Autonomous Container Database – Maintenance Reminder.
  5. In Actions, select the topic you previously created:
    1. Select Notifications.
    2. Select the Notifications Compartment.
    3. Select the Topic that you previously created.
  6. Click Create Rule.

Using the CLI

This section walks through creating the topic, subscriptions, and rule using the CLI. Your function must be deployed.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.
  1. Create the topic

    Open a command prompt and run the oci ons topic create command: 

    oci ons topic create --name "Maintenance Topic" --compartment-id "<compartment-ocid>"
  2. Add the subscriptions

    To the topic you just created in the previous step, add subscriptions referencing your function OCID and an optional email address.

    • Create a function subscription: Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "ORACLE_FUNCTIONS" --subscription-endpoint "<function-ocid>"
    • Create an email subscription: Open a command prompt and run the oci ons subscription create command:

      oci ons subscription create --compartment-id "<compartment-ocid>" --topic-id "<topic-ocid>" --protocol "EMAIL" --subscription-endpoint "maintenance.team@example.com"
  3. Create the rule

    Create a rule that is triggered by maintenance reminders and references this topic as the destination: 

    1. Create a file, action.json, that contains the following, referencing your topic created previously:
      {
        "actions": [
            {
              "actionType": "ONS",
              "description": "string",
              "isEnabled": true,
              "topicId": "<topic_OCID>"
            }
        ]
      }
    2. Open a command prompt and run the oci events rule create command: 

      oci events rule create --display-name <friendly_name> --is-enabled true --condition "{\"eventType\":[\"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"]}" --compartment-id <compartment_OCID> --actions file://action.json

      For more information about creating rules using the CLI, see To create a rule.

For help with troubleshooting, see Troubleshooting Notifications.

Using the API

This section walks through creating the topic, subscriptions, and rule using the API. Your function must be deployed.

For information about using the API and signing requests, see REST APIs and Security Credentials. For information about SDKs, see Software Development Kits and Command Line Interface.

Use the following operations:

  1. CreateTopic: Create a topic.

    Example CreateTopic request
    POST /20181201/topics
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "name": "Maintenance Topic",
      "compartmentId": "<compartment_OCID>"
    }
  2. CreateSubscription: To this topic, add subscriptions referencing your function OCID and an optional email address.

    Example CreateSubscription request: Function
    POST /20181201/subscriptions
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "topicId": "<topic_OCID>",
      "compartmentId": "<compartment_OCID>",
      "protocol": "ORACLE_FUNCTIONS",
      "endpoint": "<function_OCID>"
    }
    Example CreateSubscription request: Email
    POST /20181201/subscriptions
    Host: notification.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    {
      "topicId": "<topic_OCID>",
      "compartmentId": "<compartment_OCID>",
      "protocol": "EMAIL",
      "endpoint": "maintenance.team@example.com"
    }
  3. CreateRule: Create a rule that is triggered by maintenance reminders and references this topic as the destination.

    Example CreateRule request
    POST /20181201/rules
    Host: events.us-phoenix-1.oraclecloud.com
    <authorization and other headers>
    
    {
      "displayName": "Maintenance Reminder",
      "condition": "{
        \"eventType\": \"com.oraclecloud.databaseservice.autonomous.container.database.maintenance.reminder\"
        }",
      "compartmentId": "<compartment_OCID>",
      "isEnabled": true,
      "actions": {
        "actions": [
          {
            "actionType": "ONS",
            "topicId": "<topic_OCID>",
            "isEnabled": true
          }
        ]
      }
    }

For help with troubleshooting, see Troubleshooting Notifications.