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. That configuration endpoint is outside
this reference; use only an integration belonging to your current project.
This reference does not provide integration-list or setup operations.

For Jira Cloud or Jira Data Center, use an issue key such as DEMO-42.
For Azure DevOps, use the numeric work-item ID as a string, such as 42.
For an issue linked to a True Platform requirement, take the ALM issue key from
the requirement's sourceId; for a defect, use issueId. Use the ALM issue key
or the provider's own issue ID, not the requirement's externalIssueId.
In particular, a requirement's numeric externalIssueId is not a substitute
for its Jira key on this route and can return "Issue does not exist".
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 the authentication reference.
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. The download does not use
the same active-integration lookup as issue reads and comment creation, but
project ownership, read permission, and working provider access still matter.
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.
The provider commenter is not the TestOps caller and is not selected by the
Katalon API key or a template's authorName value.

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"
    }
  }
}

That is the only supported 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.