Mapping Global Identifiers to Workspace Identifiers

Also called "object id", URI or local identifier, is a numeric identifier, associated with each object, which is usually displayed in the format /gdc/md/{workspace_id}/obj/5308 or 5308.

• The Workspace Identifier is local to each Flex Insights workspace, and can't be externally modified.
• Any object created in a workspace causes this number to increase by 1.

Also called external identifiers or identifiers. There are two distinct categories:

• For the Data Model objects (attributes, facts, etc) the identifier has the following format "attributes.conversation.ivr_path".
• For the UI objects (reports, metrics, dashboards) the format is a 12 character long alphanumeric, for example, "b08a2c8ca8f4".

An object's Global Identifier can be manipulated under certain conditions, but Flex Insights ensures that the identifier is unique within each individual workspace.

Twilio uses the Global Identifier to ensure that the set of built-in objects with the same Global Identifier have the same definition across all Flex Insights workspaces. Workspace Identifiers, on the other hand, are used to identify specific objects within a workspace.

Here's an example where two reports have different Workspace Identifiers across two Flex Insights workspaces, but the same Global Identifier is the same. Company A and Company B both want to use Q and A Reports. In their individual Flex Insights instances, Company A and B would see the same global identifier (i.e., abPBFm6ZgjV4), but different Workspace Identifiers (e.g., 4309 for Company A, and 51684 for Company B.)

Expand image

All the Flex Insights API requests must use the Workspace Identifier, so Flex Insights provides APIs for translating back and forth between Workspace Identifiers and Global Identifiers. This allows you to map your objects to their Global Identifiers using their Workspace Identifier.

Before you can start the mapping between the Global Identifier and the Workspace Identifier, you need the following:

• a provisioned Flex Insights Workspace
• the credentials of a user with access to the Flex Insights Workspace
• The Global Identifier of the object you want to map to a Workspace Identifier
• REST API client support for cookies that are used to pass authentication tokens

Ensure that you are authenticated against the Flex Insights API by having a valid TT (temporary token). The procedure is detailed at API Authentication

You will need:

Workspace ID: Log in to the Analytics Portal and check the URL in the browser address bar. For example:

Expand image

The workspace ID is the string appearing between the #s=/gdc/projects/ segment and the vertical bar. In this case, the workspace ID is z2nxqtb1r6weuly0iivexz6hu5dathua.

Object Global Identifier: This will most likely be provided by you in some document, external documentation or by Expert Services. The expected format is abJBDYXwfBG1.

Now you have everything you need to start mapping your identifiers!

1
curl -X POST https://analytics.ytica.com/gdc/md/{WORKSPACE_ID}/identifiers \
2
  -H 'Accept: application/json' \
3
  -H 'Content-Type: application/json' \
4
  -H 'Cookie: GDCAuthTT=XXXXX-XXXXX-XXXXX' \
5
  -d '{"identifierToUri": [ "GLOBAL_IDENTIFIER" ] }'

1
{ "identifiers": 
2
  [
3
    {
4
      "identifier": "{global_identifier}",
5
      "uri": "/gdc/md/{workspace_id}/obj/{workspace_identifier}"
6
    }
7
  ]
8
}

By parsing the response JSON, you can get the Workspace Identifier at identifiers[0] ▸ uri

Multiple identifiers can be mapped in one API call since the identifiers are passed as a JSON list. A list of mappings is returned as a response.

1
curl -X POST https://analytics.ytica.com/gdc/md/{WORKSPACE_ID}/identifiers \
2
  -H 'Accept: application/json' \
3
  -H 'Content-Type: application/json' \
4
  -H 'Cookie: GDCAuthTT=XXXXX-XXXXX-XXXXX' \
5
  -d '{ "identifierToUri": [
6
          "GLOBAL_IDENTIFIER_1",
7
          "GLOBAL_IDENTIFIER_2"
8
        ]
9
      }'

1
{ "identifiers": 
2
  [
3
    {
4
      "identifier": "{global_identifier_1}",
5
      "uri": "/gdc/md/{workspace_id}/obj/{workspace_identifier_1}"
6
    },
7
    {
8
      "identifier": "{global_identifier_2}",
9
      "uri": "/gdc/md/{workspace_id}/obj/{workspace_identifier_2}"
10
    }
11
  ]
12
}

If you want to map the Workspace Identifier to the Global Identifier, you can call the same API with the parameter uriToIdentifier instead of identifierToUri and provide a list of Workspace Identifiers.

1
curl -X POST https://analytics.ytica.com/gdc/md/{WORKSPACE_ID}/identifiers \
2
  -H 'Accept: application/json' \
3
  -H 'Content-Type: application/json' \
4
  -H 'Cookie: GDCAuthTT=XXXXX-XXXXX-XXXXX' \
5
  -d '{ "uriToIdentifier": [ "WORKSPACE_IDENTIFIER" ] }'

1
{ "identifiers": 
2
  [
3
    {
4
      "identifier": "{global_identifier}",
5
      "uri": "/gdc/md/{workspace_id}/obj/{workspace_identifier}"
6
    }
7
  ]
8
}

Once you get the Workspace Identifier, it is safe to assume that for each Flex Insights workspace, the Workspace Identifier will never change.

The Workspace Identifier can be used in any API call (for example, exporting raw data.)