Skip to content

Commit 364e9fb

Browse files
talborentalboren
authored
Merge branch 'main' into feat/mailgun-improvements
2 parents 07083cd + 0c87eb9 commit 364e9fb

File tree

6 files changed

+420
-4
lines changed

6 files changed

+420
-4
lines changed

‎docs/providers/documentation/jira-provider.mdx‎

Lines changed: 223 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,10 +14,233 @@ import AutoGeneratedSnippet from '/snippets/providers/jira-snippet-autogenerated
1414
3. Get `project_key` from your project > settings > details.
1515
4. `email` would be same as of your account email.
1616

17+
## Auto-Transition Workflows
18+
19+
The Jira provider supports automatically transitioning tickets when alerts change status. This is useful for keeping your Jira board synchronized with alert states - for example, automatically closing tickets when alerts are resolved.
20+
21+
### Prerequisites
22+
23+
1. Configure a Jira Cloud provider in Keep
24+
2. Ensure your Jira user has the `TRANSITION_ISSUES` permission
25+
3. Know your Jira board name and desired transition status names
26+
27+
### Workflow 1: Create Jira Ticket on Alert
28+
29+
This workflow creates a Jira ticket when an alert fires, but only if no ticket has been created yet.
30+
31+
```yaml
32+
workflow:
33+
id: jira-create-ticket-on-alert
34+
name: Create Jira Ticket on Alert
35+
description: Create Jira ticket when alert fires
36+
disabled: false
37+
triggers:
38+
- type: alert
39+
cel: status == "firing"
40+
actions:
41+
- name: jira-action
42+
if: "not '{{ alert.ticket_id }}'"
43+
provider:
44+
type: jira
45+
config: "{{ providers.JiraCloud }}"
46+
with:
47+
board_name: YOUR_BOARD_NAME # Change this to your board name
48+
issue_type: Task # Or Bug, Story, etc.
49+
summary: "{{ alert.name }} - {{ alert.description }}"
50+
description: |
51+
"This ticket was created automatically by Keep.
52+
53+
Alert Details:
54+
{code:json}
55+
{{ alert }}
56+
{code}"
57+
enrich_alert:
58+
- key: ticket_type
59+
value: jira
60+
- key: ticket_id
61+
value: results.issue.key
62+
- key: ticket_url
63+
value: results.ticket_url
64+
```
65+
66+
**Key Points:**
67+
- `if: "not '{{ alert.ticket_id }}'"` - Only creates a ticket if one doesn't exist yet
68+
- `enrich_alert` - Stores the ticket ID, type, and URL in the alert for later use
69+
- The ticket is created in the default status (usually "To Do" or "Open")
70+
71+
### Workflow 2: Transition Ticket to Done on Alert Resolved
72+
73+
This workflow updates the existing Jira ticket and transitions it to "Done" when the alert is resolved.
74+
75+
```yaml
76+
workflow:
77+
id: jira-transition-on-resolved
78+
name: Transition Jira Ticket to Done
79+
description: Close Jira ticket when alert is resolved
80+
disabled: false
81+
triggers:
82+
- type: alert
83+
cel: status == "resolved"
84+
actions:
85+
- name: jira-action
86+
provider:
87+
type: jira
88+
config: "{{ providers.JiraCloud }}"
89+
with:
90+
issue_id: "{{ alert.ticket_id }}"
91+
summary: "{{ alert.name }} - {{ alert.description }} (resolved)"
92+
description: |
93+
"Alert has been resolved automatically by Keep.
94+
95+
Resolved at: {{ alert.lastReceived }}
96+
97+
Original Alert Details:
98+
{code:json}
99+
{{ alert }}
100+
{code}"
101+
transition_to: Done # Change to your workflow's status name
102+
```
103+
104+
**Key Points:**
105+
- Uses `issue_id: "{{ alert.ticket_id }}"` from the enriched alert data
106+
- `transition_to: Done` - Transitions the ticket to the specified status
107+
- No `if` condition needed - if the alert has no `ticket_id`, the action will simply fail gracefully
108+
109+
### Available Transition Names
110+
111+
Common Jira transition names (varies by workflow):
112+
- `Done`
113+
- `Resolved`
114+
- `Closed`
115+
- `In Progress`
116+
- `To Do`
117+
- `Canceled`
118+
119+
**How to find your transition names:**
120+
1. Go to your Jira project settings
121+
2. Navigate to Workflows
122+
3. Check the available statuses in your workflow
123+
4. Use the exact status name in the `transition_to` parameter (case-insensitive)
124+
125+
### Error Handling
126+
127+
If you specify an invalid transition name, the Jira provider will return a helpful error message listing all available transitions for that ticket:
128+
129+
```
130+
Transition 'Invalid' not found. Available transitions: To Do, In Progress, Done, Closed
131+
```
132+
133+
### Example: Three-State Workflow
134+
135+
You can also create intermediate transitions:
136+
137+
```yaml
138+
# Workflow 3: Move to In Progress when acknowledged
139+
workflow:
140+
id: jira-transition-in-progress
141+
name: Transition to In Progress
142+
description: Move ticket to In Progress when alert is acknowledged
143+
disabled: false
144+
triggers:
145+
- type: alert
146+
cel: status == "acknowledged"
147+
actions:
148+
- name: jira-action
149+
provider:
150+
type: jira
151+
config: "{{ providers.JiraCloud }}"
152+
with:
153+
issue_id: "{{ alert.ticket_id }}"
154+
summary: "{{ alert.name }} - In Progress"
155+
description: "Alert acknowledged and being worked on."
156+
transition_to: In Progress
157+
```
158+
159+
### Testing
160+
161+
1. **Create an alert** that triggers the first workflow
162+
- Verify a Jira ticket is created
163+
- Check that the alert has `ticket_id`, `ticket_type`, and `ticket_url` fields
164+
165+
2. **Resolve the alert** to trigger the second workflow
166+
- Verify the existing ticket is updated (no new ticket created)
167+
- Check that the ticket status changed to "Done"
168+
169+
3. **Check the logs** in Keep UI for any errors or debugging info
170+
171+
### Troubleshooting
172+
173+
#### Issue: Workflow creates a new ticket instead of updating
174+
175+
**Cause:** The `issue_id` parameter is missing or the alert doesn't have a `ticket_id`.
176+
177+
**Solution:** Ensure the first workflow enriches the alert with `ticket_id` and the second workflow uses it via `issue_id: "{{ alert.ticket_id }}"`.
178+
179+
#### Issue: Transition fails with "Transition 'X' not found"
180+
181+
**Cause:** The transition name doesn't match your Jira workflow.
182+
183+
**Solution:** Check the error message for available transitions and update the `transition_to` parameter accordingly.
184+
185+
#### Issue: Permission denied when transitioning
186+
187+
**Cause:** Your Jira user doesn't have the `TRANSITION_ISSUES` permission.
188+
189+
**Solution:** Grant the necessary permissions in Jira project settings.
190+
191+
### Advanced Features
192+
193+
#### Configuration Variables
194+
195+
You can use Keep's configuration variables to make the workflows more flexible:
196+
197+
```yaml
198+
consts:
199+
JIRA_BOARD: "ALERTS"
200+
JIRA_DONE_STATUS: "Done"
201+
JIRA_ISSUE_TYPE: "Task"
202+
203+
# Then use in workflows:
204+
board_name: "{{ consts.JIRA_BOARD }}"
205+
transition_to: "{{ consts.JIRA_DONE_STATUS }}"
206+
issue_type: "{{ consts.JIRA_ISSUE_TYPE }}"
207+
```
208+
209+
#### Custom Fields
210+
211+
You can also set custom fields when creating or updating tickets:
212+
213+
```yaml
214+
with:
215+
issue_id: "{{ alert.ticket_id }}"
216+
summary: "Alert resolved"
217+
custom_fields:
218+
customfield_10001: "High"
219+
customfield_10002: "Production"
220+
transition_to: Done
221+
```
222+
223+
#### Labels and Components
224+
225+
```yaml
226+
with:
227+
board_name: YOUR_BOARD_NAME
228+
summary: "{{ alert.name }}"
229+
description: "{{ alert.description }}"
230+
labels:
231+
- alert
232+
- automated
233+
- critical
234+
components:
235+
- Monitoring
236+
- Infrastructure
237+
```
238+
17239
## Notes
18240

