Introduction

Welcome to the Luzmo API! You can use our API to integrate dashboards within your own applications, create or update datasets, open up new data sources or automate just about anything about your Luzmo experience.

We offer 3 main APIs that are documented in detail:

Core API: build datasets & dashboards, manage users & groups, send event data to Luzmo
Embedding: libraries to seamlessly integrate dashboards within your own applications and exposed methods & events that can be used in your application
Plugin API: connect your own data stores or APIs with a flexible data adapter

You can start reading our guides that cover common use cases or dive right into the API specifications or Component API specifications for further detail.

In case of questions, you can reach our team at api@luzmo.com or support@luzmo.com.

Good luck, and have fun!

Guides

Dashboard embedding

Embedding a dashboard in your own application/platform is a simple process.

Set up an Integration in Luzmo

Create an Integration
Associate dashboards with Integration
Associate datasets with Integration

Embed into your application

Generate a SSO authorization token (server-side)
Embed the dashboard in your own application/platform (client-side)

Set up an Integration

The first step to embed dashboards in your application is setting up an Integration. This can be easily created and maintained from within our application as well as through our API!

Create an Integration

   Creating an Integration via API (replace with your API key & token)

JSONObject integration = client.create("integration",

  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "< Integration name in English ›",
      "fr" , "< Integration name in French >"
    )
  ));
System.out.println("Success! %s%n", integration);

   Creating an Integration via API (replace with your API key & token)

dynamic properties = new ExpandoObject();
properties.name = new {
      en = "< Integration name in English ›",
      fr = "< Integration name in French >"
    };

dynamic integration = client.create("integration",    properties);
Console.WriteLine("Success!", integration);

   Creating an Integration via API (replace with your API key & token)

client.create("integration",
  {
    name: {
        en: "< Integration name in English ›",
        fr: "< Integration name in French >"
    }
}

)
  .then(function(integration) {
    console.log("Success!", integration);
  });

   Creating an Integration via API (replace with your API key & token)

<?php
$integration = $client->create("integration",

  array (
    "name" => array (
      "en" => "< Integration name in English ›",
      "fr" => "< Integration name in French >"
    )
  )

);
print("Success! { $integration }");
?>

   Creating an Integration via API (replace with your API key & token)

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": {
    "en": "< Integration name in English ›",
    "fr": "< Integration name in French >"
  }
}
}
EOF

   Creating an Integration via API (replace with your API key & token)

integration = client.create("integration",
  {
    "name": {
        "en": "< Integration name in English ›",
        "fr": "< Integration name in French >"
    }
  }
)

If you're an Organization owner, you can login to Luzmo and on top of the page you will find the Integrations tab. From there you can start the process of creating an Integration by clicking on the New Integration button.

Associate dashboards

   Link an Integration to a dashboard in order to make that dashboard readable by SSO tokens with access to the integration

client.associate("integration", "< your Integration id >", "Securables", "< your dashboard id >",
  ImmutableMap.of(
    "flagRead" , true,
    "slug", "< lowercase alphanumeric slug name >"
  ) );

   Link an Integration to a dashboard in order to make that dashboard readable by SSO tokens with access to the integration

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.slug = "< lowercase alphanumeric slug name >";

client.associate("integration", "< your Integration id >", "Securables", "< your dashboard id >",     properties );

   Link an Integration to a dashboard in order to make that dashboard readable by SSO tokens with access to the integration

let promise = client.associate("integration", "< your Integration id >", {
    role: "Securables",
    id: "< your dashboard id >"
},
{
    flagRead: true,
    slug: "< lowercase alphanumeric slug name >"
});

   Link an Integration to a dashboard in order to make that dashboard readable by SSO tokens with access to the integration

<?php
$client->associate("integration", "< your Integration id >", "Securables", "< your dashboard id >", ,
  array (
    "flagRead" => true,
    "slug => "< lowercase alphanumeric slug name >"
  ) );
?>

   Link an Integration to a dashboard in order to make that dashboard readable by SSO tokens with access to the integration

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "< your Integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dashboard id >"
  },
  "properties": {
    "flagRead": true,
    "slug": "< lowercase alphanumeric slug name >"
  }
}
EOF

   Link an Integration to a dashboard in order to make that dashboard readable by SSO tokens with access to the integration

client.associate("integration", "< your Integration id >", {
    "role": "Securables",
    "id": "< your dashboard id >"
},
{
    "flagRead": true,
    "slug": "< lowercase alphanumeric slug name >"
});

After starting the creation of the Integration, you can select dashboards that should be associated with the Integration together with their access rights. In order to start associating dashboards with an Integration, you already need to be an owner of the dashboard and the Integration. That means that you either created the dashboard or received access from someone that gave you owner access. That way it is possible to set multiple owners for a dashboard.

The association has flag properties to define what kind of access the Integration will receive. If no flag properties are specified the Integration will receive "view" access by default. The available flags are:

'Can view' (or 'flagRead') - gives the SSO user the right to only view the dashboard.
'Can use' (or 'flagUse') - next to viewing a dashboard, the SSO user is able to create a variant of the dashboard, or duplicate it (only in editMode “editFull”).
'Can edit' (or 'flagModify') - besides viewing and duplicating the dashboard, the SSO user can edit the dashboard itself.

Warning! If you give 'can use' or 'can edit' rights on a dashboard, you must ensure that all multi-tenant (parameter) filters are defined on the dataset level (i.e. when associating the dataset(s) with the Integration/Suborganization/Group/User) and not on the dashboard level. Designer users are able to modify the dashboard content (either in a variant, in a duplicate or in the dashboard itself) and thus remove these (parameter) filters!

Next to the flag properties, you can also specify a unique slug that can be used to target the specific dashboard in your frontend (see Step 2: Embed the dashboard). This is particularly useful if you'd like to replace an embedded dashboard in your application without having to change anything in your application's code!
The gif below shows how you can replace a dashboard for a certain slug in our UI.

Associate datasets

   Link an Integration to a dataset in order to make that complete dataset readable by SSO tokens granted access to the integration

client.associate("integration", "< your Integration id >", "Securables", "< your dataset id >",
  ImmutableMap.of(
    "flagRead" , true
  ));

   Link an Integration to a dataset in order to make that complete dataset readable by SSO tokens granted access to the integration

dynamic properties = new ExpandoObject();
properties.flagRead = true;

client.associate("integration", "< your Integration id >", "Securables", "< your dataset id >",     properties );

   Link an Integration to a dataset in order to make that complete dataset readable by SSO tokens granted access to the integration

let promise = client.associate("integration", "< your Integration id >", {
    role: "Securables",
    id: "< your dataset id >"
},
{
    flagRead: true
});

   Link an Integration to a dataset in order to make that complete dataset readable by SSO tokens granted access to the integration

<?php
$client->associate("integration", "< your Integration id >", "Securables", "< your dataset id >", ,
  array (
    "flagRead" => true
  ));
?>

   Link an Integration to a dataset in order to make that complete dataset readable by SSO tokens granted access to the integration

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your Integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dataset id >"
  },
  "properties": {
    "flagRead": true
  }
}
EOF

   Link an Integration to a dataset in order to make that complete dataset readable by SSO tokens granted access to the integration

client.associate("integration", "< your Integration id >", {
    "role": "Securables",
    "id": "< your dataset id >"
},
{
    flagRead: true
});

   Link an Integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

client.associate("integration", "<your Integration id >", "Securables", "< your dataset id >",
  ImmutableMap.of(
    "flagRead", true,
    "filters", ImmutableList.of(
      ImmutableMap.of(
        "clause", "where",
        "origin", "global",
        "securable_id", "< dataset id >",
        "column_id", "< column id of a column in the dataset >",
        "expression", "? in ?",
        "value", ImmutableMap.of(
          parameter: "metadata.< parameter name >",
          type: "array[hierarchy]",
          value: ImmutableList.of(
            "< default parameter value >"
          )
        )
      )
    )
  )
);

   Link an Integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

dynamic properties = new ExpandoObject();
properties.flagRead = true;

properties.filters = new List<dynamic> {
  new {  
    clause = "where";
    origin = "global";
    securable_id = "< dataset id >";
    column_id = "< column id of a column in the dataset >";
    expression = "? in ?";
    value = new {
      parameter: "metadata.< parameter name >",
      type: "array[hierarchy]",
      value: new List<String> {
        "< default parameter value >"
      }
    };
  }
};

client.associate("integration", "< your Integration id >", "Securables", "< your dataset id >",   properties );

   Link an Integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

let promise = client.associate("integration", "< your Integration id >", {
  role: "Securables",
  id: "< your dataset id >"
},
{
  flagRead: true,
  filters: [
    {
      clause: "where",
      origin: "global",
      securable_id: "< dataset id >",
      column_id: "< column id of a column used in the dataset >",  
      expression: "? in ?",
      value: {
        parameter: "metadata.< parameter name >",
        type: "array[hierarchy]",
        value: ["< default parameter value >"]
      }
    }  
  ]
});

   Link an Integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

<?php
$client->associate("integration", "< your Integration id >", "Securables", "< your dataset id >", ,
  array (
    "flagRead" => true,
    "filters" => array(
      array(
        "clause"       => "where",
        "origin"       => "global",
        "securable_id" => "< dataset id >",
        "column_id"    => "< column id of a column used in the dataset >",
        "expression"   => "? in ?",
        "value"        => array(
          "parameter" => "metadata.< parameter name >",
          "type" => "array[hierarchy]",
          "value" => array("< default parameter value >")
        )
      )
    )
  ) );
?>

   Link an Integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "< your Integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dataset id >"
  },
  "properties": {
    "flagRead": true,
    "filters": [
        {
          "clause": "where",
          "origin": "global",
          "securable_id": "< dataset id >",
          "column_id": "< column id of a column used in the dataset >",  
          "expression": "? in ?",
          "value": {
            "parameter": "metadata.< parameter name >",
            "type": "array[hierarchy]",
            "value": ["< default parameter value >"]
          }
        }
      ]
  }
}
EOF

   Link an Integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

client.associate("integration", "< your Integration id >", {
  "role": "Securables",
  "id": "< your dataset id >"
},
{
  "flagRead": true,
  "filters": [
    {
      "clause": "where",
      "origin": "global",
      "securable_id": "< dataset id >",
      "column_id": "< column id of a column used in the dataset >",  
      "expression": "? in ?",
      "value": {
        "parameter": "metadata.< parameter name >",
        "type": "array[hierarchy]",
        "value": ["< default parameter value >"]
      }
    }  
  ]
});

   Link an Integration to a dataset, give it read rights and apply a static filter for e.g. row-level security.

client.associate("integration", "< your Integration id >", "Securables", "< your dataset id >",
  ImmutableMap.of(
    "flagRead", true,
    "filters", ImmutableList.of(
      ImmutableMap.of(
        "clause", "where",
        "origin", "global",
        "securable_id", "< dataset id >",
        "column_id", "< column id of a column in the dataset >",
        "expression", "? = ?",
        "value", "< value to be applied to the expression >"
      )
    )
  )
);

   Link an Integration to a dataset, give it read rights and apply a static filter for e.g. row-level security.

dynamic properties = new ExpandoObject();
properties.flagRead = true;

properties.filters = new List<dynamic> {
  new {  
    clause = "where";
    origin = "global";
    securable_id = "< dataset id >";
    column_id = "< column id of a column in the dataset >";
    expression = "? = ?";
    value = "< value to be applied to the expression >";
  }
};

client.associate("integration", "< your Integration id >", "Securables", "< your dataset id >",   properties );

   Link an Integration to a dataset, give it read rights and apply a static filter for e.g. row-level security.

let promise = client.associate("integration", "< your Integration id >", {
  role: "Securables",
  id: "< your dataset id >"
},
{
  flagRead: true,
  filters: [
    {
      clause: "where",
      origin: "global",
      securable_id: "< dataset id >",
      column_id: "< column id of a column used in the dataset >",  
      expression: "? = ?",
      value: "< value to be applied to the expression >"
    }  
  ]
});

   Link an Integration to a dataset, give it read rights and apply a static filter for e.g. row-level security.

<?php
$client->associate("integration", "< your Integration id >", "Securables", "< your dataset id >", ,
  array (
    "flagRead" => true,
    "filters" => array(
      "clause"       => "where",
      "origin"       => "global",
      "securable_id" => "< dataset id >",
      "column_id"    => "< column id of a column used in the dataset >",
      "expression"   => "? = ?",
      "value"        => "< value to be applied to the expression >"
    )
  ) );
?>

   Link an Integration to a dataset, give it read rights and apply a static filter for e.g. row-level security.

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your Integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dataset id >"
  },
  "properties": {
    "flagRead": true,
    "filters": [
        {
          "clause": "where",
          "origin": "global",
          "securable_id": "< dataset id >",
          "column_id": "< column id of a column used in the dataset >",  
          "expression": "? = ?",
          "value": "< value to be applied to the expression >"
        }
      ]
  }
}
EOF

   Link an Integration to a dataset, give it read rights and apply a static filter for e.g. row-level security.

let promise = client.associate("integration", "< your Integration id >", {
  "role": "Securables",
    "id": "< your dataset id >"
  },
  {
    "flagRead": true,
    "filters": [
        {
          "clause": "where",
          "origin": "global",
          "securable_id": "< dataset id >",
          "column_id": "< column id of a column used in the dataset >",  
          "expression": "? = ?",
          "value": "< value to be applied to the expression >"
        }
      ]
  }
});

When associating a dataset with an Integration you can specify some flag properties to define what kind of access the Integration will receive. If no flag properties are specified the Integration will receive viewing access by default. The available flags are:

'Can view' (or 'flagRead') - users are only allowed to query the dataset in existing dashboard(s) that are accessible to them (i.e. the user is not able to use this dataset when creating/editing a dashboard).
'Can use' (or 'flagUse') - the user is also able to use this dataset when creating or editing a dashboard.
'Can edit' (or 'flagModify') - the user is able to use this dataset when creating or editing a dashboard, and is able to edit the dataset itself (e.g. change column names, create or alter hierarchies, create or alter derived columns, etc.)

Important! For security reasons it’s of uttermost importance that multi-tenant (parameter) filters are specified on the dataset level, this ensures that they are always applied when the user queries the dataset directly or via a (new) dashboard. Parameterizable filters can be used to dynamically apply these filters by overriding the parameter value(s) when requesting a SSO token for your user. Instead of using parameterizable filters, you could also specify static filters when associating a dataset with an Integration or when requesting SSO authorization tokens.

As shown in the gif below, you can additionally specify filters when defining the dataset-Integration association. In case you want to dynamically filter a dataset based on the user logged in in your application, parameter filters are the easiest way of setting this up!

Embed into your application

1. Generate a SSO token

   Replace with your API key & token and integration_id and fill in the user's details

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer"
  }
}
EOF

   Replace with your API key & token and integration_id and fill in the user's details

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: "< Your API key >",
    api_token: "< Your API token >",
    host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >"
});

let promise = client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer"
});

promise.then(function(result){
  // return the result to the client
})

   Replace with your API key & token and integration_id and fill in the user's details

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");


$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your user >",
  "name" => "< user name >",
  "email" => "< user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "viewer"
));
?>

   Replace with your API key & token and integration_id and fill in the user's details

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your user >")
  .put("name", "< user name >")
  .put("email", "< user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .build()
);

   Replace with your API key & token and integration_id and fill in the user's details

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your user >";
properties.name = "< user name >";
properties.email = "< user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   Replace with your API key & token and integration_id and fill in the user's details

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer"
});

   This returns a JSON object with an id/token combination that we will use to embed:

{
  "type": "sso",
  "id": "< the SSO authorization key >",
  "token": "< the SSO authorization token >",
  "user_id": "< a uuid used on our end to identify the SSO user >"
  // ...
}

In this step, your server-side code makes an API request to retrieve an authorization token of type SSO. The result of this request is a key/token combination that will be used to in step 2 to securely embed the dashboard in your application/platform.

The API request is a 'create' request for an authorization. In this API call we use the Integration id that we created before (see Set up an Integration).

Property	Description
type string REQUIRED	`sso` Use the value 'sso' for embedding a dashboard.
expiry date (RFC 3339) or string REQUIRED	Date/time when this authorization will cease working. To promote better security practices this property is required and enforced with a maximum expiry date of 1 year. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
inactivity_interval integer or string	Duration of inactivity after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). If specified, a minimum value of 2 minutes is enforced to avoid undesired invalidation of a token due to e.g. missing a heartbeat signal sent by our server. Defaults to 0 (i.e. no inactivity_interval).
username string REQUIRED	Identifies the user uniquely and immutably. This should correspond to eg. the primary key for the user on your end. If it changes, the user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform! This will also be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization.
name string REQUIRED	The full name of the user (i.e. First name and Last name). This will be used in our UI.
email string REQUIRED	The email address of the user. This will be used in our UI.
suborganization string REQUIRED	Each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username.
integration_id uuid REQUIRED	The UUID of the integration that the SSO token should have access to.
role string REQUIRED	The role of the user for who you are making the authorization request. More information on the different roles: "viewer" SSO users that should only be able to view and interact with one or more dashboards, variants, and duplicates. "designer" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates. "owner" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates, and next to that they should be able to favorite dashboard variants for other SSO users within their suborganization. More info under Embedded Dashboard Editor.

For a list of all properties that you can use in the request, check Authorization in the Core API.

The request returns a JSON object that contains an authorization id & token. This is the key/token combination that will be used in our next step (client-side) to embed the dashboard in a secure way.

2. Embed the dashboard

1 Install the web component via npm package manager by running the following command in your command line interface. It's recommended to use npm to ensure you can easily get the latest version of our component when available!

npm i @luzmo/embed

 If you're not able to use npm, you can import the minified javascript file in any HTML file using the following code.

<!--
You can (programmatically) retrieve the latest version via this link:
https://cdn.luzmo.com/js/luzmo-embed/latest-version.json
-->
<script
  defer
  src="https://cdn.luzmo.com/js/luzmo-embed/<WEB_COMPONENT_VERSION>/luzmo-embed.min.js"
  charset="utf-8"
></script>

2 Import the component in a JavaScript module.

import '@luzmo/embed';

 You can also import the component in an HTML page.

<script type="module">
  import './node_modules/@luzmo/embed/index.js';
</script>
<!-- OR -->
<script
  type="module"
  src="./node_modules/@luzmo/embed/index.js">
</script>

3 Add the Luzmo component to your HTML page.

<!--
Clients on our US multi-tenant application environment,
or a dedicated instance on a specific VPC, should specify:
- appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
- apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
-->
<luzmo-dashboard
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< SSO authorization key >"
  authToken="< SSO authorization token >"
  dashboardId="< dashboard id you want to embed >"
  dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
></luzmo-dashboard>

1 Install the Angular component via npm package manager by running the following command in your command line interface.

npm i @luzmo/ngx-embed

2 Import the NgxLuzmoDashboardModule in your NgModule

import {
  NgxLuzmoDashboardModule
} from '@luzmo/ngx-embed';

@NgModule({
  ...
  imports: [
    ...,
    NgxLuzmoDashboardModule,
    ...
  ],
  ...
})

3 Add the Luzmo component in your Angular page

/*
Clients on our US multi-tenant application environment,
or a dedicated instance on a specific VPC, should specify:
- [appServer]="'https://app.us.luzmo.com/'" (or your VPC-specific address)
- [apiHost]="'https://api.us.luzmo.com/'" (or your VPC-specific address)
*/
<luzmo-dashboard
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
  [authKey]="'< SSO authorization key >'"
  [authToken]="'< SSO authorization token >'"
  [dashboardId]="'< dashboard id you want to embed >'"
  [dashboardSlug]="'< instead of dashboardId: a dashboard slug as specified in the Integration. >'"
></luzmo-dashboard>

1 Install the React component via npm package manager by running the following command in your command line interface.

npm i @luzmo/react-embed

2 Minimal required parameters to securely embed a dashboard in a React application

import { LuzmoDashboardComponent } from '@luzmo/react-embed';
...

  function LuzmoWrapper() {
    ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
      ></LuzmoDashboardComponent>
    );
  }

1 Install the React Native component via npm package manager by running the following command in your command line interface.

npm i @luzmo/react-native-embed

2 Minimal required parameters to securely embed a dashboard in a React Native application

import LuzmoDashboardComponent from '@luzmo/react-native-embed';
...

  function LuzmoWrapper() {
    ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        ref={ref}
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
      ></LuzmoDashboardComponent>
    );
  }

1 Install the Vue component via npm package manager by running the following command in your command line interface.

npm i @luzmo/vue-embed

2 Minimal required parameters to securely embed a dashboard in a Vue 3 application

import { createApp } from 'vue';
import App from './App.vue';
import VueLuzmoDashboard from '@luzmo/vue-embed';
...

const app = createApp(App);
...

// Defines the component at app level
app.use(VueLuzmoDashboard);
...

app.mount('#app');

 You can also use our Vue component in your Vue 2 application

import Vue from 'vue';
import App from './App.vue';
import VueLuzmoDashboard from '@luzmo/vue-embed/vue2';
...

Vue.use(VueLuzmoDashboard);
...

new Vue({
  render: (h) => h(App),
}).$mount('#app');

3 In your HTML template of your Vue application

<template>
  ...
  <!--
  Clients on our US multi-tenant application environment,
  or a dedicated instance on a specific VPC, should specify:
  - :appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
  - :apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
   -->
  <luzmo-dashboard
    ref="dashboardInstance"
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< SSO authorization key >"
    authToken="< SSO authorization token >"
    dashboardId="< dashboard id you want to embed >"
    dashboardSlug="< instead of dashboardId: a dashboard slug as specified in the Integration. >"
  ></luzmo-dashboard>
</template>

To embed a dashboard in your webpage, we use the Embed Libraries.

First you should install the appropriate component library in your frontend. We have a Web component, React component, React Native component, Angular component and Vue.js component which are available via npm package manager.

In this step we'll use the SSO key and token from step 1 to securely embed a dashboard in your frontend by referencing it with its id or slug.

You can optionally retrieve a list of accessible dashboards (associated with the integration that the SSO token has access to) to dynamically provide them to your users in e.g. a sidebar in your application's frontend.

Parameter	Description
appServer string	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost string	Tenancy of Luzmo API to connect to. Defaults to 'https://api.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://api.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey uuid	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken string	The authorization token from the response of the authorization request in your backend.
dashboardId uuid	This is the id of the dashboard that you want to embed. Specify either the dashboardId or dashboardSlug property.
dashboardSlug string	Instead of specifying a dashboardId, you can alternatively specify a dashboard slug. The slug is defined when associating a dashboard with an Integration. Specify either the dashboardId or dashboardSlug property.

There are additional properties that can be specified to e.g. choose which screenmode or language will be loaded and/or to style the dashboard loader. This to ensure a perfect fit with the style of your page. Check the Embedding chapter for all documentation related to our frontend components.

That's it, with these steps you securely embed a dashboard in your application/platform!

Handling multi-tenant data

Depending on your current data setup and use case, it might be necessary to dynamically:

apply row-level filtering in case you have one dataset with multi-tenant data Add a Parameter filter
point towards a different data source in case you have one dataset per tenant Specify Connection Overrides (account_overrides)

No worries if you're specific data setup is not covered by these options, we are sure we are able to support it via e.g. a plugin.
Don't hesitate to reach out to support@luzmo.com if you'd like to have some assistance on this topic!

Add a Parameter filter

You can add Parameters to your authorization requests to dynamically filter the data in your embedded dashboards.

First you need to create and define the Parameter, after which you can override the Parameter to a value of your choice when creating the authorization request.

1. Define and set a Parameter

This can be achieved when associating a dataset with an integration or when building a dashboard in our dashboard editor.

When associating a dataset with an integration

   Link an integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

client.associate("integration", "<your integration id >", "Securables", "< your dataset id >",
  ImmutableMap.of(
    "flagRead", true,
    "filters", ImmutableList.of(
      ImmutableMap.of(
        "clause", "where",
        "origin", "global",
        "securable_id", "< dataset id >",
        "column_id", "< column id of a column in the dataset >",
        "expression", "? in ?",
        "value", ImmutableMap.of(
          parameter: "metadata.< parameter name >",
          type: "array[hierarchy]",
          value: ImmutableList.of(
            "< default parameter value >"
          )
        )
      )
    )
  )
);

   Link an integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

dynamic properties = new ExpandoObject();
properties.flagRead = true;

properties.filters = new List<dynamic> {
  new {  
    clause = "where";
    origin = "global";
    securable_id = "< dataset id >";
    column_id = "< column id of a column in the dataset >";
    expression = "? in ?";
    value = new {
      parameter: "metadata.< parameter name >",
      type: "array[hierarchy]",
      value: new List<String> {
        "< default parameter value >"
      }
    };
  }
};

