GraphQL Connectors

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.

Graphqlconnector.gif

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.

Graphqlrequestmanager.gif

Headers Headers can be added to the outbound request through the request parameter and marshalling the parameter to the Header.

Header.gif

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.

Graphqlrequestparams.gif

If there is an existing json structure of the variables required, the parameters can be added through the use of a template.

Graphqlvariabletemplate.gif

For each parameter that is added through a template load, GLU parameters need to mapped.

Graphqlmapparams.gif

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.

Graphqlmarshalling.gif

EXAMPLE: If you variables json looks like this: {

 "input": {
   "beneficiary": {
     "bankAccount": {
       "name": "Sample Account",
       "bankId": "absa",
       "accountNumber": "1234567890",
       "accountType": "current",
       "beneficiaryType": "private",
       "reference": "TestBeneficiary"
     }
   }

}

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.

DB Connectors

Setup DB Connector

Step 1 – Connector Basic Information

  1. Insert a ‘Connector Name’
  2. Select OUTBOUND for the ‘Connection Direction’.
  3. Select the protocol ‘DATABASE’ for the Protocol.
  4. Insert a Description for the Connector (optional).
  5. Use the tick box to select the ‘GLU.ENGINES’ which the connector applies to.
Dbconnector V1.PNG

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.

Dbconnectorstring V1.PNG

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

Connectorproperties V1.PNG

Choose the Type of Vendor of the Database

Vendorofthedatabase V1.PNG
  1. Enter the Default Scheme * The GLU Variable ${GLU_schemaName}
  2. Enter the UserName
  3. Enter the Password
  4. 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.

Flowcode 01.png

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

SaveRequestAs 03.png

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.

SaveRequestAsFormat 01.png

Submit Time Parameter

SaveRequestAs 02.png

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

SubmitTimeParamter 01.png

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

Seleect 01.png


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.

[{ “surname”: “Cluck Norris” }, { “surname”: “Dixie Chick” }, { “surname”: “Egghead” }, { “surname”: “Foghorn Leghorn” }]

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.

Spsel 01.png


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.

The array with data is “#result-set-1”.
{

 "#result-set-1": [
   {
     "lastName": "Cluck Norris"
   },
   {
     "lastName": "Dixie Chick"
   },
   {
     "lastName": "Egghead"
   },
   {
     "lastName": "Foghorn Leghorn"
   }
 ],
 "#update-count-1": 0,
 "surname": null
}

It is possible with the logs to see the data results.

2022-03-06 | 11:08:06.637 | qtp589311025-63 |  INFO | g.g.w.c.SenderController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] Orchestration [mySQLSP] Request Call Stored Procedure : gludb.testParam(VARCHAR 5780,OUT VARCHAR surname)
udc0m  2022-03-06 | 11:08:06.637 | qtp589311025-63 | DEBUG | g.g.w.c.SenderController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] Headers :{CamelHttpMethod=post, GLU_TRX_ID=a4cdc5a6-2f80-4619-931a-f565f674bccf, id=5780, ids=5780, routeId=1-4-1, TRACE_ID=a4cdc5a6-2f80-4619-931a-f565f674bccf}
udc0m  2022-03-06 | 11:08:06.637 | qtp589311025-63 | DEBUG | g.g.w.c.SenderController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] STORED PROCEDURE : gludb.testParam(VARCHAR ${headers.id},OUT VARCHAR surname)
udc0m  2022-03-06 | 11:08:06.638 | qtp589311025-63 |  INFO | g.g.w.c.SenderController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] Engine sent Request, Orchestration [mySQLSP]
udc0m  2022-03-06 | 11:08:06.642 | qtp589311025-63 | DEBUG | o.a.c.s.SpringCamelContext | Using ComponentResolver: org.apache.camel.impl.DefaultComponentResolver@59712875 to resolve component with name: sql-stored
udc0m  2022-03-06 | 11:08:06.643 | qtp589311025-63 | DEBUG | o.a.c.util.ResolverHelper | Lookup Component with name sql-stored in registry. Found: null
udc0m  2022-03-06 | 11:08:06.643 | qtp589311025-63 | DEBUG | o.a.c.util.ResolverHelper | Lookup Component with name sql-stored-component in registry. Found: null
udc0m  2022-03-06 | 11:08:06.647 | qtp589311025-63 | DEBUG | o.a.c.i.DefaultComponentResolver | Found component: sql-stored via type: org.apache.camel.component.sql.stored.SqlStoredComponent via: META-INF/services/org/apache/camel/component/sql-stored
udc0m  2022-03-06 | 11:08:06.656 | qtp589311025-63 | DEBUG | o.a.c.m.DefaultManagementAgent | Registered MBean with ObjectName: org.apache.camel:context=camel-1,type=components,name="sql-stored"
udc0m  2022-03-06 | 11:08:06.656 | qtp589311025-63 | DEBUG | o.a.c.i.DefaultComponent | Resolving property placeholders on component: org.apache.camel.component.sql.stored.SqlStoredComponent@578e87dd
udc0m  2022-03-06 | 11:08:06.662 | qtp589311025-63 | DEBUG | o.a.c.i.DefaultComponent | Creating endpoint uri=[sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true], path=[excuteStoredProcedure()]
udc0m  2022-03-06 | 11:08:06.665 | qtp589311025-63 | DEBUG | o.a.c.s.SpringCamelContext | sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true converted to endpoint: sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true by component: org.apache.camel.component.sql.stored.SqlStoredComponent@578e87dd
udc0m  2022-03-06 | 11:08:06.671 | qtp589311025-63 | DEBUG | o.a.c.c.s.s.SqlStoredProducer | Starting producer: Producer[sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true]
udc0m  2022-03-06 | 11:08:06.672 | qtp589311025-63 | DEBUG | o.a.c.impl.ProducerCache | Adding to producer cache with key: sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true for producer: Producer[sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true]
udc0m  2022-03-06 | 11:08:06.672 | qtp589311025-63 | DEBUG | o.a.c.p.SendDynamicProcessor | >>>> sql-stored://excuteStoredProcedure()?dataSource=dataSource87740&useMessageBodyForTemplate=true Exchange[ID-data-1646564809750-0-5]
udc0m  2022-03-06 | 11:08:06.689 | qtp589311025-63 | DEBUG | o.a.c.c.s.s.TemplateStoredProcedure | Compiling stored procedure: gludb.testParam
udc0m  2022-03-06 | 11:08:06.690 | qtp589311025-63 | DEBUG | o.a.c.c.s.s.TemplateStoredProcedure | Compiled stored procedure. Call string is [{call gludb.testParam(?, ?)}]
udc0m  2022-03-06 | 11:08:06.690 | qtp589311025-63 | DEBUG | o.a.c.c.s.s.TemplateStoredProcedure | RdbmsOperation with SQL [gludb.testParam] compiled
udc0m  2022-03-06 | 11:08:06.692 | qtp589311025-63 | DEBUG | o.a.c.c.s.s.TemplateStoredProcedure | Invoking stored procedure: gludb.testParam
udc0m  2022-03-06 | 11:08:06.774 | qtp589311025-63 |  INFO | g.g.w.c.ProcessController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] Engine Received Response From Orchestration [mySQLSP]
udc0m  2022-03-06 | 11:08:06.774 | qtp589311025-63 |  INFO | g.g.w.c.ProcessController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] FIRE GLU HANDLE GLuHandleHttpOperationFailedException
udc0m  2022-03-06 | 11:08:06.775 | qtp589311025-63 |  INFO | g.g.w.c.ProcessController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] STATUS CODE: 200
udc0m  2022-03-06 | 11:08:06.775 | qtp589311025-63 |  INFO | g.g.w.c.ProcessController | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] FORCE TO STOP THE PROCESS: false
udc0m  2022-03-06 | 11:08:06.843 | qtp589311025-63 | DEBUG | g.g.w.i.h.HttpMappingUtils | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] RESPONSE PAYLOAD Orchestration : [mysql SP]{"#result-set-1":[{"lastName":"Cluck Norris"},{"lastName":"Dixie Chick"},{"lastName":"Egghead"},{"lastName":"Foghorn Leghorn"}],"#update-count-1":0,"surname":null}
udc0m  2022-03-06 | 11:08:06.843 | qtp589311025-63 | DEBUG | g.g.w.i.h.HttpMappingUtils | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] Orchestration : [mysql SP] Request Parameters with incoming Values
udc0m  2022-03-06 | 11:08:06.850 | qtp589311025-63 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] PARAM :[surname] VALUE :[Cluck Norris] Array :[#result-set-1] Array KEY [0] PARAM :[lastName] VALUE :[Cluck Norris] [ Source :  From : [ BODY ] Attribute : [lastName] XPath : [#result-set-1[]]] [ Target :  Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
udc0m  2022-03-06 | 11:08:06.851 | qtp589311025-63 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] PARAM :[surname] VALUE :[Dixie Chick] Array :[#result-set-1] Array KEY [1] PARAM :[lastName] VALUE :[Dixie Chick] [ Source :  From : [ BODY ] Attribute : [lastName] XPath : [#result-set-1[]]] [ Target :  Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
udc0m  2022-03-06 | 11:08:06.851 | qtp589311025-63 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] PARAM :[surname] VALUE :[Egghead] Array :[#result-set-1] Array KEY [2] PARAM :[lastName] VALUE :[Egghead] [ Source :  From : [ BODY ] Attribute : [lastName] XPath : [#result-set-1[]]] [ Target :  Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE
udc0m  2022-03-06 | 11:08:06.851 | qtp589311025-63 | DEBUG | g.g.w.p.utils.JSONUtil | [TRX_ID : a4cdc5a6-2f80-4619-931a-f565f674bccf] PARAM :[surname] VALUE :[Foghorn Leghorn] Array :[#result-set-1] Array KEY [3] PARAM :[lastName] VALUE :[Foghorn Leghorn] [ Source :  From : [ BODY ] Attribute : [lastName] XPath : [#result-set-1[]]] [ Target :  Attribute : [surname] XPath : [chickens[]]] [UNMARSHALLING] HAS NO DEFAULT VALUE

UnMarshalling

Response Manager Control Panel Settings

In the Response Manager Control Panel details of the response to he connection to the database can be provided.

Save Response As

SaveResponseA 01.png

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.

SaveResponseAsFormat 01.png

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

Responseparameters 01.png
Responseparameters 02.png

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
Qresponseparameters 01.png

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.

SPpay 01.png

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.

Ignore1 01.png

Delimiter

Currently this doesn’t do anything for a DB Connector and can be ignored.

USSD Simulator

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.

Menu Configuration Options

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’)

Multi-Language Menu

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.

Add Menu Sets

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.

Messages and Multi Language Support

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.

Screen Settings

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.

3 USSD Models

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.

USSD API Interfaces

Defining the API

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

    I agree with

    cookies
    We uses cookies to make your experience on this website better. Learn more
    Accept cookies