Skip to content
Developerhome
Product homepage
X3

Mutations based on Sage X3 Classes

  Less than to read

In GraphQL, mutations are used to modify the data on the server with a request sent to the Sage X3 operation through the Syracuse server. A success or failure response is returned by the server.

To create a GraphQL mutation based on an existing Sage X3 class, you’ll need a class from the Classes function (GESACLA).

Then create the operation as usual, very similarly to how Mutations based on Windows are created.

1. Class definition (GESACLA)

  • Set up your class as usual in X3.
  • Predefined standard methods are used on the API authorization setup:
    • If C, Creation is active (marked as Y), the operation may authorize Create mutations.
    • If D, Deletion is active, the operation may authorize Delete mutations.
    • If U, Modification is active, the operation may authorize Update mutations.

The Class properties and Class collections are used in the API operation (GESAPIOPE) function to automatically initialize the mapping between class properties and node properties.

Note: If needed, the main node and references and collections are also checked to initialize the mapping between the class and node properties.

2. Create your operation (GESAPIOPE)

Once the Sage X3 class is defined, you can map it to your node in the API operation function (GESAPIOPE).

  • Fill in the Sage X3 operation identifier. The operation identifier must be unique.
  • For Sage X3 class, set the Mutation type field to Create/Update/Delete.
    • Create, Update, and Delete are standard GraphQL operations. A single node may only have one of each.
      • Use the checkboxes Can create, Can update, and Can delete in the Authorization section to select the mutation type (Create, Update, or Delete) for the operation.
    • The mutation type Custom is not allowed for operations based on Sage X3 classes.
  • Define the Operation method as class to enable the Sage X3 class selection in the Definition section.
  • Select the Main node name. This is the node where the operation will be generated.
    • The node will show the operation when you explore the graph through an external tool.
    • Multiple Custom operations can be linked to the same node, but only one Create, Update or Delete operations can be defined for a node.
    • When nodes are generated, Sage X3 will only consider the active Create, Update, or Delete operations defined in the API operation function (GESAPIOPE).
  • Define the GraphQL operation name to be generated on the selected node.
    • As a property name, the operation name must be unique in the node definition.
    • The operation name must respect the camelCase naming convention.
  • For Create, Update, or Delete operations, the operation name is not used by the framework.
    • Only the mutation type (Create, Update, or Delete) is used by the framework to determine the operation when a standard GraphQL Create, Update, or Delete mutation is triggered for a node.
    • Consequently, the operation name can be anything, as it is not used by the framework.

Details

  • Select the module.
  • Select an activity code if needed.
  • Mark the operation as active or not.
  • You can use this same form to override an existing operation. If overriding rather than creating a new operation, type the name of the operation to override into Operation override. See Operation override for more details.
  • The Node binding (request) identifier is generated automatically from the operation.
    • It is initialized by default by the Sage X3 operation identifier.
  • Enter a Node name (request).
    • An operation that uses a Sage X3 class is bound to the main node tied to the Sage X3 class properties.
      • The Node name (request) field is initialized by default by the Main node.
    • After saving the operation, a node definition is automatically generated in the node bindings table based on the Node binding (request) and Node name (request).
      • This technical node is used to map the class properties to the main node and build the mutation payload.
      • The node definition is accessible in the Node binding dictionary (GESAPINOD).
  • Enter the Package name where the operation will be generated.
    • For partners, package selection is restricted to custom packages.
  • For an operation based on an Sage X3 class, the Node binding (response) field is not available. Just select the class to be used in the class field.

Authorizations

  • Functional authorization: Ties the operation to a functional access defined in the Functional profile for the user’s functional profile. This authorization is optional.
  • Option: Ties the operation to an action code you can add to the access right definition for finer control. This authorization is optional.
  • Checkboxes Can create, Can update, and Can Delete define the mutation type to be enabled in the operation.
    • The checkboxes are verified against the Sage X3 class definition and authorization.
    • Only one of the Create, Update, or Delete operations can be defined for a node.

Class properties

  • Bindings:
    • By default no boxes are checked.
    • When you check a box, it is automatically mapped with existing class information.
  • If the tables connected to the class (see the Table view field) are properly configured, the Property names will be automatically loaded.
    • The transient properties used to map the technical field defined on the class must be selected manually.
    • After saving the operation, the associated node binding record and properties are automatically created in the node bindings tables.
      • The node operation is visible in the Node bindings function (GESANODEB) in the Class left list.
      • The node operation and properties are visible in the Bindings dictionary function (GESAPINOD).
  • Use the Selection checkbox to validate the properties to be mapped on the Class properties.
    • Note: The new fields added afterward to the class definition will be displayed on the associated API operation unticked. After, it will be possible to set the corresponding property names from the node and mark the new class properties as selected for the mapping.
  • If a mandatory property is missing from the mapping, the operation can be saved but it will not be possible to activate.

How to manage collections

  • Add the collection-friendly name to the property column at the parent level.
    • Use class properties to map a collection-friendly name in the property column.
    • All class collections properties are visible below and are available for selection.
    • When a class collection contains another class collection, all properties of those classes are visible up to a maximum of 5 levels deep.
    • On collection properties, fill in the parent property matching with the collection-friendly name of the parent.
    • If multiple collections exist for the same parent node, you must define the parent line for each collection.

How to manage denormalized collections (dimensioned fields)

  • Add the property name and the denormalized collection name in the corresponding columns.
  • Properties with dimensions are grouped in a single line in the operation.
    • The dimension column indicates the number of dimensions defined and managed in the defined class collection, for collections not connected to another class.
  • The list of fields in the grid is sorted the same as the list of fields in the Sage X3 class. This includes the dimension fields.

Case of denormalized collections in grids

  • When a field is defined in a list on the class properties, the mapping must explicitly be the property + index to be mapped on the class property.
    • For example, taxes~1, taxes~2, etc.

Generated nodes

  • If a Create, Update, or Delete operation is defined on a node in X3, the following attributes will be added to the Sage X3 services node definition after running the npm run generate command in VSCode:
    • canCreate: true
    • canUpdate: true
    • canDelete: true

Sage X3 Class Mutation Schema