client.associate("integration", "< your integration id >", "Securables", "< your dataset id >",   properties );

   Link an integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

let promise = client.associate("integration", "< your integration id >", {
  role: "Securables",
  id: "< your dataset id >"
},
{
  flagRead: true,
  filters: [
    {
      clause: "where",
      origin: "global",
      securable_id: "< dataset id >",
      column_id: "< column id of a column used in the dataset >",  
      expression: "? in ?",
      value: {
        parameter: "metadata.< parameter name >",
        type: "array[hierarchy]",
        value: ["< default parameter value >"]
      }
    }  
  ]
});

   Link an integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

<?php
$client->associate("integration", "< your integration id >", "Securables", "< your dataset id >", ,
  array (
    "flagRead" => true,
    "filters" => array(
      array(
        "clause"       => "where",
        "origin"       => "global",
        "securable_id" => "< dataset id >",
        "column_id"    => "< column id of a column used in the dataset >",
        "expression"   => "? in ?",
        "value"        => array(
          "parameter" => "metadata.< parameter name >",
          "type" => "array[hierarchy]",
          "value" => array("< default parameter value >")
        )
      )
    )
  ) );
?>

   Link an integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "< your integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dataset id >"
  },
  "properties": {
    "flagRead": true,
    "filters": [
        {
          "clause": "where",
          "origin": "global",
          "securable_id": "< dataset id >",
          "column_id": "< column id of a column used in the dataset >",  
          "expression": "? in ?",
          "value": {
            "parameter": "metadata.< parameter name >",
            "type": "array[hierarchy]",
            "value": ["< default parameter value >"]
          }
        }
      ]
  }
}
EOF

   Link an integration to a dataset, give it read rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

client.associate("integration", "< your integration id >", {
  "role": "Securables",
  "id": "< your dataset id >"
},
{
  "flagRead": true,
  "filters": [
    {
      "clause": "where",
      "origin": "global",
      "securable_id": "< dataset id >",
      "column_id": "< column id of a column used in the dataset >",  
      "expression": "? in ?",
      "value": {
        "parameter": "metadata.< parameter name >",
        "type": "array[hierarchy]",
        "value": ["< default parameter value >"]
      }
    }  
  ]
});

After selecting the datasets that should be associated with the integration, you can optionally specify static & parameter filters on each dataset. Parameter filters ensure that you can dynamically fill in a parameter value in the authorization request based on the user logged in in your application!

In the dashboard editor

Instead of defining the parameter on the dashboard-integration association, you can also do this in the dashboard editor itself. This makes it easy to get a preview of how the dashboard would look like for your end user. Because the dashboard(s)/chart(s) are prefiltered they can also give a good indication of the embedded dashboard's loading performance!

You can create a parameterized filter when setting up a filter on the dashboard or widget level, and clicking on the parameter icon instead of using a static value. This will automatically create and use this parameter in the filter, as well as allowing you to also reference the same parameter in any other widget/dashboard filter. Alternatively, you can also use the "Create parameter" button to create a new parameter with a suitable type, and use it in one or more filters!

2. Override the parameter in the authorization request

   In the authorization request you should specify the parameter name together with the value to override the default value!

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "metadata": {
      "< parameter name >": ["< value to apply >"]
    }
  }
}
EOF

   In the authorization request you should specify the parameter name together with the value to override the default value!

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: "< Your API key >",
    api_token: "< Your API token >",
    host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >"
});

let promise = client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your end user >",
  name: "< end-user name >",
  email: "< end-user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  metadata: {
    "< parameter name >": ["< value to apply >"]
  }
});

promise.then(function(result){
  // return the result to the client
})

   In the authorization request you should specify the parameter name together with the value to override the default value!

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your end user >",
  "name" => "< end-user name >",
  "email" => "< end-user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "viewer",
  "metadata" => array(
    "< parameter name >" => array(
      "< value to apply >"
    )
  )
));
?>

   In the authorization request you should specify the parameter name together with the value to override the default value!

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >", "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("metadata", ImmutableMap.builder()
    .put("< parameter name >" = ImmutableList.of(
      "< value to apply >"
    ))
    .build()
  )
  .build()
);

   In the authorization request you should specify the parameter name together with the value to override the default value!

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");


dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.metadata = new{
  parameter_name = new List<String>{
    "< value to apply >"
  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   In the authorization request you should specify the parameter name together with the value to override the default value!

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "metadata": {
      "< parameter-name>": "< value to filter to >"
    }
});

Whether you've defined a default parameter filter in the dashboard editor or when associating the dataset with the integration, you want to override this parameter value in the SSO authorization request to dynamically filter the dashboard based on the end user logged in in your application. This is as easy as extending the code snippet used in step 1 by adding a metadata property to the request in which you specify the Parameter name and override its value.

Property	Description
type string REQUIRED	`sso` Use the value 'sso' for integrating a dashboard.
expiry date (RFC 3339) or string REQUIRED	Date/time when this authorization will cease working. To promote better security practices this property is required and enforced with a maximum expiry date of 1 year. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
inactivity_interval integer or string	Duration of inactivity after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). If specified, a minimum value of 2 minutes is enforced to avoid undesired invalidation of a token due to e.g. missing a heartbeat signal sent by our server. Defaults to 0 (i.e. no inactivity_interval).
username string REQUIRED	Identifies the end-user uniquely and immutably. This should correspond to eg. the primary key for the end-user on your end. If it changes, the end-user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform! This will also be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization.
name string REQUIRED	The full name of the end-user (i.e. First name and Last name). This will be used in our UI.
email string REQUIRED	The email address of the end-user. This will be used in our UI.
suborganization string REQUIRED	Each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username.
integration_id uuid REQUIRED	The UUID of the integration that the SSO token should have access to.
role string REQUIRED	The role of the user for who you are making the authorization request. More information on the different roles: "viewer" SSO users that should only be able to view and interact with one or more dashboards, variants, and duplicates. "designer" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates. "owner" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates, and next to that they should be able to favorite dashboard variants for other SSO users within their suborganization. More info under Embedded Dashboard Editor.
metadata object	Parameter name and value. The value should be a number, string or array depending on the parameter type set when creating the parameter.

Specify Connection/Account overrides

   Override the host property of your standard database connection

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "account_overrides": {
      "< Your connection id >" : {
        "host": "< The new database host to connect to. >"
      }
    }
  }
}
EOF

   Override the host property of your standard database connection

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< Your API key >",
  api_token: "< Your API token >",
  host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
});

client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your end user >",
  name: "< end-user name >",
  email: "< end-user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  account_overrides: {
    "< your connection id >": {
      host: "< The new database host to connect to. >",
    },
  },
});

   Override the host property of your standard database connection

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your end user >",
  "name" => "< end-user name >",
  "email" => "< end-user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "viewer",
  "account_overrides" => array(
    "< your connection id >" => array(
      "host" => "< The new database host to connect to. >"
    )
   )
));
?>

   Override the host property of your standard database connection

import org.json.JSONObject;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("account_overrides", ImmutableMap.builder()
    .put("< your connection id >", ImmutableMap.builder()
      .put("host", "< The new database host to connect to. >")
      .build()
    )
    .build()
  )
  .build()
);

   Override the host property of your standard database connection

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.account_overrides = new {
  "<your connection id>" = new {
    host = "< The new database host to connect to. >",

  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   Override the host property of your standard database connection

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
  "type": "sso",
  "expiry": "24 hours",
  "inactivity_interval": "10 minutes",
  "username": "< A unique and immutable identifier for your end user >",
  "name": "< end-user name >",
  "email": "< end-user email >",
  "suborganization": "< a suborganization name >",
  "integration_id": "< integration id >",
  "role": "viewer",
  "account_overrides": {
    "< your connection id >" : {
      "host": "< The new database host to connect to. >"
    }
  }
});

   Override the base_url and a custom authentication property of a plugin connection

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "account_overrides": {
      "< your connection id >" : {
        "base_url": "< The new plugin base URL to connect to. >",
        "properties": {
          "< custom authentication property ID >": "< the new custom authentication property value >"
        }
      }
    }
  }
}
EOF

   Override the base_url and a custom authentication property of a plugin connection

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< Your API key >",
  api_token: "< Your API token >",
  host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
});

client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your end user >",
  name: "< end-user name >",
  email: "< end-user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  account_overrides: {
    "< your connection id >": {
      base_url: "< The new plugin base URL to connect to. >",
      properties: {
        "< custom authentication property ID >":
          "< the new custom authentication property value >",
      },
    },
  },
});

   Override the base_url and a custom authentication property of a plugin connection

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your end user >",
  "name" => "< end-user name >",
  "email" => "< end-user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "viewer",
  "account_overrides" => array(
    "< your connection id >" => array(
      "base_url" => "< The new plugin base URL to connect to. >",
      "properties" => array(
        "< custom authentication property ID >" => "< the new custom authentication property value >"
      )
    )
   )
));
?>

   Override the base_url and a custom authentication property of a plugin connection

import org.json.JSONObject;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("account_overrides", ImmutableMap.builder()
    .put("< your connection id >", ImmutableMap.builder()
      .put("base_url", "< The new plugin base URL to connect to. >")
      .put("properties", ImmutableMap.builder()
        .put("< custom authentication property ID >", "< the new custom authentication property value >")
        .build()
      )
      .build()
    )
    .build()
  )
  .build()
);

   Override the base_url and a custom authentication property of a plugin connection

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.account_overrides = new {
  "<your connection id>" =  new {
    base_url = "< The new plugin base URL to connect to. >",
    properties = new {
      "< custom authentication property ID >" = "< the new custom authentication property value >"
    }
  }
  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   Override the base_url and a custom authentication property of a plugin connection

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
  "type": "sso",
  "expiry": "24 hours",
  "inactivity_interval": "10 minutes",
  "username": "< A unique and immutable identifier for your end user >",
  "name": "< end-user name >",
  "email": "< end-user email >",
  "suborganization": "< a suborganization name >",
  "integration_id": "< integration id >",
  "role": "viewer",
  "account_overrides": {
    "< your connection id >" : {
      "base_url": "< The new plugin base URL to connect to. >",
      "properties": {
        "< custom authentication property ID >": "< the new custom authentication property value >"
      }
    }
  }
});

  An example showing how to apply dataset level overrides when using account_overrides.

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("account_overrides", ImmutableMap.builder()
    .put("< your connection id >", ImmutableMap.builder()
      .put("datasets", ImmutableMap.builder()
        .put("< dataset ID >", ImmutableMap.builder()
          .put("table", "< new table name >")
          .build()
        )
        .build()
      )
      .build()
    )
    .build()
  )
  .build()
);
System.out.println("Success! %s%n", authorization);

  An example showing how to apply dataset level overrides when using account_overrides.

dynamic properties = new ExpandoObject();

properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.account_overrides = new {
  < your connection id > = new {
    datasets = new {
      < dataset ID > = new {
        table = "< my new table name >"
      }
    }
  }
};

dynamic authorization = client.create("authorization",    properties);
Console.WriteLine("Success!", authorization);

  An example showing how to apply dataset level overrides when using account_overrides.

client
  .create("authorization", {
    type: "sso",
    expiry: "24 hours",
    inactivity_interval: "10 minutes",
    username: "< A unique and immutable identifier for your end user >",
    name: "< end-user name >",
    email: "< end-user email >",
    suborganization: "< a suborganization name >",
    integration_id: "< integration id >",
    role: "viewer",
    account_overrides: {
      "< your connection id >": {
        datasets: {
          "< dataset ID >": {
            table: "< my new table name >",
          },
        },
      },
    },
  })
  .then(function (authorization) {
    console.log("Success!", authorization);
  });

   An example showing how to apply dataset level overrides when using account_overrides.

<?php
$authorization = $client->create("authorization",

  array (
    "type" => "sso",
    "expiry" => "24 hours",
    "inactivity_interval" => "10 minutes",
    "username" => "< A unique and immutable identifier for your end user >",
    "name" => "< end-user name >",
    "email" => "< end-user email >",
    "suborganization" => "< a suborganization name >",
    "integration_id" => "< integration id >",
    "role" => "viewer",
    "account_overrides" => array (
      "< your connection id >" => array (
        "datasets" => array (
          "< dataset ID >" => array (
            "table" => "< my new table name >"
          )
        )
      )
    )
  )

);
print("Success! { $authorization }");
?>

    An example showing how to apply dataset level overrides when using account_overrides.

curl https://api.luzmo.com/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "account_overrides": {
      "<your connection id >": {
        "datasets": {
          "< dataset ID >": {
            "table": "< my new table name >"
          }
        }
      }
    }
  }
}
EOF

  An example showing how to apply dataset level overrides when using account_overrides.

authorization = client.create("authorization",
  {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "account_overrides": {
      "< your connection id >": {
        "datasets": {
          "< dataset ID >": {
            "table": "< my new table name >"
          }
        }
      }
    }
  }

)

Your data may be split over databases per client. In such case, you can create multitenant dashboard in Luzmo using the connection overrides (account_overrides) functionality. A connection in Luzmo contains the information that is necessary to access a certain plugin or database. The connection overrides (account_overrides) functionality allows you to dynamically override one or multiple of these properties.

You can override the connection properties when creating your authorization requests to switch between databases. You could also use this approach to change the user/password in a single database in case your database provides row-level security. Row-level security in this context means that the database can automatically filter out rows based on the credentials.

You can use connection overrides if you are using one of the standard Luzmo connectors (MySQL, PostgreSQL, ...) as well as if you are using a Plugin to connect your data.

You can find your connection id by going to the Connections tab in the side menu, look for your data connection, then click on the three dots to the right of the connection name and select "More Info." Alternatively you can perform an API call to get your connections id.

Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value for both schema and database.

You can also use connection overrides (account_overrides) to override the host, key and/or token properties of the following built-in plugins: AWS Athena, BigQuery, Clickhouse, Elasticsearch, MongoDB, Oracle and Snowflake.

Property	Description
type string REQUIRED	`sso` Use the value 'sso' for integrating a dashboard.
expiry date (RFC 3339) or string REQUIRED	Date/time when this authorization will cease working. To promote better security practices this property is required and enforced with a maximum expiry date of 1 year. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
inactivity_interval integer or string	Duration of inactivity after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). If specified, a minimum value of 2 minutes is enforced to avoid undesired invalidation of a token due to e.g. missing a heartbeat signal sent by our server. Defaults to 0 (i.e. no inactivity_interval).
username string REQUIRED	Identifies the end-user uniquely and immutably. This should correspond to eg. the primary key for the end-user on your end. If it changes, the end-user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform! This will also be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization.
name string REQUIRED	The full name of the end-user (i.e. First name and Last name). This will be used in our UI.
email string REQUIRED	The email address of the end-user. This will be used in our UI.
suborganization string REQUIRED	Each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username.
integration_id uuid REQUIRED	The UUID of the integration that the SSO token should have access to.
role string REQUIRED	The role of the user for who you are making the authorization request. More information on the different roles: "viewer" SSO users that should only be able to view and interact with one or more dashboards, variants, and duplicates. "designer" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates. "owner" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates, and next to that they should be able to favorite dashboard variants for other SSO users within their suborganization. More info under Embedded Dashboard Editor.
account_overrides object	Let this token override the connection to one or more data connections (to a Plugin or database). You can use this to dynamically route requests to different endpoints (eg. the correct endpoint per client in a single-tenant setup). All overrides are optional -- if not specified, the value as configured on the original connection will be used instead.
connection id object	The database connection id for which you want to override the properties.
host string	The new database host to connect to. The database must be of the same type as the originally configured database.
port string	The new port to connect to.
user string	The new user to use when connecting.
password string	The new password to use when connecting.
database string	The new database to retrieve data from. Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value for both `schema` and `database`
schema string	The new schema to retrieve data from. Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value for both `schema` and `database`
table string	The new table to retrieve data from.
datasets object	List of dataset-level overrides. Useful if you want to override only a single table in your dashboard or if you have a separate table per client. The SQL query of the dataset can also be overridden if it's a SQL dataset within Luzmo. Allowing you to call stored procedures for example.
dataset_id string	The dataset (securable) ID that you want to override.
table string	The new table to retrieve data from.
schema string	The new schema to retrieve data from.
sql string	The new SQL query to run. NOTE: the columns returned in the new query need to conform to the same schema as the original dataset.
connection_id object	The Plugin connection id for which you want to override the properties.
base_url string	The new base URL that will be called.
properties object	Lists the custom authentication properties to override for plugin-based connections.
<custom_property_id> string	The new custom authentication property value (the key is the custom authentication property id as defined when setting up the plugin in Luzmo). This will be sent as `X-Property-<custom_property_id>` header to the Plugin.
datasets object	List of dataset-level overrides. Useful if you want to override only a single table in your dashboard or if you have a separate table per client.
dataset_id string	The dataset (securable) ID that you want to override.
table string	The new canonical dataset identifier (as defined in the Plugin) to retrieve data from.

Embedded dashboard editor

Empower your users to create and alter dashboards straight from within your application with our embedded dashboard editor. With the embedded dashboard editor, non-technical users can easily create their own insights based on the data they were given access to!

After setting up an Integration, adding the embedding code in your backend and frontend and handling your multi-tenancy, there are a few topics that are important for the embedded dashboard editor:

Define securable access rights - give the correct rights to your dashboards and datasets.
Specify the user role in backend - give the appropriate role to your user in the authorization request in your backend.
Set edit mode in frontend - specify the editMode property of the frontend component to show the dashboard in the desired mode.

Define securable access rights

To start, it is important that you define the correct access rights when associating your dashboards and datasets with the Integration.

Access to dashboard(s)

   Associate an Integration with a dashboard in order to make that dashboard available to users given access to the Integration via an SSO token. Set the rights to the dashboard to "can use".

client.associate("integration", "< your integration id >", "Securables", "< your dashboard id >",
  ImmutableMap.of(
    "flagRead" , true,
    "flagUse", true,
    "slug", "< lowercase alphanumeric slug name >"
  ) );

   Associate an Integration with a dashboard in order to make that dashboard available to users given access to the Integration via an SSO token. Set the rights to the dashboard to "can use".

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagUse = true;
properties.slug = "< lowercase alphanumeric slug name >";

client.associate("integration", "< your integration id >", "Securables", "< your dashboard id >", properties );

   Associate an Integration with a dashboard in order to make that dashboard available to users given access to the Integration via an SSO token. Set the rights to the dashboard to "can use".

let promise = client.associate("integration", "< your integration id >", {
    role: "Securables",
    id: "< your dashboard id >"
},
{
    flagRead: true,
  flagUse: true,
    slug: "< lowercase alphanumeric slug name >"
});

  Associate an Integration with a dashboard in order to make that dashboard available to users given access to the Integration via an SSO token. Set the rights to the dashboard to "can use".

<?php
$client->associate("integration", "< your integration id >", "Securables", "< your dashboard id >", ,
  array (
    "flagRead" => true,
    "flagUse" => true,
    "slug => "< lowercase alphanumeric slug name >"
  ) );
?>

  Associate an Integration with a dashboard in order to make that dashboard available to users given access to the Integration via an SSO token. Set the rights to the dashboard to "can use".

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "< your integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dashboard id >"
  },
  "properties": {
    "flagRead": true,
    "flagUse": true,
    "slug": "< lowercase alphanumeric slug name >"
  }
}
EOF

  Associate an Integration with a dashboard in order to make that dashboard available to users given access to the Integration via an SSO token. Set the rights to the dashboard to "can use".

client.associate("integration", "< your integration id >", {
    "role": "Securables",
    "id": "< your dashboard id >"
},
{
    "flagRead": true,
  "flagUse": true,
    "slug": "< lowercase alphanumeric slug name >"
});

The association has flag properties to define what kind of rights a user who has access to the Integration will receive. If no flag properties are specified, the rights will bet set to "can view" by default. The available flags are:

'Can view' (or 'flagRead') - gives the SSO user the right to only view and interact with the dashboard.
'Can use' (or 'flagUse') - next to viewing a dashboard, the SSO user is able to create a variant of the dashboard, or duplicate it (only in editMode 'editFull').
'Can edit' (or 'flagModify') - besides viewing, duplicating and creating a variant of the dashboard, the SSO user can edit the dashboard itself.

Warning! If you give 'can use' or 'can edit' rights on a dashboard, you must ensure that all multi-tenant (parameter) filters are defined on the dataset level (i.e. when associating the dataset(s) with the Integration, Suborganization, Group, or User) and not on the dashboard level. Designer users are able to modify the dashboard content (either in a variant, in a duplicate or in the dashboard itself) and thus remove these (parameter) filters if you would define them on the dashboard!

Access to dataset(s)

   Associate an Integration to a dataset, give use rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

client.associate("integration", "<your integration id >", "Securables", "< your dataset id >",
  ImmutableMap.of(
    "flagRead", true,
    "flagUse", true,
    "filters", ImmutableList.of(
      ImmutableMap.of(
        "clause", "where",
        "origin", "global",
        "securable_id", "< dataset id >",
        "column_id", "< column id of a column in the dataset >",
        "expression", "? in ?",
        "value", ImmutableMap.of(
          parameter: "metadata.< parameter name >",
          type: "array[hierarchy]",
          value: ImmutableList.of(
            "< default parameter value >"
          )
        )
      )
    )
  )
);

   Associate an Integration to a dataset, give use rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagUse = true;

properties.filters = new List<dynamic> {
  new {  
    clause = "where";
    origin = "global";
    securable_id = "< dataset id >";
    column_id = "< column id of a column in the dataset >";
    expression = "? in ?";
    value = new {
      parameter: "metadata.< parameter name >",
      type: "array[hierarchy]",
      value: new List<String> {
        "< default parameter value >"
      }
    };
  }
};

client.associate("integration", "< your integration id >", "Securables", "< your dataset id >",   properties );

   Associate an Integration to a dataset, give use rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

let promise = client.associate("integration", "< your integration id >", {
  role: "Securables",
  id: "< your dataset id >"
},
{
  flagRead: true,
  flagUse: true,
  filters: [
    {
      clause: "where",
      origin: "global",
      securable_id: "< dataset id >",
      column_id: "< column id of a column used in the dataset >",  
      expression: "? in ?",
      value: {
        parameter: "metadata.< parameter name >",
        type: "array[hierarchy]",
        value: ["< default parameter value >"]
      }
    }  
  ]
});

   Associate an Integration to a dataset, give use rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

<?php
$client->associate("integration", "< your integration id >", "Securables", "< your dataset id >", ,
  array (
    "flagRead" => true,
    "flagUse" => true,
    "filters" => array(
      array(
        "clause"       => "where",
        "origin"       => "global",
        "securable_id" => "< dataset id >",
        "column_id"    => "< column id of a column used in the dataset >",
        "expression"   => "? in ?",
        "value"        => array(
          "parameter" => "metadata.< parameter name >",
          "type" => "array[hierarchy]",
          "value" => array("< default parameter value >")
        )
      )
    )
  ) );
?>

   Associate an Integration to a dataset, give use rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "< your integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dataset id >"
  },
  "properties": {
    "flagRead": true,
    "flagUse": true,
    "filters": [
        {
          "clause": "where",
          "origin": "global",
          "securable_id": "< dataset id >",
          "column_id": "< column id of a column used in the dataset >",  
          "expression": "? in ?",
          "value": {
            "parameter": "metadata.< parameter name >",
            "type": "array[hierarchy]",
            "value": ["< default parameter value >"]
          }
        }
      ]
  }
}
EOF

   Associate an Integration to a dataset, give use rights and apply some parameter filters. The parameter specified can be overridden when requesting a SSO token to apply dynamic row-level security!

client.associate("integration", "< your integration id >", {
  "role": "Securables",
  "id": "< your dataset id >"
},
{
  "flagRead": true,
  "flagUse": true,
  "filters": [
    {
      "clause": "where",
      "origin": "global",
      "securable_id": "< dataset id >",
      "column_id": "< column id of a column used in the dataset >",  
      "expression": "? in ?",
      "value": {
        "parameter": "metadata.< parameter name >",
        "type": "array[hierarchy]",
        "value": ["< default parameter value >"]
      }
    }  
  ]
});

   Associate an Integration to a dataset, give it modify rights and apply a static filter for e.g. row-level security.

client.associate("integration", "< your integration id >", "Securables", "< your dataset id >",
  ImmutableMap.of(
    "flagRead", true,
    "flagUse", true,
    "flagModify", true,
    "filters", ImmutableList.of(
      ImmutableMap.of(
        "clause", "where",
        "origin", "global",
        "securable_id", "< dataset id >",
        "column_id", "< column id of a column in the dataset >",
        "expression", "? = ?",
        "value", "< value to be applied to the expression >"
      )
    )
  )
);

   Associate an Integration to a dataset, give it modify rights and apply a static filter for e.g. row-level security.

