SuperNimbusKnowledge Base

BrainCloud

Integration

To integrate Retool with a BrainCloud app, we need to set up a webhook which executes a script using an action parameter in order to interact with the server.

After creating your app, under Design, go to Cloud Code -> Scripts.

Create and name a new script.

Paste the following cloud code into the script and save.

"use strict";
function main() {
  var response = {};
  bridge.logDebugJson("Script Inputs", data);
  response.jsonResponse = { "message": "Hello from BrainCloud!" };
  return response;
}
main();

To test your script, click ‘Debug’, ‘Quick Auth’ and execute. The results are displayed in the right panel.

Now, return to Cloud Code, and select Design -> Web Hooks. Create a new web hook, name it and select the script that we created previously. We will select ‘Enforce Secret in Header’, though this is optional depending on the use case. Click ‘Save’ to generate the web hook URL.

Copy the webhook URL and the endpoint secret to a text file as we will use these in Retool.

Returning to our Retool app, create a new RESTQuery resource. Paste the web hook URL into the action and the secret value into Headers with the key ‘x-bc-secret’. Save and run the app and our script message should appear in the response.

Now that we have successfully integrated our Retool and BrainCloud apps, we will implement a design pattern to handle the different types of requests for customer service applications.

We will add a switch case to our script which will use an ‘action’ parameter in the Retool query request to perform different operations.

Return to the BrainCloud script that we created earlier and replace it with the following and save the changes.

"use strict";
function main() {
  var action = data.parameters.action;
  var response = {};
  switch (action) {
      case "Action1":
        response.jsonResponse = action1();
        return response
      case "Action2":
        response.jsonResponse = action2();
        return response
      case "Action3":
        response.jsonResponse = action3();
        return response
      default:
        response.jsonResponse = { "message": "DEFAULT" }
        return response
  }
}


function action1(){
    return { "message": "This is action 1..." };
}


function action2(){
    return { "message": "This is action 2..." };
}


function action3(){
    return { "message": "This is action 3..." };
}


main();

In a Retool app, create three RESTQuery resources called ‘get_players’, ‘get_player_details’, ‘update_player’. Before continuing, test that the script works as expected by running the first query we created. As it has no parameters, it should return the default case.

Because the URL and secret are used by all the queries, it is better that they can be referenced in a single place. To do this, create a folder called ‘brain_cloud_config’ and add two JavaScript variables ‘webhook_url’ and ‘secret’ and paste in our values.

In the first query, replace the hardcoded values with references to the variables. Run the query to verify that it is still working.

{{webhook_url.value}}
{{secret.value}}

Add the same references in the three new queries and verify that they are working by returning the default case.

There are two ways to send data to the server in a request to BrainCloud, either as URL parameters or in the request body. To test this, change the default case to the following:

      default:
        response.jsonResponse = {
        jsonResponse:
            {
                jsonBody: data.jsonBody,
                parameters: data.parameters
            }
        };
        return response

Then, add a parameter to the action URL:

{{ webhook_url.value }}?testParam=testing

Change the body type to JSON and add the following key-value pair:

 

{ testBody: testing body }

When the query is run to test this, we get an error that we are unable to connect to the BrainCloud server. This is because the default request action type in Retool  is GET and the server will not accept this type if it has a body.

Changing the action type to POST and running, the default case is returned along with the parameters and JSON body that we specified in the request.

Based on this, we will make the ‘get_players’ and ‘get_player_details’ queries GET requests and the ‘update_player’ as a POST request. The action type that is sent to the server should be specified as a URL parameter along with any search parameters such as playerId, playerName as well as any pagination parameters.

For any actions that add or modify data on the server the data should be included in the body, for example updating a players access type would have the playerId specified as a URL parameter but the playerId, which is not updated, would be specified in the body. To test that the different action cases are being hit, change the action URL to the following

{{webhook_url.value}}?action=Action1

This will return a message for the first case. Other cases can be tested by changing the action parameter to ‘Action2’ and ‘Action3’.

Finally, we will update our switch statement to be for specific rather than generic action names.

"use strict";
function main() {
  var action = data.parameters.action;
  var response = {};
  switch (action) {
      case "GET_PLAYERS":
        response.jsonResponse = GetPlayers();
        return response
      case "GET_PLAYER_DETAILS":
        response.jsonResponse = GetPlayerDetails(data.parameters.playerId);
        return response
      case "UPDATE_PLAYER":
        response.jsonResponse = UpdatePlayer(data.parameters.playerId, data.jsonBody);
        return response
      default:
        response.jsonResponse = {
        jsonResponse: {
                jsonBody: data.jsonBody,
                parameters: data.parameters
            }
        };
        return response
  }
}


function GetPlayers(){
    return { "message": "Here is a list of players" };
}


function GetPlayerDetails(playerId){
    return { "message": "Here are details for player " + playerId };
}


function UpdatePlayer(playerId, updateParams){
    return  {
                "message": "Player " + playerId + " has been updated...",
                "updateData" : updateParams
            };
}
main();

Change the action URLs in the GET queries to the following and test that the new messages are being returned.

{{ webhook_url.value }}?action=GET_PLAYERS
{{ webhook_url.value }}?action=GET_PLAYER_DETAILS&playerId=TEST_PLAYER_ID

For the update query, change the URL to the following and add a key-value pair to the body.

{{ webhook_url.value }}?action=UPDATE_PLAYER&playerId=TEST_PLAYER_ID

The specifics of how to fetch and manipulate data in BrainCloud are beyond the scope of this tutorial, but to end it, I will point you to the BrainCloud server logs for debugging.

Returning to the BrainCloud app, on the left panel under Global->Logs->Server Logs. Here we can see all the requests we have made from Retool along with the parameters and JSON data, as well as the responses.

Summary

We now have an application that can securely fetch data from the BrainCould servers

Jump to section