Naming Convention

Center of Excellence

1. Abstract

The following document is intended to suggest and give concrete examples of the nomenclature to be used during the development of the back end and front end of a Board solution. The aim is to have a consistent and organized nomenclature that led to a maintainable solution that can be easily consulted in the event of additional developments, post-go-live support, and maintenance activities.

2. Context

During the development of a board application, the developer needs to create hundreds of back-end structures: entities, cubes, data readers, and procedures. The same for the front-end layer with the capsule and all the screens. In all the projects, these activities are a team effort, with several developers collaborating to create the necessary structures. On top of that, many applications require post-go-live support activities and or additional developments at a later stage of the project. For all these reasons becomes crucial to define a naming convention at the beginning of the development phase and apply it when any new structure is created, or an existing modified.

3. Content

During the development of a Board application, it is strongly suggested to define a nomenclature to be used for all the structures required to create the application.

For each of the back and front-end sections, guidelines are proposed below to help the developer to give a suitable nomenclature considering dos and don’ts.

A disciplined method, classification, and naming are essential for any activities of design and review of the solution.

3.1 Back End

3.1.1 Data Model

Consider the following guidelines to give a proper data model name:

• Do not use the client’s name in the Data Model name;
• Do name the Datamodel according to the application context, for example, "Business Intelligence", or “Planning”;
• Avoid using acronyms unless specifically requested by the customer and aligned to customer conventions;
• Do not use special characters in the Database name (for instance, avoid using the ampersand symbol, &).

3.1.2 Entities

Consider the following guidelines to properly name entities

• Do use the singular form – e.g., Version not versions;
• Do Capitalize only for appropriate acronyms (e.g., SKU);
• Do make every effort to align naming conventions with those used in source systems. E.g., If you are loading ‘GL Account’ from the source into an entity, it should be called GL Account, not Account.
• Avoid the use of special characters or punctuation;
• Do not rename or delete the [R] for replicated entities;
• If an entity becomes unused, prefix it with ZZ and create a dedicated group to store all the unused entities.

3.1.3 Cubes

During the development of a Board Solution, the developer will probably create hundreds of cubes with different meanings and for different purposes. That’s why the definition of a proper classification is key.

3.1.3.1 Classification Guidelines

An example of cube classification can be as follow.

Description + one/two digit + three digits:

• Description to describe the cube
• One digits to define how the cube is populated, for example 
  • [L] if loaded through DR 
  • [D] if populated through Data entry 
  • [C] if calculated through Data flow 
• Three digits to describe how the cube is used
  • [MTX] for matrix cubes
  • [SET] for setting cubes
  • [TCH] for technical cube
  • [TMP] for temp cubes that can be cleaned at the end of the procedure
  • [STG] for staging cubes
  • [REP] for reporting cubes

Using the described naming convention, these are some cube name examples:

• ACT Sales [L][STG]: cube to store actual sales loaded though DataReader
• Current Year [D][SET]: setting cube to identify the current year
• Workflow Locker [C][TCH]: Technical cube to lock data entry based on Workflow status
• User-Role [L][MTX]: Matrix to assign user–role load through data Reader

Additional consideration:

• Add in the cube name the area/module where the cube is used. An alternative could be to use cube grouping, which is a powerful way to group, sort, and classify all the cubes created.
• Can be helpful to add in the cube name the physical name [Vxxx]. This will make the search easier during the configuration of a layout.

3.1.3.2 Nomenclature

• Do not use implied terms such as ‘Cube’. 
• Do not use abbreviations unless specifically relevant. 
• Do use Proper Capitalization. Do not use ALLCAPS. 
• Do name cubes according to the classification guidelines described above.
• If a cube becomes unused, prefix it with ZZ, and empty it. Create a dedicated group to store all the unused cubes

3.1.4 Data reader

• Prefix data readers according to the following categories: 
  • E – Data reader to load an Entity
  • H – Data reader to load and create hierarchies 
  • C – Data reader to load a cube 
• Include the module name if relevant. 
• Match the data reader name to the source file description when possible.

3.1.5 Procedures

3.1.5.1 Classification Guidelines

An example of classification for database and capsule procedure can be as follow.

• A prefix to define the relevant module name:
  • BDG – Budget
  • WRF - Workflow
  • ADM – Admin Settings
  • SYS - for system procedures such as backups
