home User Guide Getting Started Help Center Documentation Community Training Certification
menu
close
settings
Looker keyboard_arrow_down
language keyboard_arrow_down
English
Français
Deutsch
日本語
search
print
Sharing Data Through an Action Hub

In addition to delivering content to Looker’s built-in destinations, you can use actions — also called integrations — to deliver content to third-party services integrated with Looker via an action hub server.

Actions served through an action hub server differ from data actions, which are defined by the action LookML parameter.

This page will walk you through your options for building custom actions that you can request to add to the Looker Action Hub or add to your own private action hub server. This page also describes how to spin up a local action hub server to test your custom actions or run a private action hub server.

The graphic below illustrates your available workflow options for integrating actions through either a privately hosted action hub or the Looker-hosted Action Hub:

Once the action is added to the action hub, a Looker admin can enable it for use in sending or scheduling data deliveries to integrated services.

You can also set up multiple action hubs if you would like to use Looker’s integrations through the Looker Action Hub and also host your own private or custom actions. The actions for each action hub would appear on the Actions page of the Admin panel.

The Looker Action Hub

Looker hosts and provides a stateless server, the Looker Action Hub, which implements Looker’s Action API and exposes popular actions. Any data your users send using an action will be processed temporarily on the Action Hub server rather than in your Looker instance.

Looker is already integrated with several services. See the Admin Settings - Actions documentation page to learn how to enable these existing services.

Looker Action Hub Requirements

To use Looker integrations, the Looker Action Hub must be able to communicate with the Looker instance and fulfill these requirements. Admins of customer-hosted instances may need to consider additional factors when choosing to enable Looker integrations from the Looker Action Hub, especially integrations that support streamed results or that use OAuth.

The Looker Action Hub must be able to send and receive API requests:

If your Looker deployment cannot accommodate these requests or if your Looker instance is IP whitelisted, consider setting up a local action hub server to serve private Looker integrations or custom actions. Admins of customer-hosted instances can also deploy a local action server specifically for OAuth and streaming actions.

Requests from the Looker Instance to the Looker Action Hub Network

Requests to actions.looker.com resolve to a dynamic IP address. Outgoing requests from the Looker instance must be able to reach these endpoints:

actions.looker.com/
actions.looker.com/actions/<name>/execute
actions.looker.com/actions/<name>/form

where name is the programmatic name of the action.

Requests from the Looker User’s Browser to the Looker Action Hub Network

The Looker user’s browser must be able to make requests to these Looker Action Hub endpoints (for OAuth):

actions.looker.com/actions/<name>/oauth

where name is the programmatic name of the action.

Requests from the Looker Action Hub Network to the Looker Instance

The Looker Action Hub must make requests to the Looker instance for actions that support streamed results or that use OAuth.

A streaming action enables the action to consume “all results” queries, while OAuth-enabled actions use per-user authentication via OAuth2 flows. OAuth actions must store user credentials in their source Looker instance because the Looker Action Hub is stateless and multi-tenant, and it will not store user-specific credentials of any kind.

The requests from the Looker Action Hub to a Looker instance take the following forms:

GET <host_looker_url>/downloads/<random_40_char_token>
POST <host_looker_url>/action_hub_state/<random_40_char_token>

These URLs are generated on the spot in the Looker instance before being sent to the Looker Action Hub. For this reason, the Looker Action Hub needs to be able to both resolve the <host_looker_url> to an IP address and make requests into the network in which your Looker instance resides.

The Looker-hosted Action Hub has two static egress IP addresses that the requests will always come from: 35.153.89.114 and 35.169.42.87.

Considerations for Customer-Hosted Instances

To use Looker integrations, the Looker Action Hub must be able to communicate with the Looker instance and fulfill these requirements. This is not always possible with customer-hosted Looker instances, for various reasons.

Users of customer-hosted instances may be unable to configure or use actions that support streamed results or that use OAuth if the Looker-hosted Action Hub is not able to communicate with the customer-hosted Looker instance. Users may experience hanging queries when sending or scheduling data to streamed actions.

To address this potential issue, Looker admins can implement one of these solutions:

  1. Whitelist the egress IP addresses for the Looker Action Hub: 35.153.89.114 and 35.169.42.87. These are the static IP addresses from which the Looker Action Hub makes requests to the Looker instance.
  2. Deploy a customer-hosted action hub specifically for these actions.
  3. Ensure that the JAR file is hosted on a public server so that the Looker Action Hub can communicate with it. This is not usually an ideal solution.

