CEL Variables Reference

Twisp uses Common Expression Language extensively for computation across the API. Different contexts expose different variables depending on their purpose. This reference documents what variables are available in each context.

Overview

Indexes

Custom indexes use CEL expressions to define partition keys, sort keys, and filter constraints. In all index expressions, the primary variable is document, which represents the record being indexed.

Available Variables

The type of document depends on the on field specified when creating the index:

• ACCOUNT → Account
• ACCOUNT_SET → AccountSet
• TRANSACTION → Transaction
• TRANCODE → TranCode
• BALANCE → Balance
• ENTRY → Entry

Partition Expressions

Partition keys determine how records are grouped in the index.

Copymutation CreatePartitionedIndex {
  schema {
    createIndex(
      input: {
        name: "entries_by_account"
        on: Entry
        partition: [
          { alias: "accountId", value: "document.account_id" }
          { alias: "journalId", value: "document.journal_id" }
        ]
      }
    ) { name }
  }
}

Partition expressions can return arrays to create multiple index entries. For example this create multiple partitions for the account id and each of it's parent account sets (at time of posting):

Copypartition: [
  {
    alias: "accountId",
    value: "document.parent_account_ids + [document.account_id]"
  }
]

Sort Expressions

Sort keys define the ordering within each partition. In this example sorting either by th

Copymutation CreateSortedIndex {
  schema {
    createIndex(
      input: {
        name: "entries_by_effective"
        on: Entry
        partition: [{ alias: "accountId", value: "document.account_id" }]
        sort: [
          {
            alias: "effective"
            value: "'effective' in document.metadata && document.metadata.effective != null ? document.metadata.effective : document.created"
            type: STRING
            sort: DESC
          }
        ]
      }
    ) { name }
  }
}

Filter Constraints

Constraints are boolean expressions that must all evaluate to true for a record to be included in the index.

Copymutation CreateFilteredIndex {
  schema {
    createIndex(
      input: {
        name: "active_entries"
        on: Entry
        partition: [{ alias: "accountId", value: "document.account_id" }]
        constraints: {
          isNotVoidEntry: "!document.is_void_entry"
          isNotVoidedEntry: "!document.is_voided_entry"
          isSettled: "document.layer == SETTLED" 
        }
      }
    ) { name }
  }
}

Calculations

Calculations define how balances are computed and grouped. CEL expressions are used in dimension definitions and conditions.

Available Variables

Dimension Expressions

Dimensions define how balances are grouped. Common use cases include grouping by date, metadata values, or account properties.

Copymutation CreateEffectiveDateCalculation {
  createCalculation(
    input: {
      calculationId: "5867b5dd-fc69-416c-80f5-62e8a53610d5"
      code: "EFFECTIVE_DATE"
      description: "Track balances per effective date."
      dimensions: [
        {
          alias: "effectiveDate"
          value: "context.vars.transaction.effective"
        }
      ]
      scope: LOCAL
    }
  ) {
    calculationId
    code
  }
}

Multi-dimensional calculations:

Copymutation CreateMultiDimensionCalculation {
  createCalculation(
    input: {
      calculationId: "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      code: "BY_CURRENCY_AND_DATE"
      description: "Track balances by currency and effective date."
      dimensions: [
        {
          alias: "currency"
          value: "context.vars.account.metadata.currency"
        }
        {
          alias: "effectiveDate"
          value: "context.vars.transaction.effective"
        }
      ]
      scope: LOCAL
    }
  ) { calculationId }
}

Condition Expressions

Conditions filter which entries are included in the calculation. They must evaluate to a boolean.

Copymutation CreateConditionalCalculation {
  createCalculation(
    input: {
      calculationId: "b2c3d4e5-f6a7-8901-bcde-f23456789012"
      code: "POLICY_PAYMENTS"
      description: "Track only entries to accounts with policy payment metadata."
      dimensions: [
        { alias: "effectiveDate", value: "context.vars.transaction.effective" }
      ]
      condition: "has(context.vars.account.metadata.policyPayment)"
      scope: LOCAL
    }
  ) { calculationId }
}

Using entry fields in conditions:

Copycondition: "document.layer == 0 && document.direction == 0"

Tran Codes

Tran codes are templates that define how transactions and entries are created. CEL expressions are used extensively to dynamically compute values at post time.

Available Variables

Parameter Access

Parameters are defined in the tran code and passed at post time. Access them with params.<paramName>:

Copymutation CreateTranCode {
  createTranCode(
    input: {
      code: "TRANSFER"
      description: "Transfer funds between accounts"
      params: [
        { name: "amount", type: TYPE_DECIMAL, description: "Transfer amount" }
        { name: "fromAccount", type: TYPE_UUID, description: "Source account" }
        { name: "toAccount", type: TYPE_UUID, description: "Destination account" }
        { name: "memo", type: TYPE_STRING, default: "'Transfer'", description: "Optional memo" }
      ]
      transaction: {
        description: "'Transfer ' + string(params.amount) + ' - ' + params.memo"
      }
      entries: [
        {
          entryType: "'TRANSFER_DR'"
          accountId: "params.fromAccount"
          direction: "'DEBIT'"
          units: "params.amount"
          currency: "'USD'"
        }
        {
          entryType: "'TRANSFER_CR'"
          accountId: "params.toAccount"
          direction: "'CREDIT'"
          units: "params.amount"
          currency: "'USD'"
        }
      ]
    }
  ) { code }
}

Vars (Scratch Pad)

The vars field provides a scratch pad for intermediate calculations. Variables defined here can be referenced in transaction and entry expressions:

Copymutation CreateTranCodeWithVars {
  createTranCode(
    input: {
      code: "TRANSFER_WITH_FEE"
      description: "Transfer with calculated fee"
      params: [
        { name: "amount", type: TYPE_DECIMAL }
        { name: "fromAccount", type: TYPE_UUID }
        { name: "toAccount", type: TYPE_UUID }
        { name: "feeAccount", type: TYPE_UUID }
      ]
      vars: {
        feeRate: "'0.025'"
        feeAmount: "decimal(params.amount) * decimal(vars.feeRate)"
        netAmount: "decimal(params.amount) - vars.feeAmount"
      }
      entries: [
        {
          entryType: "'TRANSFER_DR'"
          accountId: "params.fromAccount"
          direction: "'DEBIT'"
          units: "params.amount"
          currency: "'USD'"
        }
        {
          entryType: "'TRANSFER_CR'"
          accountId: "params.toAccount"
          direction: "'CREDIT'"
          units: "vars.netAmount"
          currency: "'USD'"
        }
        {
          entryType: "'FEE_CR'"
          accountId: "params.feeAccount"
          direction: "'CREDIT'"
          units: "vars.feeAmount"
          currency: "'USD'"
        }
      ]
    }
  ) { code }
}

Entry Conditions

Entry conditions determine whether an entry should be created. Useful for optional entries:

Copyentries: [
  {
    entryType: "'FEE'"
    accountId: "params.feeAccount"
    direction: "'CREDIT'"
    units: "params.feeAmount"
    currency: "'USD'"
    condition: "params.feeAmount > decimal('0.00')"
  }
]

Transaction Fields

All fields in the transaction block accept CEL expressions:

Entry Fields

All fields in each entry accept CEL expressions:

Entity Field Reference

Account Fields

Account Set Fields

Transaction Fields

Entry Fields

TranCode Fields

Balance Fields

Type Constructors

When working with CEL expressions, use these constructors to create typed values:

For a complete list of functions, see the CEL Functions Reference.