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

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

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.

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.

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.

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.

General Parameters

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

NameTypeMandatory?Secure?DefaultDescription
rename_modestringyesnon/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"non/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_paramsJSONyesnon/aThe parameters coding the queries
dry_runBooleannonofalse

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_summaryBooleannonofalse

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_errorBooleannonofalse

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_threadsintegernono3

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.

tag_update_modestringnonon/a

Specifies action to be applied to the tags property of the objects

Possible values:

  • add: Add new value to the tags property
  • overwrite: Overwrite current value of the tags property
  • remove: Remove current value of the tags property

This is an optional parameter to be used only when you want to change the tags property of the object.

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 General 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 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 General Parameters).

data_productstringnodefault

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

tagsstringnon/a

(Only when you use tag_update_mode parameter, see section General Parameters)

The tag value is used in the action defined by the tag_update_mode parameter. In case 'remove' action, please keep this value empty.

tag_update_modestringnon/a

(Only when you use tag_update_mode parameter, see section General Parameters) or tags column in the query)

Specifies the action that applies to the tags property of specified object. The action defined in tag_update_mode parameter will be overwritten by this column.

 

Here is an example of the query where workspace IDs are used to identify the workspaces (see the source_identifier column):

source_identifierobject_identifierobject_namedeprecatedsummary
e863ii0azrnng2zt4fuu81ifgqtyeoj21fact.inventory_itemscustom.customfact3custom price0Custom prices for Warehouse
fuu81ifgqtyeoj21e863ii0azrnng2zt4attr.listingscustom.customattribute1custom listing item0 
fuu81ifgqtyeoj21e863ii0azrnng2zt4listingscustomdate1.dataset.dtcustom listing date1Custom date for Warehouse

 

Here is an example of the query where client IDs are used to identify the workspaces (see the source_identifier column) and the data product is specified for each workspace:

source_identifierobject_identifierobject_namedeprecateddata_product
p3489fact.inventory_itemscustom.customfact3custom pricefalseproduct_a
a9800attr.listingscustom.customattribute1custom listing itemfalseproduct_a
m4801listingscustomdate1.dataset.dtcustom listing datefalsedefault

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
  • MongoDB Connector for BI
  • MySQL
  • Snowflake
  • PostgreSQL

If you want to store the queries in an object storage service, specify the queries in a CSV file. If you want to store the queries in a data warehouse, specify the queries as an SQL query to this data warehouse.

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

{
  "s3_client": {
    "bucket": "rename",
    "accessKey": "123456789",
    "secretKey": "secret",
    "region": "us-east-1",
    "serverSideEncryption": "true"
  },
  "queries_input_source": {
    "type": "s3",
    "file": "folder/object_rename.csv”
  }
}

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

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