Skip to main content

Nominal Transactions

This document provides an overview of the operations available for the Financials (Nominal) Transactions business entity. Please note that the queries shown below only present a subset of the fields.

For a full list of fields, please refer to our schema documentation provided within our API. See Explore the API.

Mutations​

Create Journal Transactions​

To create new Nominal transactions within a Financials or Dimensions database, the Transaction bulk create endpoint can be used. This operation supports both batching and posting of transactions. You can create one or more of the following types of Nominal transactions using this operation:

  • Journal
  • Debit Tax(VAT) Journal
  • Credit Tax(VAT) Journal
  • Currency Transfer

Request​

Here's an example of how you can use the create mutation:

mutation (
  $transactions: [NominalTransactionBulkInput!]!
  $validateOnly: Boolean
) {
  financials {
    transactions {
      bulkTransactions {
        bulkCreate(transactions: $transactions, validateOnly: $validateOnly) {
          ... on IntEntityIds {
            ...IntEntityIdDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment IntEntityIdDetails on IntEntityIds {
  ids
}

fragment FailedValidationDetails on FailedValidation {
  errors {
    ...ValidationItemDetails
  }
  warnings {
    ...ValidationItemDetails
  }
}

fragment ValidationItemDetails on ValidationItem {
  message
  details {
    primaryKey
    field
    value
  }
}

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

When you execute the create mutation, it performs several steps to create new transactions:

  1. Running business validations: The API performs a number of business validations on the input data to ensure that it meets the required criteria. These validations can include checks for things like valid nominal accounts, correct gross amount, and any other business rules specific to your application. If any validation errors occur, the mutation will return a response with the details of the errors.

  2. Calculating missing information: If any required information is missing from the input object, the mutation will calculate the missing values based on default settings or any other logic defined in the system. This ensures that the transaction has all the necessary data before it is created.

  3. Saving the transaction: If all the necessary information is present and the business validations pass successfully, the mutation will save the transaction in the system and make it available for further processing or retrieval.

Parameters​

Transaction [Required]​

This mutation requires an input object of type NominalTransactionBulkInput, which should contain all the necessary information to create the transaction.

Validate Only​

This operation supports "validate only" mode by setting the validateOnly parameter to true. In this mode, the API will check your transaction against a number of business rules, but will not attempt to save the transaction to the database.

Response​

After executing the create mutation, you will receive a response containing the IDs of the updated transactions if the creation was successful. If any validation errors or unexpected errors occur during the operation, the response will include the details of those errors.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "financials": {
      "transactions": {
        "bulkTransactions": {
          "bulkCreate": {
              [100, 101, 102]
          }
        }
      }
    }
  }

Update Nominal Transactions​

To update a Nominal transaction, you can use the bulk update mutation. Like the transaction creation request, this mutation requires an input object of type NominalTransactionBulkInput, which should contain the information you wish to update on the existing transaction.

note

It is only possible to update batched transactions via this operation.

Request​

Here's an example of how you can use the update mutation to update a Journal transaction:

mutation (
  $transactions: [NominalTransactionBulkInput!]!
  $validateOnly: Boolean
) {
  financials {
    transactions {
      bulkTransactions {
        bulkUpdate(transactions: $transactions, validateOnly: $validateOnly) {
          ... on IntEntityIds {
            ...IntEntityIdDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment IntEntityIdDetails on IntEntityIds {
  ids
}

fragment FailedValidationDetails on FailedValidation {
  errors {
    ...ValidationItemDetails
  }
  warnings {
    ...ValidationItemDetails
  }
}

fragment ValidationItemDetails on ValidationItem {
  message
  details {
    primaryKey
    field
    value
  }
}

fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

When you execute the update mutation, it performs the following steps to update the Nominal transaction:

  1. Finding the transaction: The mutation first finds the Nominal transaction in the system.
  2. Updating the information: The mutation then updates the transaction with the new information provided in the NominalTransactionInput object.
  3. Recalculating missing information: If any required information is missing from the input object, the mutation will calculate the missing values based on default settings or any other logic defined in the system. This ensures that the transaction has all the necessary data before it is created.
  4. Running business validations: Similar to the create mutation, the update mutation also performs business validations on the updated data to ensure it meets the required criteria. If any validation errors occur, the mutation will return a response with the details of the errors.
  5. Saving the updated transaction: If all the necessary information is present and the business validations pass successfully, the mutation will save the updated transaction in the system. This means that the changes will be persisted and available for further processing or retrieval.

Parameters​

Transaction [Required]​

This mutation requires an input object of type NominalTransactionBulkInput, which should contain all the necessary information to create the transaction.

Validate Only​

This operation supports "validate only" mode by setting the validateOnly parameter to true, in this mode, the API will check your transaction against a number of business rules, but will not attempt to save the transaction to the database.

Response​

After executing the update mutation, you will receive a response containing the updated Nominal transaction's ID if the update was successful. If any validation errors or unexpected errors occur during the operation, the response will include the details of those errors.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "financials": {
      "transactions": {
        "bulkTransactions": {
          "bulkUpdate": {
            [100,101,102]
          }
        }
      }
    }
  }
}

Delete Nominal Transactions​

To delete Nominal transactions, you can use the delete mutation. This operation contains a mandatory primaryKeys parameter which should be populated with the primary key of each transaction you want to delete.

note

Note this endpoint only supports the deletion of Nominal Transactions. For the removal of other transaction types, please refer to our API schema documentation: Explore the API

Here's an example of how you can use the delete mutation to delete Nominal transactions:

mutation ($primaryKeys: [Int!]!) {
  financials {
    transactions {
      batchedTransactions {
        delete(primaryKeys: $primaryKeys) {
          ... on Succeeded {
            ...SucceededDetails
          }
          ... on FailedValidation {
            ...FailedValidationDetails
          }
          ... on UnexpectedError {
            ...UnexpectedErrorDetails
          }
        }
      }
    }
  }
}

fragment SucceededDetails on Succeeded {
  succeeded
}
fragment FailedValidationDetails on FailedValidation {
  errors {
    ...ValidationItemDetails
  }
  warnings {
    ...ValidationItemDetails
  }
}
fragment ValidationItemDetails on ValidationItem {
  message
  details {
    primaryKey
    field
    value
  }
}
fragment UnexpectedErrorDetails on UnexpectedError {
  errorMessage
}

In the above example, you need to provide the primaryKeys array containing the primary keys of the transactions you want to delete. The mutation will then attempt to delete the specified transactions.

If the deletion is successful, the response will include a succeeded field with a value of true. If any validation errors occur during the deletion process, the response will include the details of those errors in the errors field. Additionally, if there are any warnings related to the deletion, they will be included in the warnings field. If an unexpected error occurs, the response will include an errorMessage field with the details of the error.

An example of the three response types provided by this request can be found below:

{
  "data": {
    "financials": {
      "transactions": {
        "batchedTransactions": {
          "delete": {
            "succeeded"
          }
        }
      }
    }
  }
}

Queries​

Get Batched Nominal Transaction​

To retrieve information about a specific batched Nominal transaction, you can use the transactionEntry\header query. This query requires an input parameter id which represents the primary key of the transaction you want to retrieve.

Here's an example of how you can use the transactionEntry\header query to get the details of a batched Nominal transaction:

query ($id: Int!) {
  financials {
    transactions {
      transactionEntry {
        header(id: $id) {
          transactionType
          hasNextPage
          header {
            ...HeaderDetails
          }
          detailLines {
            ...DetailLinesData
          }
        }
      }
    }
  }
}

fragment HeaderDetails on NominalTransactionHeader {
  primaryKey
  headerReference
  description
  currency{
    code
    rate
    symbol
  }
  values {
    ...HeaderValueData
  }
  period {
    year
    yearLabel
    number
  }
  subLedger {
    code
    description
  }
}

fragment DetailLinesData on NominalTransactionDetail {
  primaryKey
  detail
  tax {
    code
    rate
    type
  }
  values {
    ...DetailValueData
  }
  costing {
    project {
      code
      name
    }
    costCentre {
      code
      name
    }
  }
}

fragment DetailValueData on TransactionValues {
  net
  tax
  gross
  currencyNet
  currencyTax
  currencyGross
}

fragment HeaderValueData on NominalTransactionValues {
  home
  currency
}

In this query, you need to provide the id parameter with the primary key of the batched Nominal transaction you want to retrieve. The response will include detailed information about the transaction, including the transaction type, dates, values, period, subledger details, and detail lines.

The query only returns first page of detail lines, to get additional pages please use transactionEntry/details.

query (
  $filter: NominalTransactionDetailFilterInput!
  $sort: [NominalTransactionDetailSortSortByInput!]
  $first: Int
) {
  financials {
    transactions {
      transactionEntry {
        details(filter: $filter, sort: $sort, first: $first) {
          items {
            primaryKey
            index
            action
            quantity
            detail
            detailReference
            detailDate
            nominalUpdate {
              debit {
                code
                name
              }
              credit {
                code
                name
              }
            }
            tax {
              code
              rate
              type
              nonRecoverableAccountCode
              nonRecoverableAccountName
              nonRecoverablePercentage
            }
            values {
              net
              tax
              gross
              currencyNet
              currencyTax
              currencyGross
            }
            currency {
              symbol
              code
              rate
              currencyEuroRate
              base2Rate
            }
            costing {
              project{
                code
                name
              }
              costCentre{
                code
                name
              }
            }
            transactionUserKeys {
              key1
              key2
              key3
              key4
              key5
            }
            custom {
              char1
              char2
              char3
              char4
              number1
              number2
              date1
              date2
              flag1
              flag2
            }
            interCompany {
              primaryKey
              databasePrimary
              nominalCode
              projectCode
              costCentreCode
              contraCode
              subLedger
              useGross
              entryCode1
              entryCode2
              entryCode3
              entryCode4
              entryCode5
              entryCode6
              entryCode7
              entryCode8
              currency
              databasePrimaryFixed
              nominalFixed
              entryCode1Fixed
              entryCode2Fixed
              entryCode3Fixed
              entryCode4Fixed
              entryCode5Fixed
              entryCode6Fixed
              entryCode7Fixed
              entryCode8Fixed
            }
          }
        }
      }
    }
  }
}

Query Transaction Details​

To retrieve detailed information about Nominal transactions, you can use the details field within the allTransactions query. This field requires the following input parameters:

  • $first: Specifies the maximum number of results to retrieve.
  • $sort: Specifies the sorting order for the results based on specific fields.
  • $filter: Specifies the conditions to filter the transactions.

Here's an example of how you can use the details field to retrieve detailed information about Nominal transactions:

query (
  $first: Int
  $sort: [NominalTransactionEnquiryDetailSortSortByInput!]
  $filter: NominalTransactionEnquiryDetailFilterInput!
) {
  financials {
    transactions {
      allTransactions {
        details(first: $first, sort: $sort, filter: $filter) {
          items {
            auditNo
            nominalType
            nominalCurrencySymbol
            batchRef
            subLedger
            date
            headerRef
            currencySymbol
            batched
            exchangeRate
            origin
            period
            yearLabel
            enteredBy
            dateEntered
            detail
            reconciled
            reconcileStatus
            journalType
            debit
            currencyDebit
            credit
            currencyCredit
            nominalCode
            inactive
            description
            createdBy
            createdDateTime
            lastUpdatedBy
            lastUpdatedTime
            postedBy
            postedDateTime
          }
        }
      }
    }
  }
}

In the above query, you can customize the parameters $first, $sort, and $filter to retrieve the desired number of results, apply sorting based on specific fields, and filter the transactions based on certain conditions.

The response will include an array of transaction details, each containing various fields such as primary key, journalType, headerRef, etc.