Operations
Use the Operations function (GESAPIOPE) to link existing or specific Sage X3 functions, such as sub-programs, windows, classes or import templates, to API nodes.
Active operations are exposed as GraphQL mutations. In GraphQL, mutations are used to modify the server data. The GraphQL mutation request is sent to the Sage X3 operation through the Syracuse server, and the server returns a success or failure response.
Prerequisites
Depending on your situation, you need to create:
-
Subprograms and parameters in the Subprograms function (GESASU)
-
Import templates from the Import/export templates function (GESAOE)
-
Windows from the Window management function (GESAWI)
-
Classes from the Classes function (GESACLA)
-
Node scripts in VS Code
Follow the procedures described under the Sage X3 Builder Mutations chapter on developer.sage.com.
Screen management
The screen is defined in 7 tabs:
-
The header,
-
The General tab,
-
The Variables tab,
-
The Imports tab,
-
The Window tab,
-
The Class tab,
-
The Node script tab.
Header
This section outlines the key information for API operations.
Mutation type (OPEMUTTYP) |
Select the mutation type. It can be:
For subprograms, select Custom. The Custom mutation type is not allowed for window-based operations and classes. |
Operation method (AX3OPE) |
Select the operation method. It can be:
For subprograms, select Script. For import/export templates, select Import. For windows, select Window. For classes, select Class. Select Node script to declare operations executed at the Sage X3 Services side on a node. The operation executes a function developed in TypeScript that is similar to computed values. |
Operation (APIOPE) |
Select or enter your Sage X3 API operation identifier. This operation identifier must be unique. |
Main node name (APIREF) |
Select the node where the operation generates. That node shows the operation when you explore the graph through an external tool. You can link multiple custom operations to the same node. You can only define one Create, Update, or Delete operation for a node. For example, SalesOrder.create or SalesOrder.delete. When nodes are generated, Sage X3 only considers the active Create, Update, or Delete operation defined in the Operations function (GESAPIOPE). |
GraphQL operation name (ANODOP) |
Define the GraphQL operation name to generate on the selected node. The operation name must be unique in the node definition, like a property name. The operation name must respect the camelCase naming convention. For example, updatePickTicketLine. For Create/Update/Delete mutation types, the operation name is not used in the GraphQL schema, which always uses the standard naming, such as SalesOrder.create, SalesOrder.delete, or SalesOrder.update. |
Description (ZADES) |
This field displays the short description for your operation. |
General
This section defines the characteristics, the node bindings, and the authorizations related to your API operation.
Characteristics
Module (MODULE) |
Select the module of your operation. |
Activity code (CODACT) |
An activity code is used to:
|
Active (ENAFLG) |
Select this checkbox to activate your operation. |
Operation override (APIOPEOVW) |
You can customize any standard operation type or method by creating a specific one and indicating it in this field. Select the operation that your current API operation replaces and overrides. For more information, consult the Mutation override documentation on developer.sage.com. |
Definition
Node binding (request) (AREQBDG) |
Enter the identifier used as a reference for the node bindings records generated for the operation. The Operation identifier initializes this field by default. |
Node name (request) (ANODE) |
Enter a node name for your request. The GraphQL operation name field initializes this field by default, but you can modify it. The node name must respect the PascalCase naming convention. After saving the operation, a transient node (not linked to a database table) automatically generates in the node bindings tables based on the Node binding (request) node identifier and the Node name (request) node name. For subprograms, this technical node stores the mapping between the subprogram parameters and the transient properties available on the main node to build the mutation payload and execute the mutation. The transient properties are added on the main node when you generate the package in VS Code. For import/export templates, windows, or classes, this technical node maps the fields to the main node and builds the mutation payload. An operation using an import template, window, or class, is bound to the main node tied to the import template, window, or class. The node definition is accessible in the Binding dictionary function (GESAPINOD). |
Package name (APACK) |
Select the package where you want to generate the operation. |
Node binding (response) (AREQRSP) |
For a script mutation, the node binding (response) is the same as the node binding (request). The node definition for the response is the same as the node definition of the request. This field is not available for operations using an import/export template or a window. |
Import/export templates (AOEOPE) |
For an operation based on an import/export template, select the import/export template to use. |
Window (AWIOPE) |
For an operation based on a window, select the window to use. |
Classes (CLAOPE) |
For an operation based on a class, select the class to use. |
Invisible fields (INVISIBLE) |
For an operation based on a window, select this checkbox to map invisible or hidden fields to the node properties. |
Script (PRG) |
For a custom operation based on a subprogram, select your script. |
Subprogram (SUBPRG) |
For a custom operation based on a subprogram, select your subprogram. |
Action (ACTION) |
For a custom operation based on a subprogram, select the action to execute in the script for this operation. |
Authorization
Functional authorization (FNC) |
Select the functional authorization for your API operation. This ties the operation to the functional access right defined in the user's functional profile (access rights by site). |
Option (OPT) |
You can tie the operation to an action code that you can add to the access rights definition for finer control. For example, a user can have the right to modify a sales order but not close it. |
Can create (CANCRE) |
Select this checkbox to set the Create mutation type for your operation. The Can create checkbox is selected and greyed for an import template-based CRUD mutation.
|
Can update (CANUPD) |
Select this checkbox to set the Update mutation type for your operation. For import/export templates, this checkbox depends on the Update allowed checkbox in the Import/export templates function (GESAOE). |
Can delete (CANDEL) |
Select this checkbox to set the Delete mutation type for your operation. |
Variables
This section allows you to map your subprogram to your node after creating it in the Users function (GESAUS).
For further information, refer to the Subprograms procedure on developer.sage.com.
Binding (ABIND) |
When you select the subprogram, the variables are automatically loaded in the Binding column. |
Property (APROPNAM) |
Enter the property names to map to the subprogram variables in the node definition. After saving the operation, a transient node and properties are automatically created in the node bindings tables based on the node identifier, the node name, and the property names. The transient node is visible in the Node bindings function (GESANODEB). The transient nodes and properties are visible in the Binding dictionary function (GESAPINOD) under the Script left list. In VS Code, the properties are generated on the node as transient, meaning not linked to the database fields as for regular properties that are bound to table fields in the Tables function (GESATB). |
Type (ATYPE) |
This column indicates the different property types. |
Direction (ASENS) |
Select if your parameter is an input, an output, or both. |
Dimension (DIME) |
Properties with dimensions are grouped on a single line on the operation. This field indicates the number of dimensions defined and managed in the subprogram for the property. |
Local menu number (NOLIB) |
This column displays the local menu related to the parameters if there is one. |
Parent property (STRUCTNAM) |
Use this field to configure your collections. Enter the name of the parent property. |
Imports
This section allows you to create a GraphQL mutation based on an import template. This is the most versatile way of creating GraphQL mutations while benefiting from the standard business rules linked to objects in Sage X3 when necessary.
You must sort the list of fields in the grid as in the import template, including the dimension fields.
Don't sort the dimensioned fields by index in the Import/export templates function (GESAOE). You need to sort them by name. As an example, refer to the JSOBPC customer import template (TEL(0), TEL(1), WEB(0), WEB(1), and so on).
For further information, refer to the Import templates procedure on developer.sage.com.
Node name (IMPANODE) |
This column indicates the node the imported fields belong to. |
Binding (IMPABIND) |
When you select the import/export template, the fields are automatically loaded in the Binding column. |
Property (IMPAPROPNAM) |
If you properly configure the import template identifiers and their corresponding nodes, the property names are also automatically loaded. You must manually select the transient properties used to map the technical field defined in the import template. 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) under the Imports left list. The node operation and properties are visible in the Binding dictionary function (GESAPINOD). |
Type (IMPATYPE) |
This column indicates the type of imported properties. |
Dimension (IMPDIME) |
Properties with dimensions are grouped on a single line on the operation. This field indicates the number of dimensions defined and managed in the import template for the property. |
Denormalized collection (IMPDENCOLGR) |
Enter the name of the denormalized collection to which this property belongs. |
Local menu number (IMPNOLIB) |
This column displays the local menu related to the imported fields if there is one. |
Join type (IMPKINDREF) |
Use this field to configure your collections. Enter the collection name in the Property column and select Collection on the same line for your collection's parent level. The parent level must be on the line just above the collection. If multiple collections are under the same parent node, then you have to define this parent line for each collection. |
Parent property (IMPARENTPROP) |
Use this field to configure your collections. Enter the collection's name defined at the parent level in the collection's Property column. |
Window
This section allows you to create a GraphQL mutation based on an existing Sage X3 window. You can then benefit from the standard business rules linked to Sage X3 objects.
For further information, refer to the Windows procedure on developer.sage.com.
Selection (SELECT) |
Select this checkbox to validate the properties to map on the screen fields. New fields added afterward in the screen definition will be displayed on the associated API operation but unselected. It will then be possible to set the corresponding property names from the node and mark the new screen fields as selected for the mapping. You can save the operation even if a mandatory property is missing in the mapping, but you won't be able to activate it. |
Node name (WINANODE) |
This column indicates the node the imported fields belong to. |
Binding (WINABIND) |
When you select the window, the fields to map are automatically loaded in the Binding column. |
Property (WINAPROPNAM) |
The property names are automatically loaded if you correctly configure the screens and reference tables. |
Type (WINATYP) |
This column indicates the type of imported properties. |
Dimension (WINDIME) |
Properties with dimensions are grouped on a single line on the operation. This field indicates the number of dimensions defined and managed in the window for the property. |
Denormalized collection (WINDENCOLGR) |
Enter the name of the denormalized collection to which this property belongs. |
Local menu number (WINNOLIB) |
This column displays the local menu related to the fields if there is one. |
Join type (WINKINDREF) |
Use this field to configure your collections. Enter the collection name in the Property column and select Collection on the same line for your collection's parent level. The parent level must be on the line just above the collection. If multiple collections are under the same parent node, then you have to define this parent line for each collection. |
Parent property (WINARENTPROP) |
Use this field to configure your collections. Enter the collection's name defined at the parent level in the collection's Property column. |
Description (WININTIT) |
This field displays the short description for your property. |
Length (WINLONG) |
This column indicates the display length of the field on the screen. |
Mandatory (WINOBLIG) |
Select this checkbox to make the field mandatory. |
Argument type (WINTYPFCT) |
This column indicates if the field is editable or not and if it is hidden. |
Screen (WINMSK) |
This column indicates the screen to which the field belongs to. |
Block (WINBLOC) |
This column indicates the screen block to which the field belongs to. |
Field (WINFLD) |
This column indicates the name of the field in the Windows function (GESAWI). |
Non-hidden field (WINNONHIDDEN) |
For each hidden field in the window to map to the node, use this column to link the corresponding fields displayed on the screen. |
Table (WINTABLE) |
This column indicates the table related to the field. |
Block type (WINTYPBLOC) |
This column defines the presentation of the fields inside their block.
|
Parent block (WINPARBLOCK) |
Use this field to configure the block number for fields displayed in card mode, such as address fields in the Customers function (GESBPC). It links the editable fields on the screen with their corresponding hidden fields defined in the grid. |
Class
This section allows you to create a GraphQL mutation based on an existing Sage X3 class.
Selection (CLASELECT) |
Select this checkbox to validate the properties to map on the class fields. New fields added afterward in the class definition will be displayed on the associated API operation but unselected. It will then be possible to set the corresponding property names from the node and mark the new screen fields as selected for the mapping. You can save the operation even if a mandatory property is missing from the mapping, but you won't be able to activate it. |
Node name (CLANODE) |
This column indicates the node the imported fields belong to. |
Binding (CLABIND) |
When you select the class, the fields to map are automatically loaded in the Binding column. |
Property (CLAPROPNAM) |
The property names are automatically loaded if you correctly configure the class and reference tables. |
Type (CLATYP) |
This column indicates the type of imported properties. |
Dimension (CLADIME) |
Properties with dimensions are grouped on a single line on the operation. This field indicates the number of dimensions defined and managed in the class for the property. |
Denormalized collection (CLADENCOLGR) |
Enter the name of the denormalized collection to which this property belongs. |
Local menu number (CLANOLIB) |
This column displays the local menu related to the fields if there is one. |
Join type (CLAKINDREF) |
Use this field to configure your collections. Enter the collection name in the Property column and select Collection on the same line for your collection's parent level. The parent level must be on the line just above the collection. If multiple collections are under the same parent node, then you have to define this parent line for each collection. |
Parent property (CLPARENTPROP) |
Use this field to configure your collections. Enter the collection's name defined at the parent level in the collection's Property column. |
Order (CLANUMFLD) |
This field displays the Order value assigned to this property in the Classes function (GESACLA). |
Description (CLAINTIT) |
This field displays the short description for your property. |
Length (CLALONG) |
This column indicates the display length of the field on the screen. |
Activity code (CLACODACT) |
An activity code is used to:
|
Mandatory (CLAOBLIG) |
Select this checkbox to make the field mandatory. |
Table (CLATABLE) |
This column indicates the table related to the field. |
Collection (CLAFLDGRP) |
Enter the name of the collection to which this property belongs. |
Linked table (CLALNKTAB) |
This column indicates the table related to the collection. |
Node script
This section allows you to create a GraphQL mutation based on a node script for custom operation types.
You can use this operation type to declare operations executed at the Sage X3 Services side on a node.
The operation executes a function developed in TypeScript that is similar to computed values.
Property (NSVAPROPNAM) |
The property names are automatically loaded if you correctly configure the node script and reference tables. |
Type (NSVATYPE) |
This column indicates the type of imported properties. |
Direction (NSVASENS) |
Select if your parameter is an input, an output, or both. |
Dimension (NSVDIME) |
Properties with dimensions are grouped on a single line on the operation. This field indicates the number of dimensions defined and managed in the node script for the property. |
Local menu number (NSVNOLIB) |
This column displays the local menu related to the fields if there is one. |
Parent property (NSVPARPROP) |
Use this field to configure your collections. Enter the collection's name defined at the parent level in the collection's Property column. |
Specific buttons
-
Copy
Select this button to copy the current record into another folder.
Copy API operation This field indicates the API operation that you are copying. From folder (DOSORG) Select the folder from which the record is copied. The possible syntaxes are described in the dedicated appendix.
All folders (TOUDOS) Select this checkbox to copy the record to all the folders defined in the dictionary (ADOSSIER table of the current solution).
To folder (DOSDES) Define the folder to which the record is copied. The possible syntaxes are described in the dedicated appendix.
-
Validation
Select this button to validate and generate the API operations.
Error messages
The only error messages are the generic ones.
Tables used
The following tables are implemented by the function:
Table | Table description |
APIOPE [APIOPE] | API operation |