User Guide Getting Started Help Center Documentation Community Training
Looker
  
English
Français
Deutsch
日本語
Sharing Data Through an Action Hub

In addition to delivering content to Looker’s built-in destinations, you can use actions to deliver content to third-party services integrated with Looker via an action hub server. The graphic below illustrates your available workflow options to integrate actions through either a privately hosted action hub or the Looker-hosted Action Hub.

This page will walk you through your options for building custom actions that you can request to add to the Looker Action Hub or to your own private action hub server.

The Looker Action Hub

Looker hosts and provides a stateless server called 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.

Users of customer-hosted instances may experience hanging queries when sending or scheduling data to destinations that support streamed results (see this Help Center article under “Streaming”) if the customer-hosted executable JAR file from Looker is not able to communicate with Looker’s Action Hub. One solution to address this potential issue is to deploy a customer-hosted action hub. Another solution is to ensure that the JAR file is hosted in a public server so that Looker’s Action Hub can communicate with it.

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. Here is 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.

When writing your action, 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 and label in string format for each parameter. 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", "wysiwyg_png". string
supportedFormattings No A list of formatting options the action supports. Valid values are: "formatted" or "unformatted". string
supportedVisualizationFormattings No A list of visualization formatting options the action supports. Valid values are: "apply" or "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 or not the action will be sent a one-time-use download URL to facilitate unlimited streaming of data. Boolean
usesOAuth No A Boolean that determines whether the action is an OAuth action or not. This will determine whether or not 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. Boolean

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.

Action Parameters

To pass information about Looker users to the action, you should specify a param in the action definition. When setting up the action in Looker, your Looker admin can choose to either type a value for the parameter or bind the value of the parameter to a particular user attribute, which can be configured to provide whatever information you like on a per-user (or group) level.

These parameters are different from the action parameter, which can be defined for dimensions or measures.

RequiredField Parameters

You can configure your model’s LookML fields to deliver data via an action by specifying which tags your action supports in the RequiredFields parameter of your action file.

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

You can configure your action so that users can authenticate into the action with their Google accounts. 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- and Query-Level Actions

In your Looker instance, 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:

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 in your LookML model by using the tags parameter.

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:

measure: 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 type of integration:

Delivering Row Data

If the integration’s entry specifies that it “Works with any field” or it “Works with fields tagged with…” then it is designed to deliver a row of data to that service. After enabling the service (and tagging fields in the LookML model, if necessary), you and your users can:

  1. View the data you want in a Look, dashboard, or Explore. If the service specifies that it “Works with fields tagged with…” 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 row 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 a Dashboard or Query Data

If the integration’s entry specifies that it “Works with any dashboard” then it is designed to deliver a dashboard to that service. Enable the service and, if necessary, tag fields in the LookML model. Then you and your users can schedule or send dashboards using that service.

If the integration’s entry specifies that it “Works with any query” or it “Works with queries tagged with…” then it is designed to deliver the entire query results from an Explore or Look to that service. Enabling the service and, if necessary, tag fields in the LookML model. Then users can schedule or send the query results of a Look or an Explore.

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 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. Here is an example for sending data to the Slack service:

    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