January 12th, 2022
Naming convention for Data Fields
As a general rule, software engineers love to give users of their applications as much flexibility as possible. If you ask them for an option allowing you to pick one of the seven rainbow colors, they’ll usually respond with some way of picking any of the 32 million colors that your display is capable of. After all, they say, it’s no more work for them to do so and it gives you, the user, much greater flexibility. But that flexibility may come at a price you’re not prepared to pay.
If your application is a virtual coloring book for young children, 32 million colors might be a bit much. How are toddlers meant to remember which seven of those are typically associated with rainbows and unicorns? The point is: having a slew of options doesn’t mean you should always use all of them.
Leaving the joyful world of coloring books and turning our attention to OL Connect, let’s take a look at the data model fields that identify the data elements being merged onto documents.
It’s only natural to give those fields meaningful names. “CustomerNumber” or “ShippingAddress” are much more explicit names than “Field1” or “Column17” because your brain doesn’t have to go through the abstract process of associating seemingly random names with their corresponding data elements.
But sometimes, it’s tempting to use an even more elaborate naming convention to make things even more explicit. You could, for instance, create fields like “Address (shipping)” and “Address (billing)“. Names like these have the advantage of making things plainly readable to the template designer. However, what you gain in readability you actually start losing in functionality: your scripts will no longer be able to refer to the fields with basic dot notation (e.g. record.fields.ShippingAddress) because of the spaces and parentheses in the field names. You will have to use the slightly more convoluted bracket notation (e.g. record.fields[“Address (shipping)”] ).
We are not going to examine the ways in which the field names could be used to cause issues with your OL Connect jobs – we don’t want to give anyone any ideas! The goal here is to raise awareness about potential issues and to prevent them from happening.
The simplest way to avoid potential issues is to adhere to a well-defined naming convention. The most consistent and established of these conventions is arguably the XML Naming Scheme (a summary of which can be found here), which defines how elements must be named for an XML file to be well-formed. Since OL Connect does not store its field names inside an XML structure, some of the XML rules don’t apply to it, so we can pretty much use a simple subset of those rules:
Going back to the examples we used earlier, proper field names could therefore be : Address_Shipping, ShippingAddress, shipping_address etc.
It’s important to note that in the case of XML, database and CSV data, OL Connect automatically uses the names of the elements, fields and columns already defined in the data to name the data model fields. In most cases, this produces field names that adhere to the rules laid out above. But occasionally – especially with DB and CSV input data – column names may include characters that result in a field name that doesn’t match those rules (for instance “Employee’s benefits” contains a space and a single quote, neither of which is allowed in the XML Naming Scheme). You should adjust those names to fit the rules (e.g. EmployeeBenefits or employee_benefits).
The short answer is yes. At some point in the future, OL Connect may implement stricter naming rules for fields. Those new rules would likely restrict usage of reserved characters. You don’t have to start converting your data models right away – there aren’t yet any firm plans to implement stricter rules – but whenever you are making changes to a data model or to a template, you should take the opportunity to also change the field names so they follow the above rules. This will immediately make your system more secure and stable, and it will also ensure that if/when OL Connect starts implementing stricter naming rules for fields, your resources will be ready.
Restrictions on variable names don’t only apply to data model fields but also to properties (which can be assigned to any entity in OL Connect, be it a data record, a content item, a job set, etc.). You should therefore follow the same naming pattern when using properties.
Tagged in: best practice, data, datamapper
Receive exclusive OL products news, tips and resources.
Comments are closed here.
January 19th, 2022
e-Invoicing standards are cropping up everywhere and are increasingly becoming mandatory. A number of those standards are based on PDF/A-3 with an XML attachment. Starting with version 2019.1, OL Connect comes with features for creating PDF/A-3, and turning them into ZUGFeRD and Factur-X conforming e-invoices. PDF/A-3 is not only for e-invoicing, it’s an archive format after all, so other applications become possible as well, of course. This article explains how to use this functionality in OL Connect.
December 8th, 2021
Just like in the Friday the 13th movie franchise, JSON is everywhere ( :-|). And now, it can be handled natively as a new data type in the DataMapper. All those web-based processes that use JSON as a data exchange format no longer require you to convert the data to something else in order to extract values from it. Read on to learn more on this feature we introduced with version 2021.1 of OL Connect.
November 17th, 2021
Loops are commonplace in data mapping configurations. Unless all your data is static, you have to use them in order to extract repeating items. However, it can sometimes be challenging to loop precisely on a specific set of conditions, especially when dealing with compound conditions. Let’s see how OL Connect 2021.1 can help us streamline loops.