Skip to main content

VerifiedImport Schema

Message Structure​

VerifiedImport Event uses the following schema.

Message structure
//Sample Event
{
    "eventType": "externaldata",
    "eventSubtype": "verifiedImport",
    "correlationId": "{{$guid}}",
    "source": "MDM",
    "priority": 1,  //Optional. Allows calling system to direct incoming event to a specific FIFO queue for
                    // processing. Currently there are two queues: Bulk (1 or less) and Normal (2 or more).
                    // If not specified default priority will be assigned based on
                    // # of entities < 20 and total message size < 40kb.
    "payload": {
        "eventIdentifier": "MDMImport-Verified",
        "integration": "MDM Updates",
        "eventConfig": {
          "entityProcessingRules": {
            //List the Policy Categories to identify the incoming fields (DataKeys and DataGroups)
            "categories": [
              "Basic Details"
            ],
            "lookupsMapping": [
                //By default incoming values will be validated against the Reference List 'Value' column
                //Configure the lookup below to specify a different column to use for mapping (e.g. Id, or custom column)
                //This configuration is applied to all fields that use the same lookup
              {
                "lookupName": "Country",
                "columnName": "MDMSystem"
              }
            ],
            "waitForSearchPropagation": true  //Optional. Verifies newly created entities have finished updating
                                              // Entity Search datastore before completing processing.
          }
        },
        "entities": [
          {
            //Entity Id or EntityResolver must be specified
            //"id": "{{$guid}}",
            "entityResolver": {
              "externalDataKey": "externalId",
              "externalSystemId": "jh_20250226_1_2"
            },
            "entityType": "Company", //Required
            "targetEntity": "Client", //Required. Used in Policy calls
            "isClient": true, //Optional. Will add the IsClient chip to entity
            "singleProperties": {
              "legalEntityName": "Create_1_2",
              "externalId": "jh_20250226_1_2",
              "category": "Corporation",
              "companyType": "Private Company",
              "countryOfIncorporation": "CAN",
              "dateOfIncorporation": "2012-07-11",
              "state": "Alabama"
            },
            "collectionProperties": {
              "addresses": {
                "mergeStrategy": "replace",
                "records": [
                  {
                    "type": "Registered|Mailing",
                    "addressLine1": "1 FREDERICK ST",
                    "addressLine2": "15D",
                    "country": "CAN"
                  }
                ]
              }
            }
          }
          //, { .. }
        ]
      }
}

Processed Message Structure​

The processed message is produced after the import logic has been executed. It contains the status of the overall import as well as the result of importing individual entities.

The structure of the processed message is intended for human-readable investigations, debugging, and audit purposes only. It may evolve over time and is not guaranteed to be backward-compatible. Therefore, it should not be used for service-to-service integration or automated processing.

Processed Message structure
{
  "eventId": "5f934de0-0538-4c95-9a3e-14a72d05e2a0",
  "messageImportStatus": "Success",
  "eventIdentifier": "MDMImport-Verified",
  "integration": "MDM Updates",
  "integrationStatus": "Processed",
  "eventConfig": {
    "entityProcessingRules": {
      "categories": [
        "Basic Details"
      ],
      "lookupsMapping": [
        {
          "lookupName": "Country",
          "columnName": "MDMSystem"
        }
      ]
    }
  },
  "entities": [
    {
      "entityId": "c45c27e6-5ae2-4ec3-9c3c-5e2442c5dcf1",
      "entityImportStatus": "Success",
      "entityResolver": {
        "externalDataKey": "externalId",
        "externalSystemId": "jh_20250226_1_2"
      },
      "entityType": "Company",
      "targetEntity": "Client",
      "singleProperties": {
        "legalEntityName": "Create_1_2",
        "externalId": "jh_20250226_1_2",
        "category": "Corporation",
        "companyType": "Private Company",
        "countryOfIncorporation": "CAN",
        "dateOfIncorporation": "2012-07-11",
        "state": "Alabama"
      },
      "collectionProperties": {
        "addresses": {
          "mergeStrategy": "replace",
          "records": [
            {
              "type": "Registered|Mailing",
              "addressLine1": "1 FREDERICK ST",
              "addressLine2": "15D",
              "country": "CAN"
            }
          ]
        }
      },
      "issues": {
        "error": null,
        "warnings": []
      },
      "validationResult": {
        // Properties validation results
      }
    }
  ]
}

Products Schema (Beta)​

Beta feature - not fully enabled yet

Verified import support for Products is currently in beta and is not enabled for all tenants. The schema below may change before general availability.

Products are nested under an Entity in the products array, and require eventConfig.productProcessingRules.categories to be configured (Policy categories used to map incoming Product datakeys).

Message structure with Products
{
    "eventType": "externaldata",
    "eventSubtype": "verifiedImport",
    "correlationId": "{{$guid}}",
    "source": "MDM",
    "payload": {
        "eventIdentifier": "MDMImport-Verified",
        "integration": "MDM Updates",
        "eventConfig": {
          "entityProcessingRules": {
            "categories": ["Basic Details"]
          },
          "productProcessingRules": {
            //List the Policy Categories used to identify incoming Product fields
            "categories": ["Product Details"]
          }
        },
        "entities": [
          {
            "entityResolver": {
              "externalDataKey": "externalId",
              "externalSystemId": "jh_20250226_1_2"
            },
            "entityType": "Company",
            "targetEntity": "Client",
            "singleProperties": {
              "legalEntityName": "Create_1_2"
            },
            "products": [
              {
                //Product Id or productResolver can be provided to update an existing Product related to the entity
                //If neither is provided, or no match is found via productResolver, a new Product will be created
                //"id": "{{$guid}}",
                "productResolver": {
                  "externalDataKey": "externalId",
                  "externalSystemId": "PROD_20250226_1"
                },
                "type": "Product Type", //Required
                "family": "Product Family", //Required
                "singleProperties": {
                  "productName": "Sample Product"
                }
                //Note: collectionProperties are not yet supported for Products
              }
            ]
          }
        ]
      }
}

Products Processed Message Structure​

Each entity in the processed message includes a products array reporting the outcome of each product's migration.

Processed Message structure with Products
{
  "entities": [
    {
      "entityId": "c45c27e6-5ae2-4ec3-9c3c-5e2442c5dcf1",
      "entityImportStatus": "Success",
      // ...entity fields as above
      "products": [
        {
          "productId": "8b1e6a2a-4d3f-4c2a-9a9e-1a2b3c4d5e6f",
          "productImportStatus": "Success",
          "productResolver": {
            "externalDataKey": "externalId",
            "externalSystemId": "PROD_20250226_1"
          },
          "type": "Product Type",
          "family": "Product Family",
          "singleProperties": {
            "productName": "Sample Product"
          },
          "collectionProperties": {},
          "issues": {
            "error": null,
            "warnings": []
          }
        }
      ]
    }
  ]
}