How to Create MetaKeys

MetaKeys Overview

In order to leverage data from multiple sources and turn it into actionable information, MetaCX relies on a concept called MetaKeys.

MetaKeys provide a way to standardize and store an endless number of data points. Because every business system uses different naming conventions, it’s necessary to have an authoritative identifier for things like

  • CompanyID
  • Location
  • Vehicle Type

By normalizing data sourced from multiple systems, you can gain a complete understanding of the actions your customers are taking across every customer touchpoint. 

An Alternate Key, or AltKey, is an identifier from one of your business systems. For example, the ID that your CRM system uses to identify your customers is an AltKey.

Within MetaCX, you will map AltKeys to MetaKeys when creating a Signal. 

How to Create a MetaKey

MetaKeys and Dimensions are important within MetaCX because they set the foundation for data normalization. Data normalization ensures that data appears similar across records which makes it much easier to properly bubble up into a metric. For MetaCX it is ultimately important that dimensions, or companies/organizations, have proper keys allocated to them--to normalize what events pertain to what objects.

For example: a MetaCX user has an organization that they intend to send events about. In the MetaCX Organization/Company Profile you can see the MetaKey value and other IDs that have been linked to that particular organization. MetaKeys are not necessarily created, but rather assigned when the organization/company is created within MetaCX.


How to Create an AlternateKey

AlternateKeys or AltKeys are used to join system generated ids to the MetaCX MetaKey to allow for proper data normalization at the Signal level. This means during instrumentation and configuration that a user "could" technically use the MetaCX generated MetaKey as their ID for events that occur within their system. However, that is not necessary, and instead AlternateKey definitions can be created to represent an org/company by updating each AlternateKey per org/company. Using the example above:

1. To create an organization/company AlternateKey you will need to generate a Machine to Machine connection and also be prepared to send GraphQL API calls. If you cannot do this, reach out to your MetaCX contact for more help!


2. Once properly authenticated, an AlternateKey definition needs to be generated using this call:


createAlternateKeyDefinition(input: {
alternateKeyName: "facilityid"
displayName: "Facility Identification Number"
metaKeyNames: ["companyid"]
}) {


3. The above API call does two things. It asks for an alternateKey name and displayName. These can be entered as the same name, however, for the display name it is recommended to submit something that is more human readable. For example: alternateKeyName: facilityid // displayName: Facility Identification Number.


4. Once you send the call above, it will create the definition. To create an alternateKey for each organization/company you will need to get each "companyId" MetaKey. The API call for updating a MetaCX organization/company is:


createAlternateKey(input: {alternateKeyName: "facilityid", alternateKeyValue: "id of the object", metaKeyName: "companyid", metaKeyValue: "387727fd3d4fakenumber"}) {
metaKey {


On the above call you'll notice a few things. First, we set the appropriate altKey name to ensure that the altkey to be updated is updated correctly. Second, we include the id of the system/location etc in the alternateKeyValue. Third, to update the standard MetaCX organization/company object you will need the companyid found in the profile. Lastly, you can copy/paste the MetaKey value of the organization/company into the metaKeyValue. Once sent, the system will respond with a success response, and the profile can be checked to ensure that you see the altKey/MetaKey pairing in app.

Have more questions? Submit a request