Building Tran Codes

Transaction codes play a critical role in identifying and categorizing transactions in the ledger, and designing them is an important part of using Twisp. By following the steps outlined in this tutorial, you will be able to create and manage transaction codes in your own ledger.

Prerequisites

Before you start, you should have added accounts to your ledger. See the tutorial on Setting Up Accounts.

Getting started

The easiest way to interact with the Twisp GraphQL API is to login to the Twisp Console and use the GraphiQL tool.

If you prefer to use your own GraphQL client, you can send authenticated requests to the Twisp API endpoint.

To seed your setup with some example accounts, sets, and tran codes, you can use the Example Setup.

Create a new tran code

To create a new tran code, use the createTranCode mutation. The input argument specifies the full configuration of the tran code and how transactions posted with this code will be structured, including all entries written to the ledger.

Many of the fields in the TranCodeInput object (and its nested objects) allow for CEL expressions to be used, which will be evaluated during the postTransaction call and the results will be used in the creation of a transaction posted with the new transaction code.

Note that the params field allows for the specification of parameters that can be used in CEL expressions for the transaction and entries fields. These parameters can be used to make the transaction code more flexible and dynamic, allowing for the creation of more complex transactions.

The transaction and entries fields, respectively, act as templates for the Transaction and Entries that are created when this tran code is used in a postTransaction call.

Here's an example of creating a new tran code for a BOOK_TRANSFER:

Copymutation CreateTranCode(
  $tcBookTransferId: UUID!
  $journalGLIdExp: Expression!
) {
  createTranCode(
    input: {
      tranCodeId: $tcBookTransferId
      code: "BOOK_TRANSFER"
      description: "Book transfer between two internal accounts."
      metadata: { category: "Internal" }
      params: [
        { name: "crAccount", type: UUID, description: "Account to credit." }
        { name: "drAccount", type: UUID, description: "Account to debit." }
        {
          name: "amount"
          type: DECIMAL
          description: "Amount with decimal, e.g. `1.23`."
        }
        {
          name: "currency"
          type: STRING
          description: "Currency used for transaction."
        }
        {
          name: "effective"
          type: DATE
          description: "Effective date for transaction."
        }
      ]
      transaction: {
        journalId: $journalGLIdExp
        effective: "params.effective"
        description: "'Book transfer for $' + string(params.amount)"
      }
      entries: [
        {
          accountId: "params.drAccount"
          units: "params.amount"
          currency: "params.currency"
          entryType: "'BOOK_TRANSFER_DR'"
          direction: "DEBIT"
          layer: "SETTLED"
        }
        {
          accountId: "params.crAccount"
          units: "params.amount"
          currency: "params.currency"
          entryType: "'BOOK_TRANSFER_CR'"
          direction: "CREDIT"
          layer: "SETTLED"
        }
      ]
    }
  ) {
    tranCodeId
  }
}

Once created, transactions can be posted using this transaction code by providing the required fields in a TransactionInput object. The inputs for a postTransaction using this tran code must include fields for the crAccount, drAccount, amount, currency, and effective.

Query tran codes

The tranCode query can be used to read back an existing tran code using its tranCodeId.

Here is an example query:

Copyquery GetBookTransferTranCode {
  tranCode(id: "e0ffa94d-ca03-4ae2-aa69-cbaaa21d3855") {
    code
    description
    params {
      name
      type
      description
    }
    transaction {
      journalId
      effective
      correlationId
      description
    }
    entries {
      accountId
      layer
      direction
      units
      currency
    }
    status
    metadata
  }
}

This query will respond with the fields for the BOOK_TRANSFER tran code created above, identified by its UUID.

The params field in the response includes information about the parameters required by this transaction code, such as the name, type, and description of each parameter.

The transaction field in the response includes details about the transaction that is created when this transaction code is used.

The entries field in the response includes information about the entries that are created when this transaction code is used.

Finally, the response includes the status of the transaction code, which can be either ACTIVE or LOCKED, and any metadata associated with the transaction code.

Modify an existing tran code

To modify an existing tran code, use the updateTranCode mutation.

Provide the tran code's id and the fields to update in the TranCodeUpdateInput input object. You can only modify a subset of fields for data integrity purposes.

Here's an example of modifying the description of an existing tran code:

Copymutation UpdateTranCode($tcBookTransferId: UUID!) {
  updateTranCode(
    id: $tcBookTransferId
    input: {
      description: "Book transfer between two customer wallet accounts."
      entries: [
        {
          accountId: "params.drAccount"
          units: "params.amount"
          currency: "params.currency"
          entryType: "'BOOK_TRANSFER_DR'"
          direction: "DEBIT"
          layer: "SETTLED"
          metadata: "{'first': 1}"
        }
        {
          accountId: "params.crAccount"
          units: "params.amount"
          currency: "params.currency"
          entryType: "'BOOK_TRANSFER_CR'"
          direction: "CREDIT"
          layer: "SETTLED"
          metadata: "{'second':2}"
        }
      ]
    }
  ) {
    tranCodeId
    description
    entries {
      metadata
    }
    history(first: 2) {
      nodes {
        version
        description
      }
    }
  }
}

This operation updates the description of a transaction code. The response includes the UUID and the updated description of the transaction code, as well as the history of the changes made to the transaction code.

Lock a tran code

Because Twisp is an immutable database, we cannot fully "delete" a tran code. Instead, Twisp marks the tran code's status as LOCKED, which prevents transactions from posting using this version of tran code.

To delete (lock) an tran code, we can use the deleteTranCode mutation. We need to provide the id of the tran code we want to delete. Here's an example mutation:

Copymutation DeleteTranCode($tcBookTransferId: UUID!) {
  deleteTranCode(id: $tcBookTransferId) {
    tranCodeId
    status
  }
}

Once the tran code is deleted, this mutation returns two fields: tranCodeId and status. tranCodeId is a UUID that uniquely identifies the deleted tran code, while status is the current status of the tran code (i.e. LOCKED).

This mutation is useful if you need to remove an tran code that is no longer needed or was created in error.

Conclusion

This tutorial covered the basics of creating, modifying, and deleting transaction codes. Transaction codes play a critical role in identifying and categorizing transactions in the ledger, and designing them is an important part of using Twisp. By following the steps outlined in this tutorial, you should be able to create and manage transaction codes in your own ledger.