NOTE: This article covers an advanced use case that assumes strong familiarity with Looker's API.

The Problem

What if we need a programmatic way to create Looker user accounts and set their default values — roles, access_filters, home default folder (or Spaces, as they were named in releases earlier than Looker 6.20), and so on? This Help Center article addresses this use case with an example API script that can be used to customize and automate the user creation process. The script can also output an account setup URL so a custom email can be sent to the new users.

NOTE: Custom welcome emails can also be created via Looker's UI.

The Solution

The example script below is written with Ruby and uses Looker's SDK gem. This demo is meant to serve as an example of how you can work with Looker's API to establish more automated workflows. To use the script, you will need to customize it for and integrate it into your system. Many of the values will need to be parameterized to work with the different clients your users are using to sign up for Looker accounts.

# CONFIG SETUP #############################################################################
#
# 1) Create a file in the same directory as this script called 'config.yml'
# 2) Fill it with these properties and set the appropriate values
# 3) Don't copy the '#' comment character
#
# client_id: your-api-client-id
# client_secret: your-api-secret
# protocol: https
# host: https://.looker.com:19999  # Update the port and path as necessary


# EXAMPLE INPUTS ###########################################################################

user_email = "person@company.com"
user_role  = "Role Name"

############################################################################################

# Bundler was used for this example script - update as needed
require 'bundler'
Bundler.setup
require 'looker-sdk'
require 'yaml'
require 'ostruct'

# Load a config file that contains API credentials (was just for this example)
app_root = File.expand_path(File.dirname(__FILE__))
Config = OpenStruct.new(YAML.load_file(File.join(app_root, 'config.yml')))

# Set up the connection to Looker
sdk = LookerSDK::Client.new(
        :client_id     => Config.client_id,
        :client_secret => Config.client_secret,
        :api_endpoint  => "#{Config.protocol}://#{Config.host}:19999/api/3.0"
        )

# Fetch all roles and associate the name to an id
roles_by_name = Hash[ sdk.all_roles.map{|role| [role.name, role.id] } ]

# Fail if we can't find a role matching the input name
unless role_id = roles_by_name[user_role]
    raise "#{user_role} does not exist - aborting."
end

begin
    # Create a new user
    user = sdk.create_user()

    # Give it an email+password style credential object (versus LDAP, SAML, etc)
    sdk.create_user_credentials_email(user.id, {:email => user_email})

    # Assign roles to user
    sdk.set_user_roles(user.id, [role_id])

    # Generate a password reset token for the user
    # Set expires=false when using as a setup token
    creds = sdk.create_user_credentials_email_password_reset(user.id, {}, {expires: false})

    # Assign access filters as needed
    sdk.create_user_access_filter(user.id, {model: 'model_name', field: 'view.dimension', value: 'Filter Value'})

    # Set the user home space - use 'lookml' for the special lookml dashboards space
    # Note the value is _always_ sent as a string even if using a space id like '42'
    sdk.update_user(user.id, {home_space_id: 'lookml'})

rescue LookerSDK::Error => e
    # if any errors occur above then 'undo' by deleting the given user (if we got that far)
    sdk.delete_user(user.id) if user
    puts "FAILED to create user: (#{e.message}) "
end

# Extract the reset token from the password reset url
# The API does not yet provide this as its own field
reset_token = creds.password_reset_url.split('/').last

# Construct the full account setup URL from the token extracted above
setup_url = "#{Config.protocol}://#{Config.host}/account/setup/#{reset_token}"

# This is where you would then send an email to the user
# None of the Looker API endpoints will try to send email
puts setup_url

For more examples of Looker SDKs in multiple languages, including Ruby, check out the Looker Open Source SDK Examples repository.

Articles in this section

Creating Users and Sending Custom Welcome Emails via API

The Problem

The Solution