Node bindings

Use this function to customize API nodes and properties. This function complements the Binding dictionary function (GESAPINOD) that specifies how nodes are linked to Sage X3 tables, windows, subprograms, import templates, and other components.

When you create a data model to reference a node, a corresponding node binding record is automatically generated in the Node bindings function (GESANODEB). Any changes to Sage X3 metadata trigger the generation or updating of data in the binding dictionary, after the revalidation of the nodes.

Prerequisites

Follow these steps before setting up node bindings:

  1. Define the relevant API packages in the Packages function (GESAPACK) to structure the nodes dictionary and the GraphQL schema.

  2. Define the nodes in the Data models function (GESAWM) or in the Operations function (GESAPIOPE).

  3. Define the property names in the Tables function (GESATAB).

Screen management

The screen is defined in 5 tabs:

  • The header,

  • The Composite references tab,

  • The Computed properties tab,

  • The Transient properties tab,

  • The Masked properties tab.

Header

This section outlines the key information for node bindings.

General information

Node binding (AREFBIND)

This field displays the node binding code. This code must be unique.

Node bindings are automatically generated:

  • For nodes when API data models are created.

  • For mutations when API operations are created.

  • For read-only nodes when API views are created.
Description (ZADES)
This field displays the short description for your node binding.
Activity code (CODACT)

An activity code is used to:

  • Make an element optional in the dictionary if the value associated with the activity code is null
  • Identify the specific/custom elements if they are marked with a code starting with X, Y, or Z
Module (MODULE)

Select the related Sage X3 module.

Definition

Type (ABDTYP)

The node binding type can be:

  • A data model

  • A script

  • An import

  • A window

  • A view
X3 entity (AX3KEY1)
This field displays the Sage X3 entity code related to the type.
Main table (MAINTABLE)
This field indicates the reference table for nodes created from API data models.
Node name (ANODE)
This field displays the node name as defined in the related API data model or API operation.
Published (APUBFLG)

Select this checkbox to publish your node.

If unselected, the node is hidden in the GraphQL schema.

In the GraphQL context, non-published nodes or properties refer to data elements or entities that exist within the database but are not exposed or accessible to users or applications querying the GraphQL schema.

Non-published nodes refer to nodes that are not intended to be directly accessed or queried by users or applications. These nodes can be used internally, such as in composite nodes or other node operations, but they are not part of the data exposed to users.

If you unpublish a node that is referenced in another node, the reference property in the second node will also be marked as unpublished.
Package name (APACKAGE)
Select the API package to which the node belongs.
Table filter (TABFLT)

Use this field to add a filter to a node. This field contains a GraphQL filter expression that uses operators such as _gt, _in, or _nin.

For example, { category: { _nin: ['openOrder'] } }.

Security

In this section, you can configure functional habilitations for the node.

Function (FNC)
You can link the node to a functional access right defined in the Functional authorization function (GESAFP) for the user's functional profile. This function allows you to grant access rights by site.
Site (ACTRLFCY)
Select the site-type property of the site to be used on the node to control site habilitations.
Access code (ACTRLACS)
This access code enables the restriction of access to the current record for some users.

Composite references

When a main node is linked to a target node with a 1:1 or 0:1 relationship, you can add the properties of the target node into the main node, defining this as a composite node, to group the properties on a single node.

Reference composite (APROPLNK)

Select the property of a linked node with a 1:1 relationship. There are 2 options:

  • Standard reference (foreign key): A node property from a linked table in the Tables function (GESATB).

  • Standalone reference: A reference added to a node in the Data models function (GESAWM) using a 0,1 or 1,1 relationship.

In both cases, the linked table must be associated with a node data model, and its primary key fields must have defined property names.
Composite path (APROPPATH)

Select the property of the linked table that you want to add to the main node. It can be:

  • A property of the linked table itself.

  • A path, which is the sequence of reference or standalone reference properties from the target node, ending with the requested property, denormalized collection, standalone reference, or collection of the target node. For example, ‘site.legalCompany.legislation’.

This field is mandatory to define the composite property, which originates from the composite reference node and will be added to the main node.
Property (APROPNAM)

This field is automatically populated with the same name as the linked property selected in the Composite path column. You can edit it if needed.

Property names must be unique within a node.

This field is mandatory to define the composite property.
Package name (APACKAGELNK)

Enter a package name for the composite property to be declared as a node extension. It then resides in a different package than the main node.

Leave this field empty for the composite property to be declared in the same package as the main node.
Mutable reference or collection (AISMUTABLE)

This option is only available for composite properties that are references or collections.

Select this checkbox for the reference node linked to the composite property to be included in the mutation payload.

If unselected, the reference node linked to the composite property is not mutable. It will not be sent in the payload and, as a result, cannot be modified.
Activity code (CODACT)

An activity code is used to:

  • Make an element optional in the dictionary.

  • Identify the specific/custom elements that are marked with a code starting with X, Y, or Z to protect them.

 

Computed properties

A computed property is a non-stored or non-persistent property that is primarily associated with a node. It is not linked to a field in the Tables function (GESATB). Instead, its value is calculated or derived based on other properties or calculations.

Computed properties allow you to define a property whose value is dynamically determined at runtime. They are particularly useful when you need to expose calculations or derived values as regular properties of a node, enabling you to encapsulate them within the GraphQL capabilities and logic.

Event (APIEVE)

