Configuring LCM via API

The recommended way of implementing Life Cycle Management (LCM) is using the bricks (see LCM Implementation).

Contents:

Prerequisites

Before you start, make sure that the following prerequisites are met:

  • You are a domain admin.
  • Segment master workspaces are created on the GoodData platform.
  • A set of client workspaces is created on the GoodData platform.
  • All associated URLs and URIs of the master workspaces and client workspaces are obtained via the gray pages or API.

Configuration Process

LCM configuration via API consists of the following main operations:

  1. Create/modify segment-to-client mapping.
  2. Set individual client/master workspace dashboards, reports, and views.
  3. Synchronize the master workspace to client workspaces.

If you are a non-whitelabeled customer, contact GoodData Support to enable the LCM functionality.

Create/Modify Segment-to-Client Mapping

Create a segment:

  1. Navigate to the gray pages for managing segments:

    https://secure.gooddata.com/gdc/domains/{domain_name}/dataproducts/{data_product}/segments
  2. Enter the segment ID.
    The segment ID is a unique identifier within your domain limited to alphanumeric characters, dashes, and underscores.
    Example: segment1

  3. Enter the master workspace URI.
    Example: /gdc/projects/e863ii0azrnng2zt4fuu81ifgqtyeoj21

  4. Click Create Segment.
    The segment is created. The segment resource page opens.


Add clients to the newly created segment:

  1. On the segment resource page, locate the 'clients' keyword and click its URI.
  2. Enter the client ID.
    Example: ProjectClient1
  3. Enter the project URI.
    Example: /gdc/projects/ e863ii0azrnng2zt4fuu81ifgqtyeoj21
  4. Enter the segment URI.
    Example: /gdc/domains/default/segments/segment1
  5. Click Create Client.
    The client is added to the segment.
  6. Repeat steps 1 to 5 to add as many clients as needed.

    To add multiple clients to the segment, you can execute the API for a bulk addition of clients.

Set Individual Client/Master Workspace Dashboards, Reports, and Views

Steps:

  1. Log in to the GoodData Portal.
  2. Set up individual dashboards, names, and so on. For more information, see:
  3. Edit the individual workspaces’ dashboards, reports, and metrics as needed.

Synchronize the Master Workspace to Client Workspaces

You must have administration access to all master and client workspaces.

Steps:

  1. On the resource page for the segment that you want to synchronize, click Synchronize clients.
    The link to a polling resource is returned.
  2. Click the polling link.
    The page opens showing successful and unsuccessful results depending on the individual client workspace permissions.
  3. Click the 'details' URL to display specific result details.

Preserve Variables During Release and Roll-out

Before synchronizing the master workspaces to the client workspaces, you may want to prevent the situation when the client workspaces contain different default values in the variables (see Filter for Variables) and they get overwritten by those from the master workspace.

To preserve variables in the client workspaces, use the API for adding configuration items to different hierarchy levels (data product, segment). Using this API, add the lcm.variables.preserve configuration item to the preferred hierarchy level and set it to one of the following values:

  • all specifies that all variables in the target workspaces will be preserved.
  • none specifies that no variables in the target workspaces will be preserved. The variables in the target workspaces will be overwritten by the master variables.
  • An array of variable identifiers ["{variable_identifier_1}", "{variable_identifier_2}, ..."] specifies that only a set of specific variables in the target workspaces will be preserved.

The lcm.variables.preserve parameter does not have a default value (variables are not preserved), so you must explicitly configure it.


Example:
To preserve variables for a segment, use the API for adding configuration items to the segment level.

This example assumes that you access your projects at https://secure.gooddata.com/.

If you are a white-labeled customer, replace secure.gooddata.com with your white-labeled domain in the procedure steps when needed.

API resource:

https://secure.gooddata.com/gdc/domains/{domain_name}/dataproducts/{data_product_name}/segments/{segment_name}/config

Method: POST

Request body:

{
  "settingItem" : {
    "key": "lcm.variables.preserve",
    "value": "all"
  }
}

Request headers:

Content-Type:application/json
Accept:application/json

To review the existing configuration items for a segment, use the API for listing configuration items for a segment.


Client Workspace Provisioning

Client workspace provisioning allows you to provision new workspaces for each client based on a master workspace and allows you to manage your release life cycle via a single API call (see API: Start client project provisioning).

Client workspace provisioning creates workspaces for all clients without a workspace. This API walks through all segments in the domain and if the segment has been synchronized at least once, iterates through all its clients without a workspace and creates a workspace from an image created upon the last synchronization.

Workspace provisioning clones the following data:

  • LDM and PDM layer
  • All UDM objects that are dependencies of LDM objects (for example, metrics used in computed attributes)
  • All pixel-perfect dashboards, KPI Dashboards, and their dependencies
  • All datasets, dimensions, and folders
  • Workspace color palettes

Workspace provisioning clones data for computed attributes and date dimensions when created. It does not synchronize computed attributes and date dimensions when updating.

Segment Provisioning

You can define specific clients to segments by adding the desired segment name in the segment attribute.

Synchronization

Synchronization allows the following objects to be synchronized:

  • KPIs
  • KPI Dashboards
  • Analytical Designer visualizations
  • Dashboards
  • Reports
  • Metrics/measures including deprecated and private metrics
  • Variables
  • Date filters for KPI alerts
  • Attribute filters for KPI Dashboards
  • Attribute folders
  • Report folders

Synchronization Behavior

When synchronizing workspaces, the following behavior applies:

  • Objects deleted in the master are deleted in clients. Existing objects in the master are locked in clients.
  • Objects deleted in the master are deleted in clients.
  • Existing objects in the master are locked in clients.

After import completes, the master objects from partial export are compared to the client objects with the LCM tag:

ConfigurationBehavior
When locked and not present in exportDelete object
When not locked and not present in exportDelete tag
When locked and present in exportDo nothing and lock all child objects if they are not locked
When not locked and present in exportLock object
When locked and not present in export and used by client objectDelete tag

Persistent URIs

If you have many workspaces that you need to embed into your application, you can maintain persistent URIs for your projects by replacing the object ID by the identifier in the above procedures. This means that the IDs will not change after every cloning procedure.

Examples:

/dashboard.html#project=/gdc/projects/e863ii0azrnng2zt4fuu81ifgqtyeoj21&dashboard=/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/2229

versus

/dashboard.html#project=/gdc/projects/e863ii0azrnng2zt4fuu81ifgqtyeoj21&dashboard=/gdc/md/e863ii0azrnng2zt4fuu81ifgqtyeoj21/obj/identifier:myDashboard