Skip to main content

Node-RED tutorials

Node-RED tutorials for FairCom Edge

Node-RED works natively with the FairCom JSON DB API. It does not require a driver or custom-built nodes. Database capabilities to Node-RED are enabled by sending simple JSON commands to FairCom Edge.

Requirements:
Table 1. Quick links to FairCom's Node-RED Tutorials

Section

Description

Create session

Create a session with any of the FairCom JSON APIs. An authenticated session must be created before commands can be sent to a FairCom server.

Create a table & index

Create a table and an index in a FairCom Edge database.

Add & query records

Insert and query records in a FairCom Edge database.



Node-RED works natively with the FairCom JSON DB API. It does not require a driver or custom-built nodes. Database capabilities to Node-RED are enabled by sending simple JSON commands to FairCom Edge

tutorialsNode-REDFairCom EdgeJSONJSON DB APIconnectors

Create session

Use Node-RED to create a session with FairCom Edge

  1. Drag an https request node into a flow.

  2. Double-click the request node to edit it.

    NodeEditor.png

    1. Select POST from the Method dropdown menu.

    2. Enter https://localhost:8443/api in the URL textbox.

    3. Check the Enable secure (SSL/TLS) connection checkbox.

    4. Create a new TLS Configuration.

      • Uncheck the Verify server certificate.

      • Create certificates for your FairCom Edge server and configure them.

    5. Click Done to finish configuring the node and to close the node editor.

  3. Drag a json node into the flow.

  4. Connect the output of the https request node to the input of the json node.

    Note

    The FairCom Edge server returns info in JSON format. The json node will translate the response into a native JSON object.

  5. Drag an inject node into the flow.

  6. Connect the output of the inject flow to the input of the https request node.

  7. Double-click the inject node to edit it.

    1. Enter createSession in the Name textbox.

    2. Enter {} JSON in the msg.payload textbox.

    3. Click ... to open the JSON editor.

    4. Paste the following JSON in the JSON editor textbox:

      {
    "api": "admin",
    "action": "createSession",
    "params": {
        "username": "ADMIN",
        "password": "ADMIN"
    }
}

    5. Click Done to close the JSON editor.

    6. Click Done so that now the inject node will send a JSON object that requests a new session from the FairCom Edge server.

      Note

      The response will include an authtoken.

  8. Drag a function node into the flow.

    Note

    We will configure this node to save the authtoken for use in other nodes.

  9. Connect the output of the json node to the input of the function node.

  10. Double-click the function node to edit it.

    1. Paste the following code in the On Message code editor textbox:

      var authToken = msg.payload.result.authToken;
node.status("Got token:"+authToken);
flow.set("tutorial_authToken", authToken);
return msg;

    2. Enter Store Auth Token in the Name textbox.

    3. Click Done to finish configuring the node and to close the node editor.

      Note

      This node will parse the JSON response object and grab the returned authtoken then store it in a flow variable called "tutorial_authToken".

  11. Click Deploy to save the flow and make it ready for use.

  12. Click the corresponding createSession node button to send the request for a new session to the FairCom Edge server.

    Note

    The authtoken for this session will be stored in a flow variable. You can inspect the flow variable via the Context Data tab or add a debug node connected to the output of the json node to see it.

Tutorials to use Node-RED to create a session with FairCom Edge

Node-REDcreate sessiontutorialsFairCom Edgeconnectors

Create a table & index

Use Node-RED to create a table & index in FairCom Edge