dynamic properties = new ExpandoObject();
properties.flagRead = true;
properties.flagUse = true;
properties.flagModify = true;

properties.filters = new List<dynamic> {
  new {  
    clause = "where";
    origin = "global";
    securable_id = "< dataset id >";
    column_id = "< column id of a column in the dataset >";
    expression = "? = ?";
    value = "< value to be applied to the expression >";
  }
};

client.associate("integration", "< your integration id >", "Securables", "< your dataset id >",   properties );

   Associate an Integration to a dataset, give it modify rights and apply a static filter for e.g. row-level security.

let promise = client.associate("integration", "< your integration id >", {
  role: "Securables",
  id: "< your dataset id >"
},
{
  flagRead: true,
  flagUse: true,
  flagModify: true,
  filters: [
    {
      clause: "where",
      origin: "global",
      securable_id: "< dataset id >",
      column_id: "< column id of a column used in the dataset >",  
      expression: "? = ?",
      value: "< value to be applied to the expression >"
    }  
  ]
});

   Associate an Integration to a dataset, give it modify rights and apply a static filter for e.g. row-level security.

<?php
$client->associate("integration", "< your integration id >", "Securables", "< your dataset id >", ,
  array (
    "flagRead" => true,
    "flagUse" => true,
    "flagModify" => true,
    "filters" => array(
      "clause"       => "where",
      "origin"       => "global",
      "securable_id" => "< dataset id >",
      "column_id"    => "< column id of a column used in the dataset >",
      "expression"   => "? = ?",
      "value"        => "< value to be applied to the expression >"
    )
  ) );
?>

   Associate an Integration to a dataset, give it modify rights and apply a static filter for e.g. row-level security.

curl https://api.luzmo.com/0.1.0/integration  \
-H "Content-Type: application/json"  \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your integration id >",
  "resource": {
    "role": "Securables",
    "id": "< your dataset id >"
  },
  "properties": {
    "flagRead": true,
    "flagUse": true,
    "flagModify": true,
    "filters": [
        {
          "clause": "where",
          "origin": "global",
          "securable_id": "< dataset id >",
          "column_id": "< column id of a column used in the dataset >",  
          "expression": "? = ?",
          "value": "< value to be applied to the expression >"
        }
      ]
  }
}
EOF

When associating a dataset with an Integration you can specify some flag properties to define what kind of rights a user who has access to the Integration will receive. If no flag properties are specified, the rights will bet set to "can view" by default. The available flags are:

'Can view' (or 'flagRead') - users are only allowed to query the dataset in existing dashboard(s) that are accessible to them (i.e. the user is not able to use this dataset when creating/editing a dashboard).
'Can use' (or 'flagUse') - the user is also able to use this dataset when creating or editing a dashboard.
'Can edit' (or 'flagModify') - the user is able to use this dataset when creating or editing a dashboard, and is able to edit the dataset itself (e.g. change column names, create or alter hierarchies, create or alter derived columns, etc.)

Specify user role in backend

  Generate an SSO token for your user. Replace with your API key & token and integration_id and fill in the user's details.

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "designer"
  }
}
EOF

   Generate an SSO token for your user. Replace with your API key & token and integration_id and fill in the user's details.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: "< Your API key >",
    api_token: "< Your API token >",
    host: "< https://api.luzmo.com (dclassefault) or https://api.us.luzmo.com/ or your VPC-specific address >"
});

let promise = client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "designer"
});

promise.then(function(result){
  // return the result to the client
})

  Generate an SSO token for your user. Replace with your API key & token and integration_id and fill in the user's details.

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");


$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your user >",
  "name" => "< user name >",
  "email" => "< user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "designer"
));
?>

  Generate an SSO token for your user. Replace with your API key & token and integration_id and fill in the user's details.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your user >")
  .put("name", "< user name >")
  .put("email", "< user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "designer")
  .build()
);

   Generate an SSO token for your user. Replace with your API key & token and integration_id and fill in the user's details.

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your user >";
properties.name = "< user name >";
properties.email = "< user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "designer";

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   Generate an SSO token for your user. Replace with your API key & token and integration_id and fill in the user's details.

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "designer"
});

   This returns a JSON object with an id/token combination that we will use to integrate:

{
  "type": "sso",
  "id": "< the SSO authorization key >",
  "token": "< the SSO authorization token >",
  "user_id": "< a uuid used on our end to identify the SSO user >"
  // ...
}

In this step, your server-side code makes an API request to retrieve an authorization token of type SSO. The result of this request is a key/token combination that will be used to in the frontend component to securely embed the dashboard in your application/platform.

The API request is a 'create' request for an authorization. In this API call we use the integration id that we created before (see Set up an Integration), and next to that we specify the role that your user should have. The flow chart below should help in making that decision for your specific use-case and user!

Property	Description
type string REQUIRED	`sso` Use the value 'sso' for embedding a dashboard or the dashboard editor.
expiry date (RFC 3339) or string REQUIRED	Date/time when this authorization will cease working. To promote better security practices this property is required and enforced with a maximum expiry date of 1 year. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
inactivity_interval integer or string	Duration of inactivity after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). If specified, a minimum value of 2 minutes is enforced to avoid undesired invalidation of a token due to e.g. missing a heartbeat signal sent by our server. Defaults to 0 (i.e. no inactivity_interval).
username string REQUIRED	Identifies the user uniquely and immutably. This should correspond to eg. the primary key for the user on your end. If it changes, the user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform! This will also be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization.
name string REQUIRED	The full name of the user (i.e. First name and Last name). This will be used in our UI.
email string REQUIRED	The email address of the user. This will be used in our UI.
suborganization string REQUIRED	Each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username.
integration_id uuid REQUIRED	The UUID of the Integration that the SSO token should have access to.
role string REQUIRED	The role of the user for who you are making the authorization request. More information on the different roles: "viewer" SSO users that should only be able to view and interact with one or more dashboards, variants, and duplicates. "designer" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates. "owner" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates, and next to that they should be able to favorite dashboard variants for other SSO users within their suborganization.

For a list of all properties that you can use in the request, check Authorization in the Core API.

Set edit mode in frontend

   In the code example below, you can see how you can set the edit mode via the component properties, as well as the main and accent color of the editor

<!--
Clients on our US multi-tenant application environment,
or a dedicated instance on a specific VPC, should specify:
- appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
- apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
-->
<luzmo-dashboard
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< SSO authorization key >"
  authToken="< SSO authorization token >"
  editMode="< view, editLimited, or editFull >"
  dashboardId="< dashboard id you want to embed >"
></luzmo-dashboard>

/*
Clients on our US multi-tenant application environment,
or a dedicated instance on a specific VPC, should specify:
- [appServer]="'https://app.us.luzmo.com/'" (or your VPC-specific address)
- [apiHost]="'https://api.us.luzmo.com/'" (or your VPC-specific address)
*/
<luzmo-dashboard
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
  [authKey]="'< SSO authorization key >'"
  [authToken]="'< SSO authorization token >'"
  [editMode]="'< view, editLimited, or editFull >'"
  [dashboardId]="'< dashboard id you want to embed >'"
></luzmo-dashboard>

import { LuzmoDashboardComponent } from '@luzmo/react-embed';
...

  function LuzmoWrapper() {
    ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        editMode="< view, editLimited, or editFull >"
        dashboardId="< dashboard id you want to embed >"
      ></LuzmoDashboardComponent>
    );
  }

import LuzmoDashboardComponent from '@luzmo/react-native-embed';
...

  function LuzmoWrapper() {
    ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        editMode="< view, editLimited, or editFull >"
        dashboardId="< dashboard id you want to embed >"
      ></LuzmoDashboardComponent>
    );
  }

<template>
  ...

  <!--
  Clients on our US multi-tenant application environment,
  or a dedicated instance on a specific VPC, should specify:
  - :appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
  - :apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
   -->
  <luzmo-dashboard
    ref="dashboardInstance"
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< SSO authorization key >"
    authToken="< SSO authorization token >"
    editMode="< view, editLimited, or editFull >"
    dashboardId="< dashboard id you want to embed >"
  ></luzmo-dashboard>
  ...
</template>

To embed a dashboard in your webpage, we use the Embed Libraries.

First, you should install and import the appropriate component in your frontend (see here).

In this step we'll use the SSO key and token received from the authorization request in your backend to securely embed a dashboard in your frontend (referencing either the dashboard id or slug). Next to that, we'll specify the initial edit mode in which the dashboard should be loaded!

The flow chart below could help out in deciding which editMode fits your use-case and application.

Parameter	Description
appServer string	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost string	Tenancy of Luzmo API to connect to. Defaults to 'https://api.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://api.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey uuid	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken string	The authorization token from the response of the authorization request in your backend.
dashboardId uuid	This is the id of the dashboard that you want to embed. Specify either the dashboardId or dashboardSlug property.
dashboardSlug string	Instead of specifying a dashboardId, you can alternatively specify a dashboard slug. The slug is defined when associating a dashboard with an Integration. Specify either the dashboardId or dashboardSlug property.
mainColor string	(Optional) Override the main color used in the whitelabeling of the embedded dashboard editor. If not provided, the main color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values, e.g. `"rgb(50,50,50)"`. A gif showcasing the influence of specifying mainColor can be seen in this Academy article.
accentColor string	(Optional) Override the accent color used in the whitelabeling of the embedded dashboard editor. If not provided, the accent color of the whitelabeling colors set on the organization will be used. Should be specified as a string of rgb values, e.g. `"rgb(50,50,50)"`. A gif showcasing the influence of specifying accentColor can be seen in this Academy article.
editMode string DashboardEditMode	The mode in which the dashboard should be loaded. Defaults to "view". "view" This mode enables your users to view and interact with an embedded dashboard, without having the option to change the dashboard itself. "editLimited" This mode is useful if you have your own dashboard navigation in your application (e.g. a sidebar containing dashboard tabs or a dropdown) and would like the user to edit (some of) the dashboards (e.g. by adding an “Edit” button that toggles the editMode between “view” and “editLimited” mode). Users will be able to create variants of the dashboard or edit the dashboard itself (depending on the access rights you defined for the dashboard) and share these dashboard (variants) with other users in their organization. "editFull" If you have a dedicated place in your application where users should be able to create & edit all their accessible dashboard(s) (e.g. in your navigation bar you have a “Dashboard editor” tab that should show the embedded dashboard editor). The user will be able to create edit, duplicate and create a variant of existing dashboards (depending on the access rights you defined for the dashboard) as well as create new dashboards and share these dashboard (variants) with other users in their organization.

That's it, with these steps you've set up the basics to provide Luzmo's embedded dashboard editor to your users!

Next steps

Below you can find some of the additional options related to embedding Luzmo dashboards into your application!

Retrieving a list of dashboards

   First we pass along a SSO key and token to the Web component, and then we call the getAccessibleDashboards method to retrieve the dashboards that are accessible to that key-token pair

<html>
  <luzmo-dashboard
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  ></luzmo-dashboard>
</html>

<script>
  // Get the component reference
  const dashboardElement = document.querySelector("luzmo-dashboard");

  // Set the SSO Authorization key and token pair
  dashboardElement.authKey = "< SSO Authorization Key >";
  dashboardElement.authToken = "< SSO Authorization Token >";

  // Retrieve the dashboards that are accessible to the SSO Authorization token
  dashboardElement.getAccessibleDashboards()
      .then(dashboards => {
          // Do something with the response, e.g. dynamically fill your application's navigation
          console.log(dashboards);
      });
</script>

1 Add the Luzmo component in your Angular page

<luzmo-dashboard
  #dashboardInstance
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
></luzmo-dashboard>

2 In your Angular Component file, add the following code to set a SSO key & token, and then retrieve the accessible dashboards

import {  OnInit, Component, ViewChild } from '@angular/core';
...
import {
  NgxLuzmoDashboardModule,
  AccessibleDashboard
} from '@luzmo/ngx-embed';
...

@Component({
  ...
})

export class LuzmoEmbeddingComponent implements OnInit {
  // Component reference
  @ViewChild('dashboardInstance') dashboardInstance: NgxLuzmoDashboardModule;

  ngOnInit(): void {
    // Set the SSO Authorization key and token pair
    this.dashboardInstance.authKey = "< SSO Authorization Key >";
    this.dashboardInstance.authToken = "< SSO Authorization Token >";

    // Retrieve the dashboards that are accessible to the SSO Authorization token
    this.dashboardInstance.getAccessibleDashboards().pipe(take(1)).subscribe((dashboards: AccessibleDashboard[]) => {
      // Do something with the response, e.g. dynamically fill your application's navigation
      console.log(dashboards);
    });
  }
}

 First we pass along a SSO key and token to the React component, and then we call the getAccessibleDashboards method to retrieve the dashboards that are accessible to that key-token pair

import { useRef } from 'react';
...
import {
  LuzmoDashboardComponent
} from "@luzmo/react-embed";
...

export function LuzmoWrapper() {
  // Component reference
  const dashboardInstance = useRef(null);

  // Set the SSO Authorization key and token pair
  dashboardInstance.current.authKey = = "< SSO Authorization Key >";
  dashboardInstance.current.authToken = "< SSO Authorization Token >";

  // Retrieve the dashboards that are accessible to the SSO Authorization token
  dashboardInstance.current.getAccessibleDashboards().then(dashboards => {
    // Do something with the response, e.g. dynamically fill your application's navigation
    console.log(dashboards);
  });

  return (
    <LuzmoDashboardComponent
      ref={dashboardInstance}
      appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
      apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    ></LuzmoDashboardComponent>
  );
}

 First we pass along a SSO key and token to the React Native component, and then we call the getAccessibleDashboards method to retrieve the dashboards that are accessible to that key-token pair

import { useRef } from 'react';
...
import LuzmoDashboardComponent from '@luzmo/react-native-embed';
...

export function LuzmoWrapper() {
  // Component reference
  const dashboardInstance = useRef(null);

  // Set the SSO Authorization key and token pair
  dashboardInstance.current.authKey = = "< SSO Authorization Key >";
  dashboardInstance.current.authToken = "< SSO Authorization Token >";

  // Retrieve the dashboards that are accessible to the SSO Authorization token
  dashboardInstance.current.getAccessibleDashboards().then(dashboards => {
    // Do something with the response, e.g. dynamically fill your application's navigation
    console.log(dashboards);
  });

  return (
    <LuzmoDashboardComponent
      ref={dashboardInstance}
      appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
      apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    ></LuzmoDashboardComponent>
  );

 First we pass along a SSO key and token to the Vue component, and then we call the getAccessibleDashboards method to retrieve the dashboards that are accessible to that key-token pair

<template>
  ...
  <luzmo-dashboard
    ref="dashboardInstance"
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  ></luzmo-dashboard>
  ...
</template>
<script>
  export default {
    mounted() {
      // Set the SSO Authorization key and token pair
      this.$refs.dashboardInstance.authKey = = "< SSO Authorization Key >";
      this.$refs.dashboardInstance.authToken = "< SSO Authorization Token >";

      // Retrieve the dashboards that are accessible to the SSO Authorization token
      this.$refs.dashboardInstance.getAccessibleDashboards().then(dashboards => {
        // Do something with the response, e.g. dynamically fill your application's navigation
        console.log(dashboards);
      });
    },
    ...
  }
</script>

   This returns an array of dashboards, together with some relevant information related to each dashboard:

[
    {
        "id": "< dashboard_1_id >",
        "modifiedAt": "2021-02-10T09:13:27.114Z",
        "name": "< dashboard_1_name >",
        "slug": null,
        "tags": [
            "< dashboard_1_tag_1 >",
            "< dashboard_1_tag_2 >"
        ],
        "accessibleBy": [
            {
                "model": "User",
                "id": "< user_A_id >",
                "name": "< user_A_name >"
            },
            {
                "model": "User",
                "id": "< user_B_id >",
                "name": "< user_B_name >"
            },
            {
                "model": "Group",
                "id": "< group_id >",
                "name": "< group_name >"
            },
            {
                "model": "Integration",
                "id": "< integration_id >",
                "name": "< integration_name >"
            }
        ],
        "accessRights": {
            "flagRead": true,
            "flagUse": true,
            "flagModify": false,
            "flagOwn": false
        }
    },
    ...
]

When you embed a dashboard with one of our embedding components (all components are listed in the Embedding chapter), you can make use of the getAccessibleDashboards method in your frontend to programmatically retrieve a list of dashboards. The dashboards that are returned are associated with the specific integration that the SSO key and token has access to, or its bootstrapped Suborganization or SSO user.
This is particularly useful if you'd like to have a dynamic way of retrieving and providing dashboards in your frontend! Some use-cases are described in this Academy article.

In Angular, the getAccessibleDashboards method is an Observable to which you can subscribe an observer function to. The observable will deliver an array of AccessibleDashboard elements.

The getAccessibleDashboards method returns a Promise that resolves with an array of AccessibleDashboard elements.

Set an initialization filter

   An example showing how to request a SSO token with an initialization filter set on a specific filter item (slider, search and select box, ...). Specifying an SSO initialization filter on a specific filter item results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity.

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a filter object contained in the dashboard >",
        "expression": "? = ?",
        "value": "< value to be applied to the expression >"
      }
    ]
  }
}
EOF

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a specific filter item (slider, search and select box, ...). Specifying an SSO initialization filter on a specific filter item results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< Your API key >",
  api_token: "< Your API token >",
  host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
});

let promise = client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your end user >",
  name: "< end-user name >",
  email: "< end-user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  filters: [
    {
      clause: "where",
      origin: "initialization",
      chart_id: "< chart id of a filter object contained in the dashboard >",
      expression: "? = ?",
      value: "< value to be applied to the expression >",
    },
  ],
});

promise.then(function (result) {
  // return the result to the client
});

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a specific filter item (slider, search and select box, ...). Specifying an SSO initialization filter on a specific filter item results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity.

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your end user >",
  "name" => "< end-user name >",
  "email" => "< end-user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "viewer",
  "filters" => array(
    array(
      "clause"     => "where",
      "origin"     => "initialization",
      "chart_id"   => "< chart id of a filter object contained in the dashboard >",
      "expression" => "? = ?",
      "value"      => "< value to be applied to the expression >"
    )
  ),
));
?>

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a specific filter item (slider, search and select box, ...). Specifying an SSO initialization filter on a specific filter item results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "initialization")
    .put("chart_id",     "< chart id of a filter object contained in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a specific filter item (slider, search and select box, ...). Specifying an SSO initialization filter on a specific filter item results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity.

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "initialization",
    chart_id = "< chart id of a filter object contained in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a specific filter item (slider, search and select box, ...). Specifying an SSO initialization filter on a specific filter item results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity.

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
  "type": "sso",
  "expiry": "24 hours",
  "inactivity_interval": "10 minutes",
  "username": "< A unique and immutable identifier for your end user >",
  "name": "< end-user name >",
  "email": "< end-user email >",
  "suborganization": "< a suborganization name >",
  "integration_id": "< integration id >",
  "role": "viewer",
  "filters": [
    {
      "clause": "where",
      "origin": "initialization",
      "chart_id": "< chart id of a filter object contained in the dashboard >",
      "expression": "? = ?",
      "value": "< value to be applied to the expression >"
    }
  ]
});

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a chart. Specifying an SSO initialization filter on a chart results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity. Note that in this case you need to supply a column_id and securable_id, next to the chart_id, and that the filter value must always consist of an array.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >", "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "initialization")
    .put("chart_id",     "< chart id of a chart object contained in the dashboard >")
    .put("expression",   "? = ?")
    .put("column_id",    "< id of the column you want to filter on (usually in category slot) >")
    .put("securable_id", "< id of the dataset that the column belongs to >")
    .put("value",        ImmutableList.of(
      "<value to be applied to the expression>"
    ))
    .build()
  ))
  .build()
);

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a chart. Specifying an SSO initialization filter on a chart results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity. Note that in this case you need to supply a column_id and securable_id, next to the chart_id, and that the filter value must always consist of an array.

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "initialization",
    chart_id = "< chart id of a chart object contained in the dashboard >",
    expression = "? = ?",
    column_id = "< id of the column to apply the filter to (usually the category) >",
    securable_id = "< id of the dataset that the column belongs to >",
    value = new List<string> {
      "< value to be applied to the expression >"
    }
  }
};

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a chart. Specifying an SSO initialization filter on a chart results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity. Note that in this case you need to supply a column_id and securable_id, next to the chart_id, and that the filter value must always consist of an array.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< Your API key >",
  api_token: "< Your API token >",
  host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
});

let promise = client.create("authorization", {
  type: "sso",
  expiry: "24 hours",
  inactivity_interval: "10 minutes",
  username: "< A unique and immutable identifier for your end user >",
  name: "< end-user name >",
  email: "< end-user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  filters: [
    {
      clause: "where",
      origin: "initialization",
      chart_id: "< chart id of a chart object contained in the dashboard >",
      expression: "? = ?",
      column_id:
        "< id of the column to apply the filter to (usually the category) >",
      securable_id: "< id of the dataset that the column belongs to >",
      value: ["< value to be applied to the expression >"],
    },
  ],
});

promise.then(function (result) {
  // return the result to the client
});

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a chart. Specifying an SSO initialization filter on a chart results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity. Note that in this case you need to supply a column_id and securable_id, next to the chart_id, and that the filter value must always consist of an array.

<?php
$client = Luzmo::initialize("< your API key >", "< your API token >",
 "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

$authorization = $client->create("authorization", array(
  "type" => "sso",
  "expiry" => "24 hours",
  "inactivity_interval" => "10 minutes",
  "username" => "< A unique and immutable identifier for your end user >",
  "name" => "< end-user name >",
  "email" => "< end-user email >",
  "suborganization" => "< a suborganization name >",
  "integration_id" => "< integration id >",
  "role" => "viewer",
  "filters" => array(
    array(
      "clause"       => "where",
      "origin"       => "initialization",
      "chart_id"     => "< chart id of a chart object contained in the dashboard >",
      "expression"   => "? = ?",
      "column_id"    => "< id of the column to apply the filter to (usually the category) >",
      "securable_id" => "< id of the dataset that the column belongs to >"
      "value"        => array(
        "< value to be applied to the expression >"
      )
    )
  ),
));
?>

   An example showing how to request a SSO token with an initialization filter set on a chart. Specifying an SSO initialization filter on a chart results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity. Note that in this case you need to supply a column_id and securable_id, next to the chart_id, and that the filter value must always consist of an array.

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a chart object contained in the dashboard >",
        "expression": "? = ?",
        "column_id": "< id of the column to apply the filters to >",
        "securable_id": "< id of the dataset that the column belongs to >",
        "value": [
          "< value to be applied to the expression >"
        ]
      }
    ]
  }
}
EOF

   (client created with API token) An example showing how to request a SSO token with an initialization filter set on a chart. Specifying an SSO initialization filter on a chart results in preselecting the specified values in that item when loading an embedded a dashboard with that SSO key and token. The preselected value(s) can still be modified using the item's interactivity. Note that in this case you need to supply a column_id and securable_id, next to the chart_id, and that the filter value must always consist of an array.

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token,
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "filters": [
      {
        "clause": "where",
        "origin": "initialization",
        "chart_id": "< chart id of a chart object contained in the dashboard >",
        "expression": "? = ?",
        "column_id": "< id of the column to apply the filters to >",
        "securable_id": "< id of the dataset that the column belongs to >",
        "value": [
          "< value to be applied to the expression >"
        ]
      }
    ]
});

An initialization filter is a type of filter that initializes a filter on a certain filter object (slider, search and select box, ...) in an embedded dashboard. This means that the specified filter will be applied when the dashboard loads, but it can still be turned off or modified afterwards.

To do this, extend the code snippet used in step 1 by adding a filters parameter to the request.

For an initialization filter on a filter object, it is not needed to specify the securable_id or column_id in the filters parameter. This is because a filter object can have multiple columns, coming from different datasets.

You can also set initialization filters on chart objects. This pre-selects a portion of the chart when the dashboard opens. The structure in this case is slightly different: next to a chart_id, you need a column_id and a securable_id.