Another reason the OAuth and streaming actions might not be useable on a customer-hosted Looker instance is if the instance uses an SSL certificate issued by a Certificate Authority (CA) not on this list.

Actions configured to support streamed results or OAuth are listed on the Admin Settings - Actions documentation page.

Building a Custom Action

This section describes the steps to follow to write and test a custom action using the Looker Action Hub source code from the looker/actions repo in GitHub.

You can create a custom action by:

  1. Setting up a development repo
  2. Writing your action
  3. Testing your action
  4. Publishing and enabling your action, either in the Looker Action Hub or on your own private action hub server

As with any action, you may need to configure your LookML models with specific parameters before you can use the action to deliver your data.

Setting Up a Development Repo

The Looker Action Hub is a Node.js server written in TypeScript, a small layer on top of modern JavaScript that adds type information to help catch programming errors. If you’re familiar with JavaScript, most of the TypeScript language should be familiar to you.

Running the Looker Action Hub requires the following software:

Once you’ve installed the required software, you’re ready to set up your development environment. Our example below uses Git.

  1. Clone the looker/actions repo locally:
git clone git@github.com:looker/actions.git
  1. Create a directory with the name of your action in the actions/src/actions directory. For example:
mkdir actions/src/actions/my_action
  1. Start populating your directory with the files you’ll need to execute your action. See the actions GitHub repo for an example file structure.

We recommend you also add:

Writing an Action

A design requirement for the Looker Action Hub server is that it remain completely stateless, so storing any information in the action application or service is not allowed. Any information needed to fulfill the action must be provided within the action file’s request calls.

The exact contents of the action file will vary depending on the service, the type or level at which the action operates, and what data or visualization formats need to be specified. The action can also be configured for Google OAuth authorization.

Action files are based on the /execute API method. Looker API requests are passed a DataActionRequest each time a user executes the action within Looker. The DataActionRequest contains all of the data and metadata needed to execute your action. There is also a /form method that can be used to collect additional information from the user before they execute the action. The fields you specify in the /form will appear in the Send or Schedule pop-up when users select the action as a destination for their data delivery.

If using the Looker Action API, the format of these parameters may be different.

When writing your action file, include at least the following parameters marked Required in your action definition:

Parameter Required Description Data Type
name Yes A unique name for the action. This should be unique across all actions in the Looker Action Hub. string
url Yes An absolute URL of the /execute endpoint for this action. string
label Yes A human-readable label for the action. string
supportedActionTypes Yes A list of action types the action supports. Valid values are "cell", "query", and "dashboard". string
formURL No An absolute URL of the /form endpoint for this action. string
description No Description of the action. string
params No Array of parameters for the action. Include the name, label, and description in string format for each parameter. These are the fields that appear on the action’s enablement page in the Admin panel. To manage how users can deliver data to an action destination, you can specify a user attribute for which a user must have a defined value. parameters
supportedFormats No A list of data formats the action supports. Valid values are "txt", "csv", "inline_json", "json", "json_detail", "json_detail_lite_stream", "xlsx", "html", "wysiwyg_pdf", "assembled_pdf", and "wysiwyg_png". string
supportedFormattings No A list of formatting options the action supports. Valid values are "formatted" and "unformatted". string
supportedVisualizationFormattings No A list of visualization formatting options the action supports. Valid values are "apply" and "noapply". string
iconName No A Data URI representing an icon image for the action. string
requiredFields No A list of descriptions of required fields that this action is compatible with. If there are multiple entries in this list, the action requires more than one field. RequiredField
supportedDownloadSettings No A Boolean that determines whether the action will be sent a one-time-use download URL to facilitate unlimited streaming of data. The parameter is set by the usesStreaming parameter, which is a true/false Boolean. If usesStreaming = true, then supportedDownloadSettings = url. If usesStreaming = false, then supportedDownloadSettings = push. Boolean
usesOAuth No A Boolean that determines whether the action is an OAuth action. This will determine whether the action will be sent a one-time-use link to be able to set state for a specific user for this action. Boolean
usesStreaming No A Boolean that determines whether the action supports streamed query results. Check the Can Stream Results Yes/No column in the list of integrated services. Actions that stream results may require configuration of a local action hub server — see the Setting up a Local Action Hub for Actions that Use OAuth and Streaming article in the Looker Help Center for more information. Boolean
minimumSupportedVersion No The minimum Looker version in which the action will appear in the Admin panel Action Hub list. string

