Object Renaming Utility

Object Renaming Utility is a utility that supports the data preparation and distribution pipeline (see Data Preparation and Distribution Pipeline). Object Renaming Utility batch-renames and/or hides metadata objects in one or more workspaces based on the criteria that you have defined (what objects to rename/hide and in what workspaces to do so).

Contents:

How Object Renaming Utility Works

When Object Renaming Utility runs, it renames and/or hides objects in the workspaces according to the criteria that you have defined in queries:

  • The object to process
  • The workspace that the object belongs to
  • The new name for the object
  • Whether the object is visible or hidden in the workspace

You can use Object Renaming Utility to process the following objects:

  • Facts
  • Metrics
  • Attributes
  • Attribute labels
  • Variables
  • Reports
  • Insights
  • Datasets
  • Date dimensions (together with its attributes)
  • Dashboards
  • KPI Dashboards
  • For date dimensions, Object Renaming Utility tries to keep the default format of attribute names and may not be able to rename attributes with customized names.
  • For renamed facts, attributes, and metrics, KPI Dashboards show their old names.

Allowing Different Customers to Use Different Naming Conventions for the Same Objects

If some of your customers require a specific report, metric or another object be called differently, use Object Renaming Utility to change the name of that particular object.

If you want to rename objects to have their names in a different language, use native support for translation (see Metadata Localization).

Hiding Unwanted Objects from Users

If you need to hide some objects (for example, objects not used in a particular workspace) from the users, especially if you allow the users to create ad hoc reports, use Object Renaming Utility to hide these objects.

The hidden objects are hidden from all users in the workspace including the workspace administrators. This may make it difficult to use them.

If you use embedded Analytical Designer and only want to prevent users from seeing some objects there, consider using the includeObjectsWithTags and excludeObjectsWithTags URL parameters (see Embed Analytical Designer).

Hiding objects using Object Renaming Utility is not a security feature. Hiding an object only affects visibility of the object in various sections of the UI (such as Analytical Designer or LDM Modeler) and the API. It does not handle the users' ability to access the data in any way.

Setting Up Custom Fields in an LDM in a Multi-tenant Environment