Create table

  1. Drag an inject node into the flow.

  2. Double-click the inject node to edit it.

    1. Enter createTable in the Name textbox.

    2. Enter {} JSON in the msg.payload textbox.

    3. Click ... to open the JSON editor.

    4. Paste the following JSON in the JSON editor textbox:

      {
    "api": "db",
    "authToken": "replaceWithRealToken",
    "action": "createTable",
    "params": {
        "databaseName": "ctreeSQL",
        "tableName": "athlete",
        "fields": [
            {
                "name": "name",
                "type": "varchar",
                "length": 30
            },
            {
                "name": "ranking",
                "type": "smallint",
                "nullable": false
            },
            {
                "name": "birthDate",
                "type": "date"
            },
            {
                "name": "playerNumber",
                "type": "number",
                "length": 32,
                "scale": 6
            },
            {
                "name": "livedPast2000",
                "type": "bit"
            },
            {
                "name": "earnings",
                "type": "money",
                "length": 32,
                "scale": 4
            },
            {
                "name": "favoriteSaying",
                "type": "varchar",
                "length": 500
            }
        ]
    }
}

    5. Click Done to close the JSON editor.

    6. Click Done on the inject node.

  3. Drag a function node into the flow.

  4. Connect the output of the createTable inject node to the input of the function mode.

  5. Double-click the function node to edit it.

    1. Enter Add auth token in the Name textbox.

    2. Paste the following code in the On Message code editor textbox:

      var authToken = flow.get("tutorial_authToken")||"BadToken";
msg.payload.authToken = authToken;
return msg;

    3. Click Done to finish configuring the node and to close the node editor.

      Note

      This node will now replace the "authToken" property of the JSON object it receives with the real auth token stored in a flow variable.

  6. Copy the http request node and paste a duplicate of it into the flow.

  7. Connect the output of the Add auth token node to the input of the request node.

  8. Drag in a JSON node and connect the output from the request node to the input of the JSON node.

  9. Drag a debug node into the flow.

  10. Connect the output of the JSON node to the input of the debug node.

    Note

    This will send the results of the request to the debug tab where it is easily inspected.

  11. Click Deploy.

  12. Click the corresponding createTable node button to send the request.

  13. Observe the results in the debug tab in a JSON payload object and an empty table in the FairCom Edge server.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Create index

  1. Add an Inject node and connect the output of the inject node to the input of the Add auth token node from above.

  2. Enter createIndex in the Name textbox.

  3. Enter {} JSON in the msg.payload textbox.

  4. Click ... to open the JSON editor.

  5. Paste the following JSON in the JSON editor textbox:

    {
    "api": "db",
    "authToken": "replaceWithRealToken",
    "action": "createIndex",
    "params": {
        "databaseName": "ctreeSQL",
        "tableName": "athlete",
        "indexName": "ranking",
        "fields": [
            {
                "name": "ranking"
            }
        ],
        "waitToBeLoaded": true
    }
}

  6. Click Done to close the JSON editor.

  7. Click Done on the inject node.

  8. Click Deploy to configure the inject node to send a JSON object to the FairCom Edge server instructing it to add an index to the created table.

  9. Click the corresponding createIndex node button to send the request.

  10. Observe the results in the debug tab in a response object and a new index on ranking in the created table.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Tutorial to use Node-RED to create a table & index in FairCom Edge

create tablecreate indexindextableNode-REDFairCom Edge

Add & query records

Use Node-RED to add & query records in FairCom Edge

Add Records

