Data items are reused in multiple tables and applications to capture information. Even though a data item captures a single type of information, you can use it differently in different contexts by defining different synonyms with different parameters.

For example, when you reuse the Name data item in the Company Directory application and the Suppliers application you're capturing the same type of information, a name, that is used differently. In the Supplier Invoices application, the field captures the name of a supplier and uses the label Supplier Name. In the Company Directory application, the field captures the name of a person or organization and uses the label Name. In addition to different labels, these fields also have different help text to explain how the field is used in each context.

Each synonym is made up of the following components:

  • Short Label—The field name that displays on list forms, detail lists, and subtables.
  • Label—The field name that displays in detail forms.
  • Help Text—The information about the field that displays when users click the Help Help icon next to the field name. Help text should help users understand the purpose of the field in an application. Learn more in How to write field names and help text.

There are best practices you should adhere to when creating synonyms. Learn more in Synonyms best practices.

Synonym parameters

In order for the same data item to display different synonyms in different contexts, you must specify parameters for your synonyms. The synonym that displays for a field is always the one with the parameters that most closely match the context of where the field is displayed.

You can configure synonyms for an entire product family, for an entire module, for a specific application, and more. The system evaluates these parameters in a hierarchy, with product family being the broadest parameter.

For example, you may create a synonym that specifies the Supplier Invoices application as a parameter, and another synonym that specifies the Financials product family as a parameter. When you launch the Supplier Invoices application, the latter synonym displays, because the Supplier Invoices application is in the Financials product family. In order for the first synonym to display, you must specify both the application and product families as parameters.

If a synonym has no parameters specified, it's considered a global synonym. Global synonyms display anywhere the field appears, provided a synonym with matching parameters doesn't exist.

The following table summarizes how synonyms display when they are configured with different parameters:

Specified parameter(s)Synonym is used for all instances of the data item...
FamilyIn all applications within that family. 
Family, ModuleIn all applications within that family and module.
Family, Module, Application In the given application. 
Application, Secondary Join TableIn the secondary join table in the given application. 
Application, SubtableIn the specified subtable in the given application. 
Application, Table Lookup As a related field, on the table lookup field, in the given application. 

If you want to override the synonym for the primary search field of a table lookup, add a unique synonym on the table lookup data item itself. For other related fields, create unique synonyms in the related field’s data item.

Application, Subtable, Table LookupAs a related field, on the table lookup, on the subtable, in the given application. 
Application, Secondary  Join Table, Table LookupAs a related field, on the table lookup, on the secondary join table, in the given application. 
View TableIn the view table. If the view table is built over a join table, the synonym is only used for the data item from the primary join table.
Reports built over the view table show the specified synonym. 
View Table, Secondary Join TableIn the secondary join table the selected view table is built over. 
Reports built over the view table show the specified synonym. 
View Table, Table LookupIn the related field from the selected table lookup. If the view table is built over a join table, the synonym is only used for the data item from the primary join table. 
Reports built over the view table show the specified synonym. 
View Table, Table Lookup, Secondary Join TableIn the related field from the selected table lookup in the secondary join table. 
Reports built over the view table show the specified synonym. 

Synonyms and Header Detail applications

For synonyms specific to header detail applications, specify the header or the detail application, depending on which application the data item is in. If the same data item is used in both the header application and detail application of a header detail application, you can create specific synonyms for the header and for the detail.

Synonyms and application layouts

Some applications have application layouts specified within their application setting. If you want to customize a data item's synonym on these applications, you must specify the name of the application layout in the Application field of your synonym configuration. 

Write help text with Nextworld intelligence

You can use Nextworld intelligence to generate suggestions for the field-level help text of your synonyms.

Every data item definition requires at least one synonym, which includes a label, short label, and help text. The help text should describe the purpose of the field and the information it captures. 

While generating synonym suggestions may streamline your development process, you must always carefully review the generated suggestions before you use them. Generated synonyms may contain inaccurate information, and even if you choose to use a suggestion, you may need to modify to ensure the information is helpful. 

Learn more in How to write field names and help text.

Generate suggestions