Property	Description
type string REQUIRED	`sso` Use the value 'sso' for integrating a dashboard.
expiry date (RFC 3339) or string REQUIRED	Date/time when this authorization will cease working. To promote better security practices this property is required and enforced with a maximum expiry date of 1 year. It is advised to only use short-living tokens (max. 24 hours) for maximum security.
inactivity_interval integer or string	Duration of inactivity after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). If specified, a minimum value of 2 minutes is enforced to avoid undesired invalidation of a token due to e.g. missing a heartbeat signal sent by our server. Defaults to 0 (i.e. no inactivity_interval).
username string REQUIRED	Identifies the end-user uniquely and immutably. This should correspond to eg. the primary key for the end-user on your end. If it changes, the end-user will not have access to their previously created content anymore. So don't use eg. an e-mail address if those can change in your platform! This will also be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization.
name string REQUIRED	The full name of the end-user (i.e. First name and Last name). This will be used in our UI.
email string REQUIRED	The email address of the end-user. This will be used in our UI.
suborganization string REQUIRED	Each SSO token should be in a suborganization. The suborganization determines which other users they can see & interact with. It is required to avoid accidentally forgetting to set it which would cause all users to see each other! If you want totally isolated users, set it to the unique username.
integration_id uuid REQUIRED	The UUID of the integration that the SSO token should have access to.
role string REQUIRED	The role of the user for who you are making the authorization request. More information on the different roles: "viewer" SSO users that should only be able to view and interact with one or more dashboards, variants, and duplicates. "designer" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates. "owner" SSO users that should be able to create, edit, view and interact with one or more dashboards, variants, and duplicates, and next to that they should be able to favorite dashboard variants for other SSO users within their suborganization. More info under Embedded Dashboard Editor.
filters array[object]
clause string	Timing of application of the filter. Possible values: `where` (applied before aggregation/grouping, for example, only select rows with a specific price), `having` (applied after aggregation/grouping, for example, to select only groups in which the total price exceeds a specific value)
origin string	This parameter specifies the level to apply the filter. For an initialization filter, this parameter should be set to `initialization`.
chart_id uuid	The id of the chart you want to apply the filter to. This chart needs to be contained in the dashboard you specified in the `securables` parameter.
expression string	The expression to be used in your filter formula. The possible filter expressions are: `? IN ?`, `? IS NOT IN ?`, `? = ?`, `? != ?`, `? > ?`, `? >= ?`, `? < ?`, `? <= ?`, `IS NULL` and `IS NOT NULL`.
value number, string, boolean, array	Value to insert in the filter.
column_id string	(Only needed in case of a non-filter object) The column to apply the filter to
securable_id string	(Only needed in case of a non-filter object) The dataset to apply the filter to

Set language or timezone

   You can specify the dashboard language and/or timezone as properties of the Frontend component

<luzmo-dashboard
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< SSO authorization key >"
  authToken="< SSO authorization token >"
  dashboardId="< dashboard id you want to embed >"
  language="< Language code, e.g. 'en', 'fr', etc. >"
  timezoneId="< Timezone ID, e.g. 'Europe/Brussels', 'America/New_York', etc. >"
></luzmo-dashboard>

<luzmo-dashboard
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
  [authKey]="'< SSO authorization key >'"
  [authToken]="'< SSO authorization token >'"
  [dashboardId]="'< dashboard id you want to embed >'"
  [language]="'< Language code, e.g. 'en', 'fr', etc. >'"
  [timezoneId]="'< Timezone ID, e.g. 'Europe/Brussels', 'America/New_York', etc. >'"
></luzmo-dashboard>

import { LuzmoDashboardComponent } from '@luzmo/react-embed';
...

  function LuzmoWrapper() {
    ...

    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        language="< Language code, e.g. 'en', 'fr', etc. >"
        timezoneId="< Timezone ID, e.g. 'Europe/Brussels', 'America/New_York', etc. >"
      ></LuzmoDashboardComponent>
    );
  }

import LuzmoDashboardComponent from '@luzmo/react-native-embed';
...

  function LuzmoWrapper() {
    ...

    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        language="< Language code, e.g. 'en', 'fr', etc. >"
        timezoneId="< Timezone ID, e.g. 'Europe/Brussels', 'America/New_York', etc. >"
      ></LuzmoDashboardComponent>
    );
  }

<template>
  ...
  <luzmo-dashboard
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< SSO authorization key >"
    authToken="< SSO authorization token >"
    dashboardId="< dashboard id you want to embed >"
    language="< Language code, e.g. 'en', 'fr', etc. >"
    timezoneId="< Timezone ID, e.g. 'Europe/Brussels', 'America/New_York', etc. >"
  ></luzmo-dashboard>
</template>

When you have built a multi-lingual dashboard (see this Academy article), you can specify what language to use when embedding a dashboard in your web page using the language property.
You can override the dashboard timezone that was set in the dashboard editor when embedding a dashboard in your web page (More info on timezone support can be found in this Academy article). This can be achieved by specifying the timezoneId property in the web component.
The provided timezone ID needs to be a valid ID that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York.

Parameter	Description
appServer string	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost string	Tenancy of Luzmo API to connect to. Defaults to 'https://api.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://api.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey uuid	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken string	The authorization token from the response of the authorization request in your backend.
dashboardId uuid	This is the id of the dashboard that you want to embed.
language string	(Optional) The language code that you wish to use in the dashboard instead of the default language of the dashboard. You can specify `'en'`, `'cs'`, `'da'`, `'de'`, `'es'`, `'fi'`, `'fr'`, `'he'`, `'hu'`, `'it'`, `'ja'`, `'ko'`, `'mk'`, `'nl'`, `'pl'`, `'pt'`, `'ru'`, `'sv'`, `'zh_cn'` or `'zh_tw'`. If that language code is not configured in the dashboard, the default language of that dashboard will be used. This Academy Webinar goes into more detail about multi-lingual dashboards.
timezoneId string	(Optional) The timezone id you wish to use in your dashboard, instead of the default timezone of the dashboard (or SSO token). This timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York. More info on timezone support in an (embedded) Luzmo dashboard can be found in this Academy article.

For all possible frontend component properties, check the Embedding chapter.

Set loader style

 You can specify the desired loader colors as rgb or rgba values in the relevant properties of the frontend component.

<luzmo-dashboard
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< SSO authorization key >"
  authToken="< SSO authorization token >"
  dashboardId="< dashboard id you want to embed >"
  loaderBackground="rgb(249, 249, 249)"
  loaderFontColor="rgb(0,0,0)"
  loaderSpinnerColor="rgba(255, 165, 0, 0.7)"
  loaderSpinnerBackground="rgba(169, 169, 169, 0.14)"
></luzmo-dashboard>

<luzmo-dashboard
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
  [authKey]="'< SSO authorization key >'"
  [authToken]="'< SSO authorization token >'"
  [dashboardId]="'< dashboard id you want to embed >'"
  [language]="'< Language code, e.g. 'en', 'fr', etc. >'"
  [timezoneId]="'< Timezone ID, e.g. 'Europe/Brussels', 'America/New_York', etc. >'"
  [loaderBackground]="'rgb(249, 249, 249)'"
  [loaderFontColor]="'rgb(0,0,0)'"
  [loaderSpinnerColor]="'rgba(255, 165, 0, 0.7)'"
  [loaderSpinnerBackground]="'rgba(169, 169, 169, 0.14)'"
></luzmo-dashboard>

import { LuzmoDashboardComponent } from '@luzmo/react-embed';
...

  function LuzmoWrapper() {
    ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        ref={ref}
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        loaderBackground="rgb(249, 249, 249)"
        loaderFontColor="rgb(0,0,0)"
        loaderSpinnerColor="rgba(255, 165, 0, 0.7)"
        loaderSpinnerBackground="rgba(169, 169, 169, 0.14)"
      ></LuzmoDashboardComponent>
    );
  }

import LuzmoDashboardComponent from '@luzmo/react-native-embed';
...

  function LuzmoWrapper() {
    ...

    /*
    Clients on our US multi-tenant application environment,
    or a dedicated instance on a specific VPC, should specify:
    - appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
    - apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
    */
    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        loaderBackground="rgb(249, 249, 249)"
        loaderFontColor="rgb(0,0,0)"
        loaderSpinnerColor="rgba(255, 165, 0, 0.7)"
        loaderSpinnerBackground="rgba(169, 169, 169, 0.14)"
      ></LuzmoDashboardComponent>
    );
  }

<template>
  ...

  <!--
  Clients on our US multi-tenant application environment,
  or a dedicated instance on a specific VPC, should specify:
  - :appServer="https://app.us.luzmo.com/" (or your VPC-specific address)
  - :apiHost="https://api.us.luzmo.com/" (or your VPC-specific address)
   -->
  <luzmo-dashboard
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< SSO authorization key >"
    authToken="< SSO authorization token >"
    dashboardId="< dashboard id you want to embed >"
    loaderBackground="rgb(249, 249, 249)"
    loaderFontColor="rgb(0,0,0)"
    loaderSpinnerColor="rgba(255, 165, 0, 0.7)"
    loaderSpinnerBackground="rgba(169, 169, 169, 0.14)"
  ></luzmo-dashboard>
</template>

When you load a page that has an embedded dashboard or chart, a few resources will need to be retrieved, and access to the dashboard needs to be verified. During this process, a loading indicator is shown.

This loader can be completely customized to match the styling of your website or platform.
You can change the color of the background, the color of the font, the color of the spinner itself, and the background of the spinner.

These colors can be specified in rgb or rgba values. For example: for the color red, the rgb value is rgb(255, 0, 0) and the rgba value is rgba(255, 0, 0, 1).

Parameter	Description
appServer string	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost string	Tenancy of Luzmo API to connect to. Defaults to 'https://api.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://api.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey uuid	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken string	The authorization token from the response of the authorization request in your backend.
dashboardId uuid	This is the id of the dashboard that you want to embed.
loaderBackground string	(optional) The background color of the container while loading the dashboard. This property should be specified as a string of rgb or rgba values, e.g. `"rgb(50,50,50)"`, `"rgba(50,50,50, 0.5)"`, etc.
loaderFontColor string	(optional) The font color of the message(s) while loading the dashboard. This property should be specified as a string of rgb or rgba values, e.g. `"rgb(50,50,50)"`, `"rgba(50,50,50, 0.5)"`, etc.
loaderSpinnerColor string	(optional) The color of the spinner while loading the dashboard. This property should be specified as a string of rgb or rgba values, e.g. `"rgb(50,50,50)"`, `"rgba(50,50,50, 0.5)"`, etc.
loaderSpinnerBackground string	(optional) The background color of the spinner while loading the dashboard. This property should be specified as a string of rgb or rgba values, e.g. `"rgb(50,50,50)"`, `"rgba(50,50,50, 0.5)"`, etc.

Embed a single dashboard item

<luzmo-dashboard
  appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
  apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
  authKey="< SSO authorization key >"
  authToken="< SSO authorization token >"
  dashboardId="< dashboard id you want to embed >"
  itemId="< an id of a Luzmo item within the dashboard >"
></luzmo-dashboard>

<luzmo-dashboard
  [appServer]="'< Luzmo App server, defaults to https://app.luzmo.com >'"
  [apiHost]="'< Luzmo API server, defaults to https://api.luzmo.com >'"
  [authKey]="'< SSO authorization key >'"
  [authToken]="'< SSO authorization token >'"
  [dashboardId]="'< dashboard id you want to embed >'"
  [itemId]="'< an id of a Luzmo item within the dashboard >'"
></luzmo-dashboard>

import { LuzmoDashboardComponent } from '@luzmo/react-embed';
...

  function LuzmoWrapper() {
    ...

    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        itemId="< an id of a Luzmo item within the dashboard >"
      ></LuzmoDashboardComponent>
    );
  }

import LuzmoDashboardComponent from '@luzmo/react-native-embed';
...

  function LuzmoWrapper() {
    ...

    return (
      <LuzmoDashboardComponent
        appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
        apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
        authKey="< SSO authorization key >"
        authToken="< SSO authorization token >"
        dashboardId="< dashboard id you want to embed >"
        itemId="< an id of a Luzmo item within the dashboard >"
      ></LuzmoDashboardComponent>
    );
  }

<template>
  ...
  <luzmo-dashboard
    appServer="< Luzmo App server, defaults to https://app.luzmo.com >"
    apiHost="< Luzmo API server, defaults to https://api.luzmo.com >"
    authKey="< SSO authorization key >"
    authToken="< SSO authorization token >"
    dashboardId="< dashboard id you want to embed >"
    itemId="< an id of a Luzmo item within the dashboard >"
  ></luzmo-dashboard>
</template>

It is possible to embed only a certain dashboard item instead of a specific dashboard. Next to specifying a dashboardId or dashboardSlug, you can specify the id of the item within the dashboard in the itemId property of the frontend component. The embedded dashboard item will automatically resize based on the parent container's width and height!

Parameter	Description
appServer string	Tenancy of Luzmo app to connect to. Defaults to 'https://app.luzmo.com/'. For US multi-tenant application, set `appServer` to 'https://app.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
apiHost string	Tenancy of Luzmo API to connect to. Defaults to 'https://api.luzmo.com/'. For US multi-tenant application, set `apiHost` to 'https://api.us.luzmo.com/'. For dedicated VPC environments, you should point towards your VPC-specific address.
authKey uuid	The authorization key (i.e. "id") from the response of the authorization request in your backend.
authToken string	The authorization token from the response of the authorization request in your backend.
dashboardId uuid	This is the id of the dashboard that you want to embed.
itemId uuid	(Optional) In case you want to embed a single item of a dashboard, you should specify a dashboardId or dashboardSlug, together with this `itemId` property set to the id of the item that you want to embed. The embedded dashboard item will automatically resize based on the parent container's width and height.

For all possible parameters, check the Embed documentation.

Retrieving a dashboard id

The dashboard id is a unique identifier for that dashboard.

You can retrieve the id of a dashboard in the 'settings' tab of the dashboard editor, on the right hand side of the screen.
At the bottom of the tab, you will find the dashboard id.

Retrieving a dataset id

The dataset id is a unique identifier for that dataset.

You can retrieve the id of a dataset in the 'data' tab of the dashboard editor, on the right hand side of the screen.
At the bottom of the tab, you will find the dataset id.

Retrieving a column id

The column id is a unique identifier for that column.

You can retrieve the id of a dataset column in the dataset preview board by clicking on the gear wheel next to the column name.

Secondly, you can also retrieve the Column ID from a widget, by hovering over the widget and clicking the table icon that appears next to it. You will now see an overview of all slots (columns) used in this chart. Click the gear icon next to the slot you want to know the id of, and then click the grey info circle.
At the bottom of the modal, you can find the column ID. Additionally, you can also find the dataset ID here.

Retrieving a chart id

The chart id is a unique identifier for that chart.

You can retrieve the id of a chart by hovering over the chart and clicking the gear icon that appears next to it. By doing this you will enter the item settings.
At the bottom of the tab, you will find the chart id.

Retrieving a connection id

The connection id is a unique identifier for that connection. A connection contains the information that is necessary to access a certain plugin or database.

You can retrieve the id of an connection in the Connections tab of the side menu.

Retrieving an integration id

The integration id is a unique identifier for the integration. You can retrieve the uuid of an integration in the Integrations overview in our UI as shown below.

Invalidating SSO tokens

   Invalidating a SSO token

private Luzmo tempClient = new Luzmo("< SSO key >","< SSO token >", "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

tempClient.delete("authorization", "< SSO key >");

   Invalidating a SSO token

Luzmo tempclient = new Luzmo("< SSO key >", "< SSO token >");

$tempClient->delete("authorization", "< SSO key >");

   Invalidating a SSO token

var tempclient = new Luzmo({
    api_key: "< SSO key >",
    api_token: "< SSO token >",
    host: "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >"
  });

let promise = tempClient.delete("authorization", "< SSO key >");

   Invalidating a SSO token

<?php
$tempclient = Luzmo::initialize("< SSO key >", "< SSO token >");

$tempClient->delete("authorization", "< SSO key >");
?>

   Invalidating a SSO token

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "delete",
  "key": "< SSO key >",
  "token": "< SSO token >",
  "version": "0.1.0",
  "id": "< SSO key >"
}
EOF

   Invalidating a SSO token

from luzmo.luzmo import Luzmo

key = "< SSO key >"
token = "< SSO token >"

client = Luzmo(key, token)

tempClient.delete("authorization", "< SSO key >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

A SSO token can only be invalidated by the SSO token itself.

You can invalidate the SSO authorization tokens that you requested in step 1 at any moment, before their specified expiry time.

Interacting with data

Connecting

   In curl, there is no need for an initial authentication. Use your API key & token in every API call.

   Replace with your API key and token.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >"
});

   Replace with your API key and token.

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);
?>

   Replace with your API key and token.

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

   Replace with your API key and token.

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

   Replace with your API key and token.

from luzmo.luzmo import Luzmo
client = Luzmo("< Your API key >","< Your API token >")

To get started, please make sure you have installed and are using the correct SDK for your preferred programming language. More info on how to connect and the different SDKs available can be found here.

Retrieving datasets/dashboards

Retrieving all columns of a particular dataset

   Replace with your API key & token and a valid dataset id.

curl https://api.luzmo.com/0.1.0/securable \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "version": "0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "find": {
    "where": {
      "id": "< your dataset id >",
      "type": "dataset"
    },
    "include":
      [{
       "model": "Column",
       "attributes": ["name", "type"]
      }],
    "attributes": ["name", "rows", "created_at"]
  }
}
EOF

   Replace with your API key & token and a valid dataset id.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >"
});

let promise = client.get("securable",
  {
    where: {
      id: "< your dataset id >"
      type: "dataset"
    },
    attributes: ["name", "rows", "created_at"],
    include:
      [{
      model: "Column",
      attributes: ["name", "type"]
      }],
  }
)
  .then(function (data) {
    console.log("Success!", data);
  })
  .catch(function (error) {
    console.error("API error:", error);
  })

   Replace with your API key & token and a valid dataset id.

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$data = $client->get("securable", array(
  "where" => array(
    "id" => "< your dataset id >",
    "type" => "dataset",
  ),
  "attributes" => array("name", "rows", "created_at"),
  "include" => array(array(
    "model" => "Column",
    "attributes" => array(
      "name",
      "type")
    ))
  )
);

print_r($data);
?>

   Replace with your API key & token and a valid dataset id.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

private JSONObject data = client.get("securable", ImmutableMap.of(
    "where", ImmutableMap.of(
      "id", "< your dataset id >"
      "type", "dataset",
    ),
    "attributes", ImmutableList.of("name", "rows", "created_at"),
    "include", ImmutableList.of(
      ImmutableMap.of(
        "model", "Column",
        "attributes", ImmutableList.of("name", "type")
      )
    )
  )
);

System.out.println(data.toString(2));

   Replace with your API key & token and a valid dataset id.

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

filter = new ExpandoObject();
filter.where = new {
  id = "< your dataset id >",
  type = "dataset"
};
filter.attributes = new List<String> {
  "name", "rows", "created_at"
};
filter.include = new List<dynamic> {
  new {
    model = "Column",
    attributes = new List<String> {
      "name", "type"
    }
  }
};
dynamic data = client.get("securable", filter);
Console.WriteLine(data);

   Replace with your API key & token and a valid dataset id.

data = client.get("securable", {
    "where": {
      "type": "dataset",
      "id": "your dataset id"
    },
    "include": [{
      "model": "Column",
      "attributes": ["name", "type"]
    }],
    "attributes": ["name", "rows", "created_at"]
})

This code example returns the name, number of rows and creation date of a specified dataset. Additionally, it returns the name and datatype of all its associated columns.

For an overview of all possible parameters of the dataset entity, please refer to the full specification.

For an overview of all possible parameters of the column entity, please refer to the full specification.

Parameter	Description
where object	(optional) A condition the entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response. To filter on columns of type date, pass your dates in the yyyy-MM-dd'T'HH:mm:ss.SSS format.
attributes array[string]	(optional) The attributes of the entity to be included. If this parameter is omitted, all attributes will be included in the response.
include array[object]	(optional)
model string	The name of an associated entity to be included. A full list of API entities and its associated entities can be found in the Core API section.
attributes array[string]	(optional) The attributes of the associated entity to be included in the response. If this parameter is omitted, all attributes will be included in the response.
where object	(optional) A condition the associated entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response.

Retrieving a list of all your dashboards

   Replace with your API key & token.

curl https://api.luzmo.com/0.1.0/securable \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "version": "0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "find": {
    "attributes": ["id", "name", "contents"],
    "include":
      [{
      "model": "Thumbnail",
      "attributes": ["url"],
      "where": {
        "size": "512px"
      }
      }],
    "type": "dashboard"
  }
}
EOF

   Replace with your API key & token.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >",
});

let promise = client
  .get("securable", {
    attributes: ["name", "contents", "id"],
    include: [
      {
        model: "Thumbnail",
        attributes: ["url"],
        where: {
          size: "512px",
        },
      },
    ],
    type: "dashboard",
  })
  .then(function (data) {
    console.log("Success!", data);
  })
  .catch(function (error) {
    console.error("API error:", error);
  });

   Replace with your API key & token.

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$data = $client->get("securable", array(
  "type" => "dashboard",
  "attributes" => array("name", "contents", "id"),
  "include" => array(array(
    "model" => "Thumbnail",
    "attributes" => array("url"),
    "where" => array(
      "size" => "512px")
    ))
  )
);

print_r($data);
?>

   Replace with your API key & token.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

private JSONObject data = client.get("securable", ImmutableMap.of(
    "type", "dashboard",
    "attributes", ImmutableList.of("name", "contents", "id"),
    "include", ImmutableList.of(
      ImmutableMap.of(
        "model", "Thumbnail",
        "attributes", ImmutableList.of("url"),
        "where", ImmutableMap.of(
          "size", "512px"
        )
      )
    )
  )
);

System.out.println(data.toString(2));

   Replace with your API key & token.

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

filter = new ExpandoObject();
filter.type = "dashboard";
filter.attributes = new List<String> {
  "name", "contents", "id"
};
filter.include = new List<dynamic> {
  new {
    model = "Thumbnail",
    attributes = new List<String> {
      "url"
    },
    where = new {
      size = "512px"
    }
  }
};
dynamic data = client.get("securable", filter);
Console.WriteLine(data);

To retrieve a full list of a certain entity, simply omit the where parameter from your request.

In this particular example, we will use an API call to return a list of the id's, names and contents of all dashboards in your Luzmo account.

Additionally, if applicable, for every dashboard the URL of the 512px dashboard thumbnail is added to the returned data.

This examples shows that you can also use a where specifier in the include parameter.

For an overview of all possible parameters of the dashboard entity, please refer to the full specification.

Parameter	Description
type string	The type of securable to be retrieved. Can be `dashboard` or `dataset`.
where object	(optional) A condition the entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response. To filter on columns of type date, pass your dates in the yyyy-MM-dd'T'HH:mm:ss.SSS format.
attributes array[string]	(optional) The attributes of the entity to be included. If this parameter is omitted, all attributes will be included in the response.
include array[object]	(optional)
model string	The name of an associated entity to be included. A full list of API entities and its associated entities can be found in the Core API section.
attributes array[string]	(optional) The attributes of the associated entity to be included in the response. If this parameter is omitted, all attributes will be included in the response.
where object	(optional) A condition the associated entity should fulfill. This condition can be specified on any field of the entity. If this parameter is omitted, no filtering will be applied and all matches will be included in the response.

Creating datasets automatically

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample

JSONObject data = client.create("data",

  ImmutableMap.of(
    "type" , "create",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "Chicken baconito ",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "Quesarito",
        "3.5",
        "700",
        "menu"
      )
    ),
    "options" , ImmutableMap.of(
      "update-metadata" , "true",
      "header" , ImmutableList.of(
        "Burrito",
        "price",
        "weight",
        "order type"
      ),
      "name" , ImmutableMap.of(
        "en" , "Burritos"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample

client.create('data',
  {
    type: 'create',
    data: [
        [
            'Chicken baconito ',
            3,
            500,
            'menu'
        ],
        [
            'Quesarito',
            3.5,
            700,
            'menu'
        ]
    ],
    options: {
        'update-metadata': 'true',
        header: [
            'Burrito',
            'price',
            'weight',
            'order type'
        ],
        name: {
            en: 'Burritos'
        }
    }
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample

curl https://api.luzmo.com/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "type": "create",
  "data": [
    [
      "Chicken baconito ",
      3,
      500,
      "menu"
    ],
    [
      "Quesarito",
      3.5,
      700,
      "menu"
    ]
  ],
  "options": {
    "update-metadata": "true",
    "header": [
      "Burrito",
      "price",
      "weight",
      "order type"
    ],
    "name": {
      "en": "Burritos"
    }
  }
}
}
EOF

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample

<?php
$data = $client->create('data',

  array (
    'type' => 'create',
    'data' => array (

      array (
        'Chicken baconito ',
        '3',
        '500',
        'menu'
      ),

      array (
        'Quesarito',
        '3.5',
        '700',
        'menu'
      )
    ),
    'options' => array (
      'update-metadata' => 'true',
      'header' => array (
        'Burrito',
        'price',
        'weight',
        'order type'
      ),
      'name' => array (
        'en' => 'Burritos'
      )
    )
  )

);
print("Success! { $data }");
?>

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample

dynamic properties = new ExpandoObject();
properties.type = "create";
properties.data = new List<Object> {

      new List<Object> {
        "Chicken baconito ",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "Quesarito",
        "3.5",
        "700",
        "menu"
      }
    };
properties.options = new {
      update-metadata = "true",
      header = new List<Object> {
        "Burrito",
        "price",
        "weight",
        "order type"
      },
      name = new {
        en = "Burritos"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

   Example of uploading data and creating the dataset + columns on the fly by detecting types from the sample

data = client.create("data",
{
    "type": "create",
    "data": [["Chicken baconito ",3,500,"menu"],["Quesarito",3.5,700,"menu"]],
    "options": {
      "update-metadata": "true",
      "header": ["Burrito","price","weight","order type"],
      "name": {
        "en": "Burritos"
      }
    }
})
print("Success! ", data)

It is possible in Luzmo to create a dataset programmatically by just sending a sample the 'data' endpoint.

In order to create it, the sample will be analyzed to determine the types of the different columns. To give names to your dataset and columns there is a header and a name option provided. The code sample on the right will create a new dataset and create 4 columns. To make sure that the types are detected correctly it is advised to send a good sample for the initial creation where each column has at least a few values.

Behind the scenes, this call is creating a securable and columns. In case you want full control on the creation of securables and columns you can also create them manually by following the Creating datasets manually guide.

Creating datasets manually

Creating a new dataset

   This code snippet creates a new dataset:

curl https://api.luzmo.com/0.1.0/securable \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "create",
  "version": "0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "properties": {
      "type": "dataset",
      "name": {
        "en": "< dataset name in English >",
        "fr": "< dataset name in French >"
    },
  "description": {
    "en": "< description in English >",
    "fr": "< description in French >"
  }
 }
}
EOF

   This code snippet creates a new dataset:

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >",
});

