VerifiedImport Overview
VerifiedImport is a new event subtype that acts as a standardized pipeline (business service) for consuming entity data and orchestrates the update within Fenergo.
Some of the key differences between it and previous Legacy Event (MigrateEntity) are
-
Stateless Integrations - Calling system does not need to know an Entity's state in Fenergo. There is an option to provide a unique identifier (e.g. centralized MDM) if available to decide if entity should be created or updated.
-
Multiple Entities per event - VerifiedImport allows for multiple entities per message.
-
Lookups Resolver - Lookup values can be provided as value, id, or custom column from the reference list definition.
-
Message Simplicity - External Systems need only provide incoming datakey and value. Fenergo will use internal policy configuration to determine data types and validations
Verified Import Flow
The system will match each entity using the provided entityId or entityResolver, then create or update it accordingly. No journey will be triggered, and the data will be verified as part of the process.
Resolver Rules
All incoming Entities need to be resolved for uniqueness to determine if we should create a new record or update an existing record.
| Data Domain | Uniqueness Rules |
|---|---|
| Entities | - The Fenergo Entity Id, or - A single datakey configured as a search indexable field in policy config. The field value must be unique across the tenant or else a duplicate entity error will occur |
Mapping Data
VerifiedImport uses Policy Configuration in Fen-X to map the incoming data to datakeys defined in Policy. The Policy mapped via eventConfig.entityProcessingRules.categories. With it you can provide the Policy categories that will be used when Creating and Updating your entity.
VerifiedImport supports the following field data type:
- Text Field
- Text Area
- Number
- Date
- Data Group
- Select Dropdown
- Multiple Select Dropdown
- Legacy Linked Select Dropdown
- Legacy Linked Multiple Select Dropdown
- Linked Select Dropdown
- Linked Multiple Select Dropdown
- Rich Text Editor
Lookup Mapping
Lookup mapping applies to fields of types:
- Select Dropdown
- Multiple Select Dropdown
- Legacy Linked Select Dropdown
- Legacy Linked Multiple Select Dropdown
- Linked Select Dropdown
- Linked Multiple Select Dropdown
By default incoming values will be validated against the Reference List 'Value' column. Lookup mapping allows to configure the lookup to use a different column for mapping (e.g. Id, or custom column). This configuration is applied to all fields that use the lookup.
For example the below config will use values from MDMSystem column in reference list to resolve and validate value for the lookup Country
"lookupsMapping": [
{
"lookupName": "Country",
"columnName": "MDMSystem"
}
]
Processed Message
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.
Error Handling
If the processing of any entity fails, the entire event will be marked as 'Failed'; otherwise, it will be 'Success'. The status of each individual entity can be checked in Event Details > Entities. Additional failure details, such as validation errors, are available in the Processed Message.
Aditional Information
Event Notifications
Because the feature is built on top of the Entity Migration - there are no entitydata:created event notifications triggered during the process. The only event notification triggered is after all of the entities are processes and is either eventingress:success or eventingress:failed based on the overall event processing status.
Products (Beta)
Verified import support for Products is currently in beta. It is gated behind a feature flag that is not enabled for all tenants. The schema and behavior described below may change before general availability. Please contact your Fenergo representative to confirm availability before relying on this feature.
VerifiedImport can optionally migrate Products nested under an Entity, alongside the entity itself. Products are provided in the products array on an Entity in the request payload.
Product Resolution
Each incoming product is resolved against the owner entity's existing Products before being created or updated:
- If a Product Id is provided, it must match an existing Product related to the owner entity, otherwise the product import fails with an error.
- If no Id is provided but a productResolver (
externalDataKey/externalSystemId) is provided, it is matched against the existing Products' properties. If a match is found, that Product is updated. - If neither an Id nor a resolver match is found, the Product is treated as new and created.
Product resolution only runs for entities that already exist or have just been created by the current VerifiedImport event - i.e. products are always resolved against the owner entity's Products as they exist at the time of processing.
Product Mapping Data
Product data is mapped using Policy Configuration in Fen-X, similar to Entities. The Policy categories used when creating/updating Products are provided via eventConfig.productProcessingRules.categories.
type and family are required discriminator fields for the Product (mapped internally to the productType/productFamily datakeys).
Collection properties are not yet supported for Products in VerifiedImport (v1) - only single properties are passed through.
Product Error Handling
If any Product fails to migrate, the owning Entity - and therefore the overall event - is marked as 'Failed'. The status of each individual product can be checked in the Processed Message under the corresponding entity's products array.