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
VerifiedImport can migrate Products nested under an Entity, in the same event as the entity itself. Products are provided in the products array on an Entity in the request payload. See VerifiedImport Schema for the payload structure.
Product Resolution
Each Product must provide either an id or a productResolver (externalDataKey/externalSystemId). Each incoming Product is resolved against the owner entity's existing Products before it is 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 a productResolver is provided, it is matched against the existing Products' properties. If a match is found, that Product is updated.
- If the productResolver doesn't match any existing Product, the Product is treated as new and created.
Products are resolved after the owner entity has been created or updated by the current event, against the owner entity's Products as they exist at the time of processing.
Product Mapping Data
Product data is mapped using Product Policy Configuration in Fen-X, similar to Entities. The Policy categories used when creating and updating Products are provided via eventConfig.productProcessingRules.categories.
typeandfamilyare required. They are mapped internally to theproductTypeandproductFamilydatakeys, and must be values from the reference lists used by those fields on your tenant.singlePropertiescontain the Product datakeys and their values.collectionPropertiescontain Product Data Groups. Each key must be a Data Group field in the Product requirement set for the provided categories. Only Data Group collections are supported for Products. The records provided become the full set of records for that Data Group (replace).
Product field values are validated by Fen-X against the Product requirement set when the Product is saved. Any field that is mandatory for the Product's type, family and jurisdiction must be provided, otherwise the Product fails with a Field must be completed error.
entityProcessingRules.lookupsMapping applies to entity fields only. Product lookup values must use the reference list 'Value' column.
If eventConfig.entityProcessingRules.validationProfile is set, it is also applied to Products in the event. See Validation Profiles.
Product Error Handling
If any Product fails to migrate, the owning Entity, and therefore the overall event, is marked as 'Failed'. The owning entity itself is still created or updated. The status and error of each individual Product can be checked in the Processed Message under the corresponding entity's products array, and in Logging Centre.
Common Product errors:
| Error | Cause |
|---|---|
Either Product Id or Product Resolver is required. | The Product has neither id nor productResolver. |
Type is required. / Family is required. | type or family is missing. |
Field '<datakey>' is not present in the Product requirement set... | A collectionProperties key isn't a Data Group field in the Product requirement set for the provided categories. |
Error migrating product: <datakey>: Field must be completed. | A mandatory Product field is missing from the payload. |