client
  .create("securable", {
    name: {
      en: "< dataset name in English >",
      fr: "< dataset name in French >",
      // optionally add more languages here...
    },
    description: {
      en: "< dataset description in English >",
      fr: "< dataset description in French >",
      // optionally add more languages here...
    },
    type: "dataset",
  })
  .then(function (dataset) {
    console.log("My new dataset id:", dataset.id);
  });

   This code snippet creates a new dataset:

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$securable = $client->create("securable", array(
  "type" => "dataset",
  "name" => array(
    "en" => "< dataset name in English >",
    "fr" => "< dataset name in French >"
  ),
  "description" => array(
    "en" => "< dataset description in English >",
    "fr" => "< dataset description in French >"
  )
));
?>

   This code snippet creates a new dataset:

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

private JSONObject securable = client.create("securable", ImmutableMap.of(
  "type", "dataset",
  "name", ImmutableMap.of(
    "en", "< dataset name in English >",
    "fr", "< dataset name in French >"
  ),
  "description", ImmutableMap.of(
    "en", "< dataset description in English >",
    "fr", "< dataset description in French >"
  )
));

   This code snippet creates a new dataset:

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "dataset";
properties.name = new {
  en = "< dataset name in English >",
  fr = "< dataset name in French >"
};
properties.description = new {
  en = "< dataset description in English >",
  fr = "< dataset description in French >"
};

dynamic securable = client.create("securable", properties);
Console.WriteLine("Dataset created with ID " + securable.id);

You can create datasets and their metadata programmatically via the API. In this case, we first build a new Securable (this is a dataset or dashboard).

The name and description are localized strings: use them to provide translations of dataset or dashboard titles, columns and other metadata. You can retrieve the most recent set languages from the locale entity.

For an explanation of the dataset entity and its possible parameters, please refer to the full specification.

Creating a column and immediately linking (associating) it with a dataset

   This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset:

curl https://api.luzmo.com/0.1.0/column \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
    "name": {
      "en": "< column name in English >",
      "fr": "< column name in French >"
    },
    "type": "hierarchy",
    "informat": "hierarchy",
    "order": 0,
    "color": "#45DE25"
  },
  "associations": [{
    "role": "Securable",
    "id": "< your dataset id >"
  }]
}
EOF

   This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset:

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >"
});

client.create("column",
 {
   name: {
     en: "< column name in English >",
     fr: "< column name in French >"
   },
   type: "hierarchy",
   informat: "hierarchy",
   order: 0,
   color: "#45DE25"
 },
 [{
   role: "Securable",
   id: "< your dataset id >"
 }]
)
 .then(...);

   This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset:

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$column = $client->create("column", array(
  "name" => array(
    "en" => "< column name in English >",
    "fr" => "< column name in French >"
  ),
  "type" => "hierarchy",
  "informat" => "hierarchy",
  "order" => 0,
  "color" => "#45DE25"),
  array(
    array(
    "role" => "Securable",
    "id" => "< your dataset id >"
    )
  )
);
?>

   This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset:

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

private JSONObject column = client.create("column", ImmutableMap.of(
  "name", ImmutableMap.of(
    "en", "< column name in English >",
    "fr", "< column name in French >"
  ),
  "type", "hierarchy",
  "informat", "hierarchy",
  "order", 0,
  "color", "#45DE25",
  ImmutableList.of(
    ImmutableMap.of(
      "role", "Securable",
      "id", "< your dataset id >"
    )
  )
)
);

   This code snippet creates a new column within a specified dataset, and immediately associates it with the specified dataset:

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.name = new {
  en = "< column name in English >",
  fr = "< column name in French >"
};
properties.type = "hierarchy";
properties.informat = "hierarchy";
properties.order = 0;
properties.color = "#45DE25";

associations = new List<ExpandoObject>();
dynamic association = new ExpandoObject();
association.role = "Securable";
association.id = "< your dataset id >"
associations.Add(association);

dynamic column = client.create("column", properties, associations);
Console.WriteLine("Column created with ID " + column.id + " and associated.");

After you have created a dataset, it is possible to create a new column and associate it to your dataset.

For an explanation of the column entity and its possible parameters, please refer to the full specification.

Linking (associating) a dataset and a column in a seperate call

   This code snippet associates the specified column with a specified dataset.

curl https://api.luzmo.com/0.1.0/column \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "associate",
  "version": "0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "id": "< your column id >",
  "resource": {
    "role": "Securable",
    "id": "< your dataset id >"
  }
}
EOF

   This code snippet associates the specified column with a specified dataset.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >",
});

client.associate("securable", "< your dataset id >", {
  role: "Columns",
  id: "< your column id >",
});

   This code snippet associates the specified column with a specified dataset.

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$securable = $client->associate(
  "securable",
  "< your dataset id >",
  "Columns",
  "< your column id >");
?>

   This code snippet associates the specified column with a specified dataset.

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

client.associate("column", "< your column id >", "securable", "< your dataset id >");

   This code snippet associates the specified column with a specified dataset.

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

client.associate("column", "< your column id >", "securable", "< your dataset id >", new ExpandoObject());

Alternatively, you could explicitly associate both new entities at a later time.

You can do this by using the associate action on the Column entity, and specifying an instance of a Securable entity as the resource parameter.

Pushing data

   Example of appending data to an existing dataset

JSONObject data = client.create("data",

  ImmutableMap.of(
    "securable_id" , "< Your securable id >",
    "type" , "append",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "Fresh new burrito ",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "Guacarrito",
        "3.5",
        "700",
        "menu"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Example of appending data to an existing dataset

client.create('data',
  {
    securable_id: '< Your securable id >',
    type: 'append',
    data: [
        [
            'Fresh new burrito ',
            3,
            500,
            'menu'
        ],
        [
            'Guacarrito',
            3.5,
            700,
            'menu'
        ]
    ]
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example of appending data to an existing dataset

curl https://api.luzmo.com/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "securable_id": "< Your securable id >",
  "type": "append",
  "data": [
    [
      "Fresh new burrito ",
      3,
      500,
      "menu"
    ],
    [
      "Guacarrito",
      3.5,
      700,
      "menu"
    ]
  ]
}
}
EOF

   Example of appending data to an existing dataset

<?php
$data = $client->create('data',

  array (
    'securable_id' => '< Your securable id >',
    'type' => 'append',
    'data' => array (

      array (
        'Fresh new burrito ',
        '3',
        '500',
        'menu'
      ),

      array (
        'Guacarrito',
        '3.5',
        '700',
        'menu'
      )
    )
  )

);
print("Success! { $data }");
?>

   Example of appending data to an existing dataset

dynamic properties = new ExpandoObject();
properties.securable_id = "< Your securable id >";
properties.type = "append";
properties.data = new List<Object> {

      new List<Object> {
        "Fresh new burrito ",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "Guacarrito",
        "3.5",
        "700",
        "menu"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

   Example of appending data to an existing dataset

data = client.create("data",
{
    "securable_id": "< Your securable id >",
    "type": "append",
    "data": [["Fresh new burrito ",3,500,"menu"],["Guacarrito",3.5,700,"menu"]]
})
print("Success! ", data)

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced.

JSONObject data = client.create("data",

  ImmutableMap.of(
    "securable_id" , "< Your securable id >",
    "type" , "replace",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "New collection Guacarrito",
        "3",
        "500",
        "menu"
      ),

      ImmutableList.of(
        "New collection Quasarito",
        "3.5",
        "700",
        "menu"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced.

client.create('data',
  {
    securable_id: '< Your securable id >',
    type: 'replace',
    data: [
        [
            'New collection Guacarrito',
            3,
            500,
            'menu'
        ],
        [
            'New collection Quasarito',
            3.5,
            700,
            'menu'
        ]
    ]
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced.

curl https://api.luzmo.com/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "securable_id": "< Your securable id >",
  "type": "replace",
  "data": [
    [
      "New collection Guacarrito",
      3,
      500,
      "menu"
    ],
    [
      "New collection Quasarito",
      3.5,
      700,
      "menu"
    ]
  ]
}
}
EOF

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced.

<?php
$data = $client->create('data',

  array (
    'securable_id' => '< Your securable id >',
    'type' => 'replace',
    'data' => array (

      array (
        'New collection Guacarrito',
        '3',
        '500',
        'menu'
      ),

      array (
        'New collection Quasarito',
        '3.5',
        '700',
        'menu'
      )
    )
  )

);
print("Success! { $data }");
?>

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced.

dynamic properties = new ExpandoObject();
properties.securable_id = "< Your securable id >";
properties.type = "replace";
properties.data = new List<Object> {

      new List<Object> {
        "New collection Guacarrito",
        "3",
        "500",
        "menu"
      },

      new List<Object> {
        "New collection Quasarito",
        "3.5",
        "700",
        "menu"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

   Example of replacing data in an existing dataset. The columns will remain the same but the data will be completely replaced.

data = client.create("data",
{
    "securable_id": "< Your securable id >",
    "type": "replace",
    "data": [["New collection Guacarrito",3,500,"menu"],["New collection Quasarito",3.5,700,"menu"]]
})
print("Success! ", data)

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset

JSONObject data = client.create("data",

  ImmutableMap.of(
    "securable_id" , "< Your securable id >",
    "type" , "append",
    "data" , ImmutableList.of(

      ImmutableList.of(
        "Fresh new burrito ",
        "3",
        "500",
        "menu",
        "newColumndata"
      ),

      ImmutableList.of(
        "Guacarrito",
        "3.5",
        "700",
        "menu",
        "newColumndata"
      )
    ),
    "options" , ImmutableMap.of(
      "update_metadata" , true,
      "header" , ImmutableList.of(
        "Burrito",
        "price",
        "weight",
        "order type",
        "newColumn"
      ),
      "name" , ImmutableMap.of(
        "en" , "Updated Burritos Name"
      )
    )
  ));
System.out.println("Success! %s%n", data);

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset

client.create('data',
  {
    securable_id: '< Your securable id >',
    type: 'append',
    data: [
        [
            'Fresh new burrito ',
            3,
            500,
            'menu',
            'newColumnData'
        ],
        [
            'Guacarrito',
            3.5,
            700,
            'menu',
            'newColumnData'
        ]
    ],
    options: {
        update_metadata: true,
        header: [
            'Burrito',
            'price',
            'weight',
            'order type',
            'newColumn'
        ],
        name: {
            en: 'Updated Burritos Name'
        }
    }
}

)
  .then(function(data) {
    console.log('Success!', data);
  });

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset

curl https://api.luzmo.com/0.1.0/data  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "securable_id": "< Your securable id >",
  "type": "append",
  "data": [
    [
      "Fresh new burrito ",
      3,
      500,
      "menu",
      "newColumndata"
    ],
    [
      "Guacarrito",
      3.5,
      700,
      "menu",
      "newColumndata"
    ]
  ],
  "options": {
    "update_metadata": true,
    "header": [
      "Burrito",
      "price",
      "weight",
      "order type",
      "newColumn"
    ],
    "name": {
      "en": "Updated Burritos Name"
    }
  }
}
}
EOF

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset

<?php
$data = $client->create('data',

  array (
    'securable_id' => '< Your securable id >',
    'type' => 'append',
    'data' => array (

      array (
        'Fresh new burrito ',
        '3',
        '500',
        'menu',
        'newColumnData'
      ),

      array (
        'Guacarrito',
        '3.5',
        '700',
        'menu',
        'newColumnData'
      )
    ),
    'options' => array (
      'update_metadata' => true,
      'header' => array (
        'Burrito',
        'price',
        'weight',
        'order type',
        'newColumn'
      ),
      'name' => array (
        'en' => 'Updated Burritos Name'
      )
    )
  )

);
print("Success! { $data }");
?>

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset

dynamic properties = new ExpandoObject();
properties.securable_id = "< Your securable id >";
properties.type = "append";
properties.data = new List<Object> {

      new List<Object> {
        "Fresh new burrito ",
        "3",
        "500",
        "menu",
        "newColumndata"
      },

      new List<Object> {
        "Guacarrito",
        "3.5",
        "700",
        "menu",
        "newColumndata"
      }
    };
properties.options = new {
      update_metadata = true,
      header = new List<Object> {
        "Burrito",
        "price",
        "weight",
        "order type",
        "newColumn"
      },
      name = new {
        en = "Updated Burritos Name"
      }
    };

dynamic data = client.create("data",    properties);
Console.WriteLine("Success!", data);

   Append data to a dataset by using 'update_metadata: true' with a header with a different set of columns. Given that there are  4 columns (Burrito, price, weight, order type), this call would introduce a new column 'newColumn' and remove weight and order type. Careful. This will delete the data from these two columns. You can also opt to update the name fo the dataset

data = client.create("data",
{
    "securable_id": "< Your securable id >",
    "type": "append",
    "data": [["Fresh new burrito ",3,500,"menu","newColumndata"],["Guacarrito",3.5,700,"menu","newColumndata"]],
    "options": {
      "update_metadata": True,
      "header": ["Burrito","price","weight","order type","newColumn"],
      "name": {
        "en": "Updated Burritos Name"
      }
    }
})
print("Success! ", data)

Regardless of how you created the dataset and columns (manually or automatically) you can append or replace the data by providing the securable_id and setting the type to 'append' or 'replace' as shown in the second and third example on the right. As long as the update_metadata boolean is disabled, this will never change anything to your columns. Setting the type to replace will replace the data in the dataset. Every row in your data parameter should have exactly the same amount of entries as there are columns in your dataset. For more information on how to find the id of a dataset, please refer to this section.

When pushing data, the dashboards that are viewing this data will be automatically brought up to date.

In case you want to automatically add/remove/update columns (use this with care), you can set the 'update_metadata' boolean to true. For example, in the third example on the right, two columns are removed and a new column is added.

Querying data

Simple example

   Replace with your own API key & token, a valid dataset id and valid column id's.

curl https://api.luzmo.com/0.1.0/data \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "version": "0.1.0",
  "key":  "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "find": {
    "dimensions": [{
      "column_id": "Type of burrito column id",
      "dataset_id": "< your dataset id >"
    }],
    "measures": [{
      "column_id": "Number burritos savoured column id",
      "dataset_id": "< your dataset id >"
    }]
  }
}
EOF

   Replace with your own API key & token, a valid dataset id and valid column id's.

client
  .query({
    dimensions: [
      {
        column_id: "Type of burrito column id",
        dataset_id: "< your dataset id >",
      },
    ],
    measures: [
      {
        column_id: "Number burritos savoured column id",
        dataset_id: "< your dataset id >",
      },
    ],
  })
  .then(function (data) {
    console.log("Result set: ", data.data);
    // Prints: [["spicy", 1256],
    //          ["sweet",  913]]
  });

   Replace with your own API key & token, a valid dataset id and valid column id's.

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$data = $client->query(
  array(
    "dimensions" => array(array(
      "column_id" => "Type of burrito column id",
      "dataset_id" => "< your dataset id >"
    )),
    "measures" => array(array(
      "column_id" => "Number burritos savoured column id",
      "dataset_id" => "< your dataset id >"
    ))
  )
);

print_r($data);
// Prints: [["spicy", 1256],
//          ["sweet",  913]]
?>

   Replace with your own API key & token, a valid dataset id and valid column id's.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

private JSONObject data = client.query(
  ImmutableMap.of(
    "dimensions", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Type of burrito column id",
        "dataset_id", "< your dataset id >"
      )
    ),
    "measures", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Number of burritos savoured column id",
        "dataset_id", "< your dataset id >"
      )
    )
  )
);

System.out.println(data.toString(2));
// Prints: [["spicy", 1256],
//          ["sweet",  913]]

   Replace with your own API key & token, a valid dataset id and valid column id's.

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

query = new ExpandoObject();
query.type = "dashboard";
query.dimensions = new List<dynamic> {
  new {
    column_id = "Type of burrito column id",
    dataset_id = "< your dataset id >"
  }
};
query.measures = new List<dynamic> {
  new {
    column_id = "Number burritos savoured column id",
    dataset_id = "< your dataset id >"
  }
};

dynamic data = client.query(query);
Console.WriteLine(data);
// Prints: [["spicy", 1256],
//          ["sweet",  913]]

Just like the charts on your dashboards request data in real-time, you can interrogate your data within the platform as well.

For example, to retrieve the total number of burritos savoured per type of burrito.

Advanced example

   Replace with your own API key & token, a valid dataset id and valid column id's.

curl https://api.luzmo.com/0.1.0/data \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "version": "0.1.0",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "find": {
    "dimensions": [{
      "column_id": "Burrito weight column id",
      "dataset_id": "< your dataset id >",
      "discretization": {
        "type": "linear",
        "bins": "10"
      }
    }],
    "measures": [{
      "column_id": "Number burritos savoured column id",
      "dataset_id": "< your dataset id >",
      "aggregation": {
        "type": "sum"
      }
    }],
    "where": [{
      "expression": "? = ?",
      "parameters": [{
        "column_id": "Type of burrito column id",
        "dataset_id": "< your dataset id >"
      },
      "spicy"
      ]
    }],
    "order": [{
      "column_id": "Number burritos savoured column id",
      "dataset_id": "< your dataset id >",
      "aggregation": {
        "type": "sum"
      },
      "order": "desc"
    }],
    "limit": {
      "by": 5
    }
  }
}
EOF

   Replace with your own API key & token, a valid dataset id and valid column id's.

client
  .query({
    dimensions: [
      {
        column_id: "Burrito weight column id",
        dataset_id: "< your dataset id >",
        discretization: {
          type: "linear",
          bins: 10,
        },
      },
    ],
    measures: [
      {
        column_id: "Number burritos savoured column id",
        dataset_id: "< your dataset id >",
        aggregation: {
          type: "sum",
        },
      },
    ],
    where: [
      {
        expression: "? = ?",
        parameters: [
          {
            column_id: "Type of burrito column id",
            dataset_id: "< your dataset id >",
          },
          "spicy",
        ],
      },
    ],
    order: [
      {
        column_id: "Number burritos savoured column id",
        dataset_id: "< your dataset id >",
        aggregation: {
          type: "sum",
        },
        order: "desc",
      },
    ],
    limit: {
      by: 5,
    },
  })
  .then(function (data) {
    console.log("Result set:", data.data);
    // Prints: [["[ 100 - 150 [", 125],
    //            ["[ 150 - 200 [", 121]]
  });

   Replace with your own API key & token, a valid dataset id and valid column id's.

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$data = $client->query(
  array(
    "dimensions" => array(
      array(
        "column_id" => "Burrito weight id column id",
        "dataset_id" => "< your dataset id >",
        "discretization" => array(
          "type" => "linear",
          "bins" => 10
        )
      )
    ),
    "measures" => array(
      array(
        "column_id" => "Number burritos savoured column id",
        "dataset_id" => "< your dataset id >",
        "aggregation" => array(
          "type" => "sum"
        )
      )
    ),
    "where" => array(
      array(
        "expression" => "? = ?",
        "parameters" => array(
          array(
            "column_id" => "Type of burrito column id",
            "dataset_id" => "< your dataset id >"
          ),
        "spicy"
        )
      )
    ),
    "order" => array(
      array(
        "column_id" => "Number burritos savoured column id",
        "dataset_id" => "< your dataset id >",
        "order" => "desc",
        "aggregation" => array(
          "type" => "sum"
        )
      )
    ),
    "limit" => array(
      "by" => 5
    )
  )
);

print_r($data);
// Prints: [["[ 100 - 150 [", 125],
//            ["[ 150 - 200 [", 121]]
?>

   Replace with your own API key & token, a valid dataset id and valid column id's.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

private JSONObject data = client.query(
  ImmutableMap.of(
    "dimensions", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Burrito weight id column id",
        "dataset_id", "< your dataset id >",
        "discretization", ImmutableMap.of(
          "type", "linear",
          "bins", 10
        )
      )
    ),
    "measures", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Number of burritos savoured column id",
        "dataset_id", "< your dataset id >",
        "aggregation" = new {
          "type"= "sum"
        }
      )
    ),
    "where", ImmutableList.of(
      ImmutableMap.of(
        "expression", "? = ?",
        "parameters", ImmutableList.of(
          ImmutableMap.of(
            "column_id", "Type of burrito column id",
            "dataset_id", "< your dataset id >"
          ),
          "spicy"
        )
      )
    ),
    "order", ImmutableList.of(
      ImmutableMap.of(
        "column_id", "Number of burritos savoured column id",
        "dataset_id", "< your dataset id >",
        "aggregation" = new {
          "type"= "sum"
        },
        "order", "desc"
      )
    ),
    "limit", ImmutableMap.of(
      "by", 5
    )
  )
);

System.out.println(data.toString(2));
// Prints: [["[ 100 - 150 [", 125],
//          ["[ 150 - 200 [", 121]]

   Replace with your own API key & token, a valid dataset id and valid column id's.

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

query = new ExpandoObject();
query.type = "dashboard";
query.dimensions = new List<dynamic> {
  new {
    column_id = "Burrito weight column id",
    dataset_id = "< your dataset id >",
    discretization = new {
      type = "linear",
      bins = 10
    }
  }
};
query.measures = new List<dynamic> {
  new {
    column_id = "Number burritos savoured column id",
    dataset_id = "< your dataset id >"
  }
};
query.where = new List<dynamic> {
  new {
    expression = "? = ?",
    parameters = new List<dynamic> {
      new {
        column_id = "Type of burrito column id",
        dataset_id = "< your dataset id >"
      },
      "spicy"
    }
  }
}
query.order = new List<dynamic> {
  new {
    column_id = "Number burritos savoured column id",
    dataset_id = "< your dataset id >",
    order = "desc"
  }
}
query.limit = new {
  by = 5
}

dynamic data = client.query(query);
Console.WriteLine(data);
// Prints: [["[ 100 - 150 [", 125],
//          ["[ 150 - 200 [", 121]]

A more elaborate example: let’s record the weight per burrito as another numeric measure.

We want the weights to be classified in 10 equal sized bins, for example [50, 100[ grams, [100, 150[ grams. These bins will be made by equally dividing the range between the minimum and maximum values in the column specified.

Now we want to retrieve the top 5 weight classes by number of burritos savoured, but only for burritos that are of the type ‘spicy’.

discretization with bins is currently only supported on datasets stored in our OLAP (i.e. locally uploaded datasets). You can disable the binning of numeric columns by setting discretization to type "none".

External data changes

   This code snippet notifies Luzmo that a dataset has changed via an external source:

curl https://api.luzmo.com/0.1.0/data \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "update",
  "version": "0.1.0",
  "key":"$LUZMO_API_KEY",
  "token":"$LUZMO_API_TOKEN",
  "id": "< your dataset id >"
}
EOF

   This code snippet notifies Luzmo that a dataset has changed via an external source:

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: "< your API key >",
  api_token: "< your API token >",
});

client.update("data", "< your dataset id >");

   This code snippet notifies Luzmo that a dataset has changed via an external source:

<?php
$client = Luzmo::initialize(
  "< your API key >",
  "< your API token >"
);

$client->update("data", "< your dataset id >", array());
?>

   This code snippet notifies Luzmo that a dataset has changed via an external source:

import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

client.update("data", "< your dataset id >", ImmutableMap.of()));

   This code snippet notifies Luzmo that a dataset has changed via an external source:

