Pennylane Trial Balance Integrity Gate

id: pennylane-trial-balance-integrity-gate
namespace: company.team

description: |
  Fetch a Pennylane trial balance for an accounting period, sum debits against credits, alert
  Slack when they do not balance within a tolerance, and log a governance audit trail either
  way. Read-only: this flow never writes to Pennylane.

inputs:
  - id: period_start
    type: STRING
    displayName: Period start
    description: Start of the accounting period, YYYY-MM-DD.
    defaults: "2026-01-01"

  - id: period_end
    type: STRING
    displayName: Period end
    description: End of the accounting period, YYYY-MM-DD.
    defaults: "2026-01-31"

  - id: max_imbalance
    type: FLOAT
    displayName: Max allowed imbalance
    description: Absolute difference between total debits and total credits above
      which the trial balance is reported out of balance, in the company's
      currency unit. A small nonzero value absorbs rounding.
    defaults: 0.01

  - id: max_records
    type: INT
    displayName: Max records
    description: Safety cap on the total number of trial balance rows retrieved
      across all pages. Leave generous, a real imbalance must be computed over
      every ledger account, not a partial page.
    defaults: 5000

tasks:
  - id: get_trial_balance
    type: io.kestra.plugin.pennylane.accounting.trialbalance.Get
    description: Read-only. Retrieves every ledger account's debits and credits for
      the period.
    allowFailure: true
    apiToken: "{{ secret('PENNYLANE_API_TOKEN') }}"
    periodStart: "{{ inputs.period_start }}"
    periodEnd: "{{ inputs.period_end }}"
    maxRecords: "{{ inputs.max_records }}"
    fetchType: FETCH

  - id: evaluate
    type: io.kestra.plugin.core.output.OutputValues
    description: Sums debits and credits across every returned row. A trial balance
      that does not net to zero within max_imbalance is a bookkeeping integrity
      problem, not a rounding artifact.
    values:
      account_count: "{{ (outputs.get_trial_balance is defined and
        outputs.get_trial_balance.count is defined) ?
        outputs.get_trial_balance.count : 0 }}"
      total_debits: "{{ (outputs.get_trial_balance is not defined or
        outputs.get_trial_balance.rows is not defined or
        outputs.get_trial_balance.rows is null) ? 0 : (({'rows':
        outputs.get_trial_balance.rows} | jq('[(.rows // [])[] | (.debits // 0 |
        tonumber)] | add // 0')) | first) }}"
      total_credits: "{{ (outputs.get_trial_balance is not defined or
        outputs.get_trial_balance.rows is not defined or
        outputs.get_trial_balance.rows is null) ? 0 : (({'rows':
        outputs.get_trial_balance.rows} | jq('[(.rows // [])[] | (.credits // 0
        | tonumber)] | add // 0')) | first) }}"
      imbalance: "{{ (outputs.get_trial_balance is not defined or
        outputs.get_trial_balance.rows is not defined or
        outputs.get_trial_balance.rows is null) ? 0 : (({'rows':
        outputs.get_trial_balance.rows} | jq('([(.rows // [])[] | (.debits // 0
        | tonumber)] | add // 0) - ([(.rows // [])[] | (.credits // 0 |
        tonumber)] | add // 0)')) | first) }}"
      severity: "{{ (outputs.get_trial_balance is not defined or
        outputs.get_trial_balance.rows is not defined or
        outputs.get_trial_balance.rows is null) ? 'CRITICAL' : (((({'rows':
        outputs.get_trial_balance.rows} | jq('(([(.rows // [])[] | (.debits // 0
        | tonumber)] | add // 0) - ([(.rows // [])[] | (.credits // 0 |
        tonumber)] | add // 0)) | if . < 0 then -. else . end')) | first)) >
        inputs.max_imbalance ? 'OUT_OF_BALANCE' : '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 ~ ': Pennylane trial balance for ' ~ inputs.period_start ~ ' to ' ~ inputs.period_end ~ ' does not balance. debits=' ~ outputs.evaluate.values.total_debits ~ ', credits=' ~ outputs.evaluate.values.total_credits ~ ', imbalance=' ~ outputs.evaluate.values.imbalance ~ ' (tolerance ' ~ inputs.max_imbalance ~ '), across ' ~ outputs.evaluate.values.account_count ~ ' account(s).'} | toJson }}
    else:
      - id: compliant
        type: io.kestra.plugin.core.log.Log
        message: "Trial balance for {{ inputs.period_start }} to {{ inputs.period_end }}
          balances: debits={{ outputs.evaluate.values.total_debits }},
          credits={{ outputs.evaluate.values.total_credits }}, across {{
          outputs.evaluate.values.account_count }} account(s)."

  - id: summary
    type: io.kestra.plugin.core.log.Log
    message: "Pennylane trial balance integrity gate complete for {{
      inputs.period_start }} to {{ inputs.period_end }}: imbalance={{
      outputs.evaluate.values.imbalance }}, severity {{
      outputs.evaluate.values.severity }}."

errors:
  - id: alert_flow_failure
    type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
    url: "{{ secret('SLACK_WEBHOOK_URL') }}"
    payload: |
      {{ {'text': 'Pennylane trial balance integrity gate failed (execution ' ~ execution.id ~ '). Check the logs.'} | toJson }}

triggers:
  - id: monthly
    type: io.kestra.plugin.core.trigger.Schedule
    description: Shipped disabled. Enable once PENNYLANE_API_TOKEN and
      SLACK_WEBHOOK_URL are set and the period inputs are mapped to a real
      closing cadence.
    cron: "0 6 1 * *"
    disabled: true
    inputs:
      period_start: "{{ trigger.date | dateAdd(-1, 'MONTHS') | date('yyyy-MM-01') }}"
      period_end: "{{ trigger.date | date('yyyy-MM-01') | dateAdd(-1, 'DAYS') |
        date('yyyy-MM-dd') }}"
      max_imbalance: 0.01
      max_records: 5000