Metadata Localization and Business Translations for Reports

Important: This feature is not available to Trial or Professional Edition users. You must be a Space Administrator to set up this feature.

A common situation for OEM or enterprise reporting solutions is that different subsets of users require different views of the same report. The data is the same for all users, but the metadata may need to be different. One difference can be the language, such as when the titles of columns need to be changed for different language readers. Other differences may reflect a business context, such as when different groups use different terminology to describe the same column.

Birst provides both language and terminology customization for a Visualizer report's attribute, expression, or measure names, without duplicating the report. For the default or a custom subject area, you map an original name to another name. You create a set of these mappings in a specific file format and upload it to Birst and mark it as a Discovery source. You create query-based session variables that return the mapped names from the mapping file, and then assign the variables to subject areas. Users can see the mapped names in subject areas and in report listings, labels, and filters.

Tips:

  • Not every name must be mapped. Both mapped and unmapped names can appear in the same report.
  • If there is no mapping, users will see the original name.
  • Dashboards 2.0 filters show the mapped names, unless another name is assigned for the filter in Dashboards 2.0.
  • You can change the mappings at any time in the Discovery source.
  • Designer reports are not supported.

Note: To translate the Birst user interface, see the Changing the Language online help topic.

There are three main steps to setting it up:

  1. Create and upload a file containing the mapping information. Set it as a Discovery source.
  2. Create one or more query-based session variables that call the file.
  3. In Visualizer, assign the variable to a subject area.

To set up the mapping file

  1. Create a file following a specific format.
    IndexSubject Area NameFully Qualified Object Name
    (attribute, measure, or expression)    		Mapped NameTenantIDLocale
    1Default Subject AreaAttributes.Categories.CategoryIDKategorie ID101de_DE
    2Default Subject AreaMeasures.QuantityAnzahl101de_DE
    3Custom Subject Area 1Products.ProductNameProd2102en_IN
    4Custom Subject Area 1 Products.DescriptionDesc2102en_IN

    File format rules and tips include:

    • The fully qualified object name and mapped name columns are required.
    • The subject area column is optional if you have only one subject area.
      • The fully qualified object name syntax is as follows for the default subject area:
        • Measures.MeasureName
        • Attributes.DimensionName.AttributeName
        • GlobalExpressions.ExpressionName (these are Visualizer variables that have been marked "Make Global".
      • The fully qualified object name syntax for custom subject areas uses the folder structure, for example:
        • FolderName.MeasureName
        • FolderName.FolderName.MeasureName
        • FolderName.FolderName.AttributeName
    • The subject area column is optional if you have only one subject area.
    • It is helpful to add an index column in case you need a primary key.
    • If you will define a query session variable geared towards individual users, set up a Locale column with the values of the Birst language setting. Do one of the following to get the Locale values:
      • Go to Admin - Manage Space - Command Window and run the listlanguages command to get the internal code used for a language. Then substitute the hyphen with an underscore (en-US becomes en_US).
      • Go to Admin - Define Sources - Query Admin and run the following query: SELECT 'V{UserLocale$}' FROM [ALL]. This shows the current possible values of UserLocales$ in the current space.

      Later in the query variable use the UserLocale$ built-in session variable, which returns the value of the user's Language setting, in a WHERE clause.

    • If you are in an OEM multi-tenant environment, you can use a TenantID or equivalent column in a WHERE clause.
  2. Enter the terminology and mappings into the file, as per the example.
  3. Upload the file. You can use Birst Connect, web services, or Admin - Define Sources - Upload File.
  4. In Admin - Define Sources - Data Flow, right-click on the source and check it as a Discovery source.

To create the query variables

  1. In Admin - Customize Space - Variables, click Create. Enter an expression that returns the mapped data.

    Example query for a multi-tenant environment, using a variable you created that returns the tenant ID:
    SELECT [MyMapping.FullyQualifiedName], [MyMapping.MappedName] FROM [ALL] WHERE MyMapping.TenantID=GetVariable('MyTenant')

    Example query for user-based localization:
    SELECT [MyMapping.FullyQualifiedName], [MyMapping.MappedName] FROM [ALL] WHERE MyMapping.Locale=GetVariable('UserLocale$')

    Tip: For multiple subject areas, when you want to provide different mapping for the same field in different custom subject areas, you can provide that information in a Subject Area column in the source and then add it to the WHERE clause.

  1. Click Validate.
  2. Click OK.

To assign a variable to a subject area

In Visualizer, you associate a subject area with a variable that returns the results from the Discovery source.

  1. Click Change Subject Area.
  2. At the bottom of the list, click S.A. Translation Settings.
  3. For the subject area, select the variable that calls the mapping file.

  4. Click Done.