Luzmo client = new Luzmo("< Your API key >", "< Your API token >");

client.update("data", "< your dataset id >", new ExpandoObject());

When you push data points into a dataset that is stored in Luzmo, all dashboards are brought up-to-date immediately. To also have real-time updates to dashboards that use data providers like relational databases, you can notify Luzmo when data changes via the Update action on the Data entity.

For example, you can do this call from within your RDBMS with a trigger on update, eg. via curl.

Core API

Introduction

This document describes the Core API which is also used by the Luzmo application. As a client, you have access to the same API that we used to build Luzmo. That means that you can automate everything:

Access rights management to dashboards/datasets for users/groups/organizations.
Loading and synchronization of datasets and setting up database connections.
Create hierarchies or add translations for existing datasets.
Set up automatic reporting schedules.
Script dashboards, or use the query API to drive a custom dashboard component.

The Core API uses REST with default HTTP verbs and JSON Content.

Connect

The API is available via WebSocket or via REST. We provide several client libraries for different languages.

Token

In order to send requests to our API, you will first need to create an API key and API token. You can get these here. Your API key and token should always be stored securely and stay private: this token pair should be considered your username and password to Luzmo!
There are multiple types of tokens; for more information about each token or how to create them programmatically, refer to the Authorization Resource.

SDKs

   Connect to the REST API

var Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
  api_key: '< your API key >',
  api_token: '< your API token >',
  host: '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >'
});

   Connect to the REST API

Luzmo client = new Luzmo(
  "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
  "< your API key >",
  "< your API token >"
);

   Connect to the REST API

<?php
$client = Luzmo::initialize(
  '< your API key >',
  '< your API token >',
  '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >'
);
?>

   Connect to the REST API

export $LUZMO_API_KEY="your-api-key"
export $LUZMO_API_TOKEN="your-api-token"

curl https://api.luzmo.com/0.1.0/<entity>  -H "Content-Type: application/json" -d @- << EOF
{
 "action": "<your-action>",
 "key": "$LUZMO_API_KEY",
 "token": "$LUZMO_API_TOKEN",
 "version": "0.1.0",
 ...
}
EOF

or

curl https://api.us.luzmo.com/0.1.0/<entity>  -H "Content-Type: application/json" -d @- << EOF
{
 "action": "<your-action>",
 "key": "$LUZMO_API_KEY",
 "token": "$LUZMO_API_TOKEN",
 "version": "0.1.0",
 ...
}
EOF

   Connect to the REST API

export $LUZMO_API_KEY="your-api-key"
export $LUZMO_API_TOKEN="your-api-token"

curl https://api.luzmo.com/0.1.0/<entity>  -H "Content-Type: application/json" -d @- << EOF
{
 "action": "<your-action>",
 "key": "$LUZMO_API_KEY",
 "token": "$LUZMO_API_TOKEN",
 "version": "0.1.0",
 ...
}
EOF

or

curl https://api.us.luzmo.com/0.1.0/<entity>  -H "Content-Type: application/json" -d @- << EOF
{
 "action": "<your-action>",
 "key": "$LUZMO_API_KEY",
 "token": "$LUZMO_API_TOKEN",
 "version": "0.1.0",
 ...
}
EOF

   Connect to the REST API

Luzmo client = new Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

   Connect to the REST API

from luzmo.luzmo import Luzmo
client = Luzmo("< Your API key >","< Your API token >",
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

The libraries below are built around the REST API. The code and installation instructions for each language can be found in the respective README file:

Node.js

npm & GitHub

PHP

Packagist & GitHub

Java

Maven & GitHub

Nuget & GitHub

Python

PyPI & GitHub

These libraries require a connection step where you provide the api key and token to get started. Sometimes the token has to be one for a specific user. For example binding a locale to a User requires you to be owner of that user. You can take ownership by using the login/api token of that specific user.

You can also access our API without a library using pure rest calls in which case you have to pass the api key and token on each call. For pure REST examples you can refer to the curl examples.

Schema

Below you can see the resources that can be accessed/created/updated/deleted via the API and how they are connected to each other:

The graph shows which resources can be associated/dissociated. When resources are associated, you can include the associated resource in a get or query request.

Actions

The core API defines actions that can be called on the resources. The api call of a specific action is standardized which means that you access each resource in a similar way. In total, 6 types of actions are defined:

Create

Get

List

Update

Delete

Associate

Dissociate

Not every action is supported on every resource (e.g. you can not delete a Dataprovider). The rest of this documentation will provide information on the call signature for each action and will then go into details with concrete examples for each combination of resource and action.

Create

   Create general Signature

JSONObject < resource name > = client.create("< resource name >",

  ImmutableMap.of(
    "attribute name" , "<attribute value>"
  ),
  ImmutableList.of(

    ImmutableMap.of(
      "role" , "<resource to link name>",
      "id" , "<resource entity id>"
    ),

    ImmutableMap.of(
      "role" , "<resource to link name>",
      "id" , "<resource entity id>"
    )
  ));
System.out.println("Success! %s%n", < resource name >);

   Create general Signature

dynamic properties = new ExpandoObject();
properties.attribute name = "<attribute value>";

dynamic < resource name > = client.create("< resource name >",    properties);
Console.WriteLine("Success!", < resource name >);

   Create general Signature

client.create('< resource name >',
  {
    'attribute name': '<attribute value>'
},
  [ {
    role: '<resource to link name>',
    id: '<resource entity id>'
},{
    role: '<resource to link name>',
    id: '<resource entity id>'
} ]
)
  .then(function(< resource name >) {
    console.log('Success!', < resource name >);
  });

   Create general Signature

<?php
$< resource name > = $client->create('< resource name >',

  array (
    'attribute name' => '<attribute value>'
  ),

  array (

    array (
      'role' => '<resource to link name>',
      'id' => '<resource entity id>'
    ),

    array (
      'role' => '<resource to link name>',
      'id' => '<resource entity id>'
    )
  )
);
print("Success! { $< resource name > }");
?>

   Create general Signature

curl https://api.luzmo.com/0.1.0/< resource name > \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "attribute name": "<attribute value>"
},
  "associations": [
  {
    "role": "<resource to link name>",
    "id": "<resource entity id>"
  },
  {
    "role": "<resource to link name>",
    "id": "<resource entity id>"
  }
]
}
EOF

   Create general Signature

resource_name = client.create("resource_name",
{
    "attribute name": "<attribute value>"
},[{
    "role": "<resource to link name>",
    "id": "<resource entity id>"
},{
    "role": "<resource to link name>",
    "id": "<resource entity id>"
}])
print("Success! ", resource_name)

Create a new instance of the requested resource type, for example: create a new User within an Organization, create a new access group, create new data rows, …

Parameter

Description

resource:

string

The lowercase name of the resource we want to create

properties:

object

Here you provide the properties of the entity you want to create in the form of a map/object

Update

   Update general Signature

JSONObject < resource name > = client.update("< resource name >", "<your < resource name > id>", 
  ImmutableMap.of(
    "attribute name" , "<attribute value>"
  ));

   Update general Signature

dynamic properties = new ExpandoObject();
properties.attribute name = "<attribute value>";

dynamic < resource name > = client.update("< resource name >", "<your < resource name > id>", );

   Update general Signature

client.update('< resource name >',
  '<your < resource name > id>',
  {
    'attribute name': '<attribute value>'
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Update general Signature

<?php
$user = $client->update('< resource name >', '<your < resource name > id>', 
  array (
    'attribute name' => '<attribute value>'
  ));
?>

   Update general Signature

curl https://api.luzmo.com/0.1.0/< resource name > \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "update",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>",
  "properties": {
  "attribute name": "<attribute value>"
}
}
EOF

   Update general Signature

resource_name = client.update("resource_name", "<your_resource_name_id>", {
    "attribute name": "<attribute value>"
})

Update the properties of a single specific entity, eg. update a column name or user password.

Parameter

Description

Resource

string

The lowercase name of the resource we want to update

uuid

The id of the entity to update

Properties

object

Here you provide the properties of the entity you want to update in the form of a map/object. If a property is not present in the map, it will remain untouched

Delete

   Delete general Signature

client.delete("< resource name >", "<your < resource name > id>");

   Delete general Signature

$client->delete("< resource name >", "<your < resource name > id>");

   Delete general Signature

let promise = client.delete('< resource name >', '<your < resource name > id>');

   Delete general Signature

<?php
$client->delete('< resource name >', '<your < resource name > id>');
?>

   Delete general Signature

curl https://api.luzmo.com/0.1.0/< resource name > \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "delete",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>"
}
EOF

   Delete general Signature

client.delete("resource_name", "<your_resource_name_id>")

Delete a resource, eg. delete a dataset or group.

Parameter

Description

Resource

string

The lowercase name of the resource we want to delete

uuid

The id of the entity to delete

Get & List

   Get general Signature

JSONObject data = client.get("< resource name >", 
  ImmutableMap.of(
    "where" , ImmutableMap.of(
      "attribute name" , "<attribute value>"
    ),
    "include" , ImmutableList.of(

      ImmutableMap.of(
        "model" , "<resource name>"
      )
    ),
    "attributes" , ImmutableList.of(
      "<attribute name>",
      "<attribute name>"
    ),
    "order" , ImmutableList.of(

      ImmutableList.of(
        "<attribute name>",
        "asc"
      ),

      ImmutableList.of(

        ImmutableMap.of(
          "model" , "<resource name>"
        ),
        "<attribute name>",
        "asc"
      )
    )
  ));

   Get general Signature

dynamic query = new ExpandoObject();
query.where = new {
      attribute name = "<attribute value>"
    };
query.include = new List<Object> {

      new {
        model = "<resource name>"
      }
    };
query.attributes = new List<Object> {
      "<attribute name>",
      "<attribute name>"
    };
query.order = new List<Object> {

      new List<Object> {
        "<attribute name>",
        "asc"
      },

      new List<Object> {

        new {
          model = "<resource name>"
        },
        "<attribute name>",
        "asc"
      }
    };

dynamic data = client.get("< resource name >",     query);

   Get general Signature

client.get('< resource name >', {
    where: {
        'attribute name': '<attribute value>'
    },
    include: [
        {
            model: '<resource name>'
        }
    ],
    attributes: [
        '<attribute name>',
        '<attribute name>'
    ],
    order: [
        [
            '<attribute name>',
            'asc'
        ],
        [
            {
                model: '<resource name>'
            },
            '<attribute name>',
            'asc'
        ]
    ]
})
  .then(function(data) {
    console.log('Success!', data);
  });

   Get general Signature

<?php
$user = $client->get('< resource name >', 
  array (
    'where' => array (
      'attribute name' => '<attribute value>'
    ),
    'include' => array (

      array (
        'model' => '<resource name>'
      )
    ),
    'attributes' => array (
      '<attribute name>',
      '<attribute name>'
    ),
    'order' => array (

      array (
        '<attribute name>',
        'asc'
      ),

      array (

        array (
          'model' => '<resource name>'
        ),
        '<attribute name>',
        'asc'
      )
    )
  ));

?>

   Get general Signature

curl https://api.luzmo.com/0.1.0/< resource name > \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "get",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "find": {
  "where": {
    "attribute name": "<attribute value>"
  },
  "include": [
    {
      "model": "<resource name>"
    }
  ],
  "attributes": [
    "<attribute name>",
    "<attribute name>"
  ],
  "order": [
    [
      "<attribute name>",
      "asc"
    ],
    [
      {
        "model": "<resource name>"
      },
      "<attribute name>",
      "asc"
    ]
  ]
}
}
EOF

   Get general Signature

data = client.get("resource_name", {
    "where": {
      "attribute name": "<attribute value>"
    },
    "include": [{
      "model": "<resource name>"
    }],
    "attributes": ["<attribute name>","<attribute name>"],
    "order": [["<attribute name>","asc"],[{
      "model": "<resource name>"
    },"<attribute name>","asc"]]
})

Get and List are the same call. The reason why we differentiate between a Get and a List action is that different security rules apply. A user who can get a resource can't necessarily list the same resource. Get and List have a different structure than the other calls since it allows for complex queries. A call is considered to be a get action if you fetch an entity using a specific id in the where clause, else it is considered to be a list action. The query syntax is very close to SQL, it consists of the following attributes:

Parameter

Description

resource:

string

The lowercase name of the resource we want to get or list

query:

object

A query object consisting of SQL-like keywords such as: where, include, attributes, order

attributes:

string[]

instead of returning all attributes, limit the set of attributes to the given list

where:

object[]

Filter the selection, each where statement has to match

include:

object[]

embed a connected object in the results, within an include you can again use where, include, attributes

order:

array[]

Order on attributes. Either provide only an attribute and 'desc' or 'asc' to filter on a top-level attribute. or provide models in the beginning of the array if you want to target the attribute of an embedded resource.

Associate

   Associate general Signature

client.associate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>", 
  ImmutableMap.of(
    "property name" , "<property value>"
  ) );

   Associate general Signature

dynamic properties = new ExpandoObject();
properties.property name = "<property value>";

client.associate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>",     properties );

   Associate general Signature

let promise = client.associate('< resource name >', '<your < resource name > id>', {
    role: '<resource to link name>',
    id: '<resource entity id>'
}, {
    'property name': '<property value>'
} );

   Associate general Signature

<?php
$client->associate('< resource name >', '<your < resource name > id>', '<resource to link name>', '<resource entity id>', , 
  array (
    'property name' => '<property value>'
  ) );
?>

   Associate general Signature

curl https://api.luzmo.com/0.1.0/< resource name > \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "associate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>",
  "resource": {
  "role": "<resource to link name>",
  "id": "<resource entity id>"
},
  "properties": {
  "property name": "<property value>"
}
}
EOF

   Associate general Signature

client.associate("resource_name", "<your_resource_name_id>", "role":"<resource to link name>","id":"<resource entity id>", {
    "property name": "<property value>"
} )

Associate two entities to each other, eg. link a Column to a Dataset. Associations can be set in both directions. Many associations are automatically set on creation as well, for example a dashboard is automatically associated with the user that created the dashboard. To know which resources can be associated please refer to the schema at the beginning of this chapter Schema).

Parameter

Description

id:

uuid

The uuid of the resource you want to associate with another resource

resource:

object

An object indicating which resource type (role) and which entity (id)

role:

string

the role of the to-be-associated resource which is usually the capitalized plural name of the resource e.g. 'Users', 'Organizations'

id:

uuid

the id of the to-be-associated resource

properties:

object

some associations can have property set on them. e.g. on a User - Dataset relationship, there is a flagOwner property

Dissociate

   Dissociate general Signature

client.dissociate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>");

   Dissociate general Signature

client.dissociate("< resource name >", "<your < resource name > id>", "<resource to link name>", "<resource entity id>");

   Dissociate general Signature

let promise = client.dissociate('< resource name >', '<your < resource name > id>', {
    role: '<resource to link name>',
    id: '<resource entity id>'
});

   Dissociate general Signature

<?php
$client->associate('< resource name >', '<your < resource name > id>', "<resource to link name>", "<resource entity id>");
?>

   Dissociate general Signature

curl https://api.luzmo.com/0.1.0/< resource name > \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action": "dissociate",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your < resource name > id>",
  "resource": {
  "role": "<resource to link name>",
  "id": "<resource entity id>"
}
}
EOF

   Dissociate general Signature

client.dissociate("resource_name", "<your_resource_name_id>", "role":"<resource to link name>","id":"<resource entity id>")

Remove an association between 2 entities. To know which resources can be disassociated please refer to the schema at the beginning of this chapter Schema).

Parameter

Description

id:

uuid

The uuid of the resource you want to dissociate with another resource

resource:

object

An object indicating which resource type (role) and which entity (id)

role:

string

the role of the to-be-dissociated resource which is usually the capitalized plural name of the resource e.g. 'Users', 'Organizations'

id:

uuid

the id of the to-be-dissociated resource

Resources

Account

Accounts contain the information necessary to access a certain plugin (e.g. Teamleader, Google Drive, your own custom plugin, etc..) or database The easiest to understand what a plugin is to show you what part of the UI makes an account (see the screenshot below). When you add a database connection and click 'connect' an account is created to make sure you can connect when you retrieve datasets later on.

Note that accounts employ a general terminology to accommodate both different plugins as dataproviders. Eg. a token in Luzmo terminology corresponds to a 'password' in a DB, where a scope in Luzmo terminology refers to the 'database' in a db which can have a different meaning in a plugin.

Properties

Parameter

Description

uuid

Unique key of the account (automatically assigned)

provider

string

Type of data provider to retrieve data from. Either the 'slug' of a plugin, e.g. googleanalytics, googledrive, quandl, salesforce, mailchimp, etc... the slug of your own plugin or one of a database such as 'postgresql'. Slugs are unique short names for plugins and dataproviders (such as dbs)

date

datetime

Date/time this account was linked by the user. Defaults to the current date.

expiry

datetime

Expiry date of the credentials.

scope

string

Provider-specific description of services used (eg. which accesses were granted, which database is used, ...).

host

string

Endpoint of this account. For relational database connections, this corresponds to the hostname of the database.

active

boolean

Indicates whether queries may be sent to this database or plugin connection. You can use this field to eg. temporarily disable any connections / queries. This might be useful in case of elevated stress on your systems.

invalid

boolean

Read-only. Indicates whether this connection has been disabled because the source system reported that the used credentials are invalid.

token

boolean

Token or password of this account.

identifier

string

Key or username of this account.

cache

integer

Defaults to 0. Number of seconds queries to this data connector are cached in Luzmo's caching layer. Use 0 to disable caching for this connector entirely. Note that queries might still not be cached if there are other uncached data connectors called in a query. You can invalidate the cache before the expiry time by calling the update method on the data endpoint.

code

string

(Update-only) OAauth2 authorization code used to retrieve an access token and refresh token.

Actions

Create

Update

Get

List

Delete

Action: Create

   Accounts are linked to users on creation

JSONObject account = client.create("account",

  ImmutableMap.of(
    "provider" , "postgresql",
    "host" , "<host address / ip>",
    "port" , "5432",
    "scope" , "<your database name>",
    "identifier" , "<username>",
    "token" , "<password>"
  ));
System.out.printf("Account id: %s%n", account.get("id"));

   Accounts are linked to users on creation

dynamic properties = new ExpandoObject();
properties.provider = "postgresql";
properties.host = "<host address / ip>";
properties.port = "5432";
properties.scope = "<your database name>";
properties.identifier = "<username>";
properties.token = "<password>";

dynamic account = client.create("account",    properties);

 Console.WriteLine("Account id is {0}", account["id"]);

   Accounts are linked to users on creation

client.create('account',
  {
    provider: 'postgresql',
    host: '<host address / ip>',
    port: 5432,
    scope: '<your database name>',
    identifier: '<username>',
    token: '<password>'
}

)
  .then(function(account) {
    var account_id = account.id;
  });

   Accounts are linked to users on creation

<?php
$account = $client->create('account',

  array (
    'provider' => 'postgresql',
    'host' => '<host address / ip>',
    'port' => '5432',
    'scope' => '<your database name>',
    'identifier' => '<username>',
    'token' => '<password>'
  )

);
print( $account['id'] );
?>

   Accounts are linked to users on creation

curl https://api.luzmo.com/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "provider": "postgresql",
  "host": "<host address / ip>",
  "port": 5432,
  "scope": "<your database name>",
  "identifier": "<username>",
  "token": "<password>"
}
}
EOF
# result format of the account contains the account id 
{
 ... 
 "id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

   Accounts are linked to users on creation

account = client.create("account",
{
    "provider": "postgresql",
    "host": "<host address / ip>",
    "port": 5432,
    "scope": "<your database name>",
    "identifier": "<username>",
    "token": "<password>"
})
user = account["user_id"]

Create

can be executed by:

Logged-in User

Action: Update

   Update the credentials of an account

JSONObject account = client.update("account", "<your account id>", 
  ImmutableMap.of(
    "identifier" , "<username>",
    "token" , "<password>"
  ));

   Update the credentials of an account

dynamic properties = new ExpandoObject();
properties.identifier = "<username>";
properties.token = "<password>";

dynamic account = client.update("account", "<your account id>", );

   Update the credentials of an account

client.update('account',
  '<your account id>',
  {
    identifier: '<username>',
    token: '<password>'
}
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Update the credentials of an account

<?php
$user = $client->update('account', '<your account id>', 
  array (
    'identifier' => '<username>',
    'token' => '<password>'
  ));
?>

   Update the credentials of an account

curl https://api.luzmo.com/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your account id>",
  "properties": {
  "identifier": "<username>",
  "token": "<password>"
}
}
EOF

   Update the credentials of an account

account = client.update("account", "<your_account_id>", {
    "identifier": "<username>",
    "token": "<password>"
})

Update

can be executed by:

Account Owner

Action: Get

   Retrieve all your accounts

JSONObject data = client.get("account", 
  ImmutableMap.of(

  ));

   Retrieve all your accounts

dynamic query = new ExpandoObject();

dynamic data = client.get("account",     query);

   Retrieve all your accounts

client.get('account', {})
  .then(function(data) {
    console.log('Success!', data);
  });

   Retrieve all your accounts

<?php
$user = $client->get('account', 
  array (

  ));

?>

   Retrieve all your accounts

curl https://api.luzmo.com/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "find": {}
}
EOF

   Retrieve all your accounts

data = client.get("account", {

})

Get

can be executed by:

Account Reader

List

can be executed by:

Account Reader

Retrieving accounts.

Action: Delete

   Delete an account

client.delete("account", "<your account id>");

   Delete an account

$client->delete("account", "<your account id>");

   Delete an account

let promise = client.delete('account', '<your account id>');

   Delete an account

<?php
$client->delete('account', '<your account id>');
?>

   Delete an account

curl https://api.luzmo.com/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your account id>"
}
EOF

   Delete an account

client.delete("account", "<your_account_id>")

Delete

can be executed by:

Account Owner

Delete is the same for each resource, the only parameters required are the resource type and the uuid of the entity you want to delete.

Associations

As can be seen from the schema, accounts are only linked to users. This link to accounts is created automatically so you will never associate an account manually.

Associate: User (implicit)

   Accounts are linked to users on creation

JSONObject account = client.create("account",

  ImmutableMap.of(
    "provider" , "postgresql",
    "host" , "<host address / ip>",
    "port" , "5432",
    "scope" , "<your database name>",
    "identifier" , "<username>",
    "token" , "<password>"
  ));
System.out.printf("User id: %s%n", account.get("user_id"));

   Accounts are linked to users on creation

dynamic properties = new ExpandoObject();
properties.provider = "postgresql";
properties.host = "<host address / ip>";
properties.port = "5432";
properties.scope = "<your database name>";
properties.identifier = "<username>";
properties.token = "<password>";

dynamic account = client.create("account",    properties);

 Console.WriteLine("User id is {0}", account["user_id"]);

   Accounts are linked to users on creation

client.create('account',
  {
    provider: 'postgresql',
    host: '<host address / ip>',
    port: 5432,
    scope: '<your database name>',
    identifier: '<username>',
    token: '<password>'
})
  .then(function(account) {
    var user = account.user_id;
  });

   Accounts are linked to users on creation

<?php
$account = $client->create('account',

  array (
    'provider' => 'postgresql',
    'host' => '<host address / ip>',
    'port' => '5432',
    'scope' => '<your database name>',
    'identifier' => '<username>',
    'token' => '<password>'
  )

);
print( $account['user_id'] );
?>

   Accounts are linked to users on creation

curl https://api.luzmo.com/0.1.0/account  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
    "provider": "postgresql",
    "host": "<host address / ip>",
    "port": 5432,
    "scope": "<your database name>",
    "identifier": "<username>",
    "token": "<password>"
  } 
}
EOF
# result format of the account contains the user_id 
{
 ... 
 "user_id": "301ca544-b8c4-42c7-8da1-ff2d76351020",
...
}

User

Account

Associate

requires:

Account Owner

and

User Owner

This is a special case similar to many entities that are linked to user. The association to the creating user is automatically added when a new account is created.

Alert

Alerts allow a user to be notified when some interesting condition on their data is met. A simple example is an email send to the sales team when the quarterly sales target has been exceeded.

The core elements of an alert are the query that checks the condition and the communication channels through which a notification will be send.

The query can be any valid query that could be send to the data service. When the query returns at least one row, the condition is assumed to have been met and the alert is fired.

A single alert can have multiple configured channels. Each will receive a message when the alert fires. Currently only email is supported as a channel, but more will follow.

Properties

Parameter

Description

uuid

Unique key of the alert (automatically assigned)

name

localized

Title of the alert

query

json

The query to execute

frequency

json

