This page was recently updated. What do you think about it? Let us know!.

Connect Jira to your preprocessing pipeline, and use the Unstructured Ingest CLI or the Unstructured Ingest Python library to batch process all your documents and store structured outputs locally on your filesystem.

The requirements are as follows.

  • A Jira Cloud account or Jira Data Center installation.

  • The site URL for your Jira Data Center installation or Jira Cloud account. For Jira Cloud, open Jira in your web browser and copy the address from the browser’s address bar. If you’re unsure, check the dashboard URL, or if viewing an issue, project or board, the site URL is typically everything that comes before but not including /jira, such as https://<organization>.atlassian.net.

  • To process Jira projects, provide the IDs for the target projects. To get a project’s ID, sign in to your Jira Cloud account or Jira Data Center installation, and then go to the following URL: https://<organization>.atlassian.net/rest/api/latest/project/<project-key>, replacing <organization> with yours, and replacing <project-key> with the target project’s key. In the response, look for the URL https://<organization>.atlassian.net/rest/api/3/project/<project-id>, where <project-id> is the target project’s ID.

  • To process Jira boards, the IDs for the target boards. To get a board’s ID, sign in to your Jira Cloud account or Jira Data Center installation, and then go to the following URL: https://<organization>.atlassian.net/rest/agile/1.0/board?projectKeyOrId=<project-key-or-id>, replacing <organization> with yours, and <project-key-or-id> with the associated project’s key or ID. In the response, look for the URL https://<organization>.atlassian.net/rest/agile/1.0/board/<board-id>, where <board-id> is the board’s ID.

  • To process Jira issues, the IDs for the target issues. To get an issue’s ID, sign in to your Jia Cloud account or Jira Data Center installation, open the issue, and then look at the URL in your browser’s address bar. The issue ID is the string of characters after the final slash in the URL.

  • A user in your Jira Cloud account or Jira Data Center installation.

  • The user must have the correct permissions in your Jira Cloud account or Jira Data Center installation to access the target projects, boards, and issues.

  • One of the following:

The Jira connector dependencies:

CLI, Python
pip install "unstructured-ingest[jira]"

You might also need to install additional dependencies, depending on your needs. Learn more.

The following environment variables:

  • JIRA_URL - The site URL for your Jira Data Center installation or Jira Cloud account, represented by --url (CLI) or url (Python).

  • One of the following:

    • For Jira Cloud or Jira Data Center, the target user’s name or email address, and password or API token, as follows:

      • JIRA_USERNAME - The name or email address of the target user, represented by --username (CLI) or username (Python).
      • JIRA_PASSWORD_OR_API_TOKEN - The user’s password (for password authentication) or API token (for API token authentication), represented by --password (CLI) or password (Python).

    • For Jira Data Center only, the target user’s personal access token (PAT), as follows:

      • JIRA_PERSONAL_ACCESS_TOKEN - The user’s personal access token (PAT), represented by --token (CLI) or token (Python).

Also, to process specific projects, boards, or issues, use:

  • --projects with a comma-delimited list of target project IDs (CLI) or project with an array of target project IDs (Python).
  • --boards with a comma-delmited list of target board IDs (CLI) or boards with an array of target board IDs (Python).
  • --issues with a comma-delimited list of target issue IDs (CLI) or issues with an array of target issue IDs (Python).
  • --status-filter with a comma-delimited list of statuses to filter Jira issues by (CLI) or status_filter with an array of statuses to filter Jira issues by (Python).
  • --download-attachments (CLI) or download_attachments=True (Python) to download attachments from Jira issues.
  • --no-download-attachments (CLI) or download_attachments=False (Python) to not download attachments from Jira issues. This is the default behavior.
  • --cloud (CLI) or cloud=True (Python) to specify using Jira Cloud. The default is to use Jira Data Center.
  • --no-cloud (CLI) or cloud=False (Python) to specify using Jira Data Center. This is the default behavior.

Now call the Unstructured CLI or Python. The destination connector can be any of the ones supported. This example uses the local destination connector.

This example sends data to Unstructured for processing by default. To process data locally instead, see the instructions at the end of this page.

#!/usr/bin/env bash

# Chunking and embedding are optional.

unstructured-ingest \
  jira \
    --url $JIRA_URL \
    --username $JIRA_USERNAME \
    --password $JIRA_PASSWORD_OR_API_TOKEN \ # Password or API token authentication.
    --token $JIRA_PERSONAL_ACCESS_TOKEN \ # Personal access token authentication only.
    --cloud \ # For Jira Cloud.
    --no-cloud \ # For Jira Data Center (default).
    --output-dir $LOCAL_FILE_OUTPUT_DIR \
    --projects <project-id>,<project-id> \
    --boards <board-id>,<board-id> \
    --issues <issue-id>,<issue-id> \
    --status-filters <status>,<status> \
    --download-attachments \
    --chunking-strategy by_title \
    --embedding-provider huggingface \
    --partition-by-api \
    --api-key $UNSTRUCTURED_API_KEY \
    --partition-endpoint $UNSTRUCTURED_API_URL \
    --strategy hi_res \
    --additional-partition-args="{\"split_pdf_page\":\"true\", \"split_pdf_allow_failed\":\"true\", \"split_pdf_concurrency_level\": 15}"

For the Unstructured Ingest CLI and the Unstructured Ingest Python library, you can use the --partition-by-api option (CLI) or partition_by_api (Python) parameter to specify where files are processed:

  • To do local file processing, omit --partition-by-api (CLI) or partition_by_api (Python), or explicitly specify partition_by_api=False (Python).

    Local file processing does not use an Unstructured API key or API URL, so you can also omit the following, if they appear:

    • --api-key $UNSTRUCTURED_API_KEY (CLI) or api_key=os.getenv("UNSTRUCTURED_API_KEY") (Python)
    • --partition-endpoint $UNSTRUCTURED_API_URL (CLI) or partition_endpoint=os.getenv("UNSTRUCTURED_API_URL") (Python)
    • The environment variables UNSTRUCTURED_API_KEY and UNSTRUCTURED_API_URL

  • To send files to the Unstructured Partition Endpoint for processing, specify --partition-by-api (CLI) or partition_by_api=True (Python).

    Unstructured also requires an Unstructured API key and API URL, by adding the following:

    • --api-key $UNSTRUCTURED_API_KEY (CLI) or api_key=os.getenv("UNSTRUCTURED_API_KEY") (Python)
    • --partition-endpoint $UNSTRUCTURED_API_URL (CLI) or partition_endpoint=os.getenv("UNSTRUCTURED_API_URL") (Python)
    • The environment variables UNSTRUCTURED_API_KEY and UNSTRUCTURED_API_URL, representing your API key and API URL, respectively.

    You must specify the API URL only if you are not using the default API URL for Unstructured Ingest, for example, if you are using a self-hosted instance of the Unstructured API.

    The default API URL for Unstructured Ingest is https://api.unstructuredapp.io/general/v0/general, which is the API URL for the Unstructured Partition Endpoint. However, you should always use the URL that was provided to you when your Unstructured account was created. If you do not have this URL, contact Unstructured Sales at sales@unstructured.io.

    If you do not have an API key, get one now.

    If the Unstructured API is self-hosted, the process for generating Unstructured API keys, and the Unstructured API URL that you use, are different. For details, contact Unstructured Sales at sales@unstructured.io.