Naming rules

Naming rules prevent conflicts between development extensions from different partners. These rules avoid overwriting another partner’s work in the vertical layer.

Since the very first version of the software, naming ranges are as follows:

• Standard layer: A-V (A reserved for the supervisor module)
• Vertical layer: X-Y
• Specific layer: Z

All elements starting with W correspond to automatically-generated items such as transactions.

There were dedicated ranges of local menus and miscellaneous tables for the vertical layer.

When a partner is alone in a customer folder, these rules can easily be considered correct.

However, today, our customers want to have a marketplace where they can find different extensions coming from several partners and install them simultaneously in their environment.

Without rules, it is impossible to answer this market expectation, which opens business opportunities for all of us.

To address the new need to install different partner extensions on the same folder, we need to ensure that they do not use the same names.

Sage created the unique identifier concept to do so.

Code extensions provided with V7 enable providing to each partner upon request:

• A unique identifier, generally a four-digit alphanumeric code
• A range of local menus and miscellaneous tables

You must use this identifier at the beginning of any name you create in the dictionary and your programs. For example, XX12.

This naming rule applies to all dictionary elements that use alphanumeric codification such as screens, classes, representations, activity codes, actions, source code, etc.

You must use these conventions for all keys, abbreviations, and settings for the elements.

The new naming ranges thus become:

• Standard layer: A-V (A reserved for the supervisor module.)
• Vertical layer:
  • Add-ons: X*** (The identifier is unique — if naming rules are respected, there is no naming conflict.)
  • Assets: Y (You can encounter conflicts if you install different assets in the same folder.)
• Specific layer: Z (The elements are customer-specific, no conflict to manage.)

For local menus and miscellaneous tables, the 13000-13999 and 18000-29999 ranges are reserved. A dedicated range, depending on your needs, can be reserved for you upon request.

The Sage Global Product Delivery team is responsible for the code allocation following a partner request.

Codes are stored in a unique database to avoid any double allocation.

The administration data (authoring, badges, menu items, etc.) is stored in the MongoDB database.

Every part of administration data must also be unique and contain the unique identifier (starting with it or including it in some cases explained later).

As of Update 8, we also strongly encourage partners to use the Factory ID to tag their elements. Factory ID has the same role as the activity code for components stored in the MongoDB database (see the Factory ID section).

If you have an existing extension created before these rules, you must rename it before moving into the add-ons program. This program offers you new business opportunities.

If you develop a new extension, apply the add-on naming and development rules immediately.

Conflicts may occur if you install a vertical that does not follow the naming rules of some add-ons.

You need to manage this directly in a project where a conflict occurs. Conflicts cannot be anticipated.

Sage’s position is to promote add-ons and to require that asset codes are renamed.

For example, the unique identifier for Sage Portugal is XX04. Everything they develop must start with XX04.

Upon request, Sage provides to each partner a range of local menus and miscellaneous tables adapted to your needs. For example, this range is 13220-13259 for Sage Portugal.

The following paragraphs explain how you should proceed to apply naming rules.

Elements added in a standard entity

When you add fields in a standard entity such as a screen:

• The name of the fields must begin with your identifier.

• You must set an activity code, that also begins with your identifier, on each added field.

In the screenshot below, X1QT represents the unique four-digit identifier for the partner.

To facilitate identification, you can use the following naming convention for fields you create that complete standard dictionary elements (tables, screens, etc.) and do not exist yet in the application. Start with the identifier followed by an underscore.

In the example, it could be X1QT_MAX.

New entity defined in the dictionary

For a new entity, such as a table or a class:

• The name and the abbreviation must begin with your identifier.
• You must set an activity code that starts with your identifier on the element.

For sub-elements like columns:

• You can use a free codification. It will not conflict with other partner extensions as they belong to your entity.
• You do not need to protect them with an activity code because the code set at the parent level protects them.

Enabling a free codification for columns facilitates the use of the class assignment, which simplifies coding.

Local menus and miscellaneous tables

