Use Cases for User Absence Planner for Jira API Integration

Overview

The User Absence Planner API for Jira Cloud provides powerful functionality for managing user absences programmatically. This can be leveraged to create seamless integrations with external tools such as Outlook, Google Calendar, or HR systems. Below are some use cases demonstrating how to use these APIs in various scenarios, including no-code solutions using tools like Zapier and custom-developed integrations.

Use Case 1: Integrating with Outlook via Zapier

Objective: Automatically create and update absences in Jira based on events in Outlook Calendar.

Steps:

1. Create a Zapier Account: Sign up for a free account at Zapier

2. Set Up a Zap: Create a new Zap in Zapier

3. Trigger:

   1. Choose “Outlook Calendar” as the trigger app

   2. Select the event trigger, such as “New Event” or “Event Start”

   3. Connect your Outlook account to Zapier and set up the trigger details

4. Action:

   1. Choose “Webhooks by Zapier” as the action app

   2. Select “POST” for creating a new absence or “PUT” for updating an existing absence

5. Configure the Webhook:

   1. For creating a new absence:

      1. Set the URL to the createAbsence endpoint (unique for your instance)

      2. Include parameters in URL with the users email address and the cloud site

      3. Define body:

         JSON

         {
           "title": "{{Outlook Event Title}}",
           "type": "Holiday",
           "start": "{{Outlook Event Start}}",
           "end": "{{Outlook Event End}}",
           "message": "Outlook Calendar Event"
         }

   2. For updating an absence:

      1. Set the URL to the editAbsence endpoint (unique for your instance)

      2. Include parameters in URL with the users email address and the cloud site

      3. Define body:

         JSON

         {
           "id": "{{Absence ID}}",
           "title": "{{Outlook Event Title}}",
           "type": "Holiday",
           "start": "{{Outlook Event Start}}",
           "end": "{{Outlook Event End}}",
           "message": "Outlook Calendar Event"
         }

6. Test and Activate:

   1. Test the Zap to ensure that it correctly creates or updates absences in Jira based on Outlook events

   2. Activate the Zap

Use Case 2: Syncing Absences with Google Calendar

Objective: Automatically create absences in Jira based on events in Google Calendar.

Steps:

1. Create a Zapier Account: Sign up for a free account at Zapier

2. Set Up a Zap: Create a new Zap in Zapier

3. Trigger:

   1. Choose “Google Calendar” as the trigger app.

   2. Select the event trigger, such as “New Event” or “Event Start”.

   3. Connect your Google account to Zapier and set up the trigger details.

4. Action:

   1. Choose “Webhooks by Zapier” as the action app.

   2. Select “POST” for creating a new absence.

5. Configure the Webhook:

   1. Set the URL to the createAbsence endpoint (unique for your instance)

   2. Include parameters in URL with the users email address and the cloud site

   3. Define body:

      JSON

      {
        "title": "{{Google Calendar Event Title}}",
        "type": "Holiday",
        "start": "{{Google Calendar Event Start}}",
        "end": "{{Google Calendar Event End}}",
        "message": "Google Calendar Event"
      }

6. Test and Activate:

   1. Test the Zap to ensure that it correctly creates absences in Jira based on Google Calendar events

   2. Activate the Zap

Use Case 3: Custom Integration with HR System

Objective: Develop a custom integration to sync employee leave data from an HR system to Jira.

Steps:

1. Set Up Your Environment:

   1. Choose your programming language (e.g., Python, Node.js)

   2. Set up a development environment and install necessary libraries for making HTTP requests (e.g., requests for Python, axios for Node.js)

2. Fetch Data from HR System:

   1. Use the API provided by your HR system to fetch employee leave data

   2. Example (Python):

      PY

      import requests
      
      hr_system_url = "https://api.hr-system.com/leaves"
      response = requests.get(hr_system_url)
      leaves = response.json()

3. Map Data to Jira API:

   1. Map the leave data from the HR system to the fields required by the User Absence Planner API

   2. Example (Python):

      PY

      for leave in leaves:
          data = {
              "title": leave["title"],
              "type": leave["type"],
              "start": leave["start_date"],
              "end": leave["end_date"],
              "message": leave["notes"]
          }

4. Send Data to Jira API:

   1. Use the createAbsence endpoint to create absences in Jira

   2. Example (Python):

      PY

      jira_url = "<cloud_site_unique_createAbsence_endpoint>?user=<user_email_address&cloudSite=<your_cloud_site>"
      headers = {"Content-Type": "application/json"}
      
      for leave in leaves:
          data = {
              "title": leave["title"],
              "type": leave["type"],
              "start": leave["start_date"],
              "end": leave["end_date"],
              "message": leave["notes"]
          }
          response = requests.post(jira_url, json=data, headers=headers)
          if response.status_code == 201:
              print(f"Successfully created absence for {leave['email']}")
          else:
              print(f"Failed to create absence for {leave['email']}: {response.text}")

Conclusion

These use cases demonstrate how the User Absence Planner API can be integrated with external tools and systems. By using no-code solutions like Zapier or developing custom integrations, you can automate the management of user absences and ensure seamless synchronisation across different platforms.