In the Data Item Definitions application, use the Generate Synonym Suggestions row action to generate help text suggestions for the data item. After you receive a notification that the suggestions have generated, use the Review Synonym Suggestions row action to open the Synonym Generator mini app. There, you can review, refine, and select a suggestion to use.

The Synonym Generator mini app displays multiple suggestions for the field's help text. These suggestions are derived using Nextworld intelligence using the data item's Org Unit Security Field, Type, and Description. Optionally, you can include additional context on the purpose of the field, how it relates to other fields in the application in the Additional Details field and generate new suggestions.

To use one of the suggestions, select the checkbox associated with the suggestion. Otherwise, you can select the Keep Current Help Text checkbox. After you save, the selected synonym on the data item definition is updated.

By default, the suggestions generated are for a global synonym. Clear the Generate Global Synonym checkbox to specify the specific scenarios where the synonym is used. Learn more about global synonyms and synonym parameters in Synonyms.

Generate suggestions for multiple data items

You can generate suggestions for multiple data items at the same time using the Suggest Synonyms form action in the list form of the Data Item Definitions application. This generates suggestions for all the data items you have filtered for, but only if they are in your current lifecycle. You can then use the Review Synonym Suggestions row action on each of the data items.

When you select this form action, you must specify synonym parameters. You cannot generate global synonyms for multiple data items. For example, if you created a new application, you could generate suggestions for synonyms specific to that application.

Synonym Generator mini app

Use the Synonym Generator mini app from the Data Item Definitions application to generate suggested help text for synonyms using Nextworld Intelligence.

To use the Synonym Generator mini app from the Data Item Definitions application, you can either:

  • Use the Generate Synonym row action on a data item, and then use the Review Synonym Suggestions row action to open the mini app.
  • Use the Improve Existing row action in the Synonyms Listing subtable.

By default, the suggestions generated are for a global synonym. Clear the Generate Global Synonym checkbox to specify the specific scenarios where the synonym is used.

The Synonym Generator mini app doesn't store any suggestions unless you chose to use them. To use one of the suggestions, select the checkbox associated with your chosen suggestion and select Save and Exit. You can always make edits to the suggestions before you save.

You must always carefully review suggestions from Nextworld intelligence. Learn more in Write help text with Nextworld intelligence.

How to write field names and help text

Follow these guidelines when creating synonyms for the data items in your applications.

When writing help text, refer to the Nextworld style guide and the Microsoft Writing Style Guide.

In particular:

  • Keep things simple. (Common words, shorter sentences.)
  • Remember who your audience is and what they might be wondering about.
  • Use complete sentences.
  • Write to the reader, in second person. ("You"...)
  • Use active voice as much as possible.
  • Use inline styles to format your field values, as well as application, field, and button names. Learn more in Nextworld custom styles. 

Guidelines

Field typeLabels and short labelsHelp textExample
Default
(most fields and data item types)
A word or phrase that describes the information captured by the field. Don't use ending punctuation.

Start the description with a one-sentence statement describing the purpose of the field. Do not simply restate the field name in sentence form.

Try to:

  • Use different words and phrasing from the label text.
  • Describe how the information is used (or could be used) in other applications

If the field label seems very self-explanatory to you and you have trouble composing a longer description, ask yourself under what circumstances someone might be confused. If it's a name field, is there any chance they might not know which name to choose? If they're entering a social security number, could they be worried about how their data is protected?

Label: Budget Owner

Help text: The name of the person responsible for managing the budget for the organization. The budget owner receives workflow notifications and reports.

List lookupA word or phrase that describes the information captured by the field. Don't use ending punctuation.

Follow the default guidelines, with these additional considerations.

In most cases, you should not describe or define the options in the list.

Only define the values when:

  • The list uses abbreviations (values) that aren't known to the majority of your audience.
  • The values impact application behavior in a complex way that must be described

Label: Country

Help text: The country where the organization is based.

Label: Customer Defined Attribute Profile Type

Help Text: 

