JSM Webhook [BETA]

Connecting to Jira Service Management

Jira Service Management receives events through an automation rule that starts with an incoming webhook trigger and creates a work item from the details.

Steps in Jira:

1. Log in to Jira Service Management

2. Select the Settings (cog) icon, then System

3. Select Global automation and then Create flow, either from scratch or from a template

4. If you are starting from scratch, select Incoming webhook in the Add a trigger submenu

5. The next step is choosing which topic events create work items as well as specifying the format/data you will see on each item. Important: When you subscribe to a topic, Electric sends every event in it. A rule that simply creates a work item will create one for each event, whatever its type, and with the same format each time. To give each event its own summary, description, and priority, add a condition for each event type, as described below.

   1. Click Condition under Add a step on the right

   2. Select IF or ELSE: Add condition options

   3. Under Conditions, click + Add condition

   4. Select {{smart values}} condition

   5. Fill in the condition:

      • First value: {{webhookData.event_type}}

      • Condition: equals

      • Second value: the event you want, for example employee.created

      • Leave Run actions if... on All conditions match, then click Next

      • See the Choosing which events create work items section below to see all the event types available to use as conditions

   6. Click the Add step button under that IF condition and select the Action step option

   7. Select Create a work item

      1. Fill out the Space and Issue type you want these work items to be created as

      2. The Summary and Description fields will show on default but you can select the Choose fields to set button to add other fields you want to set on the work item. See the Mapping fields into your work item section below to find all the available data for each topic as well as examples of Descriptions to use.

   8. Click the Add else icon (the branch icon under the + at the bottom of the path). This adds an Else if path. Repeat step c-g for each further event you want to act on

   9. Leave out any event you do not want a work item for. If no path matches, nothing is created

6. Once you have set up your flow how you want it, click Save without enabling and give your flow a name

7. After you save, click on the Incoming webhook trigger and set the work item criteria to No work items from the webhook. Electric supplies all the data, so the rule does not need to look anything up first

8. Click Generate new secret and then Copy the Webhook URL and Secret

Important: The URL and secret only appear after you save the rule for the first time. If you skip saving, the token will not be active and Jira will reject every delivery.

Need detailed instructions? Atlassian covers the trigger in Configure the incoming webhook trigger and field mapping in Use incoming webhooks with smart values.

Steps in Electric:

1. Log in to Electric

2. Select Settings, then the Webhooks tab

3. Click Create webhook and select Jira Service Management

4. Enter a Name for the webhook

5. Paste the Jira webhook URL into Endpoint URL

6. Paste the Jira secret into Automation webhook token. Electric sends it back to Jira on every delivery

7. Select your topics, leave Active on, and Click Create webhook

8. You are all set!

Choosing which events create work items

The condition for each event is in the table below, so you can copy it straight in.

Mapping fields into your work item

In your Create work item action, build the summary and description from the values Electric sends. Below you will see what data is available to select from for each topic as well as example descriptions to use.

Fields on every event

Employee lifecycle

Events: employee.created, employee.updated, employee.offboarded, employee.reactivated

Example descriptions, by event

A new employee was added.

Name: {{webhookData.first_name}} {{webhookData.last_name}}
Email: {{webhookData.email}}
Job title: {{webhookData.job_title}}
Created at: {{webhookData.event_created_at}}

An employee was updated.

"Name": {{webhookData.first_name}} {{webhookData.last_name}}
Email: {{webhookData.email}}
Job title: {{webhookData.job_title}}
Previous job title: {{webhookData.previous_job_title}}
Previous email: {{webhookData.previous_email}}
Updated at: {{webhookData.event_created_at}}

An employee was offboarded.

Name: {{webhookData.first_name}} {{webhookData.last_name}}
Email: {{webhookData.email}}
Offboarded at: {{webhookData.event_created_at}}

An employee was reactivated.

Name: {{webhookData.first_name}} {{webhookData.last_name}}
Email: {{webhookData.email}}
Job title: {{webhookData.job_title}}
Reactivated at: {{webhookData.event_created_at}}

Employee group membership

Events: employee.group_added, employee.group_removed

These events carry everything in the Employee lifecycle table, plus the two fields below. They exist because, after a removal, the group is no longer in the employee's group list, so there would otherwise be no way to tell which group changed. There are no previous_ fields on these events.

Example descriptions, by event

An employee was added to a group.

Employee: {{webhookData.first_name}} {{webhookData.last_name}} ({{webhookData.email}})
Group: {{webhookData.affected_group_name}}
Added at: {{webhookData.event_created_at}}

An employee was removed from a group.

Employee: {{webhookData.first_name}} {{webhookData.last_name}} ({{webhookData.email}})
Group: {{webhookData.affected_group_name}}
Removed at: {{webhookData.event_created_at}}

Groups & membership

Events: group.created, group.updated, group.deleted

