add external_references

external_references/Jira/README.md

@@ -0,0 +1,73 @@
+# PagerDuty to Jira Incident Mapping
+The `pagerduty_jira_incidents.py` script sends a GET request to the incidents endpoint to retrieve incident data, filters for incidents containing Jira external_references, and then generates a CSV file mapping the PagerDuty incidents to their corresponding Jira tickets:
+
+- PagerDuty Incident Number
+- Title
+- Description
+- Created At
+- Updated At
+- Status
+- PagerDuty Incident URL
+- Jira Ticket ID
+- Jira Ticket URL
+
+## Requirements
+
+- Python 3.6+
+- PagerDuty API Access Token
+
+## Installation
+
+1. Clone this repository
+   ```bash
+   git clone https://github.com/PagerDuty/public-support-scripts.git
+   ```
+
+2. `cd` to the Jira directory within `external_references`.
+
+3. Install required dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Usage
+
+1. Create a `.env` file in the Jira directory.
+
+2. Update the `.env` file with your PagerDuty API key:
+   ```
+   PAGERDUTY_REST_API_KEY=your_api_key_here
+   ```
+
+3. Define your request parameters in the `request_parameters.py` file.
+
+4. Run the `pagerduty_jira_incidents.py` script in the Jira directory:
+   ```bash
+   python3 pagerduty_jira_incidents.py
+   ```
+
+## How the Script Works
+
+The `pagerduty_jira_incidents.py` script will:
+
+1. Send a GET request to the incidents endpoint to retrieve incident data
+2. Filter incidents to include only those with Jira external_references
+3. Generate a CSV file named `pagerduty_incidents_mapped_to_jira.csv` in the Jira directory.
+
+## Error Handling
+
+The `pagerduty_jira_incidents.py` script will exit with an error message in the following cases:
+
+- If the PagerDuty API request fails
+- If no incidents with Jira external_references are found
+
+## Security Notes
+
+1. Never commit your `.env` file
+2. User Token Rest API Keys are restricted in accordance with the user's access and permissions, so the GET request to the incidents endpoint will only retrieve incidents that the user has access to. General Access Rest API Keys do not have such restrictions.
+
+## Resources
+
+1. [List incidents endpoint documentation](https://developer.pagerduty.com/api-reference/9d0b4b12e36f9-list-incidents)
+2. [Pagination documentation](https://developer.pagerduty.com/docs/pagination)
+3. [API Access Keys documentation](https://support.pagerduty.com/main/docs/api-access-keys)

external_references/Jira/pagerduty_jira_incidents.py

@@ -0,0 +1,127 @@
+import requests
+import json
+import csv
+import os
+
+from dotenv import load_dotenv
+
+import request_parameters as parameters
+
+load_dotenv()
+PAGERDUTY_REST_API_KEY = os.getenv("PAGERDUTY_REST_API_KEY")
+
+
+def get_incidents():
+    """
+    Makes a GET request to the incidents endpoint to retrieve incident data.
+
+    Raises:
+        SystemExit: If the API request fails or returns an error.
+
+    Returns:
+        dict: JSON response containing incident data if successful.
+    """
+    url = "https://api.pagerduty.com/incidents"
+
+    querystring = {"include[]":"external_references"}
+
+    headers = {
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "Authorization": f"Token token={PAGERDUTY_REST_API_KEY}"
+    }
+
+    if parameters.since:
+        querystring["since"] = parameters.since
+    if parameters.until:
+        querystring["until"] = parameters.until
+    if parameters.limit:
+        querystring["limit"] = parameters.limit
+    if parameters.offset:
+        querystring["offset"] = parameters.offset
+
+    try:
+        response = requests.get(url, headers=headers, params=querystring)
+        response.raise_for_status()
+        if response.text:
+            return response.json()
+    except requests.exceptions.RequestException as e:
+        raise SystemExit(e)
+
+
+def filter_incidents(incidents):
+    """
+    Filter incidents to only include those with Jira external_reference.
+
+    Iterates through the incidents and keeps only those containing
+    Jira external_reference.
+
+    Args:
+        incidents (dict): JSON dict containing incident data returned from the GET request
+        to the incidents endpoint.
+
+    Raises:
+        SystemExit: If no incidents with Jira external_reference are found.
+
+    Returns:
+        list: incidents containing Jira external_reference.
+    """
+    incidents_with_jira_reference = []
+    jira_incidents_set = set()
+
+    for incident in incidents["incidents"]:
+        if incident["external_references"] != []:
+            for reference in incident["external_references"]:
+                if "atlassian" in reference["external_url"] or "Jira issue" in reference["summary"]:
+                    if incident["id"] not in jira_incidents_set:
+                        incidents_with_jira_reference.append(incident)
+                        jira_incidents_set.add(incident["id"])
+
+    if not incidents_with_jira_reference:
+        raise SystemExit("No Jira external_reference found in any incidents")
+
+    return incidents_with_jira_reference
+
+def generate_csv(filtered_incidents):
+    """
+    Generate a CSV file mapping PagerDuty incidents to Jira data.
+
+    Creates a CSV file with relevant PagerDuty incident information (PagerDuty Incident Number", "Title", "Description", 
+    "Created At", "Updated At", "Status", "PagerDuty Incident URL") and
+    the corresponding Jira ticket IDs and Jira ticket URLs.
+
+    Args:
+        filtered_incidents (list): List of incidents containing Jira external_reference.
+    """
+    csv_filename = "pagerduty_incidents_mapped_to_jira.csv"
+    # Define the header for the CSV
+    headers = ["PagerDuty Incident Number", "Title", "Description", "Created At", "Updated At", "Status", "PagerDuty Incident URL", "Jira Ticket ID", "Jira Ticket URL"]
+    # Write to CSV file
+    with open(csv_filename, mode="w", newline="", encoding="utf-8") as file:
+        writer = csv.DictWriter(file, fieldnames=headers)
+        writer.writeheader()
+
+        for incident in filtered_incidents:
+            for reference in incident["external_references"]:
+                if "atlassian" in reference["external_url"] or "Jira issue" in reference["summary"]:
+                    writer.writerow({
+                        "PagerDuty Incident Number": incident.get("incident_number", ""),
+                        "Title": incident.get("title", ""),
+                        "Description": incident.get("description", ""),
+                        "Created At": incident.get("created_at", ""),
+                        "Updated At": incident.get("updated_at", ""),
+                        "Status": incident.get("status", ""),
+                        "PagerDuty Incident URL": incident.get("html_url", ""),
+                        "Jira Ticket ID": reference["external_id"],
+                        "Jira Ticket URL": reference["external_url"],
+                    })
+
+
+def main():
+    incidents = get_incidents()
+    filtered_incidents = filter_incidents(incidents)
+    csv = generate_csv(filtered_incidents)
+
+
+if __name__ == "__main__":
+    main()

external_references/Jira/request_parameters.py

@@ -0,0 +1,4 @@
+since = ""
+until = ""
+limit = None
+offset = None

external_references/Jira/requirements.txt

@@ -0,0 +1,2 @@
+python-dotenv
+requests

external_references/ServiceNow/README.md

@@ -0,0 +1,74 @@
+# PagerDuty to ServiceNow Incident Mapping
+The `pagerduty_servicenow_incidents.py` script sends a GET request to the incidents endpoint to retrieve incident data, filters for incidents containing ServiceNow metadata, and then generates a CSV file mapping the PagerDuty incidents to their corresponding ServiceNow incidents:
+
+- PagerDuty Incident Number
+- Title
+- Description
+- Created At
+- Updated At
+- Status
+- PagerDuty Incident URL
+- ServiceNow Incident ID
+- ServiceNow Incident URL
+
+## Requirements
+
+- Python 3.6+
+- PagerDuty API Access Token
+- ServiceNow v3 webhooks
+
+## Installation
+
+1. Clone this repository
+   ```bash
+   git clone https://github.com/PagerDuty/public-support-scripts.git
+   ```
+
+2. `cd` to the ServiceNow directory within `external_references`.
+
+3. Install required dependencies:
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+## Usage
+
+1. Create a `.env` file in the ServiceNow directory.
+
+2. Update the `.env` file with your PagerDuty API key:
+   ```
+   PAGERDUTY_REST_API_KEY=your_api_key_here
+   ```
+
+3. Define your request parameters in the `request_parameters.py` file.
+
+4. Run the `pagerduty_servicenow_incidents.py` script in the ServiceNow directory:
+   ```bash
+   python3 pagerduty_servicenow_incidents.py
+   ```
+
+## How the Script Works
+
+The `pagerduty_servicenow_incidents.py` script will:
+
+1. Send a GET request to the incidents endpoint to retrieve incident data
+2. Filter incidents to include only those with ServiceNow references
+3. Generate a CSV file named `pagerduty_incidents_mapped_to_servicenow.csv` in the ServiceNow directory.
+
+## Error Handling
+
+The `pagerduty_servicenow_incidents.py` script will exit with an error message in the following cases:
+
+- If the PagerDuty API request fails
+- If no incidents with ServiceNow metadata are found
+
+## Security Notes
+
+1. Never commit your `.env` file
+2. User Token Rest API Keys are restricted in accordance with the user's access and permissions, so the GET request to the incidents endpoint will only retrieve incidents that the user has access to. General Access Rest API Keys do not have such restrictions.
+
+## Resources
+
+1. [List incidents endpoint documentation](https://developer.pagerduty.com/api-reference/9d0b4b12e36f9-list-incidents)
+2. [Pagination documentation](https://developer.pagerduty.com/docs/pagination)
+3. [API Access Keys documentation](https://support.pagerduty.com/main/docs/api-access-keys)