Custom Connectors

Reference

These methods are provided by Domo in the Connector Dev Studio to make it easier for you to build your custom connector.

Auth

These methods are specifically used in the authentication code block.

Method Parameters Return Description
auth.authenticationSuccess() none none Set during the authentication process to indicate that credentials have been successfully validated.
auth.authenticationFailed(errorMessage) errorMessage none Set during the authentication process to indicate that credentials could not be validated.

 

Datagrid

Domo provides methods and constants to help you insert your data into Domo. These methods and constants are specifically used in the data processing code block.

These constants are used to define the data type of a column in a datagrid.

Name Description
datagrid.DATA_TYPE_STRING Set a column dataType to receive a String.
datagrid.DATA_TYPE_DOUBLE Set a column dataType to receive a number.
datagrid.DATA_TYPE_DATETIME Set a column dataType to receive a date/time.
Dates inserted into the table need to be formatted yyyy-MM-dd’T’HH:mm:ss.
datagrid.DATA_TYPE_DATE Set a column dataType to receive a date.
Dates inserted into the table need to be formatted yyyy-MM-dd.

 

These methods are used when storing data from your API endpoint in Domo.

Method Parameters Return Description
datagrid.addColumn(columnName, dataType) columnName, dataType none Adds a column to a table. Defines the data type used by the column.
datagrid.addCell(cellData) cellData none Adds data to one cell in the table. Columns must be defined first.
datagrid.endRow() none none Indicates a row of data is complete and a new row in the table needs to be started.
datagrid.error(code, errorMessage) code, errorMessage none Ends the processing of data and returns an error message to the user.
datagrid.magicParseCSV(csvString)  csvString  none Populates the entire datagrid when passed a properly formatted string of comma-separated values.
datagrid.magicParseJSON(jsonString)  jsonString  none Populates the entire datagrid when passed a string representation of properly formatted JSON.
datagrid.magicParseXML(xmlString) xmlString none Populates the entire datagrid when passed a string representation of properly formatted XML.

 

Discovery

If you are using the Discovery option in Advanced Mode in the Configure Reports step, Domo provides methods and constants to help you. These methods and constants are specifically used in the discovery code block.

This constant is used when building a discovery tree menu.

Name Description
discovery.tree Used with a discovery tree. This references the root node in a discovery tree.

 

These methods are used when building a discovery tree or discovery dropdown.

Method Parameters Return Description
discovery.addOption(optionValue) optionValue none Used with a discovery dropdown. Adds an option to the dropdown menu.
discovery.addNode(parentNode, nodeName) parentNode, nodeName createdNode Used with a discovery tree. Creates a new child node within the node that is passed as a parameter. Returns a reference to the newly created node.
discovery.addLeaf(parentNode, leafName) parentNode, leafName none Used with a discovery tree. Creates a new child leaf within the node that is passed as a parameter.
discovery.publishTree() none none Used with a discovery tree. This method indicates with you have finished constructing a discovery tree.

 

Domo

These methods may be useful in any code block.

Method Parameters Return Description
DOMO.log(value) value none Prints to the Dev Studio console. Make sure you remove any credentials that you are logging for testing before you submit your connector.
DOMO.sleep(milliseconds) milliseconds none Can be used to space out http requests.
DOMO.getState(key) key value Returns the value of the requested state.
DOMO.setState(key, value) key, value none Can be used to set a state value which can be returned using DOMO.getState(key).
DOMO.parseXML(xmlString) xmlString jsonObject Used to convert XML to JSON for easier parsing.

 

Encoding Method Parameters Return Description
DOMO.b64EncodeUnicode(stringToEncode) stringToEncode encodedString Encodes a string using base64 encoding.
DOMO.hmacSHA1(stringToEncode, key) stringToEncode, key encodedString Encodes a string using the provided key to create a hmac-SHA1 hash.
DOMO.hmacSHA256(stringToEncode, key) stringToEncode, key encodedString Encodes a string using the provided key to create a hmac-SHA256 hash.
DOMO.md5(stringToEncode) stringToEncode encodedString Encodes a string using the md5 algorithm.
DOMO.getJWT()  none  tokenString Creates a JSON web token (JWT) using the assigned algorithm signed with the provided key.
Note: You must set the algorithm, key, issuer, subject, expiration, and other claims. See the provided code example.
Supported algorithms: HS256, RS256, ES256

 