19241
## Useful Links
20242

21243
- https://id.atlassian.com/manage-profile/security/api-tokens
22244
- https://developer.atlassian.com/cloud/jira/software/rest/api-group-board/#api-rest-agile-1-0-board-boardid-issue-get
23245
- https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-post
246+
- https://developer.atlassian.com/cloud/jira/platform/rest/v2/api-group-issues/#api-rest-api-2-issue-issueidorkey-transitions-get (Transitions API)

‎docs/snippets/providers/jira-snippet-autogenerated.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,7 @@ Certain scopes may be required to perform specific actions or queries via the pr
1515
- **EDIT_ISSUES**: Edit Jira Issues
1616
- **DELETE_ISSUES**: Delete Jira Issues
1717
- **MODIFY_REPORTER**: Modify Jira Issue Reporter
18+
- **TRANSITION_ISSUES**: Transition Jira Issues
1819

1920

2021

@@ -51,6 +52,7 @@ actions:
5152
labels: {value} # The labels of the issue.
5253
components: {value} # The components of the issue.
5354
custom_fields: {value} # The custom fields of the issue.
55+
transition_to: {value} # Optional transition name (e.g., "Done", "Resolved") to apply after update/create.
5456
```
5557
5658

‎docs/snippets/providers/mailgun-snippet-autogenerated.mdx‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,11 @@
1-
{/* This snippet is automatically generated using scripts/docs_render_provider_snippets.py
1+
{/* This snippet is automatically generated using scripts/docs_render_provider_snippets.py
22
Do not edit it manually, as it will be overwritten */}
33

44
## Authentication
55
This provider requires authentication.
66
- **email**: Email address to send alerts to (required: False, sensitive: False)
77
- **sender**: Sender email address to validate (required: False, sensitive: False)
8+
- **email_domain**: Custom email domain for receiving alerts (required: False, sensitive: False)
89
- **extraction**: Extraction Rules (required: False, sensitive: False)
910

1011

‎examples/workflows/jira-create-ticket-on-alert.yml‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
workflow:
2+
id: jira-create-ticket-on-alert
3+
name: Create Jira Ticket on Alert
4+
description: Create Jira ticket when alert fires
5+
disabled: false
6+
triggers:
7+
- type: alert
8+
cel: status == "firing"
9+
actions:
10+
- name: jira-action
11+
if: "not '{{ alert.ticket_id }}'"
12+
provider:
13+
type: jira
14+
config: "{{ providers.JiraCloud }}"
15+
with:
16+
board_name: YOUR_BOARD_NAME # Change this to your board name
17+
issue_type: Task # Or Bug, Story, etc.
18+
summary: "{{ alert.name }} - {{ alert.description }}"
19+
description: |
20+
"This ticket was created automatically by Keep.
21+
22+
Alert Details:
23+
{code:json}
24+
{{ alert }}
25+
{code}"
26+
enrich_alert:
27+
- key: ticket_type
28+
value: jira
29+
- key: ticket_id
30+
value: results.issue.key
31+
- key: ticket_url
32+
value: results.ticket_url

‎examples/workflows/jira-transition-on-resolved.yml‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
workflow:
2+
id: jira-transition-on-resolved
3+
name: Transition Jira Ticket to Done
4+
description: Close Jira ticket when alert is resolved
5+
disabled: false
6+
triggers:
7+
- type: alert
8+
cel: status == "resolved"
9+
actions:
10+
- name: jira-action
11+
provider:
12+
type: jira
13+
config: "{{ providers.JiraCloud }}"
14+
with:
15+
issue_id: "{{ alert.ticket_id }}"
16+
summary: "{{ alert.name }} - {{ alert.description }} (resolved)"
17+
description: |
18+
"Alert has been resolved automatically by Keep.
19+
20+
Resolved at: {{ alert.lastReceived }}
21+
22+
Original Alert Details:
23+
{code:json}
24+
{{ alert }}
25+
{code}"
26+
transition_to: Done # Change to your workflow's status name

0 commit comments

Comments
 (0)