Home > Connector Builder > Connector Builder Quickstart Guide > Authentication Ping

Refer to the documentation here for more information on _authping: here

Authentication Ping

The goal of the _authping metadata method is to have a check for valid authentication. To accomplish this, the method sends a simple authentication required request and returns a simple JSON response containing: whether the _authping is a success or failure, the response status code, and any error messages.

The Structure

As a metadata method, _authping will be a function with a request and control.assignIf steps.

_authping(a)

Http.raw : service call
  • This step makes a simple call requiring authentication to the connector API. The specifics of this step will vary from connector to connector, depending on the API format, as well as the type of authentication.
  • The left operand input should take in the status code from the service call and compare it to a successful status code, often but not always ‘200’.
  • The valueIfTrue (statusCode === 200), should be a JSON object (_authping(b)) where working is true, the status code is 200, and the message affirms a successful connection
  • The valueIfTrue (statusCode !== 200), should be a JSON object (_authping(b)) where ‘working’ is false, the status code is response status code, and the message is the response error message.

_authping(b)

_authping JSON

The following JSON snippet shows how _authping is implemented. The http.raw inputs will be slightly different depending on the connector, though the outputs and handler should be the same.

{
  "name": "_authping",
  "description": "authping",
  "kind": "metadata",
  "zebricks": [
    {
      "brick": "http.raw",
      "id": "servicecall",
      "inputs": {
        "url": {
          "_type": "string",
          "_array": false,
          "_value": "{{auth.instance_url}}/services/data/v38.0/"
        },
        "method": {
          "_type": "string",
          "_array": false,
          "_value": "GET"
        },
        "headers": {
          "_type": "object",
          "_array": false,
          "_value": {
            "Authorization": "Bearer {{auth.access_token}}"
          }
        },
        "query": {
          "_type": "object",
          "_array": false,
          "_value": {
            "token": "{{{auth.access_token}}}"
          }
        }
      },
      "outputs": {
        "statusCode": {
          "_type": "number",
          "_array": false
        },
        "headers": {
          "_type": "object",
          "_array": false
        },
        "body": {
          "_type": "string",
          "_array": false
        }
      },
      "handler": {
        "method": "authpingErrorHandler", //defined below
        "merge": "join",
        "path": ""
      }
    },
    {
      "brick": "control.assignIf",
      "id": "isWorking",
      "inputs": {
        "left-operand": {
          "_type": "number",
          "_array": false,
          "_value": "{{servicecall.statusCode}}"
        },
        "operator": {
          "_type": "string",
          "_array": false,
          "_value": "=="
        },
        "right-operand": {
          "_type": "number",
          "_array": false,
          "_value": 200 		//situation may need other 2** code
        },
        "valueIfTrue": {
          "_type": "object",
          "_array": false,
          "_value": {
            "working": true,
            "serviceResponse": {
              "statusCode": 200,
              "body": "This account is successfully connecting to Salesforce."
            }
          }
        },
        "valueIfFalse": {
          "_type": "object",
          "_array": false,
          "_value": {
            "working": false,
            "serviceResponse": {
              "statusCode": "{{servicecall.statusCode}}",
              "body": "{{servicecall.body}}"
            }
          }
        }
      },
      "outputs": {
        "output": {
          "_type": "object",
          "_array": false
        }
      }
    }
  ]
}

Authentication Error Handler ( authpingErrorHandler )

Refer to documentation here: here

The goal of the authpingErrorHandler is to correctly format any errors received from _authping. This formatted error will then be joined with the output of the method.

The structure:

The error handler contains only one step, an object.construct. The brick is a metadata method that outputs an object containing the error status code and error message.

authpingErrorHandler JSON:
{
  "name": "authpingErrorHandler",
  "description": "No description provided.",
  "kind": "metadata",
  "error": {
    "_type": "object",
    "_array": false,
    "_defaultValue": {}
  },
  "zebricks": [
    {
      "brick": "object.construct",
      "id": "errorobject",
      "inputs": {
        "statusCode": "{{error.statusCode}}",
        "body": "{{error.body}}"
      },
      "outputs": {
        "output": {
          "_type": "object",
          "_array": false
        }
      }
    }
  ]
}