Confluence Stale Documentation Audit Sentinel

id: confluence-stale-documentation-audit-sentinel
namespace: company.team

description: |
  List Confluence pages across one or more spaces, flag the ones whose last edit is older than
  a retention threshold you set, alert Slack with the exact titles when any are found, and log a
  governance audit trail either way. Read-only: this flow never edits or archives a page.

inputs:
  - id: confluence_server_url
    type: STRING
    displayName: Confluence server URL
    description: Base Confluence site URL, for example
      https://your-domain.atlassian.net, without a trailing slash.
    defaults: "https://your-domain.atlassian.net"

  - id: space_ids
    type: ARRAY
    itemType: INT
    displayName: Space IDs to scan
    description: Confluence space IDs to audit. Leave empty to scan across every
      space the account can see, within limit.
    defaults: []

  - id: limit
    type: INT
    displayName: Max pages per scan
    description: Maximum pages fetched per run. API max is 250.
    defaults: 100

  - id: stale_after_days
    type: INT
    displayName: Stale after days
    description: A page whose latest version was created this many days ago or more
      is reported stale.
    defaults: 180

  - id: max_stale_count
    type: INT
    displayName: Max stale count
    description: Alert when this many or more pages are found stale.
    defaults: 1

tasks:
  - id: list_pages
    type: io.kestra.plugin.confluence.pages.List
    description: Read-only. Fetches current and archived pages, optionally scoped to
      space_ids, with each page's version metadata.
    allowFailure: true
    serverUrl: "{{ inputs.confluence_server_url }}"
    username: "{{ secret('CONFLUENCE_USERNAME') }}"
    apiToken: "{{ secret('CONFLUENCE_API_TOKEN') }}"
    spaceIds: "{{ inputs.space_ids }}"
    limit: "{{ inputs.limit }}"

  - id: evaluate
    type: io.kestra.plugin.core.output.OutputValues
    description: Compares each page's version.createdAt (its latest edit timestamp)
      against the stale_after_days cutoff, by date only, computed here so the
      comparison never depends on wall-clock time inside jq.
    values:
      stale_count: >-
        {{ outputs.list_pages is not defined ? -1 : (({'children':
        outputs.list_pages.children, 'cutoff': (now() |
        dateAdd(-inputs.stale_after_days, 'DAYS') | date('yyyy-MM-dd'))} |
        jq('.cutoff as $c | [(.children // [])[] |
        select(((.versionInfo.createdAt // "")[0:10]) as $d | $d != "" and $d <=
        $c)] | length')) | first | number) }}
      stale_titles: >-
        {{ outputs.list_pages is not defined ? '' : (({'children':
        outputs.list_pages.children, 'cutoff': (now() |
        dateAdd(-inputs.stale_after_days, 'DAYS') | date('yyyy-MM-dd'))} |
        jq('.cutoff as $c | [(.children // [])[] |
        select(((.versionInfo.createdAt // "")[0:10]) as $d | $d != "" and $d <=
        $c) | .title] | join("; ")')) | first) }}
      severity: >-
        {{ outputs.list_pages is not defined ? 'CRITICAL' : (((({'children':
        outputs.list_pages.children, 'cutoff': (now() |
        dateAdd(-inputs.stale_after_days, 'DAYS') | date('yyyy-MM-dd'))} |
        jq('.cutoff as $c | [(.children // [])[] |
        select(((.versionInfo.createdAt // "")[0:10]) as $d | $d != "" and $d <=
        $c)] | length')) | first | number) >= inputs.max_stale_count) ?
        'STALE_DOCS_FOUND' : 'OK') }}

  - id: route
    type: io.kestra.plugin.core.flow.If
    condition: "{{ outputs.evaluate.values.severity != 'OK' }}"
    then:
      - id: alert
        type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
        url: "{{ secret('SLACK_WEBHOOK_URL') }}"
        payload: |
          {{ {'text': outputs.evaluate.values.severity ~ ': ' ~ outputs.evaluate.values.stale_count ~ ' Confluence page(s) have not been edited in ' ~ inputs.stale_after_days ~ ' day(s) or more: ' ~ outputs.evaluate.values.stale_titles ~ '.'} | toJson }}
    else:
      - id: compliant
        type: io.kestra.plugin.core.log.Log
        message: "No scanned Confluence page is older than {{ inputs.stale_after_days }}
          day(s) since its last edit."

  - id: summary
    type: io.kestra.plugin.core.log.Log
    message: "Confluence stale documentation audit sentinel complete: {{
      outputs.evaluate.values.stale_count }} stale page(s), severity {{
      outputs.evaluate.values.severity }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {'text': 'Confluence stale documentation audit sentinel failed (execution ' ~ execution.id ~ '). Check the logs.'} | toJson }}

triggers:
  - id: weekly
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled. Enable once CONFLUENCE_USERNAME,
      CONFLUENCE_API_TOKEN, and SLACK_WEBHOOK_URL are set and
      confluence_server_url/space_ids point at a real site.
    cron: "0 7 * * 1"
    disabled: true
    inputs:
      confluence_server_url: "https://your-domain.atlassian.net"
      space_ids: []
      limit: 100
      stale_after_days: 180
      max_stale_count: 1