Read ALM issues and add comments

Use an existing project integration to read an external issue, download an
attachment, or post a comment. These operations support Jira Cloud, Jira Data
Center, and Azure DevOps, not Xray. Start in a non-production project.

1. Prepare your integration and IDs

Have a project administrator configure the ALM integration in the UI first.
Obtain that existing project integration ID from your project's integration
setup. It is not the connection ID, project ID, or external provider project ID.
For an existing integration, its ID is also the integration record's id in
GET /v2/alm/connections/integrations. Use only an integration that belongs to
your current project.

Use the ALM issue key or the provider's own issue ID as the issue ID:

Do not use a requirement's numeric externalIssueId. It is not a substitute
for its Jira key on this route and can return "Issue does not exist". See
Know which ID is which.
Obtain an attachment ID from the external provider when downloading an
attachment; do not substitute a Katalon Storage file ID.

2. Authenticate

Use your tenant host, https://<tenant>.katalon.io, without a trailing slash.
Use HTTP Basic with an empty username and your Katalon API key as the password.
See Authenticate with the v2 API.
Do not use a platform password, an internal Bearer token, or an x-api-key header.

Send x-project-id on every request. Your key's user needs access to that project,
and the integration must belong to it. Reads require Requirement:Read;
comment creation requires Requirement:Update. Account UUID (x-account-id)
and organization ID (x-organization-id) are optional context headers; supply
them if required by your environment's context resolution.

Set KATALON_API_HOST, KATALON_API_KEY, and KATALON_PROJECT_ID from your
environment or secret store. Keep shell tracing (set -x) disabled. This Bash
helper sends the key to curl over standard input rather than process arguments.
Escape " and \ in the key as \" and \\ for curl's configuration format.

katalon_request() {
  : "${KATALON_API_KEY:?Missing API key}"
  printf 'user = ":%s"\n' "${KATALON_API_KEY}" |
  curl --config - --silent --show-error --fail-with-body \
    --header "x-project-id: ${KATALON_PROJECT_ID:?Missing project ID}" \
    "$@"
}

3. Read an issue

Set ALM_INTEGRATION_ID to the existing project integration ID and ALM_ISSUE_ID
to the provider issue key or work-item ID. The issue read requires an active
integration. Get an ALM issue:

katalon_request \
  "${KATALON_API_HOST}/v2/alm/integrations/${ALM_INTEGRATION_ID}/issues/${ALM_ISSUE_ID}"

The JSON response contains provider issue fields such as issueId, summary,
status, and description. Fields vary by provider; accept additional fields
and do not assume that every optional field is populated.

4. Download attachment bytes

Set ALM_ATTACHMENT_ID to an attachment ID obtained from the external provider.
Download an ALM attachment:

katalon_request \
  "${KATALON_API_HOST}/v2/alm/integrations/${ALM_INTEGRATION_ID}/issues/attachments/${ALM_ATTACHMENT_ID}" \
  --output attachment.bin

Success returns application/octet-stream, not JSON or a download URL.
Choose your own output filename; no response filename is promised. This is
provider attachment content, not Katalon Storage. Project ownership, read
permission, and working provider access still apply.
If the request fails, inspect the status before treating the saved file as an
attachment: curl can save an error response too.

5. Add a comment

Comment creation requires an active integration.
Comments are posted with the credentials of the account that set up the ALM connection.
In Jira or Azure
DevOps, the comment shows that account, not the TestOps user who owns your API
key. A template's authorName value does not change the commenter.

Save this body as comment.json:

{"content":"Please confirm the acceptance criteria."}

Add an ALM issue comment:

katalon_request \
  "${KATALON_API_HOST}/v2/alm/integrations/${ALM_INTEGRATION_ID}/issues/${ALM_ISSUE_ID}/comments" \
  --request POST --header 'Content-Type: application/json' \
  --data-binary @comment.json

Success is 201 with the created comment. Response content is the rendered
provider content; authorName, when available, is the provider's author display
name. Without a template, Jira receives wiki markup unchanged and Azure DevOps
receives HTML-escaped text. Do not retry blindly after a timeout: a second request
can create another comment.

To use the clarification layout, replace the body with:

{
  "content": "Should this check include inactive records?",
  "template": {
    "slug": "requirement-clarification-questions-answers",
    "parameters": {
      "title": "Acceptance criteria clarification",
      "sourceLabel": "Integration review"
    }
  }
}

This is the only template slug. If a non-null template has a missing,
null, or unknown slug, the request returns 400. Parameters may be null;
a null or blank title falls back to the supplied content. Optional authorName,
sourceLabel, and sourceUrl render as empty text when absent. They are display
values, not credentials. Template output is Jira wiki markup or Azure DevOps
HTML; Jira wiki-special characters are not automatically escaped.

Troubleshooting

Check project access, Requirement:Read or Requirement:Update, the integration's
project, and provider access. Azure DevOps issue IDs must be numeric. Provider
errors are not guaranteed to share one status or body; preserve the status and
safe diagnostic details without logging credentials or private issue content.