Mappings configuration

Learn about the mappings section of the Subscriptions API.

The Subscriptions configuration includes the mappings section to control how entities and attributes in the Data Tenant (DT) are mapped to the corresponding entities and attributes in the Customer Tenant (CT).

The data model in the CT may be different from the data model in the DT. Entities, relations and their attributes could have different names. You might want to map an attribute on the DT to a different attribute on the CT. Or maybe, you want to map a single attribute on the DT to multiple attributes on the CT. Alternatively, you just want to subset the attributes on the DT to be mapped to the CT. The mappings section gives you a way to control the mapping of the attributes of the DT to the CT.

If the mappings section is empty, DTSS maps every entity and relationship attribute in the DT to each corresponding identical attribute in the CT. If the CT does not have an identical attribute to the DT, it is not mapped. This is the simplest case where there is a strict one-to-one mapping from the DT to the CT. However, if you want to map a subset of the DT attributes, or, if the attributes on the CT have different names from those on the DT, they can be mapped on the mappings section as shown in the example below.

"mappings": [
    {
        "copyFromDT": "configuration/entityTypes/Individual",
        "copyToCT": "configuration/entityTypes/Contact",
        "attributes": [
            {
                "copyFromDT": "configuration/entityTypes/Individual/attributes/Identifiers",
                "copyToCT": ["configuration/entityTypes/Contact/attributes/Identifiers"],
                "attributes": [
                    {
                        "copyFromDT": "configuration/entityTypes/Individual/attributes/Identifiers/attributes/ID",
                        "copyToCT": ["configuration/entityTypes/Contact/attributes/Identifiers/attributes/ID"]
                    }
                ]
            },
            {
                "copyFromDT": "configuration/entityTypes/HCO/attributes/Identifiers/attributes/Type",
                "copyToCT": ["configuration/entityTypes/HCO/attributes/Identifiers/attributes/identType"]
            }
        ]
    }
]

Two properties are used to control the behavior and enable you to map different entity types to each other:

copyFromDT - This specifies which entity in the DT is used as the source of the data.
copyToCT - This specifies the target for the data.

The attributes section within the mappings section specifies the mappings of individual attributes.

If you want to sync all the attributes except for specific ones, you should map those attributes to non-existing ones in the DTSS subscription mapping. This prevents those attributes from being synced.

Note: A single DT attribute can be copied to multiple CT attributes.

When working with simple attributes, the following constraints apply:

A top-level simple attribute in the DT object can only be mapped to top-level simple attributes in the CT object.
A nested simple attribute in the DT object can only be mapped to nested simple attributes in the CT object, at the same level of hierarchy.

These constraints help ensure structural consistency during attribute transformation.

To understand the different ways in which you can map CT and DT attributes, see the following example topics.

Mapping attributes with same names but different entity types

You can map a DT attribute with the same name to a CT attribute with a different entity type as shown below.

