A naming convention provides a framework that helps to define structure when designing a model. The naming conventions outlined here are designed to make it easy for model builders and administrators to quickly understand what a component is and how it fits into the structure of the model.
Check the naming restrictions on the Model Building page before you start.
The conventions you use, and the way you organize components, will be reflected throughout a model. For example, the way modules are organized in Settings > Modules will be reflected in Users > Roles → Modules, making administration more intuitive and straightforward.
Naming conventions for the following components are described below:
Model names should clearly represent the business function they are associated with. We also recommend noting the model mode: production, test, or development.
For example, Territory and Quota Test, and Territory and Quota Dev, clearly show the mode of the model.
Where a model is archived, or a copy is taken, append the date of the operation to the model name: Territory and Quota YYYYMMDD. It will then be clear which version of a model you are looking at.
Naming conventions help you to quickly locate the list you need, especially in a complex model.
In General Lists, create categories for the different kinds of lists you will be creating. Common categories include products, departments, geographic areas, employees, revenue or account structure, etc. Lists can be organized by hierarchy or by subsets. Hierarchy lists should be organized into sections that represent the levels of the hierarchy.
Create a dummy list and use the << and >> characters on each side of the name to differentiate category names from lists.
For those lists that don’t fall into a standard category — pick lists or lists for reporting — create a category, Other Lists.
To separate subsets, a Subsets category should be created at the end of General Lists. Line Item Subsets should be created at the start of the Line Item Subsets section.
When you click in the Applies To column, in Settings > Modules, the heading you have inserted will be displayed in the Select Lists dialog so you can easily see which subsets or line item subsets apply to the module.
A two or three-character alpha-numeric prefix, representing the category and the level of hierarchy, should be added at each level of hierarchy. In the example below, G1 Regions, G represents the Geo Hierarchy and 1 represents the top level of the hierarchy. In G2 Sub Region, the G represents the Geo Hierarchy and the 2 represents the second level of the hierarchy.
Complex hierarchies should use prefixes that identify any parent hierarchy they belong to as well as identifying the list content. In the example below, G represents the Geo Hierarchy. The O in GO4 Outlets represents Outlets and the 4 represents the fourth level in the hierarchy. In GE4 Employees, the E represents Employees and the 4 represents the fourth level in the hierarchy.
When naming a Subset, it is a best practice to adopt a naming convention that incorporates:
- a prefix to indicate a list is a subset of a larger list (for example: lss, ls, s, ss, sub).
- the name of the list where the subset is defined.
- a colon followed by a brief description of the subset.
Add a # suffix to a numbered list to distinguish it from its master list. This is useful if the two lists have similar names, for example GO5 Product Groups# and P1 Product Groups.
GO5 Product Groups# is a numbered list of all product groups that relate to each GO5 outlet whereas P1 Product Groups is a list of all product groups.
The name of a time range should include the date range and aggregation. For example, FY19-FY20 or FY18-FY22 with Qtrs. Each time range must have a unique name. Don’t:
- use an underscore at the start or end of the name.
- use the words Model Calendar.
Because they are seen by end users, functional areas and dashboards should be given friendly names that don’t use complex prefixes. Where they represent steps in a process, the names of functional areas and dashboards should include the appropriate step number.
Create separate functional areas for dashboards and for modules. Model builders can then use Roles to limit access to the functional areas that contain modules. End users won’t see modules in their Contents, but they will see dashboards. If you switch Show New Content off in Settings > Contents, when you create a new module, it won’t be displayed to end users.
Functional area names should represent sections of a business process or business function.
Dashboard names should represent the stages of the business process users should navigate.
Where the model is complex, use a 2- or 3-character alpha-numeric prefix when naming modules. In the example, SP1 Sales Planning, SP represents the Sales Planning functional area and 1 is a unique identifier (the identifier, 1, doesn’t necessarily represent a sequence in the modules).
Keep module names short so that formulae are concise and names in the Actions menu are not truncated.
Create dummy modules to separate modules into meaningful categories. Use the << and >> characters on each side of the name of dummy modules to differentiate the category name from data module names. Ensure dummy modules have no dimensionality and that end users have no access to them.
The names of module views should consist of the prefix of the the module they belong to, a greater than character ( > ), and the name of the view. Optionally, you can use the alpha numeric identifier of the View. For example, SP1 Sales Planning > Current Year or SP1 > Current Year.
Line Item Subset names should include the name of the source module, a colon, and the name of the subset. For example, SP1 Sales Planning : Items. You can also use the alphanumeric identifier of the subset, for example, SP1 : Items.
You can prefix the name with LIS (Line Item Subset) to distinguish it from other lists in the module blueprint: LIS SP1 Sales Planning : Items.
Where a Line Item Subset has been created from multiple modules, include the prefix MM, a colon, and the name of the subset. For example: MM : Reporting Summary.
Action names should consist of a number, representing the stage in the process; an abbreviation of the action type; and the name of the data source.
All import and export Actions should be included in a Process, as a data source and action cannot be deleted from a model once the action is included in a process. This will prevent accidental deletion of an action that is key to a larger process.
Where an Action is to be run by a user, the Process it is part of — not the Action — should be published to the dashboard as a button with a friendly name.
As a model builder, Actions are a key part of the model’s structure. Use a combination of numbers, letters, and locations to name Actions and make processes easy to identify. Be sure to include the source and the destination location, as that will help you navigate to the correct action each time. If you need to edit an Action, you'll be able to locate it quickly.
As you can see here, a list of imports on the left has been transformed by the addition of some numbering and locations, making the process much clearer and easier to read.
Any isolated import or export actions can be added to an All Action process. This process will never be run but prevents accidental deletion of actions that aren’t part of a process.
Imports and Exports
Action types are represented by im for import and ex for export. If the action is an export, the file name represents the name the file is given when the export is run.
In this example, 1/2 im Employee Roster from Roster Setup.csv, 1 represents the first stage in the process: im represents import; Geo Hierarchy.csv is the name of the data source.
As the import target is displayed on the left of the screen, a model builder or administrator can immediately see the source and target of the action; what type of action it is; and its location in the process.
2/2 im Employee Roster from Roster Setup.csv is the second stage in the process.
Because processes are seen by end users, and can consist of one or many steps, they should be given friendly names.
Prefix button names with a plus or minus symbol (to reinforce the action type) when creating buttons to add or delete items. Include the > character, followed by the name of the dashboard to be opened, when creating a button to open a new dashboard.
The names of User Roles are based on organization roles, such as Sales Manager or Sales Executive.