Skip to content
Developerhome
Product homepage
X3

Mutation types

  Less than to read

For a mutation based on import templates, several mutation types are available:

  • Create/Update/Delete
  • Custom

Depending on the context, which mutation to choose?

Create, Update and Delete mutations

Create, Update, and Delete mutations are added to a node. For these mutation types, in VS Code, only these decorators are added to the node:

Each decorator is set to true if one of the operations above is created in Sage X3. Nothing else gets added to the node.

Consequently, in GraphQL, create, update, and delete are reserved words.

create

mutation {
  x3ProjectManagement {
     timeEntryLine{
      create(
        data: {
           employee: "MNG",
           date: "2024-03-01",
           project: "X3-181158",
           task: "T1000",
           operation: 10,
           projectCostType: "",
           projectLaborRate: 12.95,
           employeeCostType: "",
           employeeLaborRate: 24.78,
           timeCategory: "BILLABLE",
           unit: "DA",
           timeSpent: 1,
           isValidated: true,
           isBillable: true,
           billableFrom: "2024-12-01",
           localizedDescription: "Design"
            }
      )
        {
        lineNumber
      }
    }
  }
}

update

mutation {
  x3ProjectManagement {
    timeEntryLine {
      update(
        data: {
          employee: "MNG",
          lineNumber: 1040,
          localizedDescription: "Design"}
      ) {
        _id
        employee {
          employee {
            code
          }
        }
        localizedDescription
      }
    }
  }
}

delete

mutation {
  x3ProjectManagement {
    timeEntryLine {
      delete(employee: "MNG", lineNumber: "540")
    }
  }
}

Custom mutations

For a Custom mutation, use the GraphQL operation name in GraphQL. An example:

lpnGrouping

mutation {
    x3Stock {
        stockChangeByLpn {
            lpnGrouping (parameter: {stockChangeLines: [{licensePlateNumber: "BAG00003", lineNumber: 1}], effectiveDate: "2024-01-15", stockSite: "NA021", licensePlateNumberOperationMode: 1, locationDestination: "QUA01",      stockChangeDestination: "internal", licensePlateNumberDestination: "BAG00001"}) {
                id
                stockSite {
                    code
                }
                effectiveDate
                project {
                    id
                }
                documentDescription
                licensePlateNumberOperationMode
                licensePlateNumberDestination {
                    code
                }
                locationDestination
                stockChangeLines {
                    query {
                        edges {
                            node {
                                stockChangeId
                                lineNumber
                            }
                        }
                    }
                }
            }
        }
    }
}

Pros and cons of each mutation type

Create, Update, and Delete mutations

Pros Cons

Based on standard reserved words from GraphQL language.

For an Update on collections, it’s possible to:

  • Update a line that already exists.
  • Create a new line.
  • Delete an existing line.

Non-transient pages will manage natively the CRUD actions on the node.

On non-transient pages that have been extended, the specific fields added by Sage Partners are taken natively into account in the payload.

Only one Create, Update, or Delete action can be performed as a CRUD action is unique.

Custom mutations

Pros Cons

There is no limit to the number of mutations. You can have as many as needed for your purpose.

For example, this can be useful if you have multiple import templates as each custom operation can be linked to a different import template.

When updating the lines of a collection, you cannot process individual modifications of lines automatically. This needs to be managed by the logic of the custom mutation.

On pages, the CRUD actions must be managed manually.

It is near impossible for Sage Partners to parse specific properties to the mutation.

How to choose between mutation methods then?

The answer to the following questions might help you choose a mutation method:

Will the mutation be the default CRUD mutation for this node?

If yes, the best method is the Create/Update/Delete method.

If no, the recommend method is the Custom operation.

Is this mutation not specific to the node but allows for an action?

If yes, the recommend method is the Custom operation.

Notes

If you have multiple import templates for the same node:

  • The question is to define the one to be used as the default for CRUD actions and the one to be used as a Custom operation.
  • Note: Defining a default Create/Update/Delete mutation on a node is not mandatory. All the operations can be Custom operations.

Having Create/Update/Delete import or window is the most common case for your nodes.