"attributes": [
          {
            "copyFromDT": "configuration/entityTypes/HCO/attributes/Identifiers/attributes/ID",
            "copyToCT": [
              "configuration/entityTypes/Individual/attributes/Identifiers/attributes/ID"
            ]
          },

"attributes": [
    {
        "copyFromDT": "configuration/entityTypes/Individual/attributes/Identifiers/attributes/ID",
        "copyToCT": ["configuration/entityTypes/Contact/attributes/Identifiers/attributes/ID"]
    }
]

Mapping attributes with same entity type but different attribute names

You can map a DT attribute to a CT attribute with the same entity type but with a different name as shown below.

"attributes": [
          {
  "copyFromDT": "configuration/entityTypes/HCO/attributes/Phone/attributes/GeoCountry",
  "copyToCT": [
    "configuration/entityTypes/HCO/attributes/Phone/attributes/Country",
  ]
},

{
    "copyFromDT": "configuration/entityTypes/HCO/attributes/Identifiers/attributes/Type",
    "copyToCT": ["configuration/entityTypes/HCO/attributes/Identifiers/attributes/identType"]
}

Mapping a single DT attribute with multiple CT attributes

You can map a single attribute in the DT to multiple values in the CT. A single DT reference attribute is mapped to three different attributes in CT in the example shown below.

{
            "copyFromDT": "configuration/entityTypes/HCO/attributes/ClassofTradeN/attributes/FacilityType",
            "copyToCT": [
              "configuration/entityTypes/HCO/attributes/ClassofTradeN/attributes/FacilityType",
              "configuration/entityTypes/HCO/attributes/ClassofTradeN/attributes/AccountType",
              "configuration/entityTypes/HCO/attributes/AccountType"
            ]
}

"attributes": [
    {
        "copyFromDT": "configuration/entityTypes/HCO/attributes/ClassofTradeN/attributes/FacilityType",
        "copyToCT": [
            "configuration/entityTypes/HCO/attributes/ClassofTradeN/attributes/FacilityType",
            "configuration/entityTypes/HCO/attributes/ClassofTradeN/attributes/AccountType",
            "configuration/entityTypes/HCO/attributes/AccountType"
        ]
    }
]

Mapping a DT Reference attribute to a CT Nested attribute

A reference attribute in a DT can be mapped to a nested attribute in a CT. In the following example, the Address reference attribute in the DT is mapped to the Address nested attribute in the CT. Here the DT uses the Location entity and HasAddress relation type to store address details via a reference attribute.

{ "hidden": false,
"type": "Reference",
"uri": "configuration/entityTypes/Location/attributes/Address",
"referencedAttributeURIs":[
	"configuration/relationTypes/HasAddress/attributes/AddressType",
	"configuration/relationTypes/HasAddress/attributes/CareOf",
	"configuration/relationTypes/HasAddress/attributes/Primary",
	"configuration/relationTypes/HasAddress/attributes/AddressRank",
	"configuration/entityTypes/Location/attributes/AddressLine1",
	"configuration/entityTypes/Location/attributes/AddressLine2",
	"configuration/entityTypes/Location/attributes/City",
	"configuration/entityTypes/Location/attributes/StateProvince",
	"configuration/entityTypes/Location/attributes/Zip",
	"configuration/entityTypes/Location/attributes/Country"
]
}

The DT entity types and relation types may not exist in the CT (Location and HasAddress) and do not need to be created there. The DTSS will resolve the mapping. Wild cards (*) can be used to copy all attribute values from the DT to the CT but only attributes with identical names between DT and CT will be mapped.

{
  "copyFromDT": "configuration/entityTypes/HCP/attributes/Address",
  "copyToCT": "configuration/entityTypes/HCP/attributes/AddressNested",
  "attributes": [
    {
      "copyFromDT": "configuration/entityTypes/HCP/attributes/Address/attributes/*",
      "copyToCT": [        "configuration/entityTypes/HCP/attributes/AddressNested/attributes/*"
      ]
    }
  ]
}

Mapping a DT Nested attribute to a CT Reference attribute

In this example, the AddressNested attribute in the DT is mapped to the Address reference attribute in the CT. Here the CT uses the Location entity and HasAddress relation type to store address details via reference attributes. The CT entity types and relation types may not exist in the DT and do not have to be created there. DTSS will resolve the mapping.

{ "hidden": false,
"type": "Reference",
"uri": "configuration/entityTypes/Location/attributes/Address",
"referencedAttributeURIs":[
	"configuration/relationTypes/HasAddress/attributes/AddressType",
	"configuration/relationTypes/HasAddress/attributes/CareOf",
	"configuration/relationTypes/HasAddress/attributes/Primary",
	"configuration/relationTypes/HasAddress/attributes/AddressRank",
	"configuration/entityTypes/Location/attributes/AddressLine1",
	"configuration/entityTypes/Location/attributes/AddressLine2",
	"configuration/entityTypes/Location/attributes/City",
	"configuration/entityTypes/Location/attributes/StateProvince",
	"configuration/entityTypes/Location/attributes/Zip",
	"configuration/entityTypes/Location/attributes/Country"
]
}

Reference attributes in the CT may exist either on the entity or the relationship type. The referenceObjectType property must be used to specify whether the target attribute is located on the entity or the relationship. If the target in the CT is on the entity type, the referenceObjectType property must be set to referenceEntity, and if the target in the CT is on a relation type, the referenceObjectType property must be set to referenceRelation.

{
  "copyFromDT": "configuration/entityTypes/HCP/attributes/AddressNested",
  "copyToCT": "configuration/entityTypes/HCP/attributes/Address",
  "attributes": [
    {
      "copyFromDT": "configuration/entityTypes/HCP/attributes/AddressNested/attributes/*",
      "copyToCT": [        "configuration/entityTypes/HCP/attributes/Address/attributes/*"
      ],
	"referenceObjectType": "referenceEntity"
    },
	{
      "copyFromDT": "configuration/entityTypes/HCP/attributes/AddressNested/attributes/AddressType",
      "copyToCT": [        "configuration/entityTypes/HCP/attributes/AddressType"
      ],
	"referenceObjectType": "referenceRelation"
    }
  ]
}

Mapping relationship attributes

Relationship attributes can be mapped in the same way as entities. In this example, the HasAddress relation type on the AddressType relationship attribute in the DT is mapped to the same attributes in the CT.

{
        "copyFromDT": "configuration/relationTypes/HasAddress",
        "copyToCT": "configuration/relationTypes/HasAddress",
	"attributes":[
		"copyFromDT": "configuration/relationTypes/HasAddress/attributes/AddressType",
        	"copyToCT": "configuration/relationTypes/HasAddress/attributes/AddressType"]
          }

A relationship attribute in the DT can also be mapped to multiple relationship attributes on the CT in exactly the same manner as entity attributes.

Transforming attribute values

Attribute values can be transformed. This is typically done with lookups. If the attribute value in the DT needs to be transformed to a different value in the CT, this can be done in the transform value section.

{
  "copyFromDT": "configuration/relationTypes/HasAddress/attributes/AddressRank",
  "copyToCT": [
   "configuration/relationTypes/HasAddress/attributes/AddressRank"
  ],
  "transformValue": [
    {
      "from": "1",
      "to": "0"
    },
    {
      "from": "2",
      "to": "0"
    }
  ]
}

In this example, an address rank in the DT of either one or two is transformed to an address rank of zero in the CT. This enables you to control how values on the DT map to corresponding values on the customer tenant.

Filtering attribute values

Attribute values can also be filtered on the DT so they do not get copied to the CT.

{
    "copyFromDT": "configuration/relationTypes/HasAddress",
    "copyToCT": "configuration/relationTypes/HasAddress",
    "attributes": [],
    "filter": [
        {
            "attribute": "configuration/relationTypes/HasAddress/attributes/AddressRank",
            "values": [
                "1",
                "2"
            ]
        }
    ]
}

In this example, the DT has Address Ranks going from one to 10. If you only want DT addresses that have Address ranks of only 1 or 2 to copy to the CT, you can filter them using the filter property as shown here.

Advanced Filtering

There are a variety of different expressions that can be used to do more sophisticated filtering of attribute values. The “query” key can be used to perform more advanced filtering functions.

{
    "copyFromDT": "configuration/entityTypes/HCP/attributes/Identifiers/attributes/ID",
    "copyToCT": ["configuration/entityTypes/HCP/attributes/Identifiers/attributes/ID"],
    "filter": [
        {
            "query": "regexp(value, '^[a-zA-Z]{4}\\\\d{1}$')"
 	}
    ]
}

In this example, any IDs that contain characters that are not specified in the regexp (regular expression) will be excluded from the CT. You can use this expression to ensure that characters that are not supported in the CT are not copied from the DT to the CT.

There are a number of filters that can be used as shown below:

equals(attributes.FirstName, 'Ilya') - Applied if attributes. FirstName equals 'Ilya' (case insensitive)
equalsCaseSensitive(attributes.FirstName, 'Ilya') - Applied if attributes. FirstName equals 'Ilya' (case sensitive)
fullText(attributes.Name, 'california hospital') - Applied if attributes. Name contains 'california hospital' (case insensitive)
contains WordStartingWith(attributes.Name, 'calif hospit') - Applied if any word of attributes. Name starts with any word from 'calif hospit' (case insensitive)
range(attributes.Age, 30, 40) - Applied if attributes. Age is between 30 and 40 (inclusive)
Ite(attributes.Age, 54) - Applied if attributes. Age is less than or equal to 54
gte(attributes.Age, 54) - Applied if attributes. Age is greater than or equal to 54
It(attributes.Age, 54) - Applied if attributes. Age is less than 54
gt(attributes.Age, 54) - Applied if attributes. Age is greater than 54
missing(attributes.FullName) - Applied if attributes. FullName is not present in object
exists(attributes.FullName) - Applied if attributes. FullName exists in object
inSameAttributeValue(equals(attributes.Address.City, 'Chicago') and equals(attributes.Address.State, 'IL') and equals(attributes.Address.Zip.Zip5, '12345')) - Applied if sub-conditions are met for sub-attributes of the same attribute Address
startsWith(attributes.Name, 'Hospital') - Applied if attributes. Name starts with Hospital (case insensitive)
in(attributes.FirstName,'Ilya, Upwan,Dmitry') - Applied if attributes. FirstName is one of the values comma-separated (case sensitive)
listEquals(attributes.FirstName, 'Ilya', 'Upwan') - Applied if attributes. FirstName is equal to one of 'Ilya' or 'Upwan' (case insensitive)
listEqualsCaseSensitive(attributes.FirstName, 'Ilya', 'Upwan') - Applied if attributes. FirstName equals either 'Ilya' or 'Upwan' (case sensitive)
regexp(attributes.Identifiers.ID, '\\\\d{9}') - Applied if attributes.Identifiers.ID satisfies a regexp (case sensitive)
contains(attributes.Identifiers.ID, '1?25*009') - Applied if attributes.Identifiers.ID satisfies a wildcard expression. Supported wildcards are *, which matches any character sequence (including the empty one), and ?, which matches any single character (case insensitive)

For more information on Filtering options, see topic Filtering Entities.

Unify and manage your data