Defines the frequency at which the condition is checked. Consists of a json object containing 2 properties: 'unit'(minute, hour, day, week, month, quarter, year) and 'quantity'

channels

json

Array of channel configurations

Actions

Create

Update

Get

List

Delete

Action: Create

   Alerts are linked to users on creation

JSONObject account = client.create("alert",

  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "<title of your alert>"
    ),
    "query", ImmutableMap.of(
      "dimensions" , ImmutableList.of(

        ImmutableMap.of(
          "dataset_id" , "< Burrito dataset id >",
          "column_id" , "< Type of burrito column id >"
        )
      ),
      "measures" , ImmutableList.of(

        ImmutableMap.of(
          "dataset_id" , "< Burrito dataset id >",
          "column_id" , "< Number of burritos column id >",
          "aggregation" , ImmutableMap.of(
            "type" , "sum"
          )
        )
      ),
      "where" , ImmutableList.of(

        ImmutableMap.of(
          "expression" , "? in ?",
          "parameters" , ImmutableList.of(

            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Type of burrito column id >"
            ),
            ImmutableList.of("Quesarito", "Chicken baconito")
          )
        )
      ),
      "having", ImmutableList.of(

        ImmutableMap.of(
          "expression" , "? >= ?",
          "parameters" , ImmutableList.of(
            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Sold units column id >"
              aggregation: {
                type: 'sum'
              }
            ),
            10000
          )
        )
      )
    ),
    "frequency", ImmutableMap.of(
      "unit", "day",
      "quantity", 1 
    ),
    "channels, ImmutableList.of(
      ImmutableMap.of(
        "type", "email",
        "config", ImmutableMap.of(
          "recipients", ImmutableList.of(
            "address", "user@organization.com",
            "type", "to",
            "locale", "en"
          ),
          "subject", ImmutableMap.of(
            "en", "Great sales!"
          ),
          "message", ImmutableMap.of(
            "en", "We've done great boys! Check out these numbers!"
          )
        )
      )
    )
  )
);

   Alerts are linked to users on creation

dynamic properties = new ExpandoObject();
properties.name = new {
  en = "<title of your alert>"
};
properties.query = new {
  dimensions = new List<Object> {
    new {
      dataset_id = "< Burrito dataset id >",
      column_id = "< Type of burrito column id >"
    }
  },
  measures = new List<Object> {
    new {
      dataset_id = "< Burrito dataset id >",
      column_id = "< Number of burritos column id >",
      aggregation = new {
        type = "sum"
      }
    }
  },
  where = new List<Object> {
    new {
      expression = "? in ?",
      parameters = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_i = "< Type of burrito column id >"
        },
        new List<Object>{'Quesarito', 'Chicken baconito'}
      }
    }
  },
  having = new List<Object> {
    new {
      expression = "? >= ?",
      parameters = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_id = "< Sold units column id >",
          aggregation = new {
            type = "sum"
          }
        },
        10000
      }
    }
  }
};
properties.frequency = new {
  unit = "day",
  quantity = 1
};
properties.channels = new List<Object> {
  new {
    type = "email",
    config = new {
      recipients = new List<Object> {
        new {
          address = "user@organization.com",
          type = "to",
          locale = "en"
        }
      },
      subject = new {
        en = "Great sales!"
      },
      message = new {
        en: "We've done great boys! Check out these numbers!"
      }
    }
  }
};

dynamic alert = client.create("alert", properties);

   Alerts are linked to users on creation

client.create('account',
  {
    name: { en: '<title of your alert>' },
    query: {
    dimensions: [
      {
        dataset_id: '< Burrito dataset id >',
        column_id: '< Type of burrito column id >'
      }
    ],
    measures: [
      {
        dataset_id: '< Burrito dataset id >',
        column_id: '< Number of burritos column id >',
        aggregation: {
          type: 'sum'
        }
      }
    ],
    where: [
      {
        expression: '? in ?',
        parameters: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Type of burrito column id >'
          },
          ['Quesarito', 'Chicken baconito']
        ]
      }
    ],
    having: [
      {
        expression: '? >= ?',
        parameters: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Sold units column id >',
            aggregation: {
              type: 'sum'
            }
          },
          10000
        ]
      }
    ]
  },
    frequency: {
    unit: 'day',
    quantity: 1
  },
  channels: [
    {
      type: 'email',
      config: {
        recipients: [
          {
            address: 'user@organization.com',
            type: 'to',
            locale: 'en'
          }
        ],
        subject: {
          en: 'Great sales!'
        },
        message: {
          en: "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
}
);

   Alerts are linked to users on creation

<?php
$alert = $client->create('alert',
  array (
    'name' => array (
      'en' => '<title of your alert>'
    ),
    'query' => array (
      'dimensions' => array (
        array (
          'dataset_id' => '< Burrito dataset id >',
          'column_id' => '< Type of burrito column id >'
        )
      ),
      'measures' => array (
        array (
          'dataset_id' => '< Burrito dataset id >',
          'column_id' => '< Number of burritos column id >',
          'aggregation' => array (
            'type' => 'sum'
          )
        )
      ),
      'where' => array (
        array (
          'expression' => '? in ?',
          'parameters' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Type of burrito column id >'
            ),
            array ('Quesarito', 'Chicken baconito')
          )
        )
      ),
      'having' => array (
        array (
          'expression' => '? >= ?',
          'parameters' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Sold units column id >',
              'aggregation' => array (
                'type' => 'sum'
              )
            ),
          10000
          )
        )
      )
    )
    'frequency' => array (
      'unit' => 'day',
      'quantity' => 1
    ),
    'channels' => array (
      array (
        'type' => 'email',
        'config' => array (
          'recipients' => array (
            array (
              'address' => 'user@organization.com',
              'type' => 'to',
              'locale' => 'en'
            )
          ),
          'subject' => array (
            'en' => 'Great sales!'
          ),
          'message' => array (
            'en' => "We've done great boys! Check out these numbers!"
          )
        )
      )
    )
  )

);
?>

   Alerts are linked to users on creation

curl https://api.luzmo.com/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": { "en": "<title of your alert>" }
  "query": {
    "dimensions": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Type of burrito column id >"
      }
    ],
    "measures": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Number of burritos column id >",
        "aggregation": {
          "type": "sum"
        }
      }
    ],
    "where": [
      {
        "expression": "? in ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Type of burrito column id >"
          },
          ["Quesarito", "Chicken baconito"]
        ]
      }
    ],
    "having": [
      {
        "expression": "? >= ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Sold units column id >",
            "aggregation": {
              "type": "sum"
            }
          },
          10000
        ]
      }
    ]
  },
  "frequency": { "unit": "day", "quantity": 1 }
  "channels": [
    {
      "type": "email",
      "config": {
        "recipients": [
          {
            "address": "user@organization.com",
            "type": "to",
            "locale": "en"
          }
        ],
        "subject": {
          "en": "Great sales!"
        },
        "message": {
          "en": "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
}
}
EOF

Create

can be executed by:

Logged-in (SSO) User

Action: Update

   Update the frequency of an alert

JSONObject account = client.update("alert", "<your alert id>", 
  ImmutableMap.of(
    "frequency" , ImmutableMap.of(
      "unit", "week",
      "quantity", 1
    )
  ));

   Update the frequency of an alert

dynamic properties = new ExpandoObject();
properties.frequency = new {
  unit = "week",
  quantity = 1
};

dynamic account = client.update("alert", "<your alert id>", properties);

   Update the frequency of an alert

client.update('alert',
  '<your alert id>',
  {
    frequency: {
      unit: 'week',
      quantity: 1
    }
  }
)
  .then(function(data) {
    console.log('Success!', data);
  });

   Update the frequency of an alert

<?php
$user = $client->update('alert', '<your alert id>', 
  array (
    'frequency' => array (
      'unit' => 'week',
      'quantity' => 1
    )
  ));
?>

   Update the frequency of an alert

curl https://api.luzmo.com/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "update",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your alert id>",
  "properties": {
    "frequency": { "unit": "week", "quantity": 1 }
  }
}
EOF

Update

can be executed by:

Alert Owner

Action: Get

   Retrieve all your alerts

JSONObject data = client.get("alert", 
  ImmutableMap.of(

  ));

   Retrieve all your alerts

dynamic query = new ExpandoObject();

dynamic data = client.get("alert",     query);

   Retrieve all your alerts

client.get('alert', {})
  .then(function(data) {
    console.log('Success!', data);
  });

   Retrieve all your alerts

<?php
$user = $client->get('alert', 
  array (

  ));

?>

   Retrieve all your alerts

curl https://api.luzmo.com/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "get",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "find": {}
}
EOF

Get

can be executed by:

Alert Owner

List

can be executed by:

Alert Owner

Retrieving alerts.

Action: Delete

   Delete an alert

client.delete("alert", "<your alert id>");

   Delete an alert

$client->delete("alert", "<your alert id>");

   Delete an alert

let promise = client.delete('alert', '<your alert id>');

   Delete an alert

<?php
$client->delete('alert', '<your alert id>');
?>

   Delete an alert

curl https://api.luzmo.com/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "delete",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "id": "<your alert id>"
}
EOF

Delete

can be executed by:

Alert Owner

Delete is the same for each resource, the only parameters required are the resource type and the uuid of the entity you want to delete.

Associations

Alerts are implicitly associated with the User that created the alert and with a Schedule to trigger the alert.

Associate: Schedule (implicit)

   Schedules are automatically linked to the alert on creation time

JSONObject account = client.create("alert",

  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "<title of your alert>"
    ),
    "query", ImmutableMap.of(
      "dimensions" , ImmutableList.of(

        ImmutableMap.of(
          "dataset_id" , "< Burrito dataset id >",
          "column_id" , "< Type of burrito column id >"
        )
      ),
      "measures" , ImmutableList.of(

        ImmutableMap.of(
          "dataset_id" , "< Burrito dataset id >",
          "column_id" , "< Number of burritos column id >",
          "aggregation" , ImmutableMap.of(
            "type" , "sum"
          )
        )
      ),
      "where" , ImmutableList.of(

        ImmutableMap.of(
          "expression" , "? in ?",
          "parameters" , ImmutableList.of(

            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Type of burrito column id >"
            ),
            ImmutableList.of("Quesarito", "Chicken baconito")
          )
        )
      ),
      "having", ImmutableList.of(

        ImmutableMap.of(
          "expression" , "? >= ?",
          "parameters" , ImmutableList.of(
            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Sold units column id >"
              aggregation: {
                type: 'sum'
              }
            ),
            10000
          )
        )
      )
    ),
    "frequency", ImmutableMap.of(
      "unit", "day",
      "quantity", 1 
    ),
    "channels, ImmutableList.of(
      ImmutableMap.of(
        "type", "email",
        "config", ImmutableMap.of(
          "recipients", ImmutableList.of(
            "address", "user@organization.com",
            "type", "to",
            "locale", "en"
          ),
          "subject", ImmutableMap.of(
            "en", "Great sales!"
          ),
          "message", ImmutableMap.of(
            "en", "We've done great boys! Check out these numbers!"
          )
        )
      )
    )
  )
);

   Schedules are automatically linked to the alert on creation time

dynamic properties = new ExpandoObject();
properties.name = new {
  en = "<title of your alert>"
};
properties.query = new {
  dimensions = new List<Object> {
    new {
      dataset_id = "< Burrito dataset id >",
      column_id = "< Type of burrito column id >"
    }
  },
  measures = new List<Object> {
    new {
      dataset_id = "< Burrito dataset id >",
      column_id = "< Number of burritos column id >",
      aggregation = new {
        type = "sum"
      }
    }
  },
  where = new List<Object> {
    new {
      expression = "? in ?",
      parameters = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_i = "< Type of burrito column id >"
        },
        new List<Object>{'Quesarito', 'Chicken baconito'}
      }
    }
  },
  having = new List<Object> {
    new {
      expression = "? >= ?",
      parameters = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_id = "< Sold units column id >",
          aggregation = new {
            type = "sum"
          }
        },
        10000
      }
    }
  }
};
properties.frequency = new {
  unit = "day",
  quantity = 1
};
properties.channels = new List<Object> {
  new {
    type = "email",
    config = new {
      recipients = new List<Object> {
        new {
          address = "user@organization.com",
          type = "to",
          locale = "en"
        }
      },
      subject = new {
        en = "Great sales!"
      },
      message = new {
        en: "We've done great boys! Check out these numbers!"
      }
    }
  }
};

dynamic alert = client.create("alert", properties);

   Schedules are automatically linked to the alert on creation time

client.create('account',
  {
    name: { en: '<title of your alert>' },
    query: {
    dimensions: [
      {
        dataset_id: '< Burrito dataset id >',
        column_id: '< Type of burrito column id >'
      }
    ],
    measures: [
      {
        dataset_id: '< Burrito dataset id >',
        column_id: '< Number of burritos column id >',
        aggregation: {
          type: 'sum'
        }
      }
    ],
    where: [
      {
        expression: '? in ?',
        parameters: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Type of burrito column id >'
          },
          ['Quesarito', 'Chicken baconito']
        ]
      }
    ],
    having: [
      {
        expression: '? >= ?',
        parameters: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Sold units column id >',
            aggregation: {
              type: 'sum'
            }
          },
          10000
        ]
      }
    ]
  },
    frequency: {
    unit: 'day',
    quantity: 1
  },
  channels: [
    {
      type: 'email',
      config: {
        recipients: [
          {
            address: 'user@organization.com',
            type: 'to',
            locale: 'en'
          }
        ],
        subject: {
          en: 'Great sales!'
        },
        message: {
          en: "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
}
);

   Schedules are automatically linked to the alert on creation time

<?php
$alert = $client->create('alert',
  array (
    'name' => array (
      'en' => '<title of your alert>'
    ),
    'query' => array (
      'dimensions' => array (
        array (
          'dataset_id' => '< Burrito dataset id >',
          'column_id' => '< Type of burrito column id >'
        )
      ),
      'measures' => array (
        array (
          'dataset_id' => '< Burrito dataset id >',
          'column_id' => '< Number of burritos column id >',
          'aggregation' => array (
            'type' => 'sum'
          )
        )
      ),
      'where' => array (
        array (
          'expression' => '? in ?',
          'parameters' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Type of burrito column id >'
            ),
            array ('Quesarito', 'Chicken baconito')
          )
        )
      ),
      'having' => array (
        array (
          'expression' => '? >= ?',
          'parameters' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Sold units column id >',
              'aggregation' => array (
                'type' => 'sum'
              )
            ),
          10000
          )
        )
      )
    )
    'frequency' => array (
      'unit' => 'day',
      'quantity' => 1
    ),
    'channels' => array (
      array (
        'type' => 'email',
        'config' => array (
          'recipients' => array (
            array (
              'address' => 'user@organization.com',
              'type' => 'to',
              'locale' => 'en'
            )
          ),
          'subject' => array (
            'en' => 'Great sales!'
          ),
          'message' => array (
            'en' => "We've done great boys! Check out these numbers!"
          )
        )
      )
    )
  )

);
?>

   Schedules are automatically linked to the alert on creation time

curl https://api.luzmo.com/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": { "en": "<title of your alert>" }
  "query": {
    "dimensions": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Type of burrito column id >"
      }
    ],
    "measures": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Number of burritos column id >",
        "aggregation": {
          "type": "sum"
        }
      }
    ],
    "where": [
      {
        "expression": "? in ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Type of burrito column id >"
          },
          ["Quesarito", "Chicken baconito"]
        ]
      }
    ],
    "having": [
      {
        "expression": "? >= ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Sold units column id >",
            "aggregation": {
              "type": "sum"
            }
          },
          10000
        ]
      }
    ]
  },
  "frequency": { "unit": "day", "quantity": 1 }
  "channels": [
    {
      "type": "email",
      "config": {
        "recipients": [
          {
            "address": "user@organization.com",
            "type": "to",
            "locale": "en"
          }
        ],
        "subject": {
          "en": "Great sales!"
        },
        "message": {
          "en": "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
}
}
EOF

   Schedules are automatically linked to the alert on creation time

alert = client.create("alert",
{
    "name": { "en": "<title of your alert>" }
  "query": {
    "dimensions": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Type of burrito column id >"
      }
    ],
    "measures": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Number of burritos column id >",
        "aggregation": {
          "type": "sum"
        }
      }
    ],
    "where": [
      {
        "expression": "? in ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Type of burrito column id >"
          },
          ["Quesarito", "Chicken baconito"]
        ]
      }
    ],
    "having": [
      {
        "expression": "? >= ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Sold units column id >",
            "aggregation": {
              "type": "sum"
            }
          },
          10000
        ]
      }
    ]
  },
  "frequency": { "unit": "day", "quantity": 1 }
  "channels": [
    {
      "type": "email",
      "config": {
        "recipients": [
          {
            "address": "user@organization.com",
            "type": "to",
            "locale": "en"
          }
        ],
        "subject": {
          "en": "Great sales!"
        },
        "message": {
          "en": "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
})

Alert

Schedule

The association to the schedule is created automatically when an alert is made, this association cannot be created manually.

Associate: User (implicit)

   Alerts are automatically linked to the user on creation time

JSONObject account = client.create("alert",

  ImmutableMap.of(
    "name" , ImmutableMap.of(
      "en" , "<title of your alert>"
    ),
    "query", ImmutableMap.of(
      "dimensions" , ImmutableList.of(

        ImmutableMap.of(
          "dataset_id" , "< Burrito dataset id >",
          "column_id" , "< Type of burrito column id >"
        )
      ),
      "measures" , ImmutableList.of(

        ImmutableMap.of(
          "dataset_id" , "< Burrito dataset id >",
          "column_id" , "< Number of burritos column id >",
          "aggregation" , ImmutableMap.of(
            "type" , "sum"
          )
        )
      ),
      "where" , ImmutableList.of(

        ImmutableMap.of(
          "expression" , "? in ?",
          "parameters" , ImmutableList.of(

            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Type of burrito column id >"
            ),
            ImmutableList.of("Quesarito", "Chicken baconito")
          )
        )
      ),
      "having", ImmutableList.of(

        ImmutableMap.of(
          "expression" , "? >= ?",
          "parameters" , ImmutableList.of(
            ImmutableMap.of(
              "dataset_id" , "< Burrito dataset id >",
              "column_id" , "< Sold units column id >"
              aggregation: {
                type: 'sum'
              }
            ),
            10000
          )
        )
      )
    ),
    "frequency", ImmutableMap.of(
      "unit", "day",
      "quantity", 1 
    ),
    "channels, ImmutableList.of(
      ImmutableMap.of(
        "type", "email",
        "config", ImmutableMap.of(
          "recipients", ImmutableList.of(
            "address", "user@organization.com",
            "type", "to",
            "locale", "en"
          ),
          "subject", ImmutableMap.of(
            "en", "Great sales!"
          ),
          "message", ImmutableMap.of(
            "en", "We've done great boys! Check out these numbers!"
          )
        )
      )
    )
  )
);

   Alerts are automatically linked to the user on creation time

dynamic properties = new ExpandoObject();
properties.name = new {
  en = "<title of your alert>"
};
properties.query = new {
  dimensions = new List<Object> {
    new {
      dataset_id = "< Burrito dataset id >",
      column_id = "< Type of burrito column id >"
    }
  },
  measures = new List<Object> {
    new {
      dataset_id = "< Burrito dataset id >",
      column_id = "< Number of burritos column id >",
      aggregation = new {
        type = "sum"
      }
    }
  },
  where = new List<Object> {
    new {
      expression = "? in ?",
      parameters = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_i = "< Type of burrito column id >"
        },
        new List<Object>{'Quesarito', 'Chicken baconito'}
      }
    }
  },
  having = new List<Object> {
    new {
      expression = "? >= ?",
      parameters = new List<Object> {
        new {
          dataset_id = "< Burrito dataset id >",
          column_id = "< Sold units column id >",
          aggregation = new {
            type = "sum"
          }
        },
        10000
      }
    }
  }
};
properties.frequency = new {
  unit = "day",
  quantity = 1
};
properties.channels = new List<Object> {
  new {
    type = "email",
    config = new {
      recipients = new List<Object> {
        new {
          address = "user@organization.com",
          type = "to",
          locale = "en"
        }
      },
      subject = new {
        en = "Great sales!"
      },
      message = new {
        en: "We've done great boys! Check out these numbers!"
      }
    }
  }
};

dynamic alert = client.create("alert", properties);

   Alerts are automatically linked to the user on creation time

client.create('account',
  {
    name: { en: '<title of your alert>' },
    query: {
    dimensions: [
      {
        dataset_id: '< Burrito dataset id >',
        column_id: '< Type of burrito column id >'
      }
    ],
    measures: [
      {
        dataset_id: '< Burrito dataset id >',
        column_id: '< Number of burritos column id >',
        aggregation: {
          type: 'sum'
        }
      }
    ],
    where: [
      {
        expression: '? in ?',
        parameters: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Type of burrito column id >'
          },
          ['Quesarito', 'Chicken baconito']
        ]
      }
    ],
    having: [
      {
        expression: '? >= ?',
        parameters: [
          {
            dataset_id: '< Burrito dataset id >',
            column_id: '< Sold units column id >',
            aggregation: {
              type: 'sum'
            }
          },
          10000
        ]
      }
    ]
  },
    frequency: {
    unit: 'day',
    quantity: 1
  },
  channels: [
    {
      type: 'email',
      config: {
        recipients: [
          {
            address: 'user@organization.com',
            type: 'to',
            locale: 'en'
          }
        ],
        subject: {
          en: 'Great sales!'
        },
        message: {
          en: "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
}
);

   Alerts are automatically linked to the user on creation time

<?php
$alert = $client->create('alert',
  array (
    'name' => array (
      'en' => '<title of your alert>'
    ),
    'query' => array (
      'dimensions' => array (
        array (
          'dataset_id' => '< Burrito dataset id >',
          'column_id' => '< Type of burrito column id >'
        )
      ),
      'measures' => array (
        array (
          'dataset_id' => '< Burrito dataset id >',
          'column_id' => '< Number of burritos column id >',
          'aggregation' => array (
            'type' => 'sum'
          )
        )
      ),
      'where' => array (
        array (
          'expression' => '? in ?',
          'parameters' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Type of burrito column id >'
            ),
            array ('Quesarito', 'Chicken baconito')
          )
        )
      ),
      'having' => array (
        array (
          'expression' => '? >= ?',
          'parameters' => array (
            array (
              'dataset_id' => '< Burrito dataset id >',
              'column_id' => '< Sold units column id >',
              'aggregation' => array (
                'type' => 'sum'
              )
            ),
          10000
          )
        )
      )
    )
    'frequency' => array (
      'unit' => 'day',
      'quantity' => 1
    ),
    'channels' => array (
      array (
        'type' => 'email',
        'config' => array (
          'recipients' => array (
            array (
              'address' => 'user@organization.com',
              'type' => 'to',
              'locale' => 'en'
            )
          ),
          'subject' => array (
            'en' => 'Great sales!'
          ),
          'message' => array (
            'en' => "We've done great boys! Check out these numbers!"
          )
        )
      )
    )
  )

);
?>

   Alerts are automatically linked to the user on creation time

curl https://api.luzmo.com/0.1.0/alert  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": { "en": "<title of your alert>" }
  "query": {
    "dimensions": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Type of burrito column id >"
      }
    ],
    "measures": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Number of burritos column id >",
        "aggregation": {
          "type": "sum"
        }
      }
    ],
    "where": [
      {
        "expression": "? in ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Type of burrito column id >"
          },
          ["Quesarito", "Chicken baconito"]
        ]
      }
    ],
    "having": [
      {
        "expression": "? >= ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Sold units column id >",
            "aggregation": {
              "type": "sum"
            }
          },
          10000
        ]
      }
    ]
  },
  "frequency": { "unit": "day", "quantity": 1 }
  "channels": [
    {
      "type": "email",
      "config": {
        "recipients": [
          {
            "address": "user@organization.com",
            "type": "to",
            "locale": "en"
          }
        ],
        "subject": {
          "en": "Great sales!"
        },
        "message": {
          "en": "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
}
}
EOF

   Alerts are automatically linked to the user on creation time

alert = client.create("alert",
{
    "name": { "en": "<title of your alert>" }
  "query": {
    "dimensions": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Type of burrito column id >"
      }
    ],
    "measures": [
      {
        "dataset_id": "< Burrito dataset id >",
        "column_id": "< Number of burritos column id >",
        "aggregation": {
          "type": "sum"
        }
      }
    ],
    "where": [
      {
        "expression": "? in ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Type of burrito column id >"
          },
          ["Quesarito", "Chicken baconito"]
        ]
      }
    ],
    "having": [
      {
        "expression": "? >= ?",
        "parameters": [
          {
            "dataset_id": "< Burrito dataset id >",
            "column_id": "< Sold units column id >",
            "aggregation": {
              "type": "sum"
            }
          },
          10000
        ]
      }
    ]
  },
  "frequency": { "unit": "day", "quantity": 1 }
  "channels": [
    {
      "type": "email",
      "config": {
        "recipients": [
          {
            "address": "user@organization.com",
            "type": "to",
            "locale": "en"
          }
        ],
        "subject": {
          "en": "Great sales!"
        },
        "message": {
          "en": "We've done great boys! Check out these numbers!"
        }
      }
    }
  ]
})