If you use Life Cycle Management (see Managing Workspaces via Life Cycle Management), the logical data model (LDM) is aligned across the workspaces within a segment. If you need to add custom fields (facts, attributes, and so on to the LDM so that the LDM in each client workspace gets a different set of fields, do the following:

  1. Add a fixed number of placeholder fields to the LDM in the segment's master workspace.
    For example, add attributes custom1, custom2, ... custom10 to one or more datasets in the LDM.
  2. After the LDM was propagated from the master workspace to the client workspaces, use Object Renaming Utility to rename the placeholder fields in the LDM for each client workspace based on what actual data is in a particular workspace.
  3. Use Object Renaming Utility to hide the remaining unused fields in each client workspace.

In this scenario, if you are using LCM bricks, you should run Object Renaming Utility regularly after the provisioning brick (see Provisioning Brick) to make sure that newly created client workspaces have the custom fields properly set. You may also need to run Object Renaming Utility after the rollout brick (see Rollout Brick) in case it changes the names back to the default ones in the client workspaces.

  • Prepare separate placeholders for each type of a custom field (facts, attributes, dates, and so on).
  • Object Renaming Utility does not take care of preparing data to be loaded to the custom fields. Make sure that the data is ready in the data source before loading it to the dataset.
  • Make sure that you have the data prepared properly to be loaded by Automated Data Distribution (ADD; see Use Automated Data Distribution). All the workspaces still have the same LDM, and all the fields, including the hidden ones and containing empty values, in each dataset must be mapped to the appropriate source columns (see Mapping between a Logical Data Model and the Data Source). While the placeholder fields can have a different meaning for different clients, the overall structure of the LDM remains the same. For the mapping of a field, the field identifier is used, and the identifier does not change when the field itself is renamed.

Configuration File

Object Renaming Utility does not require any parameters in the configuration file.

Schedule Parameters

When scheduling Object Renaming Utility (see Phases of Building the Data Pipeline -> Production Implementation), provide the parameters from this section in the schedule.

NameTypeMandatory?DefaultDescription
rename_modestringyesn/a

The identifier of the workspaces where objects to rename/hide belong to

Possible values:

  • client_id: The workspaces are identified by the client IDs (see Use Automated Data Distribution).
    In this case, you must also enter the domain_name parameter (see further in this table).
  • project_id: The workspaces are identified by the workspace IDs (see Find the Workspace ID).

The value of this parameter defines what you provide in the source_identifier column of your queries.

domain_namestringsee "Description"n/a

The name of the domain where the workspaces belong to

This parameter is mandatory only when rename_mode is set to client_id. Otherwise, do not use it.

gd_encoded_paramsJSONyesn/aThe parameters coding the queries
dry_runBooleannofalse

Specifies whether Object Renaming Utility should only generate a log with the objects that will be renamed/hidden instead of actual renaming/hiding of the objects.

  • If not set or set to false, the objects are renamed/hidden.
  • If set to true, the objects are not renamed/hidden; instead, a log with the objects that will be renamed/hidden is generated.
allow_blank_summaryBooleannofalse

Specifies whether Object Renaming Utility allow the object description (which is provided in the summary column of your queries) to contain an empty string or a null value.

  • If not set or set to false, Object Renaming Utility does not allow empty string or null values in the description and treats them as errors.
  • If set to true, Object Renaming Utility allows empty string or null values in the description.
    • When the summary column contains an empty string, Object Renaming Utility updates the description to be an empty string.
    • When the summary column returns a null value or is not present in the query at all, Object Renaming Utility does not update the description of this object.
dont_fail_on_errorBooleannofalse

Specifies whether Object Renaming Utility fails when an error occurs.

  • If not set or set to false, Object Renaming Utility fails when an error occurs.
  • If set to true, Object Renaming Utility keeps running if an error occurs.

Regardless of what this parameter is set to, all errors are recorded to the log where you can review it later.

number_of_threadsintegerno3

The number of threads that will be used for processing the objects

IMPORTANT: The default value is sufficient for an average workspace on a standard ADS instance. Do not change the default unless you are absolutely sure in the results that you want to achieve by changing it.

Queries

The queries define the criteria for processing the objects: what objects to rename/hide and in what workspaces to do so.

Query Structure

You can specify the queries as a CSV file or a database table with the following columns:

NameTypeMandatory?DefaultDescription
source_identifierstringyesn/a

The identifier of the workspace where objects to rename/hide belong to

What you provide in this column depends on the value of the rename_mode parameter (see Schedule Parameters).

  • If rename_mode is set to project_id, provide the workspace ID.
  • if rename_mode is set to client_id, provide the client ID.

NOTE: If you use client IDs for identifying the workspaces, you can also specify the data product that each workspace belongs to (see data_product further in this table). If the data product is not specified, the default data product is used.

object_identifierstringyesn/a

The identifier of the object

object_namestringyesn/a

The new name for the object

deprecatedBooleanyesn/a

The flag that controls whether the object is hidden or visible in the workspace

  • If set to 0 or false, the object is not visible to the users in the workspace.
  • If set to 1 or true, the object is hidden from the users in the workspace (including the workspace administrators).

NOTE: The deprecated flag is not a security feature. This flag only affects visibility of the object in various sections of the UI (such as Analytical Designer or LDM Modeler) and the API. This flag does not handle the users' ability to access the data in any way.

summarystringnon/a

The description of the object

NOTE: To handle empty string or null values in the description, use the allow_blank_summary parameter (see Schedule Parameters).

data_productstringnodefault

(Only when you use client IDs in source_identifier) The data product that each workspace belongs to


Here is an example of the query file where workspace IDs are used to identify the workspaces:

source_identifier,object_identifier,object_name,deprecated,summary
e863ii0azrnng2zt4fuu81ifgqtyeoj21,fact.inventory_itemscustom.customfact3,custom price,0,"Custom prices for Warehouse"
fuu81ifgqtyeoj21e863ii0azrnng2zt4,attr.listingscustom.customattribute1,custom listing item,0,""
fuu81ifgqtyeoj21e863ii0azrnng2zt4,listingscustomdate1.dataset.dt,custom listing date,1,"Custom date for Warehouse"

Here is an example of the query file where client IDs are used to identify the workspaces and the data product is specified for each workspace:

source_identifier,object_identifier,object_name,deprecated,data_product
p3489,fact.inventory_itemscustom.customfact3,custom price,false,product_a
a9800,attr.listingscustom.customattribute1,custom listing item,false,product_a
m4801,listingscustomdate1.dataset.dt,custom listing date,false,default

Query Source

Object Renaming Utility can read the queries from the following input data sources (see Types of Input Data Sources):

  • Amazon Redshift
  • Amazon S3
  • GoodData Data Warehouse (ADS)
  • Google BigQuery
  • Microsoft Azure Blob
  • Microsoft Azure SQL Database

  • Microsoft Azure Synapse Analytics

  • Microsoft SQL Server
  • Snowflake
  • PostgreSQL

If you want to store the queries in an S3 bucket, specify the queries in a CSV file. Otherwise, specify the queries as an SQL query to the database.

When building a JSON structure for the queries as Types of Input Data Sources specifies, replace the input_source parameter with the queries_input_source parameter.

Example: The queries stored in an S3 bucket

{
  "aws_client": {
    "access_key_id": "123456789",
    "secret_access_key": "secret",
    "region": "us-east-1"
  },
  "queries_input_source": {
    "type": "s3",
    "key": "/folder/object_rename.csv",
    "bucket": "rename"
  }
}


Example: The queries obtained from ADS

{
  "ads_client": {
    "username": "john.doe@example.com",
    "password": "secret",
    "ads_id": "rtmmgjsqc4zmf64egtu6l6xv2xhxempi"
  },
  "queries_input_source": {
    "type": "ads",
    "query": "SELECT source_identifier, object_identifier, object_name, deprecated, summary, data_product FROM object_rename;"
  }
}

Queries as Schedule Parameters

When providing the queries as schedule parameters, you have to code them using the gd_encoded_params parameter (see Schedule Parameters).

To code the queries, follow the instructions in Specifying Complex Parameters. Once done, you should have the gd_encoded_params parameter coding the queries and reference parameters encoding sensitive information that you will be adding as secure parameters.

Example: The queries obtained from ADS (sensitive information present: ADS password) to be coded by the gd_encoded_params and a reference parameter encoding the ADS password

The following will become the value of the gd_encoded_params parameter:

{
  "ads_client": {
    "username": "john.doe@example.com",
    "password": "${ads_client_password}",
    "ads_id": "rtmmgjsqc4zmf64egtu6l6xv2xhxempi"
  },
  "queries_input_source": {
    "type": "ads",
    "query": "SELECT source_identifier, object_identifier, object_name, deprecated, summary, data_product FROM object_rename;"
  }
}

In addition, you have to add the reference parameter ads_client_password as a secure parameter.

Schedule Example

The following is an example of how you can specify schedule parameters:

Logs and Error Handling

Object Renaming Utility generates a log with all the changes made and errors occured.

  • If an object specified in the queries cannot be found, Object Renaming Utility skips it, logs an error, and continues the execution as usual.
  • If a workspace or data product specified in the queries cannot be found, Object Renaming Utility tries to process as many objects as it can but the execution finishes with a state of "Failed".

By default, Object Renaming Utility fails when an error occurs. You can change this behavior by setting the dont_fail_on_error parameter to true (see Schedule Parameters).

Advanced Settings

Run Object Renaming Utility Under a Different User

If you want to execute Object Renaming Utility under a different user than the default one, provide the following four parameters in the schedule. Otherwise, do not use any of these parameters and skip this section.

Some parameters must be entered as secure parameters (see Configure Schedule Parameters).

NameTypeSecure?DefaultDescription
CLIENT_GDC_HOSTNAMEstringnosecure.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_PROTOCOLstringnohttps

The protocol to transfer data over

Explicitly set this parameter to https.

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

GDC_USERNAME

stringnon/a

The user under whom you want to execute Object Renaming Utility

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

GDC_PASSWORDstringyesn/a

The password for the user that you specified in the GDC_USERNAME parameter

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

Powered by Atlassian Confluence and Scroll Viewport.