Skip to content

Latest commit

 

History

History
65 lines (36 loc) · 5.34 KB

adding_actions.md

File metadata and controls

65 lines (36 loc) · 5.34 KB
Raw

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's 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.

  • Yarn

When you've got those installed on your machine, run yarn install to install all the dependencies.

Developing a new Action

Currently there are three places (types) of actions – query, cell and dashboard level. The Segment action is query level, which means it will attach to the scheduler. In the future, these will be able to attach to queries in Looker in other ways, but the action shouldn't need to do anything differently to support that. The Twilio Message action is a cell level action and appears in Looker by adding a "..." to the end of each cell's data in the result table. Cell level actions are essentially the same as our existing "data actions", but provided via the action API. These actions will need to specify tag information in requiredFields and the relevant fields need to be tagged in some way via the LookML tags parameter. The SendGrid action is a dashboard level action. These actions support receiving an full dashboard image. An action can also choose to hook into multiple types of actions if need be.

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, the Looker administrator 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.

A design requirement for our action server is being 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 (optionally fulfilled by user attributes) should let us do pretty much whatever we need while keeping all the state and credentials in Looker.

Regarding the format of the data payload, the ActionRequest class defines everything that's available for the action to work with. 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 useful one, which the Segment action uses, is the json_detail format, which has a lot of interesting metadata (example here). But remember, 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 against a real Looker instance. For this phase, the way to do that is to go to the Looker instance route /admin/actions?edit=true and add a new "action Hub" URL representing your development server. (This server will need to be on the public internet with a valid SSL certificate, so deploying to Heroku is the easiest choice since you get that out of the box there.)

Running a action service:

Clone and run the action service locally

git clone [email protected]:looker/actions.git
cd actions
yarn install
yarn dev

Add a new action:

Add any dependencies

yarn add my-action-sdk

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

  2. Add an icon to src/actions/my_action/my_action.svg

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

    import "./my_action/my_action.ts"

  4. Add a test to src/actions/my_action/test_my_action.ts

  5. Add a test to test/actions/test.ts

    import "./actions/test_my_action"

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

  7. To run tests yarn test

You can get a development server running with yarn dev per the instructions below.