HTTP Request

When making your http requests, use the following methods to add headers, add parameters, and make http calls.

Note: All URLs must use https.

Method Parameters Return Description
httprequest.addHeader(key, value)  key, value none Add a header to your http request. This is how you can add an Authorization header or any other header you need to your http request. Add headers and parameters before you make the http request.
httprequest.addParameter(key, value)  key, value none Add a parameter to a base url. Add headers and parameters before you make the http request.
httprequest.clearParameters(url)  url none Remove any parameters you have added to an httprequest object.
httprequest.clearHeaders(url)  url none Remove any headers you have added to an httprequest object.
httprequest.get(url)  url responseString Make an http get request. Any headers or parameters added before making the request will be included by Domo when making the get request. All URLs must use https.
httprequest.post(url)  url responseString Make an http post request without any request body. Any headers or parameters added before making the request will be included by Domo when making the post request. All URLs must use https.
httprequest.post(url, bodyString)  url, bodyString responseString Make an http post request with a request body. Any headers or parameters added before making the request will be included by Domo when making the post request. All URLs must use https.
httprequest.put(url, bodyString)  url, bodyString responseString Make an http put request with a request body. Any headers or parameters added before making the request will be included by Domo when making the put request. All URLs must use https.

 

Metadata

Information you may need to run your connector will be stored in a metadata JavaScript object. Access data from the metadata object in the same way you would access data from any JavaScript object.

Metadata object structure

{  
   "account":{  
      "username": <<null or data from authentication>>,
      "password": <<null or data from authentication>>,
      "apikey": <<null or data from authentication>>,
      "clientKey": <<null or data from authentication>>,
      "clientSecret": <<null or data from authentication>>,
      "authorizationURL": <<null or data from authentication>>,
      "accessTokenURL": <<null or data from authentication>>,
      "scope": <<null or data from authentication>>,
      "additionalParameters": <<null or data from authentication>>,
      "accesstokenMethod": <<null or data from authentication>>,
      "tokenAddlParams": <<null or data from authentication>>,
      "accesstoken": <<null or data from authentication>>,
      "code": <<null or data from authentication>>
   },
   "report":<<name of selected report>>,
   "days":1,
   "parameters":{  
      <<key/value pairs
        key = parameter name 
        value = selected parameter value (or array of values)>>
   },
   "discovery":{

   },
   "baseurl":"https://api.domo.com"
}

Metadata access examples

//Access accessToken in the account object.
var token = metadata.account.accesstoken;

//Access a parameter named "Region in United States"
//This will return an array of strings if the parameter type is a discovery tree. This will return a string if it's any other parameter type.
var region = metadata.parameter["Region in United States"];

Method Details

Auth Methods

These methods are specifically used in the authentication code block.


auth.authenticationSuccess()
Set during the authentication process to indicate that credentials have been successfully validated.

Parameters:

  • None

Returns:

  • None

Example:

if(res.indexOf('Account.Name') > 0){
  auth.authenticationSuccess();
} else {
  auth.authenticationFailed('Your username and password are incorrect');
}

auth.authenticationFailed(errorMessage)
Set during the authentication process to indicate that credentials could not be validated.

Parameters:

  • errorMessage: Message indicating why the authentication failed.

Returns:

  • None

Example:

if(res.indexOf('FeatureCollection') > 0){
  auth.authenticationSuccess();
} else {
  auth.authenticationFailed('Error connecting to earthquake.usgs.gov');
}

Datagrid Constants

These constants are specifically used in the data processing code block to define the type of your data in each of your datagrid columns.


datagrid.DATA_TYPE_STRING
Set a column dataType to receive a String.

Example:

datagrid.addColumn(‘Account ID’, datagrid.DATA_TYPE_STRING);