Alert

User

The association to the user is created automatically when an alert is made, this association cannot be created manually. The alert will be associated with the user making the request.

Authorization

Authorizations are tokens that grant access to the Luzmo platform. Tokens can be created in a cascaded way but are always ultimately tied to a single User. Authorizations are subservient to groups and users. If a user for which you make a token has no access to a certain dashboard or dataset then an authorization token made by this user will also not have access to these resources, regardless of the filters. Of course it is possible to combine the mechanisms of groups, users and authorizations. Just like groups and users, authorizations have very powerful filters that allow filtering on the granularity of datasets/dashboards as well as at the row level of datasets.

Properties

Parameter

Description

uuid

Unique key of the authorization (automatically assigned)

type

string

Authorization type. Possible types created by an API token are:

sso: create a temporary single sign-on session for an end-user.
temporary: (deprecated) create a temporary token for an end-user. This token cannot be used for storing alerts, scheduled exports, ...

Other token types:

login: a session started by manually authenticating using your user credentials
api: API token for programmatic access to Luzmo resources. Can be created only through a login session

expiry

datetime or string

Date/time when this authorization will cease working. This is the hard (maximum) expiry time of the token, after which it will *always* invalidate. The maximum expiry time is 1 year from creation. We advise to set a short expiry time, eg. 24 hours.

You can also use a duration string like 60 minutes or 1 day. The expiry will then be calculated from creation.

inactivity_interval

integer or string

Duration of inactivity (in seconds) after which the token is prematurely invalidated. You can use this to invalidate tokens quickly when the session is ended (eg. all open dashboards are closed). A value of 0 means no automatic invalidation due to inactivity (the token will only expire based on the value in expiry). Defaults to 0.

We advise not to set the interval to a value smaller than 2 minutes, to avoid accidental invalidation for a dashboard that is still open, eg. when a heartbeat signal sent to the server is missed.

You can also use a duration string like 1 hour.

environment

string

Whether this a production or test token. If set to production, your integrations will show the published production dashboard, if one exists, and the latest dashboard otherwise. If set to null, the latest dashboard will be loaded regardless of the publish status.

This property defaults to production.

array[string]

List of IP addresses or subnets. Both IPv4 and IPv6 IPs and subnets can be used. Leave empty to disable IP whitelisting. Eg.: ["123.45.67.89", "123.45.66.0/4", "2001:db8:0:1:1:1:1:1"]

securables

array[uuid]

(only for tokens with deprecated type `temporary`) List of Securable identifiers to give access to. If empty, the authorization can be used to access all Securables to which the User from which the authorization derives has access. It is advised to always explicitly list only the Securables to which the token should have access to. Eg.: ["4db23218-1bd5-44f9-bd2a-7e6051d69166", "f335be80-b571-40a1-9eff-f642a135b826"]

screenmode

string

Screen mode of dashboards to use. Either desktop, tablet, mobile, largeScreen, fixed. If empty, the window size will be used to determine the screen mode.

locale_id

string

Locale of dashboards to use, if that locale is available. Eg. nl. This is a shorthand form to set the Authorization - Locale association. If empty, the optimal locale will be automatically determined

timezone_id

string

Timezone id for dashboards to use, if that timezone id exists. This timezone id needs to be a valid id that is available in the IANA timezone database, for example: Europe/Brussels or America/New_York.

currency_id

string

Override the currency used in all datasets changing the displayed currency symbol on the dashboards. Expects a currency_id in the form of an ISO 4217 currency code, for example: EUR or USD.

width

string

Optional width the dashboard should take, e.g. 800px.

height

string

Optional height the dashboard should take, e.g. 600px.

username

string

Viewer metadata: The username of the end-user. This will be used to uniquely identify a Monthly Active Viewer (MAV) for your Organization. If not provided, functional session cookies will be used to distinguish MAVs.

name

string

Viewer metadata: name of the end-user.

string

Viewer metadata: email address of the end-user.

metadata

object

Use this parameter to set a parameter filter or specify optional Viewer metadata. This must be a valid JSON object with a maximum length of 10 000 characters.

To clear a parameter filter completely (deactivate it on the dashboard), set the metadata property clear to true: {"metadata": {"clear": true}}

To mark sensitive metadata that should not be logged, like JWT or authentication tokens, store it as an object with the sensitive property set: {"metadata": {"jwt": {"sensitive": true, "token": "..."}}}

theme

object

Optional JSON definition of a theme to apply to the dashboard

css

string

Optional CSS override to apply to the dashboard. The CSS gets appended to the existing CSS overrides in the dashboard.

account_overrides

object

Let this token override the connection to one or more data connections (to a Plugin or database). You can use this to dynamically route requests to different endpoints (eg. the correct endpoint per client in a single-tenant setup). All overrides are optional -- if not specified, the value as configured on the original Account will be used instead.

< account id >

object

The Plugin account id for which you want to override properties as property name.

base_url

string

(optional) The new base URL that will be called.

properties

object

(optional) Lists the custom authentication properties to override for plugin-based connections.

<custom_property_id>

string

(optional) The new custom authentication property value (the key is the custom authentication property id as defined when setting up the plugin in Luzmo).
This will be sent as X-Property-<custom_property_id> header to the Plugin.

datasets

object

(optional) List of dataset-level overrides. Useful if you want to override only a single table in your dashboard or if you have a separate table per client.

< dataset id >

object

The dataset (securable) ID that you want to override.

table

string

(optional) The new canonical dataset identifier (as defined in the Plugin) to retrieve data from.

< account id >

object

The database account id for which you want to override properties as property name.

host

string

(optional) The new database host to connect to. The database must be of the same type as the originally configured database.

port

string

(optional) The new port to connect to.

user

string

(optional) The new user to use when connecting.

password

string

(optional) The new password to use when connecting.

schema

string

(optional) The new schema to retrieve data from. Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value to both schema and database

database

string

(optional) the new database to retrieve data from. Note that to MySQL the concepts database and schema are identical. So when overriding a database / schema for MySQL, make sure to pass the same value to both schema and database

table

string

(optional) The new table to retrieve data from.

datasets

object

(optional) List of dataset-level overrides. Useful if you want to override only a single table in your dashboard or if you have a separate table per client. The SQL query of the dataset can also be overridden if it's a SQL dataset within Luzmo. Allowing you to call stored procedures for example.

< dataset id >

object

The dataset (securable) ID that you want to override.

table

string

(optional) The new table to connect to

schema

string

(optional) The new schema to connect to.

sql

string

(optional) The new SQL statement to use. NOTE: the columns returned in the new query need to conform to the same schema as the original dataset.

filters

array[object]

List of data filters to apply when data queries are performed with this authorization. This can be used with multi-tenanted datasets to ensure end-clients can only access their own data. The use of parameter filters is usually a better approach, however.

clause

string

Timing of application of the filter. Possible values: where (applied before aggregation/grouping, for example, only select rows with a specific price), having (applied after aggregation/grouping, for example, to select only groups in which the total price exceeds a specific value)

origin

string

Level to apply the filter. Possible values: global (row-level security, exclude specific rows from users for the complete dataset), chart (row-level security, exclude specific rows from users for a single chart), initialization (initialize an interactive filter within a dashboard to a particular value, but the end-user can override the filter value)

securable_id

uuid

In case of global or chart filter:
Dataset id to filter.

column_id

uuid

In case of global or chart filter:
Column id to filter.

chart_id

uuid

In case of initialization or chart filter:
Chart id to initialize.

expression

Which filter to apply. Possible values: ? = ?, ? > ?, ? >= ?, ? < ?, ? <= ?, ? in ?, ? not in ?, ? is null, ? is not null.

value

number, string, boolean, array

Value to insert in the filter.

last_used_at

datetime

(Read-only) Timestamp of the last API call of this authorization. Can be delayed up to 5 minutes.

Actions

Create

Get

List

Delete

Remember that an authorization is always immutable and therefore only supports Create, Get and Delete. It is possible though to associate using create fields which is explained further on. An authorization token can only be associated to the user that created it and is automatically associated to that User. Locale on the other hand is set using a property locale_id and cannot be updated after creation.

Action: Create

   Example of creating a technical user to start creating temporary tokens. The result will contain a Login token that you can use to request an API token. Make sure it is added to the correct organization using the API token of an organization owner which has access to your organization's resources

JSONObject user = client.create("user",

  ImmutableMap.of(
    "name" , "Technical User",
    "email" , "technical-user@luzmo.com",
    "password" , "... random password ..."
  ));
String login_token_key = user.getJSONObject("token").getString("id");
String login_token = user.getJSONObject("token").getString("token");

   Example of creating a technical user to start creating sso tokens. The result will contain a Login token that you can use to request an API token. Make sure it is added to the correct organization using the API token of an organization owner which has access to your organization's resources

dynamic properties = new ExpandoObject();
properties.name = "Technical User";
properties.email = "technical-user@luzmo.com";
properties.password = "... random password ...";

dynamic user = client.create("user",    properties);

// The user contains a new login token
Console.WriteLine("Token Key is {0}", user["token"]["id"]);
Console.WriteLine("Token is {0}", user["token"]["token"]);

   Example of creating a technical user to start creating sso tokens. The result will contain a Login token that you can use to request an API token. Make sure it is added to the correct organization using the API token of an organization owner which has access to your organization's resources

client.create('user',
  {
  name: 'Technical User',
  email: 'technical-user@luzmo.com',
  password: '... random password ...'
}

)
  .then(function(user) {
    var login_token_key = user.token.id; 
var login_token = user.token.token;
  });

   Example of creating a technical user to start creating sso tokens. The result will contain a Login token that you can use to request an API token. Make sure it is added to the correct organization using the API token of an organization owner which has access to your organization's resources

<?php
$user = $client->create('user',

  array (
    'name' => 'Technical User',
    'email' => 'technical-user@luzmo.com',
    'password' => '... random password ...'
  )

);
$login_token_key = $user['token']['id'] );
 $login_token = $user['token']['token'] );
?>

   Example of creating a technical user to start creating sso tokens. The result will contain a Login token that you can use to request an API token. Make sure it is added to the correct organization using the API token of an organization owner which has access to your organization's resources

curl https://api.luzmo.com/0.1.0/user  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
  "name": "Technical User",
  "email": "technical-user@luzmo.com",
  "password": "... random password ..."
}
}
EOF
# result format of the user contains the token 
{
 ... 
 "token":{
   "uid":"9392b9d6-d182-4072-8608-17d8ff7019de",
   "id":"301ca544-b8c4-42c7-8da1-ff2d76351020",
   "token":"h1MgJq0DUR2sXxI...",
   "tokenExpiry":1534412805941,
   "cookieExpiry":"2018-08-16T09:46:45.941Z"}
...
}

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token

JSONObject authorization = client.create("authorization",

  ImmutableMap.of(
    "type" , "api"
  ));
System.out.println("Success! %s%n", authorization);

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token

dynamic properties = new ExpandoObject();
properties.type = "api";

dynamic authorization = client.create("authorization",    properties);
Console.WriteLine("Success!", authorization);

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token

client.create('authorization',
  {
    type: 'api'
  }
)
  .then(function(authorization) {
    console.log('Success!', authorization);
  });

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token

<?php
$authorization = $client->create('authorization',

  array (
    'type' => 'api'
  )

);
print("Success! { $authorization }");
?>

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token

curl https://api.luzmo.com/0.1.0/authorization  -H "Content-Type: application/json" -d @- << EOF
{
  "action": "create",
  "key": "$LUZMO_API_KEY",
  "token": "$LUZMO_API_TOKEN",
  "version": "0.1.0",
  "properties": {
    "type": "api"
  }
}
EOF

   API token, (client created with LOGIN token) Get an API token for a newly created user using the login token

authorization = client.create("authorization",
{
    "type": "api"
})
print("Success! ", authorization)

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user.

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token, 
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer"
});

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >", 
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your user >")
  .put("name", "< user name >")
  .put("email", "< user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .build()
);

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your user >";
properties.name = "< user name >";
properties.email = "< user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >',
    host: '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >'
});

let promise = client.create('authorization', {
  type: 'sso',
  expiry: '24 hours',
  inactivity_interval: '10 minutes',
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer"
});

promise.then(function(result){
  // return the result to the client
})

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user

<?php
$client = Luzmo::initialize('< your API key >', '< your API token >',
 '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >');


$authorization = $client->create('authorization', array(
  'type' => 'sso',
  'expiry' => '24 hours',
  'inactivity_interval' => '10 minutes',
  'username' => "< A unique and immutable identifier for your user >",
  'name' => "< user name >",
  'email' => "< user email >",
  'suborganization' => "< a suborganization name >",
  'integration_id' => "< integration id >",
  'role' => "viewer"
));
?>

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer"
  }
}
EOF

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, and clearing another Parameter using the special value ImmutableMap.of("clear", true). Make sure to first create and set the Parameter in the dashboard or Integration.

from luzmo.luzmo import Luzmo

key = "Your Luzmo key"
token = "Your Luzmo token"

client = Luzmo(key, token, 
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >")

authorization = client.create("authorization", {
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "metadata": {
      "< parameter-name>": "< value to filter to >",
      "< parameter name of parameter to clear >" : {
        "clear": true
      }
    }
});

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, and clearing another Parameter using the special value ImmutableMap.of("clear", true). Make sure to first create and set the Parameter in the dashboard or Integration.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >", "< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your end user >")
  .put("name", "< end-user name >")
  .put("email", "< end-user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("metadata", ImmutableMap.builder()
    .put("Country"= ImmutableList.of(
      "Spain"
    ))
    .put("< parameter name >" = ImmutableList.of(
      "< value to apply >"
    ))
    .put("< parameter to clear >" = ImmutableMap.of(
      "clear", true
    ))
    .build()
  )
  .build()
);

   SSO token  (client created with API token) An example showing how temporary SSO access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, and clearing another Parameter using the special value {clear = true}.  Make sure to first create and set the Parameter in the dashboard.

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");


dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your end user >";
properties.name = "< end-user name >";
properties.email = "< end-user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.metadata = new{
  parameter_name = new List<String>{
    "< value to apply >"
  },
  " < parameter to clear >" = new {
    clear = true
  }
};

dynamic authorization = client.create("authorization", properties);
Console.WriteLine("Success!", authorization);

   SSO token  (client created with API token) An example showing how temporary SSO access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, and clearing another Parameter using the special value {clear: true}. Make sure to first create and set the Parameter in the dashboard.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >',
    host: '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >'
});

let promise = client.create('authorization', {
  type: 'sso',
  expiry: '24 hours',
  inactivity_interval: '10 minutes',
  username: "< A unique and immutable identifier for your end user >",
  name: "< end-user name >",
  email: "< end-user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  metadata: {
    "< parameter name >": ["< value to apply >"],
    '< parameter to clear >': {
      clear: true
    }
  }
});

promise.then(function(result){
  // return the result to the client
})

   SSO token  (client created with API token) An example showing how temporary SSO access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, and clearing another Parameter using the special value array('clear' => true). Make sure to first create and set the Parameter in the dashboard.

<?php
$client = Luzmo::initialize('< your API key >', '< your API token >',
 '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >');

$authorization = $client->create('authorization', array(
  'type' => 'sso',
  'expiry' => '24 hours',
  'inactivity_interval' => '10 minutes',
  'username' => "< A unique and immutable identifier for your end user >",
  'name' => "< end-user name >",
  'email' => "< end-user email >",
  'suborganization' => "< a suborganization name >",
  'integration_id' => "< integration id >",
  'role' => "viewer",
  'metadata' => array(
    '< parameter name >' => array(
      "< value to apply >"
    ),
    '< parameter to clear >' => array (
      'clear' => true
    )
  )
));
?>

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a Parameter to determine the data filter automatically applied to all queries, and clearing another Parameter using the special value {"clear": true}. Make sure to first create and set the Parameter in the dashboard.

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your end user >",
    "name": "< end-user name >",
    "email": "< end-user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "metadata": {
      "Country": ["Spain"],
      "< parameter name >": [
        "< value to apply >",
        "< other value to apply >"
      ],
      "< parameter to clear >": {
        "clear": true
      }
    }
  }
}
EOF

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your user >")
  .put("name", "< user name >")
  .put("email", "< user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "global")
    .put("securable_id", "< dataset id of a dataset used in the dashboard >")
    .put("column_id",    "< column id of a column in a dataset used in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

   SSO token  (client created with API token) An example showing how temporary SSO access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your user >";
properties.name = "< user name >";
properties.email = "< user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "global",
    securable_id = "< dataset id of a dataset used in the dashboard >",
    column_id = "< column id of a column in a dataset used in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

   Temporary token (client created with API token) An example showing how temporary SSO access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >',
    host: '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >'
});

let promise = client.create('authorization', {
  type: 'sso',
  expiry: '24 hours',
  inactivity_interval: '10 minutes',
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  filters: [
    {
      clause: 'where',
      origin: 'global',
      securable_id: '< dataset id of a dataset used in the dashboard >',
      column_id: '< column id of a column in a dataset used in the dashboard >',  
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }
  ]
});

promise.then(function(result){
  // return the result to the client
})

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard.

<?php
$client = Luzmo::initialize('< your API key >', '< your API token >',
 '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >');


$authorization = $client->create('authorization', array(
  'type' => 'sso',
  'expiry' => '24 hours',
  'inactivity_interval' => '10 minutes',
  'username' => "< A unique and immutable identifier for your user >",
  'name' => "< user name >",
  'email' => "< user email >",
  'suborganization' => "< a suborganization name >",
  'integration_id' => "< integration id >",
  'role' => "viewer",
  'filters' => array(
    array(
      'clause'       => 'where',
      'origin'       => 'global',
      'securable_id' => '< dataset id of a dataset used in the dashboard >',
      'column_id'    => '< column id of a column in a dataset used in the dashboard >',
      'expression'   => '? = ?',
      'value'        => '< value to be applied to the expression >'
    )
  ),
));
?>

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a global filter. A global filter is a filter that has effect on every chart in the dashboard.

curl https://api.luzmo.com/0.1.0/authorization \
-H "Content-Type: application/json" \
-d @- << EOF
{
  "action":"create",
  "version":"0.1.0",
  "key": "< your API key >",
  "token": "< your API token >",
  "properties":{
    "type": "sso",
    "expiry": "24 hours",
    "inactivity_interval": "10 minutes",
    "username": "< A unique and immutable identifier for your user >",
    "name": "< user name >",
    "email": "< user email >",
    "suborganization": "< a suborganization name >",
    "integration_id": "< integration id >",
    "role": "viewer",
    "filters": [
      {
        "clause": "where",
        "origin": "global",
        "securable_id": "< dataset id of a dataset used in the dashboard >",
        "column_id": "< column id of a column in a dataset used in the dashboard >",  
        "expression": "? = ?",
        "value": "< value to be applied to the expression >"
      }
    ]
  }
}
EOF

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

import org.json.JSONObject;
import com.google.common.collect.ImmutableList;
import com.google.common.collect.ImmutableMap;

private Luzmo client = new Luzmo("< Your API key >","< Your API token >", 
"< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >");

private JSONObject authorization = client.create("authorization", ImmutableMap.builder()
  .put("type","sso")
  .put("expiry", "24 hours")
  .put("inactivity_interval", "10 minutes")
  .put("username", "< A unique and immutable identifier for your user >")
  .put("name", "< user name >")
  .put("email", "< user email >")
  .put("suborganization", "< a suborganization name >")
  .put("integration_id", "< integration id >")
  .put("role", "viewer")
  .put("filters", ImmutableList.of(
    ImmutableMap.builder()
    .put("clause",       "where")
    .put("origin",       "chart")
    .put("securable_id", "< dataset id of a dataset used in the dashboard >")
    .put("column_id",    "< column id of a column in a dataset used in the dashboard >")
    .put("chart_id",     "< chart id of an object contained in the dashboard >")
    .put("expression",   "? = ?")
    .put("value",        "< value to be applied to the expression >")
    .build()
  ))
  .build()
);

   SSO token  (client created with API token) An example showing how temporary SSO access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

Luzmo client = new Luzmo("< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >",
"< Your API key >", "< Your API token >");

dynamic properties = new ExpandoObject();
properties.type = "sso";
properties.expiry = "24 hours";
properties.inactivity_interval = "10 minutes";
properties.username = "< A unique and immutable identifier for your user >";
properties.name = "< user name >";
properties.email = "< user email >";
properties.suborganization = "< a suborganization name >";
properties.integration_id = "< integration id >";
properties.role = "viewer";
properties.filters = new List<dynamic> {
  new {
    clause = "where",
    origin = "chart",
    securable_id = "< dataset id of a dataset used in the dashboard >",
    column_id = "< column id of a column in a dataset used in the dashboard >",
    chart_id = "< chart id of an object contained in the dashboard >",
    expression = "? = ?",
    value = "< value to be applied to the expression >"
  }
};

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

const Luzmo = require('@luzmo/nodejs-sdk');
var client = new Luzmo({
    api_key: '< Your API key >',
    api_token: '< Your API token >',
    host: '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >'
});

let promise = client.create('authorization', {
  type: 'sso',
  expiry: '24 hours',
  inactivity_interval: '10 minutes',
  username: "< A unique and immutable identifier for your user >",
  name: "< user name >",
  email: "< user email >",
  suborganization: "< a suborganization name >",
  integration_id: "< integration id >",
  role: "viewer",
  filters: [
    {
      clause: 'where',
      origin: 'chart',
      securable_id: '< dataset id of a dataset used in the dashboard >',
      column_id: '< column id of a column in a dataset used in the dashboard >',  
      chart_id: '< chart id of an object contained in the dashboard >',
      expression: '? = ?',
      value: '< value to be applied to the expression >'
    }
  ]
});

promise.then(function(result){
  // return the result to the client
})

   SSO token (client created with API token) An example showing how temporary SSO access can be granted for a user with a chart filter. A chart filter is a filter that has effect on only one chart in the dashboard.

<?php
$client = Luzmo::initialize('< your API key >', '< your API token >',
 '< https://api.luzmo.com (default) or https://api.us.luzmo.com/ or your VPC-specific address >');


$authorization = $client->create('authorization', array(
  'type' => 'sso',
  'expiry' => '24 hours',
  'inactivity_interval' => '10 minutes',
  'username' => "< A unique and immutable identifier for your user >",
  'name' => "< user name >",
  'email' => "< user email >",
  'suborganization' => "< a suborganization name >",
  'integration_id' => "< integration id >",
  'role' => "viewer",
  'filters' => array(
    array(
      'clause'       => 'where',
      'origin'       => 'chart',
      'securable_id' => '< dataset id of a dataset used in the dashboard >',
      'column_id'    => '< column id of a column in a dataset used in the dashboard >',  
      'chart_id'     => '< chart id of an object contained in the dashboard >',
      'expression'   => '? =

Introduction

Guides

Dashboard embedding

Set up an Integration

Create an Integration

Associate dashboards

Associate datasets

Embed into your application

1. Generate a SSO token

2. Embed the dashboard

Handling multi-tenant data

Add a Parameter filter

1. Define and set a Parameter

When associating a dataset with an integration

In the dashboard editor

2. Override the parameter in the authorization request

Specify Connection/Account overrides

Embedded dashboard editor

Define securable access rights

Access to dashboard(s)

Access to dataset(s)

Specify user role in backend

Set edit mode in frontend

Next steps

Retrieving a list of dashboards

Set an initialization filter

Set language or timezone

Set loader style

Embed a single dashboard item

Related topics

Retrieving a dashboard id

Retrieving a dataset id

Retrieving a column id

Retrieving a chart id

Retrieving a connection id

Retrieving an integration id

Invalidating SSO tokens

Interacting with data

Connecting

Retrieving datasets/dashboards

Retrieving all columns of a particular dataset

Retrieving a list of all your dashboards

Creating datasets automatically

Creating datasets manually

Creating a new dataset

Creating a column and immediately linking (associating) it with a dataset

Linking (associating) a dataset and a column in a seperate call

Pushing data

Querying data

Simple example

Advanced example

External data changes

Core API

Introduction

Connect

Token

SDKs

Schema

Actions

Create

Update

Delete

Get & List

Associate

Dissociate

Resources

Account

Properties

Actions

Action: Create

Action: Update

Action: Get

Action: Delete

Associations

Associate: User (implicit)

Alert

Properties

Actions

Action: Create

Action: Update