Confluence Anchor an Inline Comment to Page Text

arazzo: 1.0.1
info:
  title: Confluence Anchor an Inline Comment to Page Text
  summary: Read a page's storage body, anchor an inline comment to a text selection, and read the page's inline comments back.
  description: >-
    Inline comments are the hardest Confluence write to get right because they
    are anchored to a literal text selection inside the page body, and the
    anchor silently fails to attach when the selection does not appear the
    expected number of times. This flow reads the page in storage format so the
    caller can locate the exact selection, creates the inline comment with its
    textSelection and textSelectionMatchCount properties, and reads the page's
    inline comments back to confirm the anchor took. Every step spells out its
    request inline so the flow can be read and executed without opening the
    underlying OpenAPI description.
  version: 1.0.0
sourceDescriptions:
- name: commentApi
  url: ../openapi/confluence-comment-api-openapi.yml
  type: openapi
- name: pageApi
  url: ../openapi/confluence-page-api-openapi.yml
  type: openapi
workflows:
- workflowId: anchor-inline-comment
  summary: Create an inline comment anchored to a specific text selection on a Confluence page.
  description: >-
    Reads the target page's storage body, posts an inline comment bound to a
    text selection, and verifies the comment appears among the page's inline
    comments.
  inputs:
    type: object
    required:
    - pageId
    - textSelection
    - commentBody
    properties:
      pageId:
        type: string
        description: The id of the page to comment on.
      textSelection:
        type: string
        description: The exact text inside the page body that the comment anchors to.
      textSelectionMatchCount:
        type: integer
        description: >-
          How many times the selection occurs in the body. Confluence uses this
          to disambiguate the anchor; a wrong count detaches the comment.
      commentBody:
        type: string
        description: The comment body in Confluence storage format (XHTML).
  steps:
  - stepId: readPageBody
    description: >-
      Read the page in storage format so the caller can confirm the text
      selection exists verbatim in the body before anchoring to it.
    operationId: getPageById
    parameters:
    - name: id
      in: path
      value: $inputs.pageId
    - name: body-format
      in: query
      value: storage
    successCriteria:
    - condition: $statusCode == 200
    - context: $response.body
      condition: $.status == 'current'
      type: jsonpath
    outputs:
      title: $response.body#/title
      spaceId: $response.body#/spaceId
      body: $response.body#/body
      versionNumber: $response.body#/version/number
  - stepId: createInlineComment
    description: >-
      Create the inline comment bound to the text selection. The
      inlineCommentProperties carry the anchor; without them Confluence stores
      an unanchored comment.
    operationId: createInlineComment
    requestBody:
      contentType: application/json
      payload:
        pageId: $inputs.pageId
        body:
          representation: storage
          value: $inputs.commentBody
        inlineCommentProperties:
          textSelection: $inputs.textSelection
          textSelectionMatchCount: $inputs.textSelectionMatchCount
    successCriteria:
    - condition: $statusCode == 200
    outputs:
      commentId: $response.body#/id
      resolutionStatus: $response.body#/resolutionStatus
      anchoredSelection: $response.body#/properties/textSelection
      webui: $response.body#/_links/webui
  - stepId: verifyInlineComments
    description: >-
      Read the page's inline comments back to confirm the new comment is present
      and anchored rather than silently dropped.
    operationId: getInlineComments
    parameters:
    - name: id
      in: path
      value: $inputs.pageId
    - name: body-format
      in: query
      value: storage
    - name: limit
      in: query
      value: 250
    successCriteria:
    - condition: $statusCode == 200
    - context: $response.body
      condition: $.results.length > 0
      type: jsonpath
    outputs:
      inlineComments: $response.body#/results
  outputs:
    pageTitle: $steps.readPageBody.outputs.title
    commentId: $steps.createInlineComment.outputs.commentId
    anchoredSelection: $steps.createInlineComment.outputs.anchoredSelection
    inlineComments: $steps.verifyInlineComments.outputs.inlineComments