Provisioning Brick

The provisioning brick creates clients' workspaces under the appropriate segments, and deploys the reports, dashboards, filters, logical data model, ETL, and metadata from the master workspace to the clients' workspaces within a segment. Optionally, the provisioning brick deletes obsolete clients and their workspaces.

For information about how to use the brick, see How to Use a Brick.

Contents:

Prerequisites

Before using the provisioning brick, make sure that the following is true:

  • The release brick (see Release Brick) has been executed.
  • You have an input source with a list of the client workspaces to be provisioned.
    The preferred source is a Data Warehouse (ADS) instance.

How the Brick Works

The provisioning brick creates the new workspaces specified in the input source and associates them with the appropriate segment.

Depending on how the 'delete_mode' parameter is set, the brick may also delete the existing client workspaces that are no longer in the input source. If the titles of some workspaces have changed in the input source, the brick renames these workspaces.

Other than deleting and renaming, the brick does not touch the existing workspaces.

Input

The provisioning brick expects to receive the data about which client should be provisioned under which segment.

The input data format is the following:

segment_idclient_idproject_titleproject_token
basic_segmentclient_1workspace_onevertica_token
premium_segmentclient_2workspace_two
  • Values in the 'segment_id' and 'client_id' columns must match following regex:
    [a-zA-Z0-9_\-]+
  • If the 'project_title' column is missing from the input data, the workspace name is populated from the data in the 'client_id' column.
  • If the 'project_token' column is missing from the input data or is empty, the PostgreSQL authorization token of the master workspace (see the 'tokens' parameter in Release Brick) is used for provisioning client workspaces.
    If you have a Vertica authorization token, you can provision client workspaces on Vertica. To do so, specify your Vertica token in the 'project_token' column for those workspaces.

In addition, you have to add the parameters when scheduling the brick process.

Parameters

When scheduling the deployed brick (see How to Use a Brick and Schedule a Process on the Data Integration Console), add parameters to the schedule.

NameTypeMandatory?DefaultDescription

organization

string

yes

n/a

The name of the domain where the brick is executed

segments_filterarrayyesn/a

The segments that you want to provision

You must encode this parameter using the 'gd_encoded_params' parameter (see Specifying Complex Parameters).

Example:

"segments_filter": ["BASIC", "PREMIUM"]
input_sourceJSONyesn/a

The input records that identify active client workspaces

You must encode this parameter using the 'gd_encoded_params' parameters (see Specifying Complex Parameters).

The preferred source is a Data Warehouse (ADS) instance. For more information about setting up the input source on the Data Warehouse instance as well as the other types of the input sources, see Types of Input Data Sources.

Example:

"ads_client": {
  "jdbc_url": "jdbc:gdc:datawarehouse://mycompany.com/gdc/datawarehouse/instances/kluuu4h3sogai9x2ztn4wc0g8lta7sn8"
},
"input_source": {
  "type": "ads",
  "query": "SELECT DISTINCT client_id, segment_id, project_title FROM lcm_workspace;"
}
data_productstringno

default

The data product that contains the segments that you want to provision

delete_modestringnonone

Defines how the brick should process the clients and their workspaces when detecting that one or more clients existing in the segment are not present in the input source.

Possible values:

  • none leaves the clients who are not in the input source intact (the clients remain in the segment and their workspaces are accessible). This is the default.
  • delete_extra removes from the segment the clients who are not in the input data source and disassociates their workspaces from the segment (the workspaces will still exist but you will not be able to refer to them by client_id).
  • delete_projects deletes the clients who are not in the input source and physically deletes their workspaces (the workspaces will not be accessible).
technical_usersarraynon/a

The users that are going to be added as admins to each client workspace

You must encode this parameter using the 'gd_encoded_params' parameter (see Specifying Complex Parameters).

Example:

"technical_users": ["dev_admin@gooddata.com", "admin@gooddata.com"]

Example: Brick Configuration

The following is an example of configuring the brick parameters in the JSON format:

{
  "organization": "myCustomerDomain",
  "delete_mode": "delete_projects",
  "gd_encoded_params": {
    "segments_filter": ["BASIC"],
    "ads_client": {
      "jdbc_url": "jdbc:gdc:datawarehouse://analytics.myCustomDomain.com/gdc/datawarehouse/instances/kluuu4h3sogai9x2ztn4wc0g8lta7sn8"
    },
    "input_source": {
      "type": "ads",
      "query": "SELECT DISTINCT client_id, segment_id, project_title FROM lcm_workspace;"
    },
    "technical_users": ["dev_admin@myCustomDomain.com", "admin@myCustomDomain.com"]
  }
}

Advanced Settings

This section describes advanced settings of the provisioning brick.

Change these settings only if you are confident in executing the task or have no other options. Adjusting the advanced options in a wrong way may generate unexpected side effects.

Proceed with caution.

 Click here to view the advanced settings.
NameTypeMandatory?DefaultDescription
dynamic_paramsJSONnon/aSee dynamic_params.

dynamic_params

The 'dynamic_params' parameter lets you add client-specific, dynamically changing parameters to all or some schedules in all or some client workspaces.

Example:
You want to add the 'MODE' parameter with the value set to 'specific_mode' to the schedules named 'main.rb' for the client with the client ID 'client_1'.

To do so, do the following:

  1. On your Data Warehouse instance, create a table that maps parameters, their values, schedule names, and clients. Give the table the name; for example, 'schedule_params'.

    param_nameparam_valueschedule_titleclient_id
    MODEspecific_modemain.rbclient_1
  2. Create the 'dynamic_params' parameter as follows:

    "dynamic_params": {
      "input_source": {
        "type": "ads",
    	"query": "select 'MODE' as param_name, 'specific mode' as param_value, 'main.rb' as schedule_title, 'client_1' as client_id from schedule_params"
      }
    }
  3. Add the 'dynamic_param' parameter to the brick schedule. Because it is a complex parameter, encode it using the 'gd_encoded_params' parameter (see Specifying Complex Parameters).

    "gd_encoded_params": {
      "dynamic_params": {
        "input_source": {
    	  "type": "ads",
    	  "query": "select 'MODE' as param_name, 'specific mode' as param_value, 'main.rb' as schedule_title, 'client_1' as client_id from schedule_params"
    	}
      }
    }

Consider the following additional options:

  • To add dynamic parameters to all schedules for 'client_1', do not explicitly specify 'schedule_title' in the query:

    "gd_encoded_params": {
      "dynamic_params": {
        "input_source": {
    	  "type": "ads",
    	  "query": "select 'MODE' as param_name, 'specific mode' as param_value, schedule_title, 'client_1' as client_id from schedule_params"
    	}
      }
    }
  • To add dynamic parameters to the schedules named 'main.rb' in all clients, do not explicitly specify 'client_id' in the query:

    "gd_encoded_params": {
      "dynamic_params": {
        "input_source": {
    	  "type": "ads",
    	  "query": "select 'MODE' as param_name, 'specific mode' as param_value, 'main.rb' as schedule_title, client_id from schedule_params"
    	}
      }
    }
  • To use different column names instead of the default ones, map your column names to the default ones. You can map one or multiple column names.
    For example, your columns are named 'name', 'value', 'schedule_name', and 'client' instead of the default 'param_name', 'param_value', 'schedule_title', and 'client_id', respectively.
    To map your column names, use the following mapping parameters:
    • 'param_name_column' for mapping 'param_name'
    • 'param_value_column' for mapping 'param_value'
    • 'schedule_title_column' for mapping 'schedule_title'
    • 'client_id_column' for mapping 'client_id'

    Add those parameters under the 'gd_encoded_params' parameter and set them to your column names. Then, update the query parameter to refer to your mapped column names instead of the default ones.

    "gd_encoded_params": {
      "param_name_column": "name",
      "param_value_column": "value",
      "schedule_title_column": "schedule_name",
      "client_id_column": "client",
      "dynamic_params": {
        "input_source": {
          "type": "ads",
          "query": "select 'MODE' as name, 'specific mode' as value, 'main.rb' as schedule_name, 'client_1' as client from schedule_params"
        }
      }
    }