There are multiple types of CDA profiles, including: 

  • Transaction—Transaction profiles represent a directional flow of data between two tables that occurs as part of a business process, such as a workflow transition. Transaction profiles always include a source table and a destination table. For example, the source and destination table for the Item Receipts to Item Ledger profile are ItemReceipts and ItemLedgerTransactions, respectively. 
  • Reporting—Reporting profiles function similarly to transaction profiles, but the destination table is always a report flat table that your report version applications are built over. Adding CDAs to a reporting profile allows you to filter and sort using the CDAs in your report version applications. If you need to display the CDAs in your reports, however, you must create a report layout. Learn more in Configure report layouts with customer defined attributes. 
  • Master—Unlike the other types of CDA profiles, Master profiles do not represent a flow of data between tables. Instead, they represent a single table that doesn’t require data to flow to or from it. For example, you may need to add a CDA to the Lots CDA profile so that your unique field is accessible in the Lot Master application, which is only used for reference.
SubtableA word or phrase that describes the information captured by the field. Don't use ending punctuation.

Start the help text with "Lists ..." and a brief description of the information the table captures.

In the detail form of a record, a subtable with no entries appears with just the label and an Add button. Help text should provide enough information to explain the purpose of the subtable to a user who doesn't see a table.

Remember the columns within the subtable have their own help fields. You only need to give a brief description of the table as a whole.

Label: Emails

Help text: Lists all email addresses associated with the organization. You can make changes to the emails associated with the organization here.

True False

A word or phrase that describes the selected (or true) checkbox. Don't use ending punctuation.

Provide a label that implies two opposite states. The label should describe the selected state. (The behavior if the box is checked.) 

For longer labels (where you need a longer phrase), write the check box label as a phrase or imperative sentence with no ending punctuation.

If there's any ambiguity in the label, explain the states clearly in the help text.

This data item type creates a checkbox.

Use selected to described a checked box, cleared to describe an unchecked box. (Don't talk about it being checked or unchecked.)

Use language like:

  • When selected, indicates that....
  • Select the Label check box to...

Label: Track Budgets

Help text: When selected, budgeting applications automatically create budgets for this organization in the budget cycle process.

If this checkbox is cleared, you can still create budgets for the organization manually. 

Synonyms best practices

These best practices ensure that data item synonyms are configured consistently throughout Nextworld applications.

Data item synonyms are configured on the Synonyms page in Data Item Definitions.

Label and Short Label

The synonym should not contain any numbers, special characters, or punctuation in the Label or Short Label fields.

The list form field name you put in the Short Label field should be a shorter, more concise version of the detail form field name you have in the Label field. For example, if Unit of Measure is the name of the field in the detail form field, you can abbreviate the list form field as UOM. 

Help Text

Write help text to be as reusable as possible. Data items need a different synonym when the field serves a different purpose. For example, the data item Notes can be used for many different purposes and requires multiple synonyms. If both the foundation and manufacturing families want to use Notes for their applications, they would make synonyms to use the same data item for different purposes. For an application in the foundation family the label may be Contact Notes, and in an application in the manufacturing family the label may be Work Order Notes.

Avoid creating a synonym where the labels and help text match another synonym. The family and module are multiple selection fields, so add your family or module to the existing synonyms. This helps control translation cost.

Avoid adding references to specific application or table names in the synonym help text, because these references reduce the reusability of the synonym and increase the likelihood that the help text has to be updated over time.

Use the examples below as reference when writing help text:

ConventionExample: data itemExample: help text
Construct help text that defines the field’s purpose and avoids stating instructions.DiscountDateThe last day that an invoice can be paid and still receive a discount.
Provide information in your help text about the attributes of a field.FullCardNumberThe 15 or 16 digit number on the front of the credit card. If the card is an American Express card, there is a 15 digit number. Otherwise, there is a 16 digit number.
Provide examples in your help text that help users understand the field’s meaning clearly.DirectoryDescriptionA description of the contact, such as what their purpose is and how your company is associated with them.

The help text must be written in full sentences and adhere to the Nextworld Style Guide. Learn more in Nextworld style guide and How to write field names and help text.

Synonym specificity

Create at least one generic synonym for every data item. A generic synonym has no family, module, or application entered. This synonym appears in applications that use the data item, but do not have a specific family, module, or application synonym defined.

When you define an application for a synonym, you should also define a family and module. When you define a module for a synonym, you should also define a family.