Select one of the following options:

  • computeValue properties: You can use these for more complex calculations. They allow you to include custom TypeScript code encapsulated within a function. The code (function) will be added in the Sage X3 Services development environment.

    Developers can create their own subdirectories within the lib directory of the relevant application. They must then reference these directories in this grid. Additionally, they must update the index.ts script in the lib directory to include the new functions.

  • getValue properties: You can use these for basic operations. You can define a piece of code that can be easily translated into an SQL statement. For example, a simple calculation like orderedQuantity*salesPrice can be directly transformed into an SQL expression without requiring additional logic.

    You can use the following tokens in getValue expressions. An error occurs if any unsupported tokens are detected:

    • Basic operators: +, -, /, *, ||, &&, <, <=, >, >=, (, and )

    • Non-typed comparison (types are converted before comparison and the resulting values are compared): ==, !=

    • Typed comparison (both type and value are compared): ===, !==

    • Null value alternative: ??. For example, myNumber??0 means that if myNumber is null or undefined, then use 0.

    • The || and && operators are allowed for defining boolean expressions. For example:

      • conditionA||conditionB means conditionA or conditionB

      • conditionA&&conditionB means conditionA and conditionB
Property (APRTNAM)
Enter the name of the property as it will appear in the node.
Denormalized collection (DENCOLGR)

Indicate the name of the denormalized collection linked to this property.
Type (ATYPE)
Select one of the types from the list.
Menu code (MENCOD)
This field is mandatory when the type is Enum (local menu). It links the property to the specified local menu.
Target (ATARGET)
This field is mandatory when the type is Node. Indicate the name of the node linked to this property to make the property a reference or a link to a collection of that node.
Join type (KINDREF)
This field is mandatory when the type is Node. If Reference is selected, it indicates a one-to-one relationship, while Collection defines a one-to-many relationship.
Package name (APIPKG)
Enter the name of the package in which the property will be generated.
Depends on (APIDPD)
List the properties the computeValue property depends on, separated by commas.
Expression (APIEXX)
Enter the expression to use to compute the getValue property.
Function package (FNCPACK)
Enter the package in which the function is delivered for a computeValue property, expressed as @[namespace]/[package].
Function path (APIFNCPATH)
Enter the path where the function is located, under the lib directory inside the package, for a computeValue property, expressed as mydirectory.functionName.
Activity code (CODACT)

An activity code is used to:

  • Make an element optional in the dictionary.

  • Identify the specific/custom elements that are marked with a code starting with X, Y, or Z to protect them.

Transient properties

Properties generated as transient on a node are not linked to database fields, unlike regular properties that are bound to table fields in the Tables function (GESATB).

In this section, you can declare the transient properties that will be sent to an API operation for your node.

You can use transient properties to map the technical fields defined in Sage X3 to the API operation (mutation), such as entry transactions or document printing destinations.

Property (ATRPROPNAM)
Enter the transient property name.
Type (ATRTYPE)
Select the type of the transient property.
Package name (ATRPACKAGE)
Select the package to which the transient property belongs.
Activity code (CODACT)

An activity code is used to:

  • Make an element optional in the dictionary.

  • Identify the specific/custom elements that are marked with a code starting with X, Y, or Z to protect them.

Masked properties

In the GraphQL context, non-published properties refer to data elements or entities that exist within the database but are not exposed or accessible to users or applications querying the GraphQL schema.

Non-published properties refer to properties associated with nodes that are not meant to be exposed to end-users or applications interacting with Sage X3. These properties can be used internally within nodes for processing or other operations, but they are not included in the visible GraphQL schema, ensuring they remain hidden from external queries.

Non-generated properties on nodes refer to properties that are explicitly defined as non-generated, rather than those automatically created based on the table definition. Distinguishing between these property types is important for effective data management and for querying nodes.

Property (APROPEXCL)

Select the properties to be hidden on the node.

If you unpublish a key property:

  • The node remains available for queries, even though the key property is unpublished.

  • If the node is used as a reference in another node, it still is accessible as a reference.

Setting up non-published properties on a node is not available for collections, standalone references, computed properties, or transient properties.
Denormalized collection (DENCOLGR)

Indicate the name of the denormalized collection linked to the property.
Excluded (AEXCLUDED)

Select this checkbox for the hidden property to be excluded from the associated node.

If you exclude a key property, the entire node will not be generated by the code generator in VSCode.

Specific buttons

  • Select this button to validate and generate the node bindings in the selected folder, with or without details.

  • Select this button to go to the Binding dictionary function (GESAPINOD) to see the node bindings.

General parameters

Configure the LAUNCHAPIG - Node generation launch after patch integration parameter (SUP chapter, PRF group) to automatically trigger node validation when a folder is validated.

  • If the value is set to No or left empty (default value), the node validation is not performed when the folder is validated.

  • If the value is set to Yes, the node validation is performed automatically when the folder is validated.

When using Sage X3 Services APIs, it is recommended to set the parameter value to Yes. Otherwise, you can execute the node validation manually through the Node bindings function (GESANODEB).

Error messages

The only error messages are the generic ones.

Tables used

The following tables are implemented by the function:

Table Table description
ANODEBDG [ANODEB] Node binding
ANODCPS [ANODCP] Composite references
ANODCPT [ANODCT] Computed properties
ANODTRANS [ANODTR] Transient properties
ANODPEXCL [ANODEX] Masked properties