datagrid.DATA_TYPE_DOUBLE
Set a column dataType to receive a number.

Example:

datagrid.addColumn(‘Amount’, datagrid.DATA_TYPE_DOUBLE);

datagrid.DATA_TYPE_DATETIME
Set a column dataType to receive a String. Dates inserted into the table need to be formatted yyyy-MM-dd’T’HH:mm:ss.

Example:

datagrid.addColumn(‘Date Created’, datagrid.DATA_TYPE_DATETIME);

datagrid.DATA_TYPE_DATE
Set a column dataType to receive a String. Dates inserted into the table need to be formatted yyyy-MM-dd

Example:

datagrid.addColumn(‘Date Created’, datagrid.DATA_TYPE_DATE);

Datagrid Methods

These methods are specifically used in the data processing code block to insert your data into Domo.


datagrid.addColumn(columnName, dataType)
Adds a column to a table. Defines the data type used by the column.

Parameters:

  • columnName: The column name that the user will see when they look at the table.
    • dataType: The Domo data type. It may be datagrid.DATA_TYPE_STRING, datagrid.DATA_TYPE_DOUBLE, datagrid.DATA_TYPE_DATETIME, or datagrid.DATA_TYPE_DATE.

Returns:

  • None

Example:

datagrid.addColumn(‘Name’, datagrid.DATA_TYPE_STRING);

datagrid.addCell(cellData)
Adds data to one cell in the table. Columns must be defined first.

Parameters:

  • cellData: The datum to be inserted into this table cell. The type of the data should match the type in the column.

Returns:

  • None

Example:

datagrid.addCell(‘Jane Jones’);

datagrid.endRow()
Indicates a row of data is complete and a new row in the table needs to be started.

Parameters:

  • None

Returns:

  • None

Example:

datagrid.addColumn('Name', datagrid.DATA_TYPE_STRING);
datagrid.addColumn('Birthday', datagrid.DATA_TYPE_DATE);

datagrid.addCell('Jane Jones');
datagrid.addCell('2017-10-25');
datagrid.endRow();

datagrid.error(code, errorMessage)
Ends the processing of data and returns an error message to the user.

Parameters:

  • code: A integer code you would like to use to define the error.
    • errorMessage: An error message that will be returned to the user.

Returns:

  • None

Example:

datagrid.error(0, metadata.report + ‘ is not a supported report.’);

datagrid.magicParseCSV(csvString)
Populates the entire datagrid when passed a properly formatted string of comma-separated values. The magicParse automatically determines type, and leaves any undetermined types as strings.

Parameters:

  • csvString: A string containing a comma-separated values. The first line should contain the comma-separated column names.

Returns:

  • None

Example:

var res = `Name,Birthday,Department
"Jane Jones",1981-03-04,"Engineering"
"Peter Paul",1975-08-09,"Marketing"`;

datagrid.magicParseCSV(res);

Result:


datagrid.magicParseJSON(jsonString)
Populates the entire datagrid when passed a string representation of properly formatted JSON. The magicParse automatically determines type, and leaves any undetermined types as strings.

Parameters:

  • jsonString: A string representation of a properly formatted JSON. The magicParseJSON method only works for JSON table data presented in key/value pairs.

Returns:

  • None

Example:

var res = `[{
  "Name": "Jane Jones",
  "Data": {
    "Birthday": "1981-03-04",
    "Department": "Engineering" }
},{
  "Name": "Peter Paul",
  "Data": {
    "Birthday": "1975-08-09",
    "Department": "Marketing" }
}]`;

datagrid.magicParseJSON(res);

Result:


datagrid.magicParseXML(xmlString)
Populates the entire datagrid when passed a string representation of properly formatted XML. The magicParse automatically determines type, and leaves any undetermined types as strings.

Parameters:

  • xmlString: A string representation of a properly formatted XML.

Returns:

  • None

Example:

var res = `
<BirthdayList>
  <Entry>
    <Name>Jane Jones</Name>
    <Birthday>1981-03-04</Birthday>
    <Department>Engineering</Department>
  </Entry>
  <Entry>
    <Name>Peter Paul</Name>
    <Birthday>1975-08-09</Birthday>
    <Department>Marketing</Department>
  </Entry>
</BirthdayList>
`;