Examples from the Looker Action Hub actions are on GitHub for reference.

Supported Action Types

Looker supports three types of actions, as specified in the supportedActionTypes parameter of your action: query, cell, and dashboard.

Adding User Attributes to Custom Actions

add

New in Looker 7.12, you can specify user attributes in a custom action definition, requiring that users have a value defined for that user attribute to be able to send Looker content to the action destination.

For custom actions, you can add user attributes in the params parameter of your action file. A user must have a value for this attribute defined in their user account or for a user group they belong to, in addition to the send_to_integration permission, to see the action as a destination option when sending or scheduling content.

To add a user attribute to your action:

  1. A Looker admin may need to create the user attribute corresponding to the user_attribute_param if it does not already exist.
  2. Define a valid value for the user attribute for the users or user groups that need to deliver content to your action destination. (These users must also have send_to_integration permissions.)
  3. The params parameter represents the form fields that a Looker admin must configure on the action’s enablement page from the Actions list in the Admin panel. In the params parameter of your action file, include:

params = [{ description: "A description of the param.", label: "A label for the param.", name: "action_param_name", user_attribute_name: "user_attribute_name", required: true, sensitive: true, }]

where user_attribute_name is the user attribute defined in the Name field on the User Attributes page in the Users section of the Admin panel, required: true means that a user must have a non-null and valid value defined for that user attribute to see the action when delivering data, and sensitive: true means that user attribute is encrypted and never displayed in the Looker UI once entered. You can specify multiple user attribute subparameters. 1. Deploy your updates to the action hub server. * If you are adding a new action, a Looker admin will need to enable the action by clicking the Enable button next to the action on the Actions page in the Admin panel. * If you are updating an existing action, refresh your list of actions by clicking the Refresh button. Next, click the Settings button. 1. On the action settings/enablement page, a Looker admin must configure the action’s form fields to pull information from the user attribute by clicking the the user attribute icon to the right of the appropriate field and selecting the desired user attribute.

requiredField Parameters in Cell-Level Actions

For cell-level actions, you can configure your model’s LookML fields to deliver data to that action destination by specifying which tags your action supports in the requiredFields parameter of your action file.

Parameter Required Description Data Type
tag No If present, matches a field that has this tag. string
any_tag No If present, supersedes tag and matches a field that has any of the provided tags. string
all_tags No If present, supersedes tag and matches a field that has all of the provided tags. string

Supported Data Formats

The DataActionRequest class defines what data delivery format is available for the action to work with. For query-level actions, the request will contain an attachment that can be in several formats. The action can either specify one or more supportedFormats or let the user choose the format by specifying all possible formats. For cell-level actions, the value of the cell will be present on DataActionRequest.

Configuring an Action for OAuth Authentication

OAuth-enabled actions cannot be configured from the Looker Action Hub for Looker instances that are IP whitelisted or for Looker instances that cannot accommodate the Looker Action Hub requirements. See the Setting Up a Local Action Hub for Actions That Use OAuth and Streaming article in the Looker Help Center for more information about configuring an action for OAuth.

You can configure your action so that users can authenticate into the action with OAuth. Even though the Looker Action Hub must remain stateless, you can enforce a state through a form request from the Looker Action API.

Looker Action OAuth Flow

For actions in the Looker Action Hub, you can extend an OAuthAction instead of a Hub.Action to set a Boolean that indicates which OAuth methods are needed to authenticate a user into an action. For every OAuth- or state-enabled action, Looker stores a per-user, per-action state, so that each action and user combination has an independent OAuth event.

The flow for creating actions typically involves a /form request followed by a /execute request. For OAuth, the /form request should have a method to determine if the the user is authenticated within the target service. If the user is already authenticated, the action should return a normal /form in accordance with whatever the /execute request requires. If the user is not authenticated, the action returns a link that will initialize an OAuth flow.

Saving State with the OAuth URL

Looker will send an HTTP POST request with an empty body to the ActionList endpoint. If the action returns uses_oauth: true in its definition, then the action will be sent a one-time-use state_url in every /form request from Looker. The state_url is a special one-time-use URL that sets a user’s state for a given action.

If the user is not authenticated with the endpoint, the /form returned should contain a form_field of type oauth_link that goes to the /oauth endpoint of an action. The state_url should be encrypted and saved as a state param in the oauth_url that is returned. For example:

