Mutations

Mutations are for performing any operations which change an entity, e.g., Inserting, Updating or Deleting.

note

• Using fragments is recommended
• For better performance always use variables instead of adding parameters directly in the query body

Operations

There are various operations which can be performed which mutate an entity.

Some mutations provide an option to run the operation in "validate only" mode. By setting the validateOnly parameter to true, you can perform a validation check without actually persisting the changes. This can be useful if you want to verify the write operation before committing to the write process.

Inserting

For some of our more complicated entities such as transactions we will perform a series of calculations to populate unspecified values, e.g., when creating a transaction for a given customer we will calculate the currency from the customers.

After the calculating is finished we will then perform validation on inputs where appropriate, e.g., does the customer exist and is it active.

If validation has passed then we will commit the changes to the entity, e.g., adding the transaction to the enquiries and updating customer & nominal balances.

Updating

All of our update operations are targeted. This means that if you want to update the description of a batched transaction, all you need to send to us is the primary key (or unique id) and the new description. We treat null as an instruction to preserve the current value.

As with inserting, we will validate the changes and commit them if the validation passes.

Deleting

If the entity is valid to be deleted then we will make all the appropriate changes to remove an entity. For example deleting a sales transaction will adjust appropriate customer & nominal balances.

Processing

Sometimes an operation is more of a process than fitting nicely into one of the above types. e.g. allocating transactions.

Results

Most of our mutations return a union of results. It is important to handle each one appropriately.

Here is an example of how to handle a union mutation result

mutation CreateSalesTransactions($transactions: [SalesTransactionBulkInput!]!) {
  debtors {
    transactions {
      bulkTransactions {
        bulkCreate(transactions: $transactions) {
          ...SalesTransaction
          ...Validation
          ...Errors
        }
      }
    }
  }
}

fragment SalesTransaction on IntEntityIdsResultGraphType {
  ... on IntEntityIds {
    ids
  }
}

fragment Validation on IntEntityIdsResultGraphType {
  ... on FailedValidation {
    errors {
      message
      details {
        primaryKey
        field
        value
      }
    }
  }
}

fragment Errors on IntEntityIdsResultGraphType {
  ... on UnexpectedError {
    errorMessage
  }
}

Success

When a mutation has succeeded we will return a type indicating success. This could be just true, the primary key of the updated entity or something more.

Validation

If validation has failed we will return a FailedValidation response. It should look like the following

• errors: An array of error objects.
  • message: A message describing the validation error.
  • details: An array of details to indicate which part of the input produced the error
    • field: A path to the field on the input object e.g. DetailLines("Line1").Analysis.Code if it was an issue with the chosen analysis on the line with Index Line1
    • primaryKey: The main id for the entity such as primary key
    • value: The value of the field which was marked as invalid

Unexpected Error

If this has returned, it is unlikely to have been an invalid request. You will see an UnexpectedError type with a message describing information about the fault.

• errorMessage: A message describing the unexpected error that occurred.

In this situation we would recommend retrying as these errors could be transient, e.g., a timeout.