Figure 1. Flow of nodes
Flow of nodes


  1. Drag an inject node into the flow.

  2. Connect the output of the inject node to the input of the Add auth token node that the createTable node feeds into.

  3. Double-click the inject node to edit it.

    1. Enter insertRocords in the Name textbox.

    2. Enter {} JSON in the msg.payload textbox.

    3. Click ... to open the JSON editor.

    4. Paste the following JSON into the JSON editor textbox:

      "api": "db",
  "authToken": "<valid authToken>",
  "action": "insertRecords",
  "params": {
    "databaseName": "ctreeSQL",
    "tableName": "athlete",
    "dataFormat": "objects",
    "sourceData": [
      {
        "name": "Michael Jordan",
        "ranking": 1,
        "birthDate": "19630217",
        "playerNumber": 23,
        "livedPast2000": true,
        "earnings": 1700000000,
        "favoriteSaying": "There is no 'i' in team but there is in win."
      },
      {
        "name": "Babe Ruth",
        "ranking": 2,
        "birthDate": "18950206",
        "playerNumber": 3,
        "livedPast2000": false,
        "earnings": 800000,
        "favoriteSaying": "Every strike brings me closer to the next home run."
      },
      {
        "name": "Muhammad Ali",
        "ranking": 3,
        "birthDate": "19420117",
        "playerNumber": 1,
        "livedPast2000": true,
        "earnings": 60000000,
        "favoriteSaying": "Float like a butterfly, sting like a bee."
      },
      {
        "name": "Pele",
        "ranking": 4,
        "birthDate": "19401023",
        "playerNumber": 10,
        "livedPast2000": true,
        "earnings": 115000000,
        "favoriteSaying": "Everything is practice."
      },
      {
        "name": "Wayne Gretzky",
        "ranking": 5,
        "birthDate": "19610126",
        "playerNumber": 99,
        "livedPast2000": true,
        "earnings": 1720000,
        "favoriteSaying": "You miss 100 percent of the shots you never take."
      },
      {
        "name": "Michael Schumacher",
        "ranking": 6,
        "birthDate": "19690103",
        "playerNumber": 1,
        "livedPast2000": true,
        "earnings": 990000000,
        "favoriteSaying": "Once something is a passion, the motivation is there."
      }
    ]
  }
}

    5. Click Done to close the JSON editor.

    6. Click Done to save the inject node.

  4. Click Deploy to configure the inject node to send a JSON object to the FairCom Edge server instructing it to insert 6 records into the table we created.

  5. Click the corresponding createIndex node button to send the request.

  6. Observe the results in the debug tab.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

Query data

Figure 2. Flow of nodes
Flow of nodes


  1. Drag an inject node into the flow.

  2. Connect the output of the inject node to the input of the Add auth token node that the createTable node feeds into.

  3. Double-click the inject node to edit it.

    1. Enter getRecordsStartingAtKey in the Name textbox.

    2. Enter {} JSON in the msg.payload textbox.

    3. Click ... to open the JSON editor.

    4. Paste the following JSON in the JSON editor textbox:

      {
    "api": "db",
    "authToken": "replaceWithRealToken",
    "action": "getRecordsStartingAtKey",
    "params": {
        "databaseName": "ctreeSQL",
        "tableName": "athlete",
        "indexFilter": {
            "indexName": "ranking",
            "operator": ">=",
            "indexFields": [
                {
                    "fieldName": "ranking",
                    "value": 3
                }
            ]
        },
        "reverseOrder": false
    }
}

    5. Click Done to close the JSON editor.

    6. Click Done to save the inject node.

  4. Click Deploy to configure the inject node to send a JSON object to the FairCom Edge server instructing it to return records where "ranking" is equal to or greater than three.

  5. Click the corresponding createIndex node button to send the request.

  6. Observe the results in the debug tab.

    Note

    "errorCode" with a value of 0 indicates success. "errorCode" with a non-zero value indicates a failure. See Errors and contact FairCom for more information about an error.

  7. Click the "msg.payload" object in the debug tab.

  8. Expand the "result" property.

  9. Expand the "data" property to view the list of four objects (numbered 0-3).

  10. Expand the 0 object to view the first row returned by the query.

    QueryData.png

Tutorial to use Node-RED to add & query records in FairCom Edge

add recordsquery recordsNode-REDFairCom Edgeconnectorstutorials

Enable HTTP on port 8080

This FairCom tutorial uses HTTP to communicate with the server on port 8080. Because HTTP is insecure, this port is typically disabled.

Do the following to enable the HTTP protocol on port 8080:

  1. Shut down the FairCom server.

  2. Edit the services.json file located in the <faircom>/config folder.

  3. Find the listener service named "http8080".

  4. Change "enabled":false to "enabled":true.

  5. Restart the FairCom server.

The modified listener configuration object in services.json should look something like this:

{
  "serviceName": "http8080",
  "description": "Port 8080 using insecure HTTP protocol...",
  "port": 8080,
  "protocol": "http",
  "enabled": true
}