Labels and synonyms

There are several best practices to follow, including:

  • Size fields based on the length of the short label and the expected length of the value of the field. Do not make the field big just to fill up empty space.
  • Always include Help Text, a Label, and a Short Label when a you define synonyms. 
  • Do not include any punctuation, special characters, or symbols in the Label and Short Label. 
  • Labels for True False data items must be formatted as statements. If the statement is true, then the checkbox is selected. If the statement is false, then the checkbox is not selected.

Data items can be shared across families as synonyms can be specific to family, module and/or application. If any of the formatting and validation options, such as storage decimals, extended precision or min/max value are changed, should those changes affect your table or do you want to ensure consistency across tables. For example, the unit cost field is used in many tables. All tables throughout the entire business process flow must have the same extended precision, otherwise rounding will occur as the value moves from one table to another.  In this case, it is better to use the same data item.  

Naming conventions and standards

Name data items so that they are free of numbers, special characters, and spaces. Once a data item is created, the name cannot be changed at a later date. All words must be written in upper camel case, which means the first letter of each word should be capitalized. The name should reflect the type of information that is being stored in the table. For example, ItemNumber or TaxAmount. 

The name of the data item should reflect the intent of the field and follow the upper camel case convention. For example, ItemNumber, TaxAmount, and AccountingMethod are all acceptable data item names. 

If the data item is a Message type, the naming format is <ProductFamily>Msg####. The number is not automatically assigned, so you must find the number used in that product family's last created message data item to determine what the new message number should be. For example, PlatformMsg10, FinancialsMsg9, and ManufacturingMsg12 are acceptable names for message data items.

For data item groups, the naming format is <DataItemPurpose>Fields. For example, SupplierFields or ItemOrgUnitFields. 

If the data item has the Automatic Number checkbox selected, the field name should contain ID or Number. For example, ContactID and PurchaseOrderNumber.

If the data item is used in the Action Label field in the Workflow Definition application, the data item needs to be defined as a Label type with the naming format of <ProductFamilyDescription>WFAction<ActionLabel>. The <ActionLabel> being the label used for the workflow transition. If the same workflow action label is used across many families, each family should have their own data item label.  Do not share workflow action data items across families. For example, FinancialsWFActionPost, FinancialsWFActionActivate, and FoundationWFActionActivate are acceptable names for workflow action label data items.

Table Lookup Definition

When a data item is defined as a Table Lookup and a Primary Search Field,  Secondary Search Field,  or Tertiary Search Field is defined, that field will override the field defined in the table definition. At a minimum, an index should be established for whatever field is specified as the primary search field. You should also not define a data item as a primary, secondary, or tertiary search field if it's optional or could be empty.

How to write an error message

When you're writing an error message, your main goal is to tell the user what went wrong and how to fix it.

Bottom line

Let the user know exactly what the error was, why it happened, and what they can do about it.

Ask yourself:

  • Will the user know where the problem is?
  • Will the user know what to do to fix the problem?
  • Is there a clear first step?

Tips

  • Use complete sentences with proper punctuation.
  • Avoid slang, jargon, colloquialisms, pop-culture references, and jokes.
  • In general, you should address the user in second person using "you." However, you should never blame the user. It's better to use passive voice than to say "you messed up."

Words to avoid

  • Oops
  • Error
  • Failed
  • Problem
  • Invalid
  • Wrong
  • Prohibited
  • Sorry

When to reference object names that can be customized

Application names, field names, and field values can be customized by users in downstream environments. If you reference the name of the object in your message and a user customized the synonyms or menu entries for the object in their environment, it may confuse the user.

In general, strive to refer to generic concepts instead specific object names. If the object you need to reference in your message is a generic concept, great! Just don't capitalize the object's name so that it appears to be a generic concept.

However, there are cases where the risk that the user is unable to resolve the cause of the error without a reference to a particular object outweighs the risk that the object's name may be different in a customer environment. Use your best judgement.

Validation best practices

These best practices ensure that validations are configured consistently throughout Nextworld.

Validation names should reflect the type of information in the validation. If the validation is for one field only, the name of the validation should be the same name as the field. If the validation is generic and can be applied to multiple data items, name the validation with purpose of the validation, for example, TextOnly and IntegrationName.

Field format best practices

These best practices ensure that field format definitions are configured consistently throughout Nextworld. Field format names should be a descriptive value of what is being formatted, for example SocialSecurityNumber and CreditCard.

Data items in tables best practices

These best practices ensure that data items added to tables are organized consistently throughout Nextworld.

Data items must be added and configured as application fields using the Table Definitions application.

