Release Brick

The release brick creates master workspaces for one or more segments within a data product based on a predefined template called “Development master workspace”. If the segments or the data product do not yet exist, the release brick creates them as well.

The Development master workspace is a workspace that is created in advance and set up according to your needs: it contains required dashboards, reports, metrics, and so on. The master workspaces created based on the Development master workspace inherit all the objects from it.

Each execution of the release brick creates a new version of the segment’s master workspaces instead of changing the current ones.

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

Prerequisites

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

  • A domain is implemented at your site, and a domain admin exists.
  • The Development master workspace with the content that needs to be released is created.
  • (If your input source resides on the GoodData Data Warehouse (ADS)) You have an ADS instance, and the domain admin has admin rights to this instance.

How the Brick Works

The release brick accesses the Development master workspace to retrieve all metadata (for example, logical data model (LDM), processes, metrics, reports, and dashboards). If your input source resides on ADS, the release brick creates the lcm_release table on the ADS instance (the table where the latest segment master workspace IDs and versions are stored).

The brick creates new master workspaces in the domain and copies the dashboards and the objects referenced in those dashboards (reports, metrics, and so on) from the Development master workspace to those master workspaces. To change what objects should be copied (for example, copy all the objects, not just the dashboards), use the production_tags and transfer_all parameters (see Advanced Settings).

If the segments did not exist before you run the release brick, the release brick creates them according to your specification.

Input

The release brick does not require any input besides the parameters that you have to add when scheduling the brick process.

Parameters

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

NameTypeMandatory?DefaultDescription
organizationstringyesn/aThe name of the domain where the brick is executed
segmentsarrayyesn/a

The segments that are going to be provisioned in the domain

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

Example:

"segments": [
  {
    "segment_id": "BASIC",
    "development_pid": "e863ii0azrnng2zt4fuu81ifgqtyeoj21",
    "driver": "pg",
    "master_name": "Master BASIC ##{version}"
  },
  {
    "segment_id": "PREMIUM",
    "development_pid": "fuu81ifgqtyeoj21e863ii0azrnng2zt4",
    "driver": "pg",
    "master_name": "Master PREMIUM ##{version}",
    "ads_output_stage_uri": "/gdc/datawarehouse/instances/kluuu4h3sogai9x2ztn4wc0g8lta7sn8/schemas/default",
    "ads_output_stage_prefix": "out_"
  }
]
  • segment_id identifies the segment to be provisioned (for example, BASIC or PREMIUM). segment_id must match the following regex: [a-zA-Z0-9_\-]+
  • development_pid identifies the ID of the Development master workspace.
  • driver: pg indicates that the master workspace will be running on PostreSQL. If needed, you will be able to provision client workspaces on Vertica later (see Provisioning Brick).
  • master_name specifies the name of the segment's master workspace. master_name can contain the ##{version} placeholder.
  • (If your input source resides on ADS) ads_output_stage_uri specifies the URI of the Output Stage to use instead of the Output Stage in the Development master workspace. Use this parameter only when you have different development and production domains. The specified Output Stage must be in the production domain.
  • (If your input source resides on ADS; optional) ads_output_stage_prefix specifies the prefix to use in the Output Stage in the released segments that will override the default prefix.
tokensJSONyesn/a

The authorization token to use for creating the new master workspaces on PostgreSQL

If needed, you will be able to provision client workspaces on Vertica later (see Provisioning Brick).

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

"tokens": {
  "pg": "{PostgreSQL_token}"
}
CLIENT_GDC_HOSTNAMEstringyessecure.gooddata.com

The white-labeled domain name in the format of your.domain.com (for example, analytics.mycompany.com)

The parameter name is case-sensitive and must be written in uppercase.

CLIENT_GDC_PROTOCOLstringyeshttps

The protocol to transfer data over

The parameter name is case-sensitive and must be written in uppercase.

ads_clientJSONsee "Description" columnn/a

(Only if your input source resides on GoodData Data Warehouse (ADS)) The ADS instance where the lcm_release table will be created (see the release_table_name parameter later in this table)

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

Example:

"ads_client": {
  "jdbc_url": "jdbc:gdc:datawarehouse://my.company.com/gdc/datawarehouse/instances/kluuu4h3sogai9x2ztn4wc0g8lta7sn8"
}
data_productstringnodefault

The data product that contains the segments that you want to release. If the specified data product does not exist, it is created.

NOTE: If your input source resides on ADS and you have two or more data products, use the release_table_name parameter (see further in this table).

release_table_namestringsee "Description" columnLCM_RELEASE

(If your input source resides on ADS and you have multiple data products stored in one ADS instance) The name of the table in the ADS instance where the latest segment's master workspace IDs and versions are stored

disable_kd_dashboard_permissionBooleanno

false

Shared dashboard permissions for user groups are enabled by default. Even when the parameter is not explicitly specified in the syntax, it is assumed. Set to true to disable synchronizing user group permissions for shared dashboards. For more information, see LCM and Shared Dashboards.
development_clientJSONnon/a

(If the user who executes the release brick does not have access to the Development master workspace; for example, it is located in a different domain) Credentials of a user with access to the Development master workspace

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

Example:

"development_client": {
  "server": "https://your.domain.com",
  "username": "john.doe@yourdomain.com",
  "password": "${development_client_password}"
}

LCM and Shared Dashboards

In a segment’s master workspace, dashboards can be private or shared with all or some users/user groups.

The sharing permissions are propagated from the master workspace to the client workspaces in the following way:

  • Dashboards set as private in the master workspace remain private in the client workspaces.
  • Dashboards shared with all users in the master workspace become dashboards shared with all users in the client workspaces.
  • Dashboards shared with some users/user groups in the master workspace become dashboards shared with some user groups in the client workspaces

In addition to the sharing permissions, the dashboards can be configured:

  • To allow only administrators to update the dashboards (that is, editors cannot update such dashboards)
  • To be displayed to users when they drill to these dashboards from facts, metrics, and attributes, even if the dashboards are not explicitly shared with those users

These settings are propagated to the client workspaces exactly as they are set in the master workspace. For more information about these settings, see Share Dashboards.

Example - Brick Configuration

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

{
  "organization": "myCustomDomain",
  "CLIENT_GDC_HOSTNAME": "analytics.myCustomDomain.com",
  "CLIENT_GDC_PROTOCOL": "https",
  "gd_encoded_params": {
    "segments": [
      {
        "segment_id": "BASIC",
        "development_pid": "e863ii0azrnng2zt4fuu81ifgqtyeoj21",
        "driver": "pg",
        "master_name": "Master BASIC ##{version}",
        "production_tags": ["transfer_to_basic", "at_release"]
      },
      {
        "segment_id": "PREMIUM",
        "development_pid": "fuu81ifgqtyeoj21e863ii0azrnng2zt4",
        "driver": "pg",
        "master_name": "Master PREMIUM ##{version}"
      }
    ],
    "tokens": {
      "pg": "01234567890123"
    },
    "ads_client": {
      "jdbc_url": "jdbc:gdc:datawarehouse://analytics.myCustomDomain.com/gdc/datawarehouse/instances/kluuu4h3sogai9x2ztn4wc0g8lta7sn8"
    },
    "development_client": {
      "server": "https://myCustomDomainDev.com",
      "username": "jane.dow@myCustomDomain.com",
      "password": "${development_client_password}"
    }
  },
  "development_client_password": "enter_as_a_secure_parameter"
}

Advanced Settings

This section describes advanced settings of the release brick.

NameTypeMandatory?DefaultDescription
additional_paramsJSONnon/a

Additional parameters that will be added to all schedules in the master workspaces

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

"additional_params": {
  "{parameter_1_name}": "{parameter_1_value}",
  "{parameter_2_name}": "{parameter_2_value}"
}
additional_hidden_paramsJSONnon/a

Additional secure parameters that will be added to all schedules in the master workspaces

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

"additional_hidden_params": {
  "hidden_parameter_1_name": "${hidden_parameter_1}",
  "hidden_parameter_2_name": "${hidden_parameter_2}"
}
transfer_allBooleannofalseSee transfer_all and production_tags.
production_tagsarraynon/a
exclude_fact_ruleBooleannofalse