{
        "name": "login",
        "type": "oauth_link",
        "label": "Log in",
        "description": "OAuth Link",
        "oauth_url": "ACTIONHUB_URL/actions/my_action/oauth?state=encrypted_state_url"
}

In this example, the /oauth endpoint redirects the user to the authentication server. The /oauth endpoint constructs the redirect in the oauthUrl(...) method on an OAuth action, as shown in the Dropbox OauthUrl.

The state param containing that encrypted state_url should be passed to the Looker Action Hub.

Saving State with the Action Hub Redirect URI

In the /oauth endpoint, a redirect_uri for the Action Hub is also created and passed to the action’s oauthUrl(...) method. This redirect_uri is of the form /actions/src/actions/my_maction/oauth_redirect and is the endpoint used if the authentication returns a result.

This endpoint will call the oauthFetchInfo(...) method, which should be implemented by the OauthAction method to extract the necessary information and attempt to receive or save any state or auth received from the authentication server.

The state decrypts the encrypted state_url and uses it to POST state back to Looker. The next time that a user makes a request to that action, the newly saved state will be sent to the Looker Action Hub.

Adding Your Action Files to the Looker Action Hub Repo

Once your action file is written, in the Looker Action Hub repo:

  1. Add the action file (for example, my_action.ts) to actions/src/actions/index.ts.
import “./my_action/my_action.ts”
  1. Add any Node.js package requirements that you utilized in the writing of your action. For example:
yarn add aws-sdk
yarn add express
  1. Install the Node.js dependencies of the Looker Action Hub server.
yarn install
  1. Run any tests you wrote.
yarn test

Testing an Action

For complete testing, you can try your action against your Looker instance by hosting a private action hub server. This server needs to be on the public internet with a valid SSL certificate and must be able to initiate and receive connections or HTTPS requests to and from Looker. For this, you can use a cloud-based platform, like Heroku, as shown in the following example, or you can use any platform that satisfies the aforementioned requirements.

Setting Up a Local Action Hub Server

In this example, we will take the action we developed in the looker/actions/src/actions GitHub repo and will be committing the code to a new Git branch. We recommend that you work on features using branches so that you can easily track your code and, if desired, easily create a PR with Looker.

  1. To get started, create your branch and then stage and commit your work. For example:
git checkout -b my-branch-name
git add file-names
git commit -m commit-message
  1. For this example, to push a branch to Heroku, configure your Git repo with Heroku as a remote option in your command line:
heroku login
heroku create
git push heroku
  1. Heroku will return the public URL now hosting the action hub for your use. Visit the URL or run heroku logs to confirm that the action hub is running. If you forget the public URL, you can run the following in your command line:
heroku info -s | grep web_url

Heroku will return your public URL. For example: https://my-heroku-action-server-1234.herokuapp.com

  1. In your command line, set your action hub base URL:
heroku config:set ACTION_HUB_BASE_URL="https://my-heroku-action-server-1234.herokuapp.com"
  1. Set your action hub label:
heroku config:set ACTION_HUB_LABEL="Your Action Hub"
  1. Looker uses an authorization token to connect to the action hub. Generate the token in your command line:
heroku run yarn generate-api-key

If you are not using Heroku, as we are in this example, instead use:

yarn generate-api-key

Heroku will return your authorization token. For example: Authorization: Token token="abcdefg123456789"

  1. Set your action hub secret using the secret key:
heroku config:set ACTION_HUB_SECRET="abcdefg123456789"

Customer-hosted deployments may require configuration of additional environment variables not documented here.

  1. Add your action on your local Looker instance by going to Admin > Actions.

If your action requires that specific kinds of data be passed from Looker, be sure to configure any models to include the appropriate tags parameter.

Now you’re ready to test your action!

Testing Dashboard-Level and Query-Level Actions

In your Looker instance, configure your LookML model with tags, if necessary. Create and save a Look. On the saved Look, click the upper-right menu and select Send with your action as the destination. If you have a form for delivery, Looker will render it in the Sent window.

Click Send Test to deliver the data. The status of the action will appear in the Scheduler History in the Admin panel. If your action encounters an error, it will be shown in the Admin panel and Looker will send an email with the error message to the user who sent the action.

Testing Cell-Level Actions

Set up a LookML field with the proper tags for your action. In your Looker instance, run a query that includes that field. Find the field in the data table. Click the in the cell and select Send from the drop-down menu. If you receive errors, you’ll need to do a full refresh on the data table after addressing those errors.