datagrid.magicParseXML(res);

Result:


Discovery Constants

This constant is used when building a discovery tree menu in the Configure Reports Advanced Mode.


discovery.tree
Used with a discovery tree. This references the root node in a discovery tree.

Example:

discovery.addLeaf(discovery.tree, "Jane Jones");

discovery.addNode(discovery.tree, "Marketing");

Discovery Methods

These methods are used when building a discovery tree or discovery dropdown in the Configure Reports Advanced Mode.


discovery.addOption(optionValue)
Used with a discovery dropdown. Adds an option to the dropdown menu.

Parameters:

  • optionValue: The value to be displayed in the dropdown menu.

Returns:

  • None

Example:

var data = ["Alice", "Jane", "Jim"];

for (let name of data){
  discovery.addOption(name);
}

Result:


discovery.addNode(parentNode, nodeName)
Used with a discovery tree. Creates a new child node within the node that is passed as a parameter. To create a node at the root level, you must use discovery.tree as the node parameter.

Parameters:

  • parentNode: An existing node object in the discovery tree.
  • nodeName: The name displayed on the new node.

Returns:

  • createdNode: A reference to the newly created node object

Example:

var data = {
  "Marketing": ["Alice", "Jane", "Jim"], 
  "Engineering": ["Samantha", "George", "Peter"]
};

for (let department in data){
  DOMO.log(department);
  let node = discovery.addNode(discovery.tree, department);
  for (let name of data[department]){
    DOMO.log(name);
    discovery.addLeaf(node, name);
  }
}

discovery.publishTree();

Result:


discovery.addLeaf(parentNode, leafName)
Used with a discovery tree. Creates a new child leaf within the node that is passed as a parameter.

Parameters:

  • parentNode: An existing node object in the discovery tree.
  • leafName: The name displayed on the new leaf.

Returns:

  • None

Example:

var data = ["Alice", "Jane", "Jim"];

for (let name of data){
  discovery.addLeaf(discovery.tree, name);
}

discovery.publishTree();

Result:


discovery.publishTree()
Used with a discovery tree. This method indicates when you have finished constructing a discovery tree.

Parameters:

  • None

Returns:

  • None

Example:

var data = ["Alice", "Jane", "Jim"];

for (let name of data){
  discovery.addLeaf(discovery.tree, name);
}

discovery.publishTree();

Domo Methods

These methods may be useful in any code block.


DOMO.log(value)
Prints to the Dev Studio console. Make sure you remove any credentials that you are logging for testing before you submit your connector.

Parameters:

  • value: The value to print. In JavaScript, this can be a a string, but it doesn't have to be.

Returns:

  • None

Example:

//To log a JavaScript object, just log the object. Just like console.log. :)
DOMO.log(metadata);
DOMO.log(‘metadata.report: ‘ + metadata.report);

DOMO.sleep(milliseconds)
Can be used to space out http requests.

Parameters:

  • milliseconds: An integer value representing the number of milliseconds you want your connector to sleep.

Returns:

  • None

Example:

DOMO.sleep(5000);

DOMO.getState(key)
If you have set a state for your connector, this method returns the value of the requested state.

Parameters:

  • key: The key to the state.

Returns:

  • value: The value stored with that key.

Example:

DOMO.setState("key", "value");

var value = DOMO.getState("key");
DOMO.log(value);

DOMO.setState(key, value)
If you have need to set a state for your connector, this method can be used to set a state value which can be returned using DOMO.getState(key).

Parameters:

  • key: The key to the state.
  • value: The value stored with that key.

Returns:

  • None

Example:

DOMO.setState(1, 123456);

var value = DOMO.getState(1);
DOMO.log(value);

DOMO.parseXML(xmlString)
Used to convert XML to JSON for easier parsing.

Parameters:

  • xmlString: The key to the state.

Returns:

  • jsonObject: A JSON object.

Example:

var res = `
<BirthdayList>
  <Entry>
    <Name>Jane Jones</Name>
    <Birthday>1981-03-04</Birthday>
    <Department>Engineering</Department>
  </Entry>
  <Entry>
    <Name>Peter Paul</Name>
    <Birthday>1975-08-09</Birthday>
    <Department>Marketing</Department>
  </Entry>
</BirthdayList>
`;

var jsonObject = DOMO.parseXML(res);
DOMO.log(jsonObject);

Result:

{  
   "BirthdayList":{  
      "Entry":[  
         {  
            "Department":"Engineering",
            "Birthday":"1981-03-04",
            "Name":"Jane Jones"
         },
         {  
            "Department":"Marketing",
            "Birthday":"1975-08-09",
            "Name":"Peter Paul"
         }
      ]
   }
}

Domo Encoding Methods

These methods may be useful in any code block to encode data.


DOMO.b64EncodeUnicode(stringToEncode)
Encodes a string using base64 encoding. Base64 encoding is used in the Basic Authentication process, and most endpoints that use username and password will use the Basic Authentication standard.

Parameters:

  • stringToEncode: The string you wish to encode with base-64 encoding.

Returns:

  • encodedString: The base-64 encoded string.

Example:

var encodedString = DOMO.b64EncodeUnicode(metadata.account.username + ‘:’ + metadata.account.password);

DOMO.hmacSHA1(stringToEncode, key)
Encodes a string using the provided key to create a hmac-SHA1 hash.

Parameters:

  • stringToEncode: The string you wish to encode.
  • key: The string used to create the hmac-SHA1 hash.

Returns:

  • encodedString: The hmac-SHA1 encoded string.

Example:

var encodedString = DOMO.hmacSHA1(“password”, “key”);

DOMO.hmacSHA256(stringToEncode, key)
Encodes a string using the provided key to create a hmac-SHA256 hash.

Parameters:

  • stringToEncode: The string you wish to encode.
  • key: The string used to create the hmac-SHA256 hash.

Returns:

  • encodedString: The hmac-SHA256 encoded string.

Example:

var encodedString = DOMO.hmacSHA256(“password”, “key”);

DOMO.md5(stringToEncode)
Encodes a string with the md5 algorithm.

Parameters:

  • stringToEncode: The string you wish to encode with md5 encoding.

Returns:

  • encodedString: The md5 encoded string.

Example:

var encodedString = DOMO.md5(“password”);

DOMO.getJWT()
Creates a JSON web token (JWT) token using the assigned algorithm signed with the provided key.
Note: You must set the algorithm, key, issuer, subject, expiration, and other claims.
Supported algorithms: HS256, RS256, ES256

Parameters:

  • None

Returns:

  • tokenString: The JWT token.

Example:

//Choose the algorithm, Set the authorization key, issuer, subject, claims, and expiration
DOMO.jwtBuilder.algorithm = “HS256”;
DOMO.jwtBuilder.authKey = "DD558ECE4B3DF7FD31DE964E4F07E43B";
DOMO.jwtBuilder.issuer = "DOMO";
DOMO.jwtBuilder.subject = "12345670";
DOMO.jwtBuilder.claims["abc"] = "test";
DOMO.jwtBuilder.expiration = "1530228571";

//Get the token
var token = DOMO.getJWT();

HTTP Request Methods

These methods may be useful in any code block. When making your http requests, use the following methods to add headers, add parameters, and make http calls.
Note: All URLs must use https.


httprequest.addHeader(key, value)
Add a header to your http request. This is how you can add an Authorization header or any other header you need to your http request. Add headers and parameters before you make the http request.

Parameters:

  • key: A string that is the header key.
  • value: A string that is the header value.

Returns:

  • None

Example:

var encodedData = DOMO.b64EncodeUnicode(metadata.account.username + ':' + metadata.account.password);

httprequest.addHeader('Authorization', 'Basic ' + encodedData);

var res = httprequest.get('https://developer.domo.com/samplecrm');  

httprequest.addParameter(key, value)
Add a parameter to a base url. Add headers and parameters before you make the http request.