• A few digits to describe the procedure purpose, for example:
  • LOAD - to identify procedures that load data
  • OUT - to identify procedures that export data
  • SAVE - to identify procedures that save data entered by the user
  • GOTO – to identify procedures to navigate across the screen
• Description.

Using the described naming convention, these are some examples:

• BDG – LOAD – Expenses Target
• BDG – OUT – Export Expenses Baseline
• ADM – SAVE – Yearly Settings
• WRF – CALC – CC open

Additional considerations:

• Can be helpful to prefix unused or test procedures with ‘ZZ’. They will then show at the end of the procedure list and should be deleted before promoting to production.
• If unique to a screen, capsule procedure names should start with the screen number where they are used. Subsequent procedures used in the same screen should be enumerated 1.1, 1.2, etc. This can help identify the steps sequence the end user is following.
• Can be helpful to prefix with “CALL” a procedure that is called from multiple procedures. This is alerting the consultant that changing this procedure there can have an impact on any procedure that is calling it.

3.2 Front End

3.2.1 Capsule

3.2.1.1 Nomenclature

• Capsule names and their parent folder names are the first things a user will see when they land on the Board web home screen. Do ensure folder and capsule naming is relevant to the user audience, using business functional terms.
• Do not use ALLCAPS unless relevant to client branding.
• Do use proper capitalization.
• Do not use implied terms (e.g., ‘Capsule’).
• Do not use special characters.

3.2.1.2 Organization

