Skip to content
Developerhome
Product homepage
X3

Import templates

  Less than to read

You can create a GraphQL mutation based on an import template.

This is the most versatile way of creating GraphQL mutations as it benefits from the standard business rules linked to objects in Sage X3 when necessary.

1. Create your import template (GESAOE)

  • Create your import template with identifiers and fields as usual in X3.
  • Set the File type field to Json (API). This determines that the import template is dedicated to the GraphQL API and will only accept JSON GraphQL payloads.
  • Each Identifier must be linked to a relevant node.

Import fields

  • Add the imported fields in the grid as usual.
  • Separator fields are not required.
  • You must manually add the technical fields (*#) defined in an import template (such as *61, *62...) in the node definition as transient properties.
    • Declare the transient properties to be sent to an API operation for your node in the Node bindings function (GESANODEB).

Composite nodes

  • In some cases, the same identifier may refer to multiple tables. In those cases, the node linked to the identifier must be a composite node.
    • For example, in the standard BPC Import Template, some fields with the identifier B are linked to the BPCustomer table and some others, with the same identifier, are linked to the BPARTNER table.
    • For the identifier B, the Node name (API) field can be set to Customer. This is a composite node with properties bound to both BPARTNER and BPCUSTOMER.
  • You can define composite nodes in the Node bindings function (GESANODEB).

2. Create your operation (GESAPIOPE)

Once your import template is created, you can map it to your node in the API Operations function (GESAPIOPE).

  • Fill in the X3 operation identifier. The operation identifier must be unique.
  • For import templates, you can set the Mutation type field to Custom or Create/Update/Delete.
    • Create, Update, and Delete are standard GraphQL operations. A single node may only have one each.
      • Use the checkboxes Can create, Can update and Can delete under the Authorization section to select the mutation type (create, update, or delete) for the operation.
      • By default, Can create is always selected and greyed for an import-template-based CRUD mutation.
      • The checkbox Can update depends on the checkbox Update allowed on the Import template definition (GESAOE).
    • Custom operations are miscellaneous operations that can perform any action linked to the node and return any structure or reference. Custom operations can be freely defined.
  • Define the Operation method as Import to link the operation to your import template.
  • Select the Main node name. This bonds the node to an operation. The node will show the operation when you explore the graph with the aid of an external tool.
    • Multiple Custom operations can be linked to the same node, but only one Create, Update, or Delete operation can be defined for a node.
    • When nodes are generated, X3 only takes into account the active Create, Update, or Delete operations defined in the Operations function (GESAPIOPE).
  • Define the GraphQL operation name to be generated on the selected node.
    • The operation name must be unique for that node.
    • The operation name must respect the naming convention.
  • For Create, Update, or Delete operations, the operation name is not used by the framework.
    • The mutation type (Create, Update or Delete) is used by the framework to determine the operation to be executed when a standard GraphQL Create, Update or Delete mutation is triggered for a node.
    • X3 executes the active Create, Update or Delete operation defined in the Operations function (GESAPIOPE).

Details

  • Select the module, activity code (if required), and mark the operation as active.
  • Enter a Node binding (request) identifier.
    • This identifier is used as a reference for the node bindings record generated for the operation.
    • X3 operation identifier initializes it by default.
  • Enter a Node name (request).
    • An operation using an import template is bound to the main node tied to the import template.
      • 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 binding tables. The node definition is based on the node identifier and node name.
      • This technical node is used to map the import template fields to the main node and build the mutation payload.
      • The node definition is accessible in the Binding dictionary function (GESAPINOD).
  • Enter the Package name where the operation will be generated.
    • For partners, the package selection is restricted to custom packages.
  • For an operation using an import template, the node binding (response) field is not available.
  • For an operation based on an import template, the following field is editable:
    • Select the import template to be used in the Import/Export template 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 that you can add to the access right definition for finer control. This authorization is optional.

Imported fields

  • Bindings:
    • Once the import template is selected, the fields are automatically loaded in the grid in the Binding column.
  • If the import template identifiers and their corresponding nodes are properly configured, the Property names are also loaded automatically.
    • The transient properties used to map the technical field defined in the import template 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 Import left list.
      • The node operation and properties are visible in the Bindings dictionary function (GESAPINOD).

How to manage collections

  • Add the collection friendly name to the property column at parent level.
    • If there are multiple collections under the same parent node, a parent line for each collection needs to be defined.
    • As an example, please see the API Operation mapping for the standard operation COM_BPC_CUD based on the JSOBPC Import Template.

How to manage denormalized collections

  • Add the property name and the denormalized collection name in the corresponding columns.
    • As an example, please see the API Operation mapping for the standard operation COM_BPC_CUD (salesReps, addressLines, ...).
  • 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 import template.

Notes:

The list of fields in the grid must be sorted the same as the list of fields in the import template. This includes the dimension fields.

The dimension fields in the Import template function should not be sorted by index. Instead, they should be sorted by name.

  • As an example, please see the Customer Import Template JSOBPC (TEL(0), TEL(1), ..., WEB(0), WEB(1), ...).

Operation override

  • Any standard operation type or method can be customized. You can do this by creating specific ones or by using the Operation override field.

Generated nodes

  • If a create, update or delete operation is defined on a node in X3, the following attributes will be added to the x3-services node definition after the npm run generate command is run in VSCode:
    • canCreate: true
    • canUpdate: true
    • canDelete: true