Configuring LCM via API

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.

Create/Modify Segment-to-Client Mapping

Create a segment:

1. Navigate to the gray pages for managing segments:

   https://example.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 workspace URI. Example: /gdc/projects/rnng2zt4fuu81ifgqtyeazeoj21863ii0 

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:
   • Dashboards
   • Create Insights
   • Get Started with Using MAQL to Write Metrics
   • Managing Workspace Data and Data Access
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.

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 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.

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

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

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:

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?

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

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.

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