Record Uniqueness

Identifying a Unique Record

It is important to understand how PYXI determines that a record is unique, especially when designing an application and considering how data is loaded.

When data or configuration is loaded, whether through a file DataLoad, a Blueprint or through the API, PYXI will look at the values of the fields provided to determine if these refer to an existing record which should be updated, or if not, they will be used to add a new record.

For built-in record-types, PYXI is configured to recognise existing records usually based on unique Names (for almost all configuration records). There are some exceptions or enhancements:

  • Person – a Person will be considered a match only if the FirstName, LastName and Email are all provided and match
  • Organisation – an Organisation will be matched if its OrganisationNumber matches, or if its Name is an exact match
  • Field – the combination of RecordTypeName and FieldName determines uniqueness
  • View – the combination of Name and RecordTypeName determines uniqueness
  • Rule – the combination of Name and RecordTypeName determines uniqueness
  • Step – the combination of Name and RecordTypeName determines uniqueness

New Record Types

If you add a Record Type, then you need to consider if its records are to be unique. Normally, you will want to ensure that this is the case for any Record Types that contain lookup lists of ‘reference data’.

Any RecordType flagged as being a Category will automatically assume that records are uniquely identified by their Name field.

For all other Record Types, if you want the Name field to be treated as a unique identifier, then you must set the isNameFieldUnique field of the Record Type to true.

If any of the Fields on your Record Type refer to unique identifiers from another system, such as an account number, then you should flag that Field with the isKeyLookupField flag. This will then treat this field as a unique identifier. This is especially important if you are subsequently going to be loading transactions or other data linked to these records.

Fields Linked to Another Record

If you are loading data of a Record Type (e.g. Transactions) where one of its fields is a link to another Record Type (e.g. a ‘Master Record’), then the value provided in the field will be used to lookup the linked record. It will follow the uniqueness rules outlined above. For this reason, it is particularly important to consider what information is available in data loads or API calls with such linked information. Usually, you will want to store an account number or other unique identifier as a ‘key lookup field’ so that providing this identifier alone is enough to guarantee that you are linking to the correct record.