Parameters:

  • key: A string that is the parameter key.
  • value: A string that is the parameter value.

Returns:

  • None

Example:

httprequest.addHeader('Authorization', 'OAuth ' + metadata.account.accesstoken);
httprequest.addParameter('metadata', '0');
httprequest.addParameter('fields', 'id,name,accounts');

//The parameters added above will be automatically added to the url
//Resulting URL: https://graph.facebook.com/v3.1/me?metadata=0&fields=id,name,accounts
var res = httprequest.get('https://graph.facebook.com/v3.1/me');

httprequest.clearParameters(url)
Remove any parameters you have added to an httprequest object.

Parameters:

  • url: The url that you used to make an http request.

Returns:

  • None

Example:

httprequest.addHeader('Authorization', 'OAuth ' + metadata.account.accesstoken);
httprequest.addParameter('metadata', '0');
httprequest.addParameter('fields', 'id,name,accounts');

//The parameters added above will be automatically added to the url
//Resulting URL: https://graph.facebook.com/v3.1/me?metadata=0&fields=id,name,accounts
var res = httprequest.get('https://graph.facebook.com/v3.1/me');

//Clear the parameters to make a different call with the same url
httprequest.clearParameters('https://graph.facebook.com/v3.1/me');

httprequest.clearHeaders(url)
Remove any headers you have added to an httprequest object.

Parameters:

  • url: The url you used to make an http request.

Returns:

  • None

Example:

var encodedData = DOMO.b64EncodeUnicode(metadata.account.username + ':' + metadata.account.password);

httprequest.addHeader('Authorization', 'Basic ' + encodedData);

var res = httprequest.get('https://developer.domo.com/samplecrm');

//Clearing header to make call with different header information
httprequest.clearHeaders('https://developer.domo.com/samplecrm');

httprequest.get(url)
Make an http get request. Any headers or parameters added before making the request will be included by Domo when making the get request.
Note: All URLs must use https.

Parameters:

  • url: The url you would like to use to make an http get request.

Returns:

  • responseString: The response from the endpoint you called.

Example:

var encodedData = DOMO.b64EncodeUnicode(metadata.account.username + ':' + metadata.account.password);

httprequest.addHeader('Authorization', 'Basic ' + encodedData);

var res = httprequest.get('https://developer.domo.com/samplecrm');

httprequest.post(url)
Make an http post request without any request body. Any headers or parameters added before making the request will be included by Domo when making the post request.
Note: All URLs must use https.

Parameters:

  • url: The url you would like to use to make an http post request.

Returns:

  • responseString: The response from the endpoint you called.

Example:

var encodedData = DOMO.b64EncodeUnicode(metadata.account.username + ':' + metadata.account.password);

httprequest.addHeader('Authorization', 'Basic ' + encodedData);

var res = httprequest.post('https://developer.domo.com/samplecrm');

httprequest.post(url, bodyString)
Make an http post request with a request body. Any headers or parameters added before making the request will be included by Domo when making the post request.
Note: All URLs must use https.

Parameters:

  • url: The url you would like to use to make an http post request.
  • bodyString: The body of your http post request.

Returns:

  • responseString: The response from the endpoint you called.

Example:

var encodedData = DOMO.b64EncodeUnicode(metadata.account.username + ':' + metadata.account.password);

httprequest.addHeader('Authorization', 'Basic ' + encodedData);

var res = httprequest.post('https://developer.domo.com/samplecrm', 'This is my request body');

httprequest.put(url, bodyString)
Make an http put request with a request body. Any headers or parameters added before making the request will be included by Domo when making the put request.
Note: All URLs must use https.

Parameters:

  • url: The url you would like to use to make an http get request.
  • bodyString: The body of your http post request.

Returns:

  • responseString: The response from the endpoint you called.

Example:

var encodedData = DOMO.b64EncodeUnicode(metadata.account.username + ':' + metadata.account.password);

httprequest.addHeader('Authorization', 'Basic ' + encodedData);

var res = httprequest.put('https://developer.domo.com/samplecrm', 'this is my request body');