Use Table Lookup fields to establish foreign keys to other tables. The primary and secondary lookup fields are rendered as the typeahead values of the foreign key record in applications.  At a minimum, an index should be established for the field that is specified as the primary search field.  You should also not define a data item as a primary, secondary, or tertiary search field if it's optional and could be empty. 

Organize data items in a logical order.

  • List fields that make up the unique key first in the same order they are listed in the unique key.
  • Place fields that serve a similar purpose together. For example, if there are several amount fields that work together such as TransactionAmount, PaidAmount, and OpenAmount in a table.
  • Fields that establish a range be listed together with the From field followed by the Through field. For example, EffectiveFrom and EffectiveThrough.
  • Fields that establish a relationship should be listed parent followed by the child. For example, ParentItem and ChildItem.
  • Fields that establish a hierarchy should be listed for highest level to lowest level. For example, Company, OrgUnit, InventoryLocation, Lot.
  • Place work fields at the very end of the list of fields.

For statistical information, use a Work Field to dynamically calculate the value rather than storing the value in the table where it requires to be constantly updated.  

Do not add Work Field  to store current value of a record.  Instead, use the Fetch Original Record logic action.

The usage of common fields that are in both the main and subtable or header and detail should be limited since this denormalizes the table.  Mapping of common fields should be configured in the table definition rather than writing code in logic block to keep the data in synch.  The following situations may justify the need for a common field:

  • To filter a table lookup field or mini app. It needs to be common field so it can be accessed.
  • To use the field as part of the unique key in the subtable or detail table.
  • To access data via a table lookup for display in an application.
  • A field in the detail table is defaulted from the header, but can be overridden. 
  • When a table uses a Subtable Main, an integration table should also be created. See the Data import integration configuration section for more information on how to build and design a integration application. A Subtable Main would follow the standards for a  Header Detail integration table. 

Number data item best practices

These best practices ensure that Number data items are configured consistently throughout Nextworld.

Number data items are configured in Data Item Definitions.

Ensure that the settings for data precision and display precision are correct. Caution must be taken if the display precision stored is changed as rounding issues may occur.

When adding the QuantityFrom data item to a table, do not add the QuantityTo data item as well. Including a range may cause a quantity gap when a user enters values with decimals. For example, a user may enter from 1.0000 to 2.0000, with four decimals, and then from 3.000 to 4.000, with only three decimals. This could cause a discrepancy between stock amounts available from suppliers and stock amounts needed by customers.

Quantity Fields

When creating a Number data item that represents a quantity, the best practice is to set the Data Precision to 8 and the Display Precision to 2.

Extended Precision

Extended precision profiles can be configured and associated to a set of data items where the number precision must be the same for all the data items in the group. 

Considerations: 

  1. Consider the entire business process flow of the data item, so there is no loss of precision.  For example, a quantity field in a sales quote flows into a sale orders which flows into account receivables.  The data item in different tables may be different.  All data item must have the same precision profile.  
  2. Only re-use data items with a precision profile if you need the precision.  If you data item does not need the precision, then use a different data item.  

Currency data item best practices

These best practices ensure that Currency data items are configured consistently throughout Nextworld.

Currency data items are used for total amounts as well as individual amounts.  For example,  a unit price for an item is $1.10.  If an order for a quantity of 10 is entered, the total or extended amount is $11.00.    

Extended Precision

Data items that represent Unit Cost and Unit Price in Nextworld can hold more precision than what is determined by the currency code.  For example, a unit cost in USD may have 7 decimal precision although the USD currency precision is set to 2 decimals.  When the unit cost is calculated into the Total or Extended Amount (quantity x unit cost), it is rounded to the currency precision for the currency code.  In the example above, if the unit price is set to $1.0981, the total amount is now $10.98. 

Nextworld delivers two Precision Profiles.  One for cost and one for price.  Data items that need to follow the extended precision must have proper precision profile set in the data item.  

Considerations: 

  1. Consider the entire business process flow of the data item, so there is no loss of precision.  For example, a unit price in a sales quote flows into a sale orders which flows into account receivables.  The data item in different tables may be different.  All data item must have the same precision profile.  
  2. Only re-use data items with a precision profile if you need the precision.  If you data item does not need the precision, then use a different data item.  

Date and Date Time data item best practices

These best practices ensure that Date and DateTime data items are configured consistently throughout Nextworld.

Date and DateTime data items are configured in Data Item Definitions.

If you have data that crosses timezones, then use DateTime fields. If the data does not cross timezones, then use a Date field. For example, data items like BirthDate, StartDate, and EffectiveDate are Date fields that do not cross any timezones, but if you need to use a data item to track dates of flights, then use a DateTime field. Using the DateTime field always displays the correct time zone that the user is in. 

