Adding Actions

We've tried to make it as simple as possible to add a new action to Looker's official Action Hub.

The service is a Node.js server written in TypeScript.

If you're not familiar with TypeScript it is a small layer on top of modern JavaScript that adds type information to help catch programming errors faster. If you're familiar with JavaScript, most of the language should be familiar to you.

The project is written with the most current JavaScript style and features (currently ES2015) to help improve code clarity and expressiveness.

Requirements

To get started contributing a service you'll need to install:

• Node.js

  The project is set up to use nvm to select the proper Node.js version. You can also use nodenv with the package-json-engine plugin.

• Yarn

Be sure to review the official Action Hub docs before diving in to the details here.

Overview

Currently there are three "levels" to which an action can apply in Looker – cell, query, and dashboard. These values correspond to the supported_action_types of an action. For example, the Segment action is query level, which means it will be available from the Send and Schedule menus. (In the future there may be other ways to operate on a query in Looker, but the idea is that the action shouldn't need to do anything differently to support that). The Twilio Message action is a cell level action so it appears via the "..." menu append to each cell's data in the result table. Cell level actions are essentially the same as the existing LookML "data action", but provided via the action API. These actions need to specify tag information in their requiredFields property, and the relevant fields need to be tagged via the LookML tags parameter. The SendGrid action is a dashboard level action. These actions support receiving an full dashboard image. An action can support multiple types if needed.

When actions are enabled in the Looker instance they can be given global config values indicated by the params property in the action definition. This is useful for settings like client_id or bucket name. The settings can also be bound to a particular user attribute, which will dynamically substitute the value of that attribute at runtime. This is useful for providing settings at the group or individual user level, without exposing the values to end users.

A design requirement for our action server is to be completely stateless, so storing any information in the action application is not allowed. Any information needed to fulfill the action must be provided along with the action payload. Params allow us to accomplish this by keeping all state and credentials in Looker.

Regarding the format of the data payload, the ActionRequest class defines all data that will be available for the action to work with (it also supplies sevel helper functions). For query type actions, the request will contain an attachment that can be in many formats. The action can specify particular supportedFormats (including just a single one) and work with that data how it pleases. The most verbose one is the json_detail format, which contains copious metadata typically used by the Looker frontend (example here). But, you can also pick CSV or Excel or let the user decide the format.

For complete testing, you'll probably want to try your action in a real Looker instance. You can do this by visiting /admin/actions?edit=true in your instance, then scrolling to the buttom and pressing the "Add Action Hub" button. Input the URL and Authorization token (ACTION_HUB_SECRET) of your development server. This server will need to be accessible from the Looker host and use a valid SSL certificate, so deploying to a service like Heroku can help keep things simple.

Running an Action Hub service locally:

Clone this repo and install dependencies. If you are familiar with GitHub, you may wish to create your own fork of the repo first, and do your development in a new branch.

git clone git@github.com:looker/actions.git
git checkout -b my_new_branch
yarn install

Create a config file based on the provided example. You can change the values as needed but the defaults are sufficient for development.

cp .env.example .env 

Start the service. This uses nodemon which automatically restarts the server when you make code changes.

yarn dev

If all goes well you will see a message saying the Action Hub is listening. You can confirm this by visiting the base_url:port in your web browser to see a status page.

Add a new action:

1. Write a new action in src/actions/my_actions_group/my_action.ts.

   We recommend using the existing code as a guide. Many common use cases already have examples in the repository. The Action API docs are also a useful reference.

2. If your action code uses dependencies from npm not yet included in the project (such as API client SDKs), add those to the package.json with:

   yarn add my-action-dependency

3. Add an icon to src/actions/my_actions_group/my_action.svg

4. Add the action to src/actions/index.ts

   import "./my_actions_group/my_action.ts"

5. Add a test to src/actions/my_actions_group/test_my_action.ts

6. Add the test to test/actions/test.ts

   import "../src/actions/my_actions_group/my_action"

7. Add a README.md to src/actions/my_actions_group explaining the purpose and means for authentication. Screenshots can be helpful.

8. Run tests with yarn test

As discussed above, you can attach your custom Action Hub server to a Looker instance in order to fully test the new action in the Looker UI. Note however that Looker requires a trusted HTTPS connection to Action Hub. You can temporarily modify the framework server code to implement this (advanced), or set up a reverse proxy such as nginx or ssl-proxy, or deploy to a service like Heroku or your own corporate infrastructure.

Submit a PR

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

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.

More information about publishing actions or deploying a private Action Hub for production use is available here: https://docs.looker.com/sharing-and-publishing/action-hub

Please don't hesitate to reach out to Looker Support or your Success team contacts with questions about action development.