R - Domo API SDK (rdomo)

Current Release: 0.1.0

About

• The Domo API SDK is the simplest way to automate your Domo instance
• The SDK streamlines the API programming experience, allowing you to significantly reduce your written code
• rdomo is not currently on CRAN but can be installed using the devtools package (details below)

Features:

• DataSet and Personalized Data Policy (PDP) Management
  • Use DataSets for fairly static data sources that only require occasional updates via data replacement
  • This SDK automates the use of Domo Streams so that uploads are always as fast as possible
  • Add Personalized Data Policies (PDPs) to DataSets (hide sensitive data from groups of users)
  • Docs: https://developer.domo.com/docs/domo-apis/data
• User Management
  • Create, update, and remove users
  • Major use case: LDAP/Active Directory synchronization
  • Docs: https://developer.domo.com/docs/domo-apis/users
• Group Management
  • Create, update, and remove groups of users
  • Docs: https://developer.domo.com/docs/domo-apis/group-apis
• Page Management
  • Create, update, and delete pages
  • Docs: https://developer.domo.com/docs/page-api-reference/page

Installation

To install, please install the devtools package and type the following command.

devtools::install_github(repo='domoinc/rdomo',ref='main')

This installation will re-install any of the dependencies needed for operating the package. If you don't want to re-install packages, use the following code. Doing this might affect the operation of the package.

devtools::install_github(repo='domoinc/rdomo',ref='main',dependencies=FALSE)

Setup and Authentication

In order to connect R to Domo, you will need to have a valid set of credentials. Credentials can be generated by going to Domo's developer site and do the following.

• Click the "login" button in the top ribbon (just left of the search box).
  • This will take you to a Domo login screen and will require your username and password.
  • If you are currently logged in, you will not be required to give your username and password.
• Once you have signed in, click "My Account" and "New Client".
• Give your client a name and a description (description optional).
• Click any of the resources you want this set of credentials to be able to access.
• Click "Create".

After clicking Create, the developer site will display your client id and secret.

Your client id and secret are then used to authenticate from R. To create a new connection to Domo, use the following code.

domo <- rdomo::Domo(client_id='your client id',secret='your secret')

This code creates an object called "domo" that stores all your connection information and all functions necessary to interact with Domo's API. For example, if you would like to download a data set from Domo, you can now use the following code. (The data set id can be found in the URL for a data set in Domo's data center or you can use the "ds_list" function to get a list of all your data sets.)

my_dataset <- domo$ds_get('some data set id')

In order to simplify writing code against the API, you can put your credentials into your global environment. This has the benefit of eliminating the need to type your credentials everytime you need to connect AND it keeps your credentials out of every one of the scripts you will write. To do this, put the following in your .Renviron file in your home folder.

RDOMO_CLIENTID="your client id"
RDOMO_SECRET="your secret"

When this is done, you can now connect without needing to specify those values.

domo <- rdomo::Domo()

Reference classes

This package uses a reference class as the primary way of interacting with the Domo API. Reference classes allow us to mimic objects found in other programming languages like Python. More information can be found here.

The primary benefit of using refernce classes in this package is the ability to authenticate easily against multiple Domo instances. When this is done, you can transfer data or make other modifications to multiple instances. For example, the following code authenticates against two different Domo instances, downloads data from one instance and pushes that same data to the seccond instance.

domo1 <- rdomo::Domo(client_id="client id 1",secret="secret 1")
domo2 <- rdomo::Domo(client_id="client id 2",secret="secret 2")

data_set_to_copy <- 'data set id'

data1 <- domo1$ds_get(data_set_to_copy)
data1_info <- domo1$ds_meta(data_set_to_copy)

uploaded_data <- domo2$ds_create(as.data.frame(data1),data1_info$name,data1_info$description)

To continue the example, if there were PDP policies on the data set copied, you might also want to copy all of the PDP policies. That can be done as follows.

pdp_policies <- domo1$pdp_list(data_set_to_copy)
added_policies <- lapply(pdp_policies,function(x){
	policy_spec <- x
	policy_spec$id <- NULL #doing this to make sure Domo assigns its own PDP policy id
	pdp_create(data_set_to_copy,policy_spec)
})

Available Functions

The functions in this package match most parts of the API documented at developer.domo.com and follow a specific convention. Each set of functions is preceeded by the portion of the API it operates on. The following lists all the sets of functions available in this package. For further help, refer to help available in R by typing "?" and the name of the function you're interested in.

• Data sets - This set of functions is designed to transfer data in and out of Domo.
  • ds_get - downloads data from Domo
  • ds_create - creates a new data set
  • ds_update - updates an existing data set, only data sets created by the API can be updated
  • ds_meta - downloads meta data regarding a single data set
  • ds_list - downloads a list of data sets in your Domo instance
  • ds_delete - deletes a data set (be careful)
  • ds_query - allows you to send a query to a data set, Domo will evaluate that query and sends the results back as a list or a tibble
  • ds_rename - renames an existing data set
• Groups - This set of functions modifies and creates groups.
  • groups_add_users - adds users to an existing group
  • groups_create - create a group
  • groups_delete - delete an existing group
  • groups_list - list all groups
  • groups_remove_users - remove users from a group
  • groups_list_users - list users in a group
• Pages - functions related to managing Domo pages
  • page_update - update a page
  • page_list - list all pages
  • page_get_collections - list all collections on a page
  • page_get - get information regarding a page
  • page_create - create a page
• PDP - functions to manage PDP
  • pdp_update - update an existing PDP policy
  • pdp_list - list all PDP policies
  • pdp_enable - toggle PDP on and off
  • pdp_delete - delete a PDP policy
  • pdp_create - create a PDP policy
• Users - functions to manage users
  • users_delete - delete a user
  • users_update - update a user
  • users_list - list all users
  • users_get - get a single user record
  • users_add - create a user (or users)