JIRA: Updating Epics Automatically When Linked Issues Are Updated

Developing a small web service to update the status of Epics automatically when User Stories are updated. Using a small web service based on NodeJS, which listens to User Story changes via a JIRA WebHook and updates the Epics via the JIRA REST API.

Our Development Process

Good functioning processes are essential for successfully developing software products. There are many tools out on the market that support these processes. Moreover, these tools specialize in specific parts of the development process. Therefore, it is important to connect the different tools to create a seamless experience, which decreases the manual work and automates the processes.

We use SCRUM and JIRA extensively in our software development process to create issues and track them through the whole development process. We create User Stories and push them in the process from “To Do” until “Deployed”. Every User Story belongs to a parent Epic. These Epics are discussed and prioritized. These operations are done in Productboard. Consequently, the Epics are pushed to JIRA and we create User Stories for development under these Epics. I am describing this process to illustrate why updating the status of the Epics based on the transitions of the child User Stories is important. As soon as the first User Stories transitions to “In Progress”, the Epic should also automatically move to “In Progress”. Similarly, as soon as the last User Story is in “Deployed”, the epic should also transition to “In Done”. Unfortunately, JIRA is not able to update the status of Epics automatically from its child User Stories:

Building the web service

We built our own little web service that updates the Epics’ status based on their child User Story states. JIRA offers extensive possibilities for integration with other tools and services. It does not only provide a REST API but lets you also configure WebHooks. We implemented a NodeJs web server that listens to the WebHook and calls the JIRA API. You can find the source code of this implementation on GitHub. The basic steps of this service are:

1) Create a WebHook and listen for status changes on User Stories

The WebHook can be directly configured in the JIRA settings (JIRA Application Settings > WebHooks > Create a WebHook).

  • Name: Enter a name to identify your WebHook
  • URL: “http:///webhook” (I created a path “/webhook” on my server)
  • Issue Related Events: Enter the JQL to specify the issues which should trigger an action. I used:
    "project = MyProject AND issue type = Story AND "Epic Link" != EMPTY"

    (which specifies all User Stories of the “MyProject” project which are linked to an Epic)

  • Select the checkbox “Issue updated”

2) Create a service that listens to the WebHook and extracts the linked Epic number

Now the programming starts. The web service (NodeJs and Express) listens to the incoming WebHook. The POST route “/webhook” is called on incoming events and receives all the data in JSON format that JIRA has about the specific User Story that was updated. Consequently, we extract the linked Epic from this information.

let epic = body.issue.fields.customfield_10008

3) Search for all linked User Stories

Knowing the Epic’s name, we have to find all other User Stories that are linked to this Epic. We use the JIRA search endpoint where we can specify the search criteria via JQL:

jira.search(`project = ABC AND 'Epic Link'='${epic}'`).then(stories => {
// Action

This will return all linked User Stories. As a next step, we call the JIRA search API and search for all stories that are linked to this Epic. This will return the data of the User Stories in JSON format. We are only interested explicitly in the status of these tickets.

4) Evaluate the status and update the parent Epic

Now we have to evaluate the status of all User Stories linked to the Epic. The simple rule set is to update the Epic to:

  • “To Do” if all linked User Stories are in “To Do”
  • “In Progress” if one or more linked User Stories are “In Progress”
  • “Done” if all linked User Stories are “Deployed”

Finally, we call the JIRA issue endpoint again and update the status of the Epic.

Now you only have to keep the service running and the status of the Epics will be updated automatically of User Stories are updated.
You can find the full source code on GitHub.




  1. Ankita Sinha   •  

    can this be used on JIRA cloud?

    • maichriedler   •     Author

      yes, it uses the JIRA API

  2. Ankita Sinha   •  

    can you please tell me where should NodeJS be hosted?

Leave a Reply

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.