Programmatic Filtering

If you prefer not to work through the licensing and provisioning of mirror users both in your systems and Domo, the main alternative is to persist the policies you have already setup in your systems by applying Programmatic Filters in server-side code. This way, you can still personalize embedded content for any number of viewers even if they do not have a Domo account.

This diagram summarizes the flow of tokens and data through the service account that acts as proxy for all other viewers. Steps 1-5 highlight the sequence of messages between your servers and the Domo API during Programmatic Filtering.

Step 1: Point iframe to your server

A. Download the sample code from one of the example GitHub repositories to access even more detailed instructions in the readme file or check out example code:

Although other apps can be privately embedded, the Inline Dataset Editor and Form Viewer apps cannot be used with programmatic filters because of their reliance on OAuth.
  • The JavaScript version uses a Node.js repository


  • The ASP version is based on a .NET repository


  • Check out example Python code for Programmatic Filtering


  • Check out example PHP code for Programmatic Filtering


B. Open the “sample.html” file in the example code

  • Focus on this line: <iframe src=”http://localhost:3001/embed/item/1″ width=”1200″ height=”600″ scrolling=”no”></iframe>
    • When you are ready to move from testing to a production environment, replace localhost:3001 with the domain for your server
    • This can feel counter-intuitive at first since the default embed code is an iframe that points to the Domo instance
    • However, this temporary detour in your domain is how the server side code is processed before the final version of the embedded content is sent by Domo
  • Step 4 below will swap your domain with the Domo instance domain in the self-submitting HTML form

Step 2: Get access token

A. Activate an API client buy signing in to as the user who will serve as proxy for every other viewer:

Ensure this user has the relevant cards and pages shared with them before trying to embed content

B. Create an account by clicking My Account > New Client and filling out the fields as follows:

  • For more information about creating the CLIENT_ID and CLIENT_SECRET review the details in the following link:


C. Copy the IDs for the cards or dashboards from the embed dialog in Domo using the “private” authenticated option:

D. Create a file with a blank name and .env extension

  • Customize the configuration settings with your own values
    • Include “USE_XHR=true” only if cookie based authentication won’t work for the endpoint on your server.
    • The CLIENT_ID and CLIENT_SECRET is used to create the access token which will be used to then create an embed token for use with the private embed.
    • The EMBED_ID references the card or the dashboard you are embedding.
Best practices
This ID is NOT the one you can see in the URL of the Domo instance. It is the 5-character embed ID you can only copy from the embed dialog for that card or dashboard.
  • The EMBED_TYPE must be either the word ‘dashboard’ or ‘card’ (without the quotes).
  • Save the .env file in the same directory as the sample code

Step 3: Get embed token

A. Open the embed.js file

  • Notice it covers these functions:
    • “getAccessToken”
    • “getEmbedToken”
    • “returnEmbedInfo”
    • “handleRequest”
    • “refreshEmbedToken”
  • No customization should be required

Processing can be viewed from the command line when the testing environment is live (see step 5)

Deeper details on the possible requests and responses for the Embed API can be found here:


Step 4: Return html form

A. Open the file users.js in a text editor and modify the filter settings for each user to customize the filtering that each user will have applied to them.

Currently each user has an empty filter being applied to them “[]”.

  • There are some example filters in the file that are commented out that you can use that give you an idea of the format expected for the filters.
  • Once you make filter changes to the users.js file, you will need to save the file, restart the express server, refresh the page, and then log back in.

It is critical that the developer of the code understands the schema of the underlying dataset.

  • Otherwise, the query will fail and the api will respond with “Bad Request”.
  • This is to maintain the security of your server-side Programmatic Filters.

The complete list of available operators for use in filters are:

  • “IN”
  • “NOT_IN”
  • “EQUALS”
Best practices

  • Browsers set a standardized size limit around 8kb on the JSON Web Token (JWT) used to define programmatic filters: .
  • In a few edge cases (primarily with “IN” operator), filters that try to include extremely long lists of values can hit that size limit.
  • To resolve this, transform the data and create a new column of aggregated values that will simplify the server-side filter logic.

Step 5: Token and filter submitted in form

A. Navigate to the base folder where the repository was unzipped to install the necessary dependencies

  • Install nodejs


  • Install yarn


B. Start the express server by running the “yarn start” or “node express” command from the base folder of the project in Terminal / Command line.

  • Go to the url localhost:3001 in your browser and verify that you are able to see the card or dashboard after you login.
  • The available usernames are listed in the express.js file (“mike”, “susan”, “tom”, and “rachael”).
  • The password is not verified and so any will work.