Specifies whether to skip number format validation (up to 15 digits, including maximum 6 digits after the decimal point).

  • If not set or set to false, number format validation is used.
  • If set to true, number format validation is skipped.
set_master_projectstringnon/a

Specifies the ID of the workspace that you want to set as the segment master workspace instead of the one currently set.

Use this parameter if you rolled out a new version of the segment's master workspace to its client workspaces but then decided to revert to the previous version of the master workspace (for example, because an error was discovered in the new version). To go back to the previous version, set this parameter to the ID of the workspace that was the master workspace before you rolled out the new version. You can obtain this ID in the "Result of UpdateReleaseTable" section of the execution log of the release brick (see Review a Log of Data Load Execution).

After reverting to the previous version of the master workspace, run the rollout brick (see Rollout Brick) to synchronize the client workspaces with this version of the master workspace.

skip_actionsarraynon/a

The actions or steps that you want the brick to skip while executing (for example, synchronizing computed attributes or user groups)

The specified actions and steps will be excluded from the processing and will not be performed.

NOTE: Using this parameter in a wrong way may generate unexpected side effects. If you want to use it, contact the GoodData specialist who was involved in implementing LCM at your site.

transfer_all and production_tags

The transfer_all parameter specifies what objects should be copied from the Development master workspace to the master workspaces when the master workspaces are created.

  • If not set or set to false, only dashboards and the objects referenced in those dashboards (reports, metrics, and so on) are copied from the Development master workspace to the master workspaces.
  • If set to true, all objects (dashboards, KPI Dashboards, reports, insights, metrics, and variables) are copied from the Development master workspace to the master workspace.

The production_tags parameter makes the brick copy only the objects with the tags and the objects referenced in them. The production_tags parameter is an array that can have one or multiple tags:

"production_tags": ["some_tag"]
"production_tags": ["tag_1", "tag_2", "tag_3"]

 

By default, the transfer_all parameter is set to false and the production_tags parameter is not set at all. In this default configuration, the brick copies only dashboards and the objects referenced in those dashboards (reports, metrics, and so on).

You can configure the transfer_all parameter and production_tags parameter depending on what objects you want to copy from the Development master workspace to the master workspace:

  • To copy only the objects with the specified tags and the objects referenced in them, set the production_tags parameter to these tags. The transfer_all parameter must be either not set at all or set to false. This can be useful in the following situations:

    • You have two segments with the same LDM but different dashboards, reports, and metrics built on top of this LDM (for example, for a basic and premium versions of your service). You want the segment’s master workspaces to be based on the same Development master workspace. In this case, you can build all the dashboards, reports, and metrics in the same Development master workspace, tag them to be related to one of the segments, and then use the production_tags parameter to copy only the relevant objects to each segment’s master workspace.
    • You want to copy only a subset of the dashboards from the Development master workspace (for example, you build numerous dashboards and want to copy those that are ready while the rest is in progress). In this case, tag the dashboards that are ready, and then use the production_tags parameter to copy only those dashboards to the segment’s master workspace.
  • To copy all objects (dashboards, KPI Dashboards, reports, insights, metrics, and variables), set the transfer_all parameter to true. In this case, the production_tags parameter will be ignored regardless of whether it is set up or not.

Setting up the production_tags parameter in the brick schedule

While the transfer_all parameter can be set directly in the brick schedule, the production_tags is a complex parameter (see Specifying Complex Parameters) and must be included in your gd_encoded_params parameter (see Example - Brick Configuration).

You can set up the production_tags parameter in the following ways:

  • Globally for all segments:

    "gd_encoded_params": {
      "production_tags": ["tag1", "tag2", "tag3"],
      ...
    }
    
  • Per segment (segment-specific parameters take precedence over the globally set one):

    "gd_encoded_params": {
      "segments": [
        {
          "segment_id": "BASIC",
          "development_pid": "e863ii0azrnng2zt4fuu81ifgqtyeoj21",
          "driver": "pg",
          "master_name": "Master BASIC ##{version}",
          "production_tags": ["tag1", "tag2", "tag3"]
        },
        ...
      ]
      ...
    }