Retool User Guide

The Retool User Guide enables users to manage and update product and biller mappings, as well as upload configuration files to the Electrum Console. In addition, this page outlines the necessary steps for managing and uploading configuration files and mappings using Retool.

Overview of Retool and Mappings

Retool simplifies the management and generation of a catalogue and its configuration files through a user-friendly interface. Electrum helps you by setting up your catalogue in Retool. This catalogue details all products, their associated codes, and mapping information—specifically, where a single product uses distinct client and service provider product codes. The Electrum catalogue requires specific output configuration files, which can be either JSON or CSV format. These are generated from Retool. These output files are then uploaded via configure on the Electrum Console. Once approved, the new catalogue is live.

Retool has three key functions:

• Product/Biller Management: This feature serves as the central place to maintain the list of products (e.g., airtime, digital vouchers) and billers that your system supports.

• Management of Mapping: This feature enables you to map your unique product/biller identifiers to the corresponding identifiers used by the service provider. This translation ensures Electrum processes transactions correctly.

• File Generation: Retool generates the required configuration files (JSON and CSV) for catalogue management.

For more details about the various features, refer to the different types of catalogues in the section below.

Different types of catalogues

You can use Retool to manage the following features:

• Airtime product catalogue

• Digital vouchers product catalogue

• Biller list

Add and update products or billers

This process explains how to create a new product mapping.

Add a new mapping row (in Retool)

1. Log in to your client-specific Retool account.

2. Locate the product catalogue table within the application interface.

3. To add a new mapping, click the 'add a new row plus (+)' button on the bottom right of the table:

4. A blank row appears at the bottom of the screen.

5. Next, populate the fields for the new product or the new biller using the information provided by the service provider's product catalogue or biller list.

Add the Product ID

1. Populate the columns, such as clientId, bitTestId, bitProdId, mmTestId, and mmProdId, with the product/biller ID your system uses. Accurately map this ID to the one the service provider uses to uniquely identify the same entity.

Fill the remaining columns

1. Populate the remaining columns to match the information specified by the customer. Ensure that the product amounts, descriptions, and validity match the provided information. These columns include validityDuration, validityUnit, longDesc, and shortDesc.

Using Retool to make Catalogue changes

This section explains how to edit or add products and billers within the Retool interface.

Setting up the environment

To determine which environment a mapping is active for, you must specify TRUE/FALSE in the corresponding environment fields. See image below:

The ‘true’ or ‘false’ field directly controls whether the product is included in the generated file for a specific environment. The customer specifies which environment activates the product.

In the screenshot below, the first two characters indicate the specific service provider (e.g., "BL" for Blue Label, "MM" for Mobile Mart). Everything after the underscore shows the environment represented by the column:

Electrum recommends this naming convention, which enables you to accurately specify the products supported by each partnered service provider, offering precise granularity at the per-provider and per-environment level. You are not required to follow this convention; you may use any naming rule (or convention) that you choose.

Generate and download files

This section explains the Retool functions required to create the final, validated JSON/CSV files.

1. After validating your new mappings, you must generate the files that the Config App requires to load the new mappings onto the switch.

2. Select the Environment (e.g., QA or Prod) in which you want to generate files.

3. Click the Generate Files button.

4. Depending on the service impacted, the Retool App may output several JSON and/or CSV files. The Biller list creates only a single output.

Upload files to the Configure tab

1. Navigate to the Config App (Configure).

2. On your Electrum Console (either Production or Pre-Production, depending on where you are making the changes), navigate to the Configure tab.

3. In the Configure section, select Mappings and navigate to the particular mapping that you need to update.

4. Upload the file (Example: Airtime Product Catalogue Map)

5. Open the map you wish to update (e.g., Airtime Product Catalogue Map)

6. Click on the Viewing drop-down and select Editing. This enables you to upload your file.

7. Click on Upload File and locate the generated file from Retool on your system. Then, select it to upload (e.g., AirtimeProductCatalogue.json).

8. Click Upload File. Note that uploading a file will completely replace the current map contents.

Review and submit for approval

1. On the Mappings screen in Edit mode, click Submit.

2. Enter a comment for the reviewer to see when they review the changes.

3. Click Okay. The changes will remain visible in Edit mode until the reviewer either applies or rejects the changes.

4. Click on the View drop-down and select unsubmitted changes to view all the changes made to the map.

5. Changes are colour-coded:

See example below:

6. Confirm that all changes are correct, then submit for approval. After clicking Submit, you can view the map changes in the Approvals tab under Configure.

Review and Approval Workflow

To ensure accuracy, the process includes a review and approval step. After submitting the necessary change within the Config App, notify the approver so that they can log into the Electrum Console and review the changes before applying or rejecting them.

Addressing a rejected change

A reviewer who rejects a change must provide an explanation of the reason for the rejection. If your changes have been rejected, return to Retool and resolve the specific issue the reviewer identified. This is crucial as it ensures that Retool is kept up-to-date with what is currently implemented by the Electrum Catalogue. Once you make the change, re-download the newly generated configuration files (both the JSON and CSV formats). Re-upload these new files to the Config App to ensure Retool maintains perfect synchronisation with the recently implemented catalogue.

Product removals

Product removal is the most complex operation and cannot be processed directly through the Retool UI at this time. To remove a product, you must log a request via the Electrum support channel support@electrum.co.za.