Sub-programs

Less than 5 minutes to read

Create your sub-program (GESASU)

Create your sub-programs with the same parameters as before in X3.

Note: The script must respect the following format:

##########################################################################
# APIOPE-TEMPLATE VERSION = 2.0     -----don't change this line
# APIOPE-TEMPLATE DATE = 2023/06/20 -----don't change this line
# --------------------------------------------------------------
#######################################################################
#   script for API operation xtrem usecase
# label ACTION is mandatory
# ACTION START and END are mandatory
# action COMPUTE_TEMPLATE is an example
#######################################################################
$ACTION
 
Case ACTION
  When "START"             : Gosub START_TEMPLATE
  When "COMPUTE_TEMPLATE"  : Gosub COMPUTE_TEMPLATE
  When "END"               : Gosub END_TEMPLATE
Endcase
Return
 
$START_TEMPLATE
# Caution the log is already opened, you don't have to call OUVRE_TRACE
#
 
#This Action is mandatory
#here we can define some local variables, open some files.....
#perhaps add some entry points in the future
Return
 
$END_TEMPLATE
#This Action is mandatory
#to kill some global variables if needed or other things
Return
 
$COMPUTE_TEMPLATE
# an example
#Call API_TEST(RVAR,RCODE)
Return
 
###################################################################################################
# an example of subprog
###################################################################################################
Subprog API_TEST(RVAR,RCODE)
Value Char RVAR
Variable Integer  RCODE
 
End

Please note:

The header comments are mandatory.
START and END actions are mandatory.
Between the START and END actions, you can replace the COMPUTE_TEMPLATE action with your actions and code.

Create your operation (GESAPIOPE)

Once your sub-program is created, you can map it to your node in the API operation function (GESAPIOPE).

For sub-programs, set the Mutation type field to Custom.
Set the Operation method field to Script.
Fill in the X3 operation identifier. The operation identifier must be unique.
Select the Main node name. This is the node where the operation will be generated.

Multiple custom operations can be linked to the same node.

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 naming convention (camelCase).

Details

Select the module of your sub-program operation.
Select an activity code if needed.
Mark the operation as active or not.
Enter a Node binding (request) identifier.

This identifier is used as a reference for the node bindings records generated for the operation.
It is initialized by default by the x3 operation identifier.

Enter a Node name (request).

Is it initialized by default by the GraphQL operation name field, but it can be modified.
The node name must respect the friendly names naming convention (PascalCase).
After saving the operation, a transient node is automatically generated in the node bindings tables based on the node identifier and node name.

This node stores the mapping between the sub-program parameters and the transient properties generated in the main node to build the mutation payload and execute the mutation.
The transient properties will be added to the main node when the package is generated in VSCode.

Enter the Package name where the operation will be generated.

For partners, the package selection is restricted to their specific packages.

For a script mutation, the node binding response is the same as the node binding request.
For a custom operation based on a sub-program, the following fields are editable:

Select your script in the Script field.
Select the Sub-program field.
Select the Action to be executed in the script for this operation.

The following authorizations are possible to select:

Functional authorization
Option

Variables and sub-program parameters

Bindings:

Once the sub-program is selected, the variables are automatically loaded in the variables grid in the Binding column.

In the grid, define the Property names to be mapped to the sub-program variables in the node definition.

After saving the operation, a transient node and its properties are automatically created in the node bindings table based on the node identifier, node name, and property names.

The transient node is visible in the Node bindings function (GESANODEB).
The transient nodes and properties are visible in the Bindings dictionary function (GESAAPINOD) under the Script left list.

In VSCode, the properties will be generated on the node as transient, meaning not linked to the database fields as for regular properties that are bound to table fields (GESATB).

Parent property

For object type properties, child properties can be linked.

Example of a mutation

The following example showcases a mutation for a Currency creation:

mutation {
  x3MasterData{
    currency{
      currencyRateShowcase(parameters:{rateType:1,sourceCurrency:"EUR",destinationCurrency:"ZAR",rateDate:"20231009",rate:"15.2222",divisor:"0.0656935265598928",daction:"C"}){
        rateType
        sourceCurrency
        destinationCurrency
        rateDate
        rate
        divisor
        daction
      }
    }
  }  
}