When adding the EffectiveFrom Date or DateFrom DateTime data items to a table, consider adding EffectiveThrough Date or DateTo DateTime data items as well to create a date range. It is easier and more intuitive to fetch a date when it is within a range.

When using Date data items on an application and the default should be "today", these fields should be defaulted from the application settings whenever possible. This is because application setting defaults can use the user’s browser time zone and users will expect “today” to mean their current date. Use the following example, if the tenant time zone is UTC -6, the application’s Organizational Unit time zone is UTC -4, the user’s browser time zone is UTC +10, and the current UTC Time is 1:00:00. If the field is just defaulted to "today" in logic when using the Set Value action, a time zone must be specified in either the tenant time zone or the application’s Organizational Unit time zone, both of which are “yesterday” to the user. Using System (Current Date) Today from an application setting, will be in the context of the user’s browser time zone and give the appropriate value for “today.” 

When using DateTime data items to an application and the default should be "now", it does not matter if this field is defaulted using a logic block or an application setting because "now" is always in UTC and is already handled by the system for display purposes. 

Message data item best practices

These best practices ensure that Message data items are configured consistently throughout Nextworld.

Message data items are configured in Data Item Definitions.

If you are configuring a Message type data item, you must follow the Message type naming standards. See Data item best practices to find the naming standards for Message type data items. 

Place the content of the message in the Description field when entering the description of the data item. This allows you to filter for messages when needed.

Use a unique Message type data item for each product module family. For example, you may need to create a message data item for an error in procurement even though an existing message data item in manufacturing has the exact message you want. You cannot reuse the manufacturing message. You must make a new Message data item exclusively for procurement.

When using the message in a logic block, include inputs to provide additional relevant information to the user.    

If the message or input references workflow, use the workflow state type as the workflow state can be user defined. 

Subtable data item best practices

These best practices ensure that Subtable data items are configured consistently throughout Nextworld.

Subtable data items are configured in the Data Item Definitions application. Tables built on top of Subtable type data items are configured in the Table Definitions application.

Always use a table of type Main when creating a table to attach a Subtable type data item to.

Subtables are limited to 700 entries per record. For example, in an application capturing contact details, a subtable of email addresses can store up to 700 emails for each contact. 

Always position fields on the left and checkboxes on the right.

Use a standard application with a subtable when:

  • You have a one to many relationship where the list of fields and the number of rows in the subtable is small.

Table lookup data item best practices

These best practices ensure that Table Lookup data items are configured consistently throughout Nextworld applications.

Table Lookup data items are created in the Data Item Definitions application, and configured in the Table  Definitions application.

Use a Table Lookup type data item when the value in the Child Field of the table can change and you want the change to be reflected in all tables that are pointing to the record. For example, EmployeeName is a data item table lookup to Directory. If the employee changes their name, you want any expense reports or transactions to automatically reflect the new name. 

Common best practices

Whenever configuring, use a table lookup to:

  • Link fields from one table to another. Do this instead of storing values in multiple tables and using logic blocks to fetch them.
  • Store a value in one table, and reference that value from other tables without duplicating the value. In other words a table lookup ensures that you don't have to store the value twice.

If you create a chain of table lookups, it should not be longer than two links beyond the source. If more than two levels are used in the table lookup chain, then an error appears when you try to generate an application over the table that is third level from the source.

Type Ahead Best Practices

These best practices ensure that type aheads are configured consistently throughout Nextworld.

Primary and Secondary type ahead should be configured at a table level.  This ensures consistency in all applications. 

The primary and secondary type ahead configured on the data item overrides the table type aheads and should be used sparingly.   The exception is a data item that represents the Org Unit.  Configure these data items to have the Primary Type Ahead as Org Unit Number and the Secondary Type Ahead as Org Unit 

Static text data item best practices

These best practices ensure that Static Text data items are configured consistently throughout Nextworld.

Static Text data items are configured in Data Item Definitions.

Only use Static Text data items in applications when the application has parameters that are complex enough that it needs specific instruction and/or a major action is non-reversible. For example, the application Supplier Invoices has a Void row action that opens a mini app that allows you to add information on why you are voiding a record. The static text in this mini app provides instruction on what information is necessary and what you must do once that information is entered: Enter a date, and click Void to continue or Close to exit.

Configure the display size of the data item as Full. The Full size reliably covers the amount of space that a Static Text data item should cover in the generated application. For more on the amount of space that should be covered in the generated application, see the Application pages and rows best practices section.