JIRA Integration via AWS Lambda
JIRA Integration via AWS Lambda
The downside of using Marid is that it requires running and maintaining an additional application component, which is not ideal or feasible for many use cases. Lambda is the compute service from AWS that runs your code without any servers. AWS Lambda is a great solution for many use cases including integrations, particularly when integrating SaaS solutions like OpsGenie and JIRA.
The steps below describe how to integrate OpsGenie and JIRA using using AWS API Gateway and Lambda Services.
Creating the Lambda Function over API Gateway endpoint
Go to AWS Lambda console.
If this is your first time using AWS Lambda you’ll see a welcome screen. Just click on “Get Started Now”.
Click on the "Blank Function" to select the blueprint.
Select "API Gateway" as function trigger.
Enter a API Name for the API Gateway endpoint, e.g. OpsGenieJIRAIntegrationAPI.
Select "prod" as Deployment stage and "Open" as Security options.
Click on the “Next” button.
Enter a Name for the Lambda function, e.g. OpsGenieJIRAIntegration.
Description can be empty or anything you like.
Runtime should be Node.js and Code entry type should be Edit code inline.
At the beginning of the code there are a few options that you need to set according to your OpsGenie and JIRA account information.
If you’re using hosted version of JIRA (from Atlassian) replace <jiraAccount> with your JIRA account name.
If you’re using a custom installation of JIRA you need to update jiraHost, jiraBasePath, jiraProtocol and jiraPort variables accordingly.
Replace <ogApiKey> with your OpsGenie API Key from the Default API Integration or any other API Integration.
Enter correct values for <jiraUsername> and <jiraPassword> in accordance with your JIRA account.
For each Alert created by OpsGenie, a new JIRA Issue is created in a JIRA Project. In order to be able to determine which Project an Issue will be created in, there are two settings in the code that you can utilize.
With the alertTagToJiraProjectKey map, you can associate Alert Tags to JIRA Project Keys.
jiraDefaultProjectKey stands for the default JIRA Project Key which is used if none of the tag-key mappings can be matched from the alert.
If you have a single project in your JIRA installation or if you want all issues to created in the same JIRA Project then just enter its key as the default and leave the mapping as an empty array.
Leave Handler’s value as index.handler, select Create a custom role for the Role.
On the newly opened window just click on “Allow” in order to give necessary permissions to our Lambda function to be able to send logs to AWS CloudWatch.
In the Advanced settings pane select Timeout value as 5 just to be safe for our case. Leave Memory value as 128 which is more that necessary for our case.
After completing all steps in the “Configure function” page click on “Next”.
On the next page just click on “Create function”.
Go AWS -> Services -> API Gateway.
Choose your API that you created for your lambda script under "APIs" tab on the left menu.
Click on "ANY" under "/your_lambda_function_name".
Click on "Actions" above and select "Delete Method" under "METHOD ACTIONS".
Confirm the delete action.
After that click again on "Actions" and select "Create Method" under "RESOURCE ACTIONS".
Select "POST" on the newly created combobox.
Click on check sign.
After this a new page will open.
Select your lambda region.
Type the name of your lambda function into the field that will be created after selecting region.
Click on Save button on the down-right of the page.
Confirm "Add Permission to Lambda Function" dialog.
Click on "Actions" again and select "Deploy API" under "API ACTIONS".
Select "prod" as your "Deployment stage".
Click on "Deploy" button.
Configuring an OpsGenie Webhook Integration
Now go to “Integrations” page of your OpsGenie Dashboard at https://www.opsgenie.com/integration. Click on “Add New Integration” and then start adding a “Webhook” integration by clicking on its icon.
Write the API endpoint that AWS API Gateway provided in the Webhook URL text field. Just to make our experiment safer by not sending all alerts to the JIRA installation as issues, add an Alert Filter with a tag matching condition for a tag such as jira. You may name your integration as you like; it’s named LambdaJiraWebhook here. After configuring the integration click on “Save Integration”.
Testing the Integration
Now we’re ready to go. Create a new Alert with jira tag.
Now go to your the default JIRA project you configured and see an issue is created from the alert!
Also check that the alert you just created has been assigned a new tag with jiraProjectKey: prefix. This tag is used for associating this OpsGenie Alert to the JIRA Issue whose key is included in the tag.
Integration flows supported by the implemented function
Besides creating new JIRA issues upon new Alert creation, the following flows are also implemented with this integration:
- when you add a new note to the alert, a new comment is added to the issue,
- when you acknowledge the alert, progress on the issue gets started,
- when you close or delete the alert, the issue is closed as well.
All these flows are depicted in the following sequence diagram. Note that all items in the diagram are representative and may not reflect the actual implementations of the mentioned systems.
Of course, you can further customize the code in order to meet your own requirements.
Monitoring Lambda runtime and function logs via CloudWatch Logs
You can also check CloudWatch logs for the logs we’ve written over the console object and also the ones written by the AWS Lambda runtime. Go to CloudWatch console first.
Click on “Logs”.
Click on the Log Group associated with our Lambda function.
Click on one of the Log Streams, e.g. the most recent one after sorting them by Last Event Time.
Check logs written by the runtime and our function itself.
Exploring the auto configured API Gateway API
You can also check the API Gateway console to see what’s been created and configured for you automatically. Go to the service console first.
Then click on the API, OpsGenieJiraIntegrationAPI, and explore what’s been setup for you. Note that we could have created an API from scratch and associate it with the Lambda function from the API Gateway console but the Lambda console provided us a shortcut and managed some details itself.
Problems you may encounter would be likely because of configuration of your JIRA installation. JIRA is a flexible system and some of its features that seem central to it may not be part of your installation or they may be configured differently or the user accessing the API may not have necessary permissions to use them.
Our Lambda function has three assumptions about your installation and they are hardcoded in the code:
- There is an issue type named ‘Bug’
- Progress on issues can be started and the transition id for this action is ‘4’.
- Issues can be closed and the transition id for this action is ‘2’.
You may need to change these values to make the code run smoothly against your installation.
To see available issue types you can invoke the following call against the REST API endpoint of your JIRA installation:
To see available transitions on a particular issue, you can invoke the following call against the REST API endpoint of your JIRA installation:
The type of the JIRA projects created to accompany this document are JIRA Default Schemes.