Prepare the Tableau <source ID> configuration file

The lineage harvester uses the configuration file to connect to Tableau. You use the Tableau <source ID> configuration file to:

  • Define your Tableau operating model.
  • Provide additional information about databases and files in Tableau. For example, you can define the system name of databases in Tableau.
  • Map a Tableau technical database name to the real database name, to preserve stitching. See the databaseMapping property.
  • Define in which domains in Collibra you want to ingest assets from your Tableau sites and projects. See the domainMapping and filters properties.

Tip "<source ID>" refers to the value of the Id property in the lineage harvester configuration file.

Steps

  1. Create a new JSON file in the lineage harvester config folder.
  2. Give the JSON file the same name as the value of the Id property in the lineage harvester configuration file.
    Example If the value of the Id property in the lineage harvester configuration file is tableau-source-1, then the name of your JSON file should be tableau-source-1.conf.
    Important Your JSON file must have the file extension .conf.
  3. For each database in Tableau, add the following content to the JSON file:
    Tip You can use wildcards to capture multiple string combinations for any of these properties.
    PatternDescription
    *Matches everything.
    ?Matches any single character.
    [seq]Matches any character in "seq".
    [!seq]Matches any character not in "seq".

    Property

    		Description
    collibraSystemNames

    This section contains the system information for different Tableau data sources. Depending on the kind of data source or connection, you have to specify how to connect to this data source.

    Tip For more information, see the Tableau documentation. We also recommend to check the list of supported connectors in Tableau.

    databases

    This section contains connection information to one or more databases in Tableau.

    Tip 
    • If you do not have databases in Tableau, you can remove this section.
    • The values that you specify for this property are not case-sensitive.
    hostName
    		The host name of the database.
    collibraSystemName

    The system name of the database.

    Let's assume you have two databases named Customers. When you prepare the physical data layer in Data Catalog, you create a System asset for each of these databases. Let's say you named them Customers-Europe and Customers-USA. You can then configure this property as follows.

    "collibraSystemNames": {
   "databases": [
   {
       "hostName": "database-hostname-1",
	"collibraSystemName": "Customers-Europe"
   },
   {
	"hostName": "database-hostname-2",
	"collibraSystemName": "Customers-USA"
   }
],

    Warning The value of this property must exactly match (including for case-sensitivity) the name of your System asset in Collibra.

    files

    This section contains connection information to one or more files in Tableau.

    Tip If you do not have files in Tableau, you can remove this section.

    filePath
    		The full path to the file. For example, the path to a JSON file.
    collibraSystemName
    		The system name of the file.
    connectors

    This section contains connection information to one or more connectors in Tableau.

    Tip 
    • If you do not have connectors in Tableau, you can remove this section.
    • The values that you specify for this property are not case-sensitive.
    connectorUrl
    		The URL of the connector. For example, the URL to Google Analytics.
    collibraSystemName
    		The system name of the connector.
    cloudFiles

    This section contains connection information to one or more cloud files in Tableau's input data.

    Tip If you do not have cloud files in Tableau, you can remove this section.

    name
    		The name of the file. For example, the name of a Zendesk file.
    collibraSystemName
    		The system name of the cloud file.

    databaseMapping

    The Tableau API returns a technical database name based on the hostname, instead of the actual database name, which breaks stitching. The values that you specify for this property are not case-sensitive.

    This property allows you to map a Tableau technical database name to the real database name, for example:

     
 "databaseMapping": {
	"<hostname:port>":"<actual database name>" 
 }

    Including the port, as shown in the example, is optional.

    filters

    This section defines:

    • From which Tableau sites and projects you want to harvest metadata.
    • Into which domains in Collibra you want to ingest the corresponding assets.

    Filtering is transitive, which means that all resources in a specified project, such as Tableau workbooks and all sub-projects, are ingested.

    Tableau assets that are not mapped to the specified domains, for example the Tableau Server assets and the parent projects (if you specify their sub-projects), are ingested in the default domain.

    Important The domainMapping and filters sections are mutually exclusive. Do not include both domainMapping and filters sections in your JSON file.

    Tip 
    • If you want to ingest all of the projects in a Tableau site into multiple domains in Collibra, use the domainMapping section.
    • If you want to ingest all of the projects in a Tableau site into the default domain, use only the domainID property in the lineage harvester configuration file. The domainID property represents the default domain.
    • If you want to ingest all of the projects in a Tableau site into a single domain in Collibra, use site filtering.
    • If you want to ingest metadata from only some of the projects in a Tableau site, use project filtering.
    • You can use site filtering and project filtering together:
      • If filtering on the same site, this "filtering" is actually domain mapping, because nothing is filtered out. The contents of the projects are ingested in the specified domains, and the rest of the contents of the site are ingested in a different, specified domain.
      • If you are site filtering on a specific site and project filtering a different site, then site filtering is again a form of domain mapping, and the filtered projects are ingested in their specified domains.
      • If your lineage harvester configuration file includes sites that are not mentioned in the filters section of your <source ID> configuration file, those sites are ingested in the default domain.
    sites

    The Tableau sites to be ingested and the domain in which you want to ingest metadata from the Tableau sites.

    Tip If you have only one Tableau site, do not include a sites section in your <source ID> file. Instead, use a projects section, to filter on Tableau projects. Include a sites section only if all of the following are true:
    • You have more than one Tableau site.
    • You want to ingest all of the metadata from only one Tableau site into a single domain in Collibra.
    • The domain into which you want to ingest is not the default domain, meaning the domain specified in the domainId property in your lineage harvester configuration file.
    site_name: domain_id
    site_name
    The name of the site to be ingested. The site name is case-sensitive.
    domain_id
    The unique reference ID of the domain in Collibra in which you want to ingest metadata. The domain ID is case-sensitive.
    To ingest all metadata from a Tableau site in the specified domain, specify the site name and a separate domain ID for each site that you list on the siteIds property in the lineage harvester configuration file for Tableau. If the site_name or domain_id property is not specified for a site, the metadata from the site is ingested in the default domain.

    Open the relevant domain in Collibra. The URL looks like: https://<yourcollibrainstance>/domain/22258f64-40b6-4b16-9c08-c95f8ec0da26?view=00000000-0000-0000-0000-000000040001. In this example, the reference ID is in bold.

    {
  "filters":{
	"sites":{
	  "Training":"ca60b822-781b-4b3a-b44d-f65bd107ff92"
	},
	"projects":{
	  "Testing > Databricks":"e8f4e4a8-4062-4a33-9b44-3ce3e18e4e22",
	  "Product Demo > Customer Insights":"a305e6f7-7a49-49aa-aa85-41b1e689121b"
	}
   }
}
    projects

    The Tableau projects to be ingested and the domain in which you want to ingest metadata from the Tableau projects or sub-projects.

    Tip Project filtering is not relevant for those who have an Explorer role in Tableau, because Explorers need to configure permissions for each data object in Tableau that they want to ingest. As the Administrator role has access to all data objects, project filtering allows Administrators to specify which projects to ingest.

    site_name > project_name : domain_id

    The site_name should be the Tableau site name. The project_name should be the Tableau project name.

    The domain_id should be the unique reference ID of the domain in Collibra in which you want to ingest metadata.

    When you specify the site and project names, the following rules apply:

    • Add spaces before and after >. The spaces are separators between the site and project.
    • Specify the full exact site and project names.
    • The values are case-sensitive.

    When you specify a Tableau project, all assets in the project are ingested in the specified domain. If you want to ingest assets from different Tableau projects in one domain, you can specify the same value for domain id for different projects.

    Example

    "Collibra_tab_partner_site > JB_Test_2812": "d224a1a5-43b4-43b2-8df0-ddf8f2726b82"

    site_name > project_name > sub-project_name : domain_id

    The site_name should be the Tableau site name. The project_name should be the Tableau project name. Optionally, use sub-project_name to specify the Tableau sub-project name.

    The domain_id property should be the unique reference ID of the domain in Collibra in which you want to ingest metadata.

    When you specify the site, project and sub-project names, the following rules apply:

    • Add spaces before and after >. The spaces are separators between the site and project.
    • Specify the full exact site and project names.
    • The values are case-sensitive.

    Example

    "Collibra_tab_partner_site > JB_Test_2812 > ProjectJJ2": "d224a1a5-43b4-43b2-8df0-ddf8f2726b82"

    domainMapping

    This section defines in which domains in Collibra you want to ingest assets from your Tableau sites and Tableau projects.

    Domain mapping is transitive, meaning that all resources, such as Tableau workbooks and data attributes in a parent Tableau site, project or sub-project, are ingested in the same domain as the parent.

    Important The domainMapping and filters sections are mutually exclusive. Do not include both domainMapping and filters sections in your JSON file.

    Tip 
    • If you want to ingest all of the projects in a Tableau site into multiple domains in Collibra, use this domainMapping section.
    • If you want to ingest all of the projects in a Tableau site into the default domain, use only the domainID property in the lineage harvester configuration file. The domainID property represents the default domain.
      Note Tableau assets that are not mapped to specific domains via this domainMapping section, for example Tableau Server assets, are ingested in that default domain.
    • If you want to ingest all of the projects in a Tableau site into a single domain in Collibra, use site filtering.
    • If you want to ingest metadata from only some of the projects in a Tableau site, use project filtering.

    Let's say that you have a Tableau site named "Site-1". You want to ingest all Tableau projects in "Site-1" in a domain named "Domain-1" in Collibra, with the exception of one Tableau project named "Project-Default", which you want to ingest in "Domain-2". You should configure the domainMapping section as follows.

    "domainMapping": {
	 "<Site-1>": "reference-id-of-Domain-1",
	 "<Site-1> > <Project-Default>": "reference-id-of-Domain-2"
	}

    If you want to specify a domain for a sub-project of "Project-Default", use the <site name> > <project name> > <sub-project name> property, as described below.

    Tip For the properties in this domainMapping section, ensure that you maintain the spaces before and after ">", for example "Site-1 > Project-Default". The spaces serve as a separator between the site and the projects.
    site name

    The Tableau site name, followed by the unique reference ID of the domain in Collibra in which you want to ingest resources from the Tableau site.

    Important In the configuration file, use the actual site name, along with the domain reference ID, for example: "Collibra_tab_partner_site": "afc8cfb0-91f1-4075-a3e5-7ce6d1f9bcc9"
    site name > project name

    The Tableau project name, preceded by the name of the Tableau site to which it belongs, and followed by the unique reference ID of the domain in Collibra in which you want to ingest resources from the Tableau project.

    Important In the configuration file, use the actual site and project names, along with the domain reference ID, for example: "Collibra_tab_partner_site > JB_Test_2812": "d224a1a5-43b4-43b2-8df0-ddf8f2726b82"
    site name > project name > sub-project name

    The Tableau sub-project name, preceded by the name of the Tableau site and project to which it belongs, and followed by the unique reference ID of the domain in Collibra in which you want to ingest resources from the Tableau sub-project.

    Important In the configuration file, use the actual site, project and sub-project names, along with the domain reference ID, for example: "Collibra_tab_partner_site > JB_Test_2812 > ProjectJJ2": "d224a1a5-43b4-43b2-8df0-ddf8f2726b82"
    .

    Copy code

    {
  "collibraSystemNames": {
    "databases": [
      {
        "hostName": "database-hostname",
        "collibraSystemName": "public"
      }
    ],										
    "files": [
      {"filePath": "C:\\ProgramData\\Tableau\\Tableau Server\\data\\files\\sample.xls",
        "collibraSystemName": "sample-files"
      }
    ],
    "connectors": [
      {
        "connectorUrl": "tableau-server-connector-url.com",
        "collibraSystemName": "Oracle-connector"
      }
    ],
    "cloudFiles": [
      {
        "name": "file-name",
        "collibraSystemName": "FILE"
      }
    ]
  },
  "databaseMapping": {
	 "<hostname:port>":"<actual database name>"
  },
  "filters": {
	 "sites":{
	   "site_name":"domain_id"
	 },
        "projects":{
          "site_name2 > project_name2": "domain-reference-id2",
          "site_name3 > project_name3 > subproject_name": "domain-reference-id2"
	 }
   }	
}

    Tip Click Copy code to copy the example to your clipboard.

    .

    Copy code

    {
  "collibraSystemNames": {
    "databases": [
      {
        "hostName": "database-hostname",
        "collibraSystemName": "public"
      }
    ],										
    "files": [
      {"filePath": "C:\\ProgramData\\Tableau\\Tableau Server\\data\\files\\sample.xls",
        "collibraSystemName": "sample-files"
      }
    ],
    "connectors": [
      {
        "connectorUrl": "tableau-server-connector-url.com",
        "collibraSystemName": "Oracle-connector"
      }
    ],
    "cloudFiles": [
      {
        "name": "file-name",
        "collibraSystemName": "FILE"
      }
    ]
  },
  "databaseMapping": {
	 "<hostname:port>":"<actual database name>"
  },
  "domainMapping": {
	 "<Site-1>": "reference-id-of-Domain-1",
	 "<Site-1> > <Project-Default>": "reference-id-of-Domain-2"
  }	
}

    Tip Click Copy code to copy the example to your clipboard.

  4. Save the <source ID> configuration file.