Publishing and Enabling an Action

There are two publication options for custom actions:

Once your action is published, you can enable it from the Actions page in the Admin panel.

Publishing to the Looker Action Hub

This is the easiest approach and is perfect for any action that you’d like to make available to anyone using Looker.

After your action has been tested, you can submit a PR to the looker/actions repo in GitHub. Enter:

git push <your fork> <your development branch>

Then create your pull request with the looker/actions repo as your target.

Looker will review your action code. Looker reserves the right to decline your PR, but can help you with any issues you have and offer suggestions for improvement. Looker then merges the code into the looker/actions repo and deploys it to actions.looker.com. Once deployed, it will become available to everyone who uses Looker.

The final step is to enable the action in your Looker instance, so that it will appear as an option for data delivery.

Publishing to a Private Action Hub Server

If you have custom actions that are private to your company or use case, you should not add your action to the looker/actions repo. Instead, you can use the same Node.js framework used to test your action to create a private action hub to serve your own custom actions.

You can set up your internal action hub server on your own infrastructure or using a cloud-based application platform (our example used Heroku). Don’t forget to fork the Looker Action Hub to your private action hub server before deployment.

Configuring Your LookML Model

You identify the relevant data fields for your action by using the tags parameter in your LookML model.

For each action, the Actions page in the Admin panel will provide information about the tags that are required for the service, if any. For example:

The Zapier integration states that it works with any query. There is no requirement to add the tags parameter to a field in your LookML model.

The Twilio Send Message service, however, sends a message to a list of phone numbers. It requires a query that includes a phone number field and uses the tags parameter to identify which field in the query contains phone numbers. You identify a phone number field in LookML by specifying tags: ["phone"] for that field. Your LookML for a phone number field might look like this:

dimension: phone { tags: ["phone"] type: string sql: ${TABLE}.phone ;; }

Be sure to identify any required fields in your LookML model with the tags parameter so that your users can use the service to send data.

Delivering Data

Your data can be delivered in several ways, depending on the level on which the action operates. Actions work on the field, query, or dashboard level and can operate on one or more levels. Each action listed on the Actions page of the Admin panel has a description of how it is used. You can:

Delivering a Cell of Data

Field-level actions are denoted on the Actions page of the Admin panel by a description that includes “Action can be used with fields” or with a Yes in the Can Use from Fields column in the list of integrated services.

Field-level actions are designed to deliver a cell of data to the specified service. They work similarly to data actions except that they are served via the Looker Action API. Instead of defining an action LookML parameter for a dimension or measure, you must configure your LookML model by tagging the relevant fields with the information provided in the Tags for This Action column in the list of integrated services.

After enabling the service and tagging fields in the LookML model, you can:

  1. View the data you want to deliver in a Look, a dashboard, or an Explore. If the service specifies “Action can be used with queries that have a field tagged…”, then your query or one of the dashboard’s tiles must include one or more fields with any required tags.

  2. The tagged field in each cell in the Look, dashboard tile, or Explore will contain a drop-down list, indicated by an ellipsis (…). Click on the ellipsis to see the actions available for that link:

  3. In the ACTIONS section, click the service that you want to receive the row data.

Delivering Dashboard or Query Data

Query-level actions are denoted on the Actions page of the Admin panel by a description that includes “Action can be used with queries that have a field tagged…” or “Action can be used with any query.” According to the Can Send or Schedule column in list of integrated services, you can deliver Every row (in a Look or an Explore). Query-level actions are designed to deliver the entire query results from an Explore or Look to the specified service.

Dashboard-level actions are denoted on the Actions page of the Admin panel by a description that includes “Action can be used with any dashboard.” According to the Can Send or Schedule column in list of integrated services, you can deliver A dashboard. Dashboard-level actions are designed to deliver a dashboard to the specified service.

Enable the service and, if necessary, tag fields in the LookML model.

To send or schedule delivery of your data:

  1. Navigate to the saved content (dashboard or Look) or create a query in an Explore.

  2. Use the gear menu to send the results immediately or schedule a data delivery.

  3. Choose the service as the destination. When starting from a Look or an Explore, the service may require tagged fields, which must be in the query results for the integration service to appear as a possible destination.

  4. A service may have destination-specific delivery options. Enter the information your service requires. The list of integrated services includes links to articles describing the destination-specific delivery options.

  5. If you are immediately sending your data, click Send. If you are scheduling a data delivery, click Save All to have your data sent according to your schedule options.

Top