Please note: group.deleted is shorter than the other two. It contains the fields on every event plus {{webhookData.id}} and nothing else, because the group no longer exists by the time the event is sent. If you need the group's name when it is deleted, look it up from the ID in your own records.

Example descriptions, by event

A group was created.

Group: {{webhookData.name}}
Created at: {{webhookData.event_created_at}}

A group was updated.

Group: {{webhookData.name}}
Previous name: {{webhookData.previous_name}}
Employees: {{webhookData.employees_count}}
Updated at: {{webhookData.event_created_at}}

A group was deleted.

Group ID: {{webhookData.id}}
Deleted at: {{webhookData.event_created_at}}

Tasks

Events: request.created, request.completed, request.canceled, request.automation_failed

Remember that the Tasks topic uses request in its field and event names. request.completed and request.canceled can create their own work items, as in the examples below, or update the work item you created for request.created. See Keeping your work items in sync below.

Example descriptions, by event

{{webhookData.request_title}}

Requested by: {{webhookData.requester_name}} ({{webhookData.requester_email}})
Requested for: {{webhookData.on_behalf_of_name}} ({{webhookData.on_behalf_of_email}})
Category: {{webhookData.request_type_category_slug}}

A task was completed.

Task: {{webhookData.request_title}}
Requested for: {{webhookData.on_behalf_of_name}} ({{webhookData.on_behalf_of_email}})
Assigned to: {{webhookData.assignee_name}}

A task was canceled.

Task: {{webhookData.request_title}}
Requested by: {{webhookData.requester_name}} ({{webhookData.requester_email}})

An automated step failed for a task.

Task: {{webhookData.request_title}}
Requested for: {{webhookData.on_behalf_of_name}} ({{webhookData.on_behalf_of_email}})
Category: {{webhookData.request_type_category_slug}}

Open the task in Electric to follow up.

Keeping your work items in sync

By default, every event creates a new work item. For events that describe a change to something you already track, you may prefer to update the existing work item instead. Here are two patterns to try.

Comment on an existing work item when an employee is updated

An employee.updated event carries the new values plus a previous_ version of each field that changed. Instead of creating a new work item for every change, your rule can find the work item you created for that employee and add a comment such as "Job title changed from Support Engineer to Software Engineer".

1. When you create the work item for employee.created, add a label containing the employee's ID, for example employee-{{webhookData.id}}. The ID never changes, even when a name or email does, so it is a reliable way to find the work item again.

2. In your employee.updated path, add a Lookup work items action with a JQL search such as labels = "employee-{{webhookData.id}}".

3. Add an Add comment action that describes the change using {{webhookData.previous_job_title}} and {{webhookData.job_title}}, or {{webhookData.previous_email}} and {{webhookData.email}}.

If you track employees by email instead of ID, previous_email is how you find the original work item after an email change, because the old work item still carries the old address.

Close the loop on tasks

Add a label containing the task ID, such as request-{{webhookData.request_id}}, when you handle request.created. When request.completed or request.canceled arrives, look up the work item by that label, then add a comment or transition it.

Please note: These patterns depend on how your Jira project is set up. Build them with a test event first and confirm the lookup finds the right work item.

Handling fields that are not always filled in

Some values are only there sometimes. An employee may have no job title set, and the previous value of a field is only sent when that field actually changed. On employee.updated, Electric sends the old value as previous_ followed by the field name, for example {{webhookData.previous_job_title}}.

If you reference one of these on an event that does not carry it, the line still appears in your work item with nothing after it. You have two options:

• Accept the blank line. This is the simplest approach and is usually fine.

• Show the line only when the value is present. Wrap it in a Jira if smart value. This keeps work items tidy but takes more familiarity with Jira automation.

Show a line only when the value exists

Wrap the line in a Jira if smart value. The line, and its label, appear only when the field has a value:

{{#if(webhookData.job_title)}}Job title: {{webhookData.job_title}}{{/}}
{{#if(webhookData.previous_job_title)}}Previous job title: {{webhookData.previous_job_title}}{{/}}

Tip: Test events always have an empty start_date and group_ids, so they are a handy way to check your condition. Wrap the start date line, send a test event, and confirm that line is missing from the work item:

{{#if(webhookData.start_date)}}Start date: {{webhookData.start_date}}{{/}}

Atlassian documents these in Automation smart values: conditional logic.

Please note: A successful run sometimes displays the created work item twice in the audit log. Only one work item is created.

Using one rule or several

If you subscribe one webhook to several topics, a single rule receives all of them. You have two options:

• Create a separate webhook and rule for each topic. We recommend this if you are new to Jira automation. Each rule stays simple, and each audit log shows only one kind of event.

• Use one rule with conditional logic. Add an IF or ELSE: Add condition options on {{webhookData.event_type}} and set it to equals the event you want to match, for example employee.created or request.created, then add a different action in each path. To match a whole family of events at once, choose starts with and enter the start of the name, for example employee.. This keeps everything in one place but takes more familiarity with Jira automation.

Atlassian describes these comparison options in Jira automation conditions.