Sage assigns partners a range of local menus and miscellaneous tables to use for development.

Use values included within this range and set activity codes starting with your ID for any new element that you create.

Source code

The name of all the scripts that you create should start with your identifier.

Administration data

This category includes all the elements stored in the MongoDB database.

Most of these elements are delivered to customers as part of their add-on. Sage wants to avoid naming conflicts with other elements coming from other partner extensions when you install your package on a customer site.

The solution is to have your unique identifier in the name. It can be at the beginning of the name or inside it.

You can use a Factory ID since Update 8. Factory ID allows you to tag items you own and protect them from modification unless you are logged in with the same Factory ID.

Factory ID

Since Update 8, you can tag all administration with a Factory ID.

To enable this feature, you need to modify the nodelocal.js file and authorize Factory ID.

There are two advantages in doing so:

• Your developments are protected from customer modification. Customers can only duplicate and rename them if necessary.

• You can easily extract all the elements linked to a Factory ID in a single patch.

Setting the partner Factory ID

As a partner, you can define your Factory ID in a security profile if your nodelocal.js file authorizes this option.

A user with this security profile can flag data as factory.

You can do this on the principal entities of the administration module. You can flag personalized pages as factory as well.

Sage uses this method to protect delivered data and to prevent wrong updates from the customer. You can duplicate data using the Save as button but not modify nor delete it.

In the example below, elements are marked with a Factory ID and the related owner. In this case, the owner is Sage.

Administration data naming – Best practices

This section details the main categories of data you can create.

For data types missing from this list, the objective is the same: choose a name that avoids any conflict when running the installation on a customer folder where other partner extensions might be present.

The best solution is to include your unique identifier in the name.

Menu items, menu module, menu submodule

There are two ways of creating these elements:

• A direct creation using the Syracuse entity
• The import tool

The rules are adapted to be consistent.

The import tool creates menu items only for classic functions and Version 6 gadgets.

Since Update 9, the naming rule for creating bespoke or vertical items is the following. FUNCTION is the function code.

• SPE_X3_ERP_FUNCTION for Sage X3 bespoke functions
• SPE_X3_HRM_FUNCTION for Sage X3 HR & Payroll bespoke functions
• VER_X3_ERP_FUNCTION for Sage X3 add-ons or vertical functions
• VER_X3_HRM_FUNCTION for Sage X3 HR & Payroll add-ons or vertical functions

You do not need to add your unique identifier as the function name should already include it.

The difference between vertical and specific naming during import is linked to the parameter used when the copy is launched:

• If the role is associated with a security profile that has a Factory ID set, the Set imported elements as Factory check box is on the launching page.
  If this check box is selected, the VER_ prefix naming is used.
• Otherwise, the applied naming rule is the SPE_ prefix.

During this tool's execution, only one type of naming is used regardless of how the functions are named. For instance:

• VER_X3_ERP_ZFUNC could be created in an import execution if the check box is set, even if the normalization of vertical functions should not use Z as a prefix.
• SPE_X3_ERP_XFUNC could be created in an import execution if the check box is not set, even if the normalization of bespoke functions should not use the X prefix.

To preserve global consistency, use the same rules if you create a menu item for a classic function directly instead of using the import tool.

For any Syracuse function that you add, no import function creates the entry for you. You need to create your menu item, submodule, or module.

Normalization is not defined yet, but you should:

• Include your unique identifier as part of the code
• Include your add-on name in the title
• Use the Factory ID to tag the element

Authoring pages

When you author pages, you need to provide:

• A code that includes your unique identifier.
• Title and description. The title can include the name of your add-on as that is the only information visible by the end-user. The code is not displayed.
• The Save as setting. The Factory option is only available if:
  • The EnablePartnerID feature is set.
  • Your security profile is defined with a Factory ID set.

  The Factory ID associated with your security profile is set for the element. You do not have to fill in the value.

Other administration data

You can either:

• Start your codification with your unique identifier
• Include your unique identifier in any position inside the key