Reference Data: What you need to know

Understanding Reference Data

Reference data are lookup tables that help Urbantz understand your business-specific information. They act as translation layers between your internal systems and Urbantz, as well as between Urbantz and external carriers.

For example, your warehouse management system might call a location "Store_ABC_Paris", while Urbantz refers to it as "Hub #789", and the carrier knows it as "XYZ123". Reference data creates the connection between these different naming systems.

Common Use Cases

Carrier Integration Many customers use reference data to map their internal identifiers to external carrier systems. Some customers, for instance, use reference data to translate their internal hub IDs into the store IDs that external carriers require for deliveries.

Business Rules and Configuration Reference data can store business logic that's specific to your operations. This might include priority levels for different delivery types, service time requirements based on item categories, or pricing matrices that vary by geographic zone.

Script Support If you're using custom scripts for announcements or other automated processes, reference data can provide the configuration values and business rules these scripts need to function properly.

How Reference Data Works

Reference data are structured as tables, similar to Excel spreadsheets.

When Urbantz needs information, it searches the appropriate reference data table to find the corresponding value. For example, if the system needs to find the external store ID for Hub #789, it will look up that hub ID in your reference data and return the corresponding external ID.

Managing Your Reference Data

You can import reference data from CSV, XLS, or XLSX files through the Urbantz interface. The system also allows you to export your data as XLSX files for backup or editing purposes. Note that reference data can only be managed through the web interface - API access is not available.

Avoiding Common Problems

Column Header Issues One of the most frequent problems occurs when column headers don't match exactly what the system expects. For example, if a feature requires a column named "name" but your file has "Name" or "item_name", the system won't be able to find the data it needs. The columns are case sensitive and should be named exactly as in the system, no additional symbols or spaces.

Duplicate Entries Having the same identifier appear multiple times in your reference data can cause the system to fail. Each key or ID should appear only once in your table. Before uploading, review your data to ensure there are no duplicates.

File Size Considerations Large reference data files can significantly impact system performance. Try to keep your files under 5MB when possible by removing unnecessary columns or splitting large datasets into multiple tables.

Missing Required Data Some features, like bin packing optimization, require specific data to be present in your reference data. If this information is missing, the feature will fail to work properly. Make sure you understand what data is required for the features you're using.

Data Consistency Inconsistent formatting can cause lookup failures. For example, if you sometimes write "Paris-Nord", sometimes "paris nord", and sometimes "PARIS_NORD", the system might not recognize these as the same location. Establish consistent naming conventions and stick to them.

Troubleshooting

Here's how to check if something changed:

If something seems off, check if any members of your team made changes in the reference data through the platform under Administration > Logs > Select "Reference_Data" :

Here are some examples of errors commonly seen:

"Cannot parse reference data" errors typically indicate problems with column headers or data format. Double-check that your column names match the documentation exactly and that your data is in the expected format.

Performance issues are often related to file size. If you notice slower response times after uploading reference data, consider reducing the file size or splitting it into smaller tables.

Optimization failures after updating reference data usually mean that the required information is missing or incorrectly formatted. Review the requirements for any optimization features you're using.

Best Practices

After uploading, test the functionality with a small batch before processing large volumes. Monitor system performance to ensure the new data isn't causing slowdowns.

Only update reference data when necessary, and ensure you update your CSM about the changes made beforehand, as changes can sometimes have unexpected effects. Keep backups of working versions, and document any changes you make for future reference.

Getting Support

If you encounter issues with reference data, contact your CSM, respectively the support team, with the exact error message, the name of the affected reference data table, details about recent changes, and screenshots if applicable.