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

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:

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

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:

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