GraphQL is a query language for API’s. GLU supports integration into graphQL endpoints on outbound orchestrations. For more information on graphQL itself, you can find it here: https://graphql.org/
Connector Setup
GraphQL is available as an outbound connector. The connector can be created, allocated to the relevant GLU.Engines and the environment connector settings setup as required.
Integration Builder Usage
GraphQL requests can consist of 3 elements:
Query: The written graphQL query
Variables: A variable set that the graphQL query references
Headers: Any HTTP headers required on the endpoint (Authorization etc).
GraphQL Query Create the orchestration and select the GraphQL connector. This will change the request manager panel to include the Query. The GraphQL query element can be added to the query input as indicated below.
The GLU console does not validate the graphQL syntax. It can be helpful to use postman or the graphQL playground (https://www.graphqlbin.com/v2/new) to ensure you have a working graphQL call.
Headers Headers can be added to the outbound request through the request parameter and marshalling the parameter to the Header.
GraphQL Variables GraphQL variables are added into the outbound request through the use of the GLU parameters. Each variable required must be setup as a request parameter in the outbound orchestration.
If there is an existing json structure of the variables required, the parameters can be added through the use of a template.
For each parameter that is added through a template load, GLU parameters need to mapped.
The variables json structure is generated using the marshalling rules. You can define the structure by using the object / collection path. If you load the variables through a template, the full path will be automatically generated for you, simplifying the configuration considerably.
The beneficiaryType parameter will have the marshalling object / collection path set as: input.beneficiary.bankAccount
This will ensure that when the variables json is generated from the outbound request parameters, the beneficiaryType parameter will be generated in the json payload in the correct position.
Insert a Description for the Connector (optional).
Use the tick box to select the ‘GLU.ENGINES’ which the connector applies to.
Step 2 – Connector Environment Settings
Host Settings
Click Connector Environments Setting button, to start entering the Connector Environment Settings. The following screen will appear with the Host Setting tab to forefront.
Set the Host for the DB Connection.
If this is a mySQL connection, then the example command below would be used on the server which the GLU.Ware Application will run on to test connectivity to the mySQL database (replace the URL/Host with your own).
nc -zv glu.*****.us-east-1.rds.amazonaws.com 3306
Where glu.*****.us-east-1.rds.amazonaws.com is the Host URL and 3306 is the port (default to 3306 for mySQL) Set the ReadTimeOut and Connection TimeOut values, in most cases these are left as null.
Properties
Choose the Type of Vendor of the Database
Enter the Default Scheme * The GLU Variable ${GLU_schemaName}
Enter the UserName
Enter the Password
Choose whether Dynamic Datasource or not by selecting the tick box.
Marshalling with DB Connectors
Create EndPoint
1. In Orchestration Manager in the Integration create an EndPoint.
2. Set the Connector to be equal to the connector defined for the Database connection.
3. Ensure the Flow Code is Unique.
4. Select or unselect Async.
Flow Code
Used by Handlers to redirect the flow of a transaction (to specific Flow Code). Thus, the flow of any orchestration is not necessarily sequential in line with the sequence of that the transactions steps with Receiving Systems are defined in the Console.
Async
If selected, this connection will be performed asynchronously. By default, all connections are performed synchronously.
Note: The Flow between connectors can be altered with the use of Handlers – Flows marked as ‘Async’ will be invoked irrespective of any Handlers.
Request Manager Control Panel Settings
In the Request Manager Control Panel details of the connection to the database can be provided.
This will tell the orchestration how it is going to use the connection to the database.
i.e. CRUD queries, Database scrips and trigger stored procedures
Save Request As
It is possible to record the contents of the command which is sent to the Database in a variable in the GLU.Engine. The variable can then be used in a later orchestration.
As an example this could be used to audit the command which is sent to the database, but storing the variable (with the command in it) in a separate database or in queueing mechanism.
The variable should be typed in to Save Request As field.
When using the variable remember to mask the date into which ever date format is required.
Submit Time Parameter
It is possible to capture the timestamp to record the specific point in time when a Request / Response messages are sent or received from the connector.
The name of the variable where the timestamp value will be placed needs to be provided.
This variable can then be used in a subsequent connector for auditing purposes.
Query & Stored Procedure
GLU Supports either a Query or a call to a stored procedure.
The syntax of the call to the DB Connector is defined by the Database being called.
i.e. If Oracle Query is being called then the syntax will be based on SQL*Plus for the version of Oracle which the DB being connected to supports.
If an Oracle stored procedure is being called then the syntax of the call will be based on Oracle PL/SQL.
This syntax be specific the different databases types being used.
Query
In the query box define the query which you would like to execute against the Database.
Use the the variable names availble in the GLU.Engine directly in the query.
In this example above the field id has been passed as an Request Parameter in the api.
Logs Extract
As can be seen below the extract of the logs from a DB Connect shows how the results of multiple rows is presented in JSON.
h2tm 2022-03-05 | 07:44:54.867 | qtp1572820532-68 | DEBUG | g.g.w.i.h.HttpMappingUtils | [TRX_ID : 6cfe81e7-a7ad-4678-936e-ab51d80e691d] RESPONSE PAYLOAD Orchestration : [mysql Select][{"lastName":"Cluck Norris"},{"lastName":"Dixie Chick"},{"lastName":"Egghead"},{"lastName":"Foghorn Leghorn"}]
hh2tm 2022-03-05 | 07:44:54.867 | qtp1572820532-68 | DEBUG | g.g.w.i.h.HttpMappingUtils | [TRX_ID : 6cfe81e7-a7ad-4678-936e-ab51d80e691d] Orchestration : [mysql Select] Request Parameters with incoming Values
hh2tm 2022-03-05 | 07:44:54.867 | qtp1572820532-68 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : 6cfe81e7-a7ad-4678-936e-ab51d80e691d] PARAM :[surname] VALUE :[Cluck Norris] Array :[] Array KEY [0] PARAM :[lastName] VALUE :[Cluck Norris] [ Source : From : [ BODY ] Attribute : [lastName] XPath : [[]]] [ Target : Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
hh2tm 2022-03-05 | 07:44:54.868 | qtp1572820532-68 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : 6cfe81e7-a7ad-4678-936e-ab51d80e691d] PARAM :[surname] VALUE :[Dixie Chick] Array :[] Array KEY [1] PARAM :[lastName] VALUE :[Dixie Chick] [ Source : From : [ BODY ] Attribute : [lastName] XPath : [[]]] [ Target : Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
hh2tm 2022-03-05 | 07:44:54.868 | qtp1572820532-68 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : 6cfe81e7-a7ad-4678-936e-ab51d80e691d] PARAM :[surname] VALUE :[Egghead] Array :[] Array KEY [2] PARAM :[lastName] VALUE :[Egghead] [ Source : From : [ BODY ] Attribute : [lastName] XPath : [[]]] [ Target : Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
hh2tm 2022-03-05 | 07:44:54.868 | qtp1572820532-68 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : 6cfe81e7-a7ad-4678-936e-ab51d80e691d] PARAM :[surname] VALUE :[Foghorn Leghorn] Array :[] Array KEY [3] PARAM :[lastName] VALUE :[Foghorn Leghorn] [ Source : From : [ BODY ] Attribute : [lastName] XPath : [[]]] [ Target : Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
hh2tm 2022-03-05 | 07:44:54.868 | qtp1572820532-68 | DEBUG | g.g.w.i.h.HttpMappingUtils | 6cfe81e7-a7ad-4678-936e-ab51d80e691d BODY IS JSON ARRAY
Stored Procedure
To Call a DB stored procedure, select Stored Procedure and provide the syntax for the stored procedure name.
In the example the following store procedure is being called, in the schema gludb.
Note the schema gludb could be replaced by the GLU variable ${GLU_schemaName}.
Example of mySQL Stored Procedure:
DELIMITER ;;
CREATE DEFINER=`admin`@`%` PROCEDURE `testParam`(IN chickens VARCHAR(30), OUT lastName VARCHAR(30))
BEGIN
if chickens = 5780
then
SELECT surname as lastName
FROM pet
WHERE postalCode=chickens;
else
SELECT surname as lastName
FROM pet
WHERE ID=chickens
LIMIT 1;
end if;
END;;
DELIMITER ;
As with Query DB Connectors for Stored Procedure it is not necessary to define Request Parameters for the variables referred to in the query.
Logs Extract
Below defined an example for JSON of the structure the results payload.
In the Response Manager Control Panel details of the response to he connection to the database can be provided.
Save Response As
It is possible to record the contents of the payload which was received from the database in a variable in the GLU.Engine. The variable can then be used in a later orchestration.
As an example this could be used to audit the response payload received from the database, by storing the variable (with the command in it) in a separate database or in queueing mechanism.
The variable should be typed in to Save Response As field.
When using the variable remember to mask the date into which ever date format is required.
Response Time Parameter
[[ ]]
It is possible to capture the timestamp to record the specific point in time when a Response message is received from the connector.
The name of the variable where the timestamp value will be placed needs to be provided.
This variable can then be used in a subsequent connector for auditing purposes.
Response Parameters
Query or Stored Procedure
The properties define where the values from the connector are placed in the GLU.Engine are the same for Query and Store Procedure.
As multiple rows of values within arrays will be returned from the DB connector it will be necessary to define a Parameter Name and an Object / Collection Path as an array to store the values.
Query
Unmarshaling fields
Enter the name of the attribute which is returned from the Query in Attribute(s) Name.
In the Object / Collection Path, enter [] too define an array where multiple values will be stored from the query.
Stored Procedure
Unmarshaling fields
Enter the name of the attribute which is returned from the Query in Attribute(s) Name.
Always enter the value #result-set-1[] in the Object / Collection Path.
(#result-set-1[] is a reserved word in GLU.Ware as it will always contain the data which is returned from a stored procedure.)
the Attribute name must match the outbound parameters (OUT) defined in the Stored Procedure call definition.
Console Fields not used
The following fields in the Control Panel are not used for DB Connectors.
From & Store All Attributes as Key And value
Ignore unmarshal from a Query, Header, Body or file, this is not used for DB Connectors.
Ignore Store All Attributes as Key And value, this is not used for DB Connectors.
Delimiter
Currently this doesn’t do anything for a DB Connector and can be ignored.
The USSD simulator allows the user to experience the USSD menu using a device simulator.
Check Connectivity
Your application needs to be running in order to use the simulator. Complete the host and port to point to where the application is currently running. The endpoint where your application will be running needs to be accessible to the GLU console to ensure the simulator will work. Test the connectivity to ensure that the simulator has access to the running application.
Select Configuration of Simulator
In the configuration of the simulator, the user must select the API and transaction which will be simulated. This will auto-populate values from the menu builder setup during configuration. In the payload, it is important to ensure that the ${input} parameter (whatever parameter is set as the input parameter) is set as such.
Step 1: The input parameter selected on the configuration. Parameter name = input
Step 2: The payload used for the simulator is setup here. For ease of use, suggest defining the input parameter with the device input set – ${input}.
Step 3: The request payload for simulator will be pulled in when launching the simulator. If step 1 and 2 are completed above, there is no need to edit the payload in the simulator.
Simulating the user input and showing a result
The user can enter the shortcode into the device. The request payload represents what the gateway would send to the GLU.Engine. The appropriate menu will be displayed on the device. The user can submit the relevant values and submit (by using the Enter key) and can test and view their USSD string successfully using the USSD simulator.
The response payload represents the payload that will be returned to the USSD gateway.
When there are no Handlers in the Configuration section, the order of the Menu Sets is important as the first menu to be rendered to the User will be the first Menu Set on the GLU console.
Display menu rules using Menu Handlers
The ‘Show Menu Manager’ can also be used independently of the Menu Language function. In the example below, the menu in question will only be visible if the value of the ‘maxLoanable’ parameter is ‘Greater than or Equal’ to 10000.
Understanding Prompts
A prompt is created in order to prompt the user for something and to trigger a transaction in the associated Integration Engine.
In order to do this, the ‘Transaction Code‘ field must be populated with an Transaction Code configured in the Integration Builder. This essentially enables the Menu to hand-off the call to the Integration Engine to make the call to another system to verify the balance. The handoff happens after all prompt parameters are worked through.
A prompt must always be configured and followed by a result screen or another prompt.
Prompt Parameters
As per the screenshot below there are various options for prompt parameters.
Text, Float and Integer – Allows you to set a specific parameter value, it also validation options such as ‘Required’, length validations etc
Drop Down – Enables you to define in the ‘Default’ field a list of options (one under the next) for the User to select from
Hidden – Will retrieve values from message payload without actually prompting the User to enter anything
Confirmation – Allows you to return options to confirm a selection e.g. with a YES / NO. When using confirmation, the FIRST option is seen as the success, and the SECOND the failure. So ensure that the correct values are entered into the list box. See example below of the confirmation:
Prompt Logic
Once the prompt is triggered, the prompt will first work through all the parameters. At the end of the parameter list, the integration engine transaction will be triggered. If the integration engine returns a ‘Successful’ response template, the user will follow onto the next item in the configuration (either a result screen, handler or another prompt).
If the integration engine returns a ‘failure’ response template, the error message setup on the prompt configuration will be displayed.
Prompt Handler
Displaying Items in an Array
Dependency: In the related GLU Integration, create an orchestration in the Transaction, which retrieves the list of information that creates the array. EXAMPLE: Loan[]
In the USSD configuration:
1) Create a PROMPT to trigger the related integration in order to retrieve the array.
2) Add a second PROMPT and add a parameter – Type = Dropdown. This is to display the list to the customer. Add the following syntax in the “Default” section : ${arrayname.arrayattributename}
3) Add a second parameter – Type = hidden. In the default section – add ${arrayname}[${firstparametername}].(array_attribute_you_want_to_pass_into_transaction) This would take the attribute value that you require and pass it into the transaction.
Seeing an example for products: First param would be name = productSelect : ${products.productName} (display the list of ‘productName’ value in the array ‘products’)
In addition there are two ‘checkbox’ options. The first ‘Is Menu Language’ is used along with the second ‘Show Menu Manager’ to enable the configuration of different languages within a ‘Change Language’ menu. In this case, if the Language code = ‘EN’ (English) then the Menu Manager is directing the Menu Builder to render the Change Language menu option in Farsi (FA).
So on the Main menu, the entire menu will be in English with the exception of the ‘Change Language’ menu option which will present the Farsi prompt. If the English menu is being rendered and a user selects to change the Menu language to Farsi, that change can be asynchronously delivered to a back-end system but in addition, the GLU USSD Server will update the session language identifier to ‘FA’ (for Farsi) and the menu’s and messages delivered thereafter will be the configured Farsi menu’s and messages.
GLU.Ware support the creation and maintenance of one or more USSD Menus or ‘Menu Sets’ … simply click the ‘Add Menu Set’ button in the Menu Set Panel to add a new Menu Set. There is no limit to the number of Menu Sets one can run on the same USSD Server.
Once you add a new Menu Set, you must assign an identifier or ‘Menu Set Code’ and within the Menu Set Item Panel you’ll see three tools to start building out your Menu by adding Menu Tiers, Prompts and Handlers.
When you click on ‘Add Menu’, a Menu Item will be added with the tools in the Menu Control Panel now including options to add a Sub-Menu and additional prompt, handler and result logic.
This is where you define all the possible messages that the USSD Server can deliver back to the USSD Gateway. Each messages is identified within the Menu Builder by assigning it a message ‘Code’. Since the Menu Builder supports multi-language menu’s, this is where you can define different language options for your messages by toggling the Language option at the top of the configuration panel. Note: Contact the GLU Support Desk when you need to add support for any additional language/s as these additions are associated with your Customer Account Profile on GLU.Ware and are controlled by GLU Support. If you have multi-language, remember to also complete the language-specific Max Character Length on the configuration settings -> API Interface Panel.
One is also able to pass variables in these messages by referencing the variable attribute name in the usual ${variableName} format. So for example to return a message with an ‘amount’ value that is a variable, one could define a balance notification message as follows:
مانده شما ${balance} است (if in Farci) or …
You balance is ${balance}.
In order to do this, the ‘amount’ parameter must be configured in the Response payload associated with the payload that is returned to the Menu Builder from the Integration Engine. One can send multiple variables in messages in this way e.g.
You balance on Account Number ${accountNo} is ${balance}.
The screenshot below is from the Integration Builder showing these variables in the response payload.
When setting up the screen settings, it is important to note that the label given should indicate the input to be used else the user will just be displayed the label without the instruction as how to navigate there.
Header: This is where you can add a standard ‘header’ to all Menu, Prompt and or Result screens.
Main Menu: This is the code that will be available on every selected screen (Menu / Prompt / Result screen) to indicate which input can be used to return to the Main Menu.
Next Page: This code allows the user to scroll to the next page when pagination is applicable (where the menu options don’t fit all on one screen due to the USSD Char count limitation).
Previous Page: This code allows the user to scroll to previous when pagination is applicable (where the menu options don’t fit all on one screen due to the USSD Char count limitation).
Previous Screen: This allows the user to navigate back one screen.
These items can be ordered to your preference and will be rendered on the relevant menu’s as per the order on the console.
There are three different frameworks that can be configured using the GLU menu builder.
Type 1. Acknowledge is ON, and respond back to separate URL
This design is used when the USSD gateway requires an ACK message to be returned when the request is received. The ACK is returned in response to the incoming request, and the final USSD response is sent back to a different endpoint.
Type 2. Acknowledge OFF and respond back to different endpoint
It is possible to specify the response endpoint as a different endpoint to the incoming request. This different endpoint can be defined by selecting the correct connector and defining the relevant path or context name (response back url).
Type 3. Acknowledge OFF and respond back to the same endpoint as incoming request
This is a straight request and response model. The response generated in the menu builder will be sent back to the same endpoint as the incoming request.
Here you define the Inbound Connector that will receive the Request from the USSD Gateway. This Connector must be pre-configured in the Connectors Tool and once configured there should be selected from the Drop-down list.
Additionally, the following settings can be made (these would be provided to you by the USSD Gateway operator):
‘Timeout’ in seconds for the USSD Gateway can be set. (We have found this setting to be critical to the interaction and control of the session.)
‘Maximum Character Length’: that the USSD Gateway supports should be set (some may support up to 160 chars, others as few as 120 chars). Note – the ‘Maximum Character Length’ can be set per Language. Should your USSD menu support multi languages, it is important to ensure that you have your max characters set for each language. A warning will display should you not set it for the alternate language/s.
‘Format Line Break’:
Transaction Sets
One can configure one or more Transaction Sets. Each Transaction Set defined should be assigned a ‘Transaction Code’. Within the Configuration Panels you define the Request Payload, the Response Payload and the Handlers to direct the USSD Server on what do do with the received Request.
Request Definition
A Transaction Set is essentially defined by an inbound Request Payload, different Request Payload structures would typically require different Transaction Sets to be configured. This request payload would often be defined by the USSD Gateway Service.
Request parameters
Parameter Types: Input Data The parameter marked as input data will be used as the input to receive the customers action on the USSD String. e.g. 2, for the user selecting 2 etc Device The parameter marked as device is used to indicate the unique customer (the customers device). Other Can be used for any other data that is required to be pulled from the incoming request payload. Short Code Used to indicate which parameter on the incoming request payload is marked as the shortcode. SessionID If no specific sessionID parameter is added, USSD session is by default created using the parameter that is set as the ‘device’ on the request parameters. Otherwise the added parameter marked as ‘Session ID’ will be used. Customized Session ID This allows you to concatenate parameters to create a customised session ID.
Response Definition
The Response Template should be used to define the response message structure that the USSD Gateway expects to receive. Within that Response Template, the variable ${result} would be used to return the result or outcome from the USSD interaction to the USSD Gateway. So the output of the menu process, will be posted back through the ${result} field in the response payload.
Transaction Handlers
In order to add a handler to the transaction – the following syntax must be used:
Condition: ${paramName}==3 then include the menu set that should be routed to when that condition is met.
Shortcode sets
This is where you define the USSD Shortcode string that will invoke the session:
Long Codes and Jump Codes
In this example, to get to “Enquire about our Credit Service” you can do any of the following:
Dial *811# then select option 10 for Airtime
Dial *811*10# for “Airtime”
Dial *811*567# to jump straight to “Airtime” – This is especially useful when going several layers deep in a USSD menu.
Fill the form and we’ll contact you shortly
We uses cookies to make your experience on this website better. Learn more