• Capsules should be organized with navigation and folder security in mind.
• In a Sandbox environment, the structure of Capsules and folders should be exactly aligned to production. This is to assure testing is conducted in a like-for-like fashion and all capsule links are preserved (i.e., folder paths and capsule names remain consistent between environments.
• Create a dedicated folder for unused or deprecated capsules which is excluded from general user security profiles.
• Create a dedicated folder for Backups. Ideally, this should contain timestamped sub-folders. (This should also be excluded from general user security profiles).

3.2.2 Screen

3.2.2.1 Nomenclature

• The screen name appears in the top bar and will be identified by the end user as the screen title. Use a proper name that is consistent with the objective and purpose of the screen and meaningful for the end user.
• Do not use implied terms like ‘Screen’.
• Use proper capitalization.
• Do not use ALL CAPS.
• Do not use special characters.

3.2.2.2 Organization

• If the number of screens in the application is relatively small, it can be evaluated to start the screen name with a logical number sequence that reflects the logical navigation and workflow.
• Define sub-categories with a dot, but ideally, limit them to 3 levels. E.g., ‘1.1.1 Main Menu’, ‘3.1.1 Validate and Submit’. You should consider the most appropriate time to introduce the number pre-fix to avoid very frequent alterations to screen codes during the development.
• When testing or creating a temporary screen, prefix the screen name ‘ZZ’. ZZ screens should be deleted from the release candidate capsule and not promoted to production. An alternative could be to create an ad hoc test capsule.

3.2.3 Mask

3.2.3.1 Nomenclature

• Mask names are not displayed in any part of an application at run-time so naming conventions need to help the developer or power user.
• Unlike all other naming conventions, it is recommended to prefix masks with the implied term “Mask” because when multiple masks and screens are open in the Board thick client, it is not possible to differentiate them.
• Do not use ALLCAPS.
• Link the Mask name to the relevant module or audience.
• Keep it generic, in line with the mask content – like:
  • MASK – Admin Settings
  • MASK – Budget entry
  • MASK – Reporting

Krisztina Zappert

Thank you for the comprehensive guide.

Could we have a bit more detail on the difference between [TCH] and [SET] cubes?

I don't see the prefix for cubes that are populated via data flow. Would that be [DF]? Furthermore, in the examples displaying cube naming, we have the instuctions “Description + one digit + three digits:”, but then all the examples are two digits: “Two digits to define how the cube is populated, for example” “[DR] if loaded through DR” “[DE] if populated through Data entry”.

On the same topic, what is the recommendation for cases where cubes are populated in different ways? For example, biyearly, the cube is populated with a data flow, but also users are free to go in and change the data manually whenever they wish (which they might do very rarely, more rarely than the data flows). What is the recommendation here, what do we prioritize in the convention?

It was previously ill advised to use spaces in procedure names. Have the issues that the spaces caused been fixed?

Possibly, an addition could be made to the procedure section. When the name involves a dot, it is not possible to call that procedure using an API. Actively advising against dots in procedure names for that reason (or just pointing it out for procedures considered for API use) could be helpful.

We used to have instructions on how to use naming conventions to connect MAIN and SUB procedures (module_description_1.0_MAIN, module_description_1.1_SUB_detail, module_description_1.2_SUB_detail etc), is this something that is still advised?

How would a CALL prefix look like in practice? "CALL - BDG – OUT – Export Expenses Baseline" ?

Thank you!

Federica Antonelli

Federica Antonelli

Thanks @Krisztina Zappert, your review is really appreciated!

TCH vs SET: SET is more a setting cube like the one to manage the calendar to set the current budget year or open vs close months in a rolling forecast. While TCH is a technical cube to manage for example a customer sorting or a custom filter or a locker.

One/two digit: you are right! we also reviewed the article. It can be 2 digits like [DR] or [DE] or one digit like [L] for loaded cubes, [D] for data entry and [C] for calculated cubes. There is no one that is more correct than the other - the suggestion is to use a naming convention and make it clear in the documentation.

Cubes populated in different ways: this is interesting. The idea is always to indentify clearly cubes that are populated through Data Entry because we need to be careful with the content. If cleared out it's more critical to retrieve the data. So I suggest to tag this cube as a data entry cube. An alternative option, when applicable, can be to have a data entry cube, one populated through data flow and a final one that combines the two, which is the output/reporting cube.

Yes “spaces” are allowed in the procedure name.

Connect Main and Sub: it's dependent on the complexity you are managing but it's advisable to use and explain which is the naming convention used.

For CALL procedure: yes could be a way or we can use CALL - Export Expenses Baseline [BDG][OUT]. It's really just to be able to quickly identify procedures that are called from others.

Andrea Duò

Hi @Krisztina Zappert,

regarding “When the name involves a dot, it is not possible to call that procedure using an API”, I would like to ask you more details. If I call via Postman a Board procedure that has dots in the name, it works fine. Is it possible that the API client you are using interprets the dot as a special character and needs an escape?

Andrea

Michael Feith

Hello @Federica Antonelli,

thank you so much for this guide, its super helpful! I was looking for something like this for a while now.

Do you know if there exists a similar best-practice guide for documentation of a project?

Kind regards

Michael

Federica Antonelli

Hello @Michael Feith thanks for your feedback!

Good point. We are working on a revised project methodology in which each project phase has a set of documents that must be drafted. For documents that are responsibility of the project team, we are creating templates and best practices (such as the Solution Design Document, for example).

Stay tuned for more details on this topic.

Krisztina Zappert

https://community.board.com/discussion/comment/14118#Comment_14118

Hi Federica,

Thank you for the detailed response, it is very educational! I am looking forward to reading more templates and best practices!

Krisztina

Krisztina Zappert

https://community.board.com/discussion/comment/14125#Comment_14125

Hi Andrea,

I will look into this further on our end, thank you very much for the tip!

Krisztina

Shisong

Thanks for sharing. It would be great if you could provide more detail about the reason why "Do not use the client’s name in the Data Model name;".

Federica Antonelli

Hello @Shisong.

The recommendation is to use a name for the data model that reflects the process rather than relying on the client's name only. Under the same customer - it may be necessary to create multiple databases and using the client name could be constraining.

Shisong

Hi @Federica Antonelli
Thanks for the quick response. Appreciate it a lot.

Hamza Mesbahi

Hi @Federica Antonelli,

Thanks for the great insights and article! As a consultant, it's always helpful to go into development with a consistent naming convention that we all follow. One follow-up I have is regarding the Data Model naming section. You mention not to use the client’s name in the Data Model name or to name the Datamodel according to the application context, for example, "Business Intelligence", or “Planning”. So out of curiosity what are some examples of how we should be naming our data models?

Thanks,

Hamza

Federica Antonelli

Hi @Hamza Mesbahi - yes we mentioned a couple in the article as you said. I can give you some other examples that I used in the past:

• FPnA (Financial Planning Application)
• RBM (Result Based Management Application)
• Reporting Conso (a Datamodel that was consolidating data across multiple Datamodels for reporting purposes)
• PnL Budgeting
• DBF (Driver Based Forecast application)

There are many more but I hope these additional examples help!