Configuring LCM via API

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

We recommend that you use the process of configuring LCM via API only when you cannot use the bricks for LCM implementation.

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:

Create/modify segment-to-client mapping.
Set individual client/master workspace dashboards, reports, and views.
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

In GoodData, terms workspace and project denote the same entity. For example, project ID is exactly the same as workspace ID. See Find the Workspace ID.

Create a segment:

Navigate to the gray pages for managing segments:

https://example.gooddata.com/gdc/domains/{domain_name}/dataproducts/{data_product}/segments

Enter the segment ID. The segment ID is a unique identifier within your domain limited to alphanumeric characters, dashes, and underscores. Example: segment1
Enter the master workspace URI. Example: /gdc/projects/e863ii0azrnng2zt4fuu81ifgqtyeoj21
Click Create Segment. The segment is created. The segment resource page opens.

Add clients to the newly created segment:

On the segment resource page, locate the ‘clients’ keyword and click its URI.
Enter the client ID. Example: ProjectClient1
Enter the workspace URI. Example: /gdc/projects/``rnng2zt4fuu81ifgqtyeazeoj21863ii0
Enter the segment URI. Example: /gdc/domains/default/segments/segment1
Click Create Client. The client is added to the segment.
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:

Log in to the GoodData Portal.
Set up individual dashboards, names, and so on. For more information, see:
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:

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

Client Synchronization and Provisioning Metadata

Client synchronization creates metadata objects on the GoodData platform. These objects are then used during provisioning.

These objects are automatically cleaned up three years after the synchronization process was last executed.

To prevent issues with provisioning related to the missing metadata objects, always keep the production master workspace synchronized with the production client workspaces. Use a different workspace for development.

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.

Access the API endpoints through your GoodData subdomain https://{your-subdomain-name}.gooddata.com. For example, https://example.gooddata.com. If your workspaces use whitelabeling, use your domain address. For example, https://example.com.

API resource:

https://example.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.

Get Information about LCM Entities

You can use the API to get a list of LCM entities. Each LCM entity represents the relationship between the workspace, client, segment and data product. Only a domain administrator or the entity owner can retrieve the entity.

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 including deprecated and private metrics
Variables
Date filters for KPI alerts
Attribute filters for KPI Dashboards
Attribute folders
Report folders
Custom themes

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:

Configuration	Behavior
When locked and not present in export	Delete object
When not locked and not present in export	Delete tag
When locked and present in export	Do nothing and lock all child objects if they are not locked
When not locked and present in export	Lock object
When locked and not present in export and used by client object	Delete tag

Troubleshooting

Provisioning process fails

The provisioning process fails with the following error message:

Master release not found. You must call client synchronization to create a master release before provisioning new projects.

Why has this happened?

When executing, the provisioning process relies on the platform metadata objects that the client synchronization process generates (see Client Synchronization and Provisioning Metadata). These objects are automatically cleaned up three years after the client synchronization was last executed.

How can you fix this?

Synchronize the client workspaces to create the platform metadata objects that the provisioning process uses. To do so, use the synchronization API.
Run the provisioning process again.

Persistent URIs

If you have many workspaces that you need to embed into your application, you can maintain persistent URIs for your workspaces 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

LCM Implementation