Canonical ID: Using Foreign Keys to easily import data to Totango



Canonical ID allows you to store multiple Foreign Keys in Totango to synchronize data from multiple systems using their own account IDs.

Each system has its own account id. This external account ID is the Foreign Key in Totango

Using Foreign Keys allows you to import data to Totango from systems that do not have the Totango account ID without changes in these source systems.

This new capability is extremely important for customers bringing data to Totango from multiple sources. In a reality of scaling and complex systems architecture with many components, customers need to import data to Totango from many systems without any changes in these systems.

With Foreign Key you can:

  • Manage all account IDs from multiple systems in Totango
  • No need to change source systems in order to bring data to Totango
  • Faster to import data to Totango. Does not require any preparation work. 
  • Each account in Totango can have more than one foreign key for different external systems.


A customer might be using Salesforce as their main source system and import data to Totango from it.

In addition, they want to import to Totango billing info from Zuora and tickets info from Jira.

In Zuora and Jira they do not have the same account IDs 

With Foreign key, they can import data from these systems without adding custom fields to them with the Totango account ID.

Instead, they can use the local Zuora and Jira account IDs as Foreign Keys in Totango and Totango will be able to match the Zuora/Jira account ID to the Totango Account ID.

Totango will do the trick for you.


Step by step setup

  1. Import accounts to Totango from your main source system as usual.
  2. To import data from another system that does not have the Totango account id:
    1. Create and Import Keys mapping table (Totango account ID  |  Foreign Key ) using a Foreign Key job: 
    2. Import the required data from the other system as usual but use Foreign key in the job mapping table for mapping the account ID in the Totango side instead of Account ID
    3. The Foreign Key attribute can be created directly as part of the job mapping as in the step above or in the Data Modeler:
      In the job mapping:

      In Data Modeler:
  3. The data imported from the other system will be updated in Totango accounts based on the matching with the Foreign key. You can see all the Foreign Keys for specific account in the Data Sources command in Account Profile

Notes and Limitations

  • Foreign Key is not supported in SDRs and APIs
  • The foreign key values for a specific source system must be unique across all the accounts
  • Foreign keys are stored in Totango in lowercase (case insensitive)
  • Accounts modeled in hierarchy in Totango are supported as well when you want to bring data from another system using foreign key
  • If there is no account with the key value for the parent Id, we return an error and don’t create the account
  • By default, the option “Allow new object creation” is set to true. This means that if there is no account with the Foreign Key value, a new account will be created in Totango with the Foreign Key as the Account ID and also as the Foreign Key value of this account.
  • “Allow new object creation” is relevant only for accounts
  • If  “Allow new object creation” is not checked and there is no account with the Foreign Key value it will be an error.
  • If a job is using Foreign Key  for mapping Account ID, also Parent ID should be mapped to an attribute with a Foreign Key value






Was this article helpful?

0 out of 0 found this helpful

Have more questions? Submit a request