Best Practices in Writing Procedures

Center of Excellence

1. Abstract

Most probably every Board application will have procedures to cover interactivity by the user (e.g., navigation), perform calculations (e.g., processing plan data) or run other backend processes like creating a backup. To provide the best maintainability, quality, and robustness, some guidelines should be considered when creating a procedure – both for developers and end users. This document sums up the most important aspects to take into account in general and specifically.

2. Context

Procedures provide a broad variety of actions and use cases, where the complexity begins at a simple 3-step procedure to apply a new selection to a screen and might end with a complex allocation sequence that takes more than 100 steps. Every developer is in charge of designing those procedures in a way that all involved creators are supported to understand the structure and content of a procedure.

3. Content

3.1 General settings of the procedure

3.1.1 Database vs. capsule procedure

Procedures can either be created in a capsule or database. While the approach of creating the process is the same in both places, they might be executed for different purposes. For example, only DB-procedures can be scheduled and they are accessible from all capsules – this helps to centralize certain actions or processes and avoid redundancy and increased effort in cases of changes to that process. On the other hand, not every procedure should be stored in the database: the database should be clean and processes that only apply to a certain application/capsule should be decentralized. Some actions like Go To Screen are only available for capsule procedures. Some more insights on the differences can be found here: Capsule Procedure vs Datamodel Procedure — Board Community.

3.1.2 Execution notification

At the beginning of a procedure, a specific “notification” to the user can be defined.

Options here are that:

• a pop-up opens, which can be closed and the user could continue working on the screen. Default option which fits in most situations;
• the whole screen freezes until the procedure finishes; the user cannot do anything on the screen in the meanwhile. Should be used if the process takes several seconds and you want to avoid any interaction from the user in the meanwhile (e.g. do further data entries, which might be affected by the result of the procedure). Also, if the process is completed by a “refresh screen” action, any further user interactions with the screen are not interrupted suddenly;
• it is running silently in the background; again letting the user continue to work on the screen. Especially this mode is recommended if a procedure uses one or more sub-procedures and should be applied to the nested ones to avoid too much flickering on the screen.

3.1.3 Temporary cubes

Make use of temporary cubes whenever possible. All procedure steps which rely on a layout configuration or are cube-based support the use of temporary cubes starting from version 12.5.1 (the supported actions in older versions are more limited). The background and concept are explained in this article: Temporary Cube vs Staging Cubes — Board Community.

3.1.4 Renaming procedures

Take care when renaming procedures. Buttons/labels that run procedures or within nested procedures renaming those procedures will result in an error if the call procedure step is not getting updated manually with the new procedure name. Currently, this only applies to database procedures.

3.2 Content of the procedure

3.2.1 Use comments

For each step in the procedure, a comment field is available. As in every code-based document, comments help to clarify the specific action and can provide context on why it has been designed this way. Applications are usually maintained by different developers (either at the same time or over time) and comments can also help to overcome lacks in knowledge. Not every single step needs a comment, focus on complex dataflows, dynamic selections or IF THEN ELSE steps, for example.

Every disabled step should be commented with the information by whom, when and why it has been disabled. This is especially helpful in debugging situations. The ideal situation would be that a procedure does not contain any disabled steps at all (if an action is disabled then it is probably not used anymore) but there still might be situations where something needs to be disabled temporarily or alternative approaches are kept as a backup.

For entity/tree/cube extractions to file it is useful to copy/paste the extraction path in the comment field. This way it is not required to click on the specific step to see it. The same applies e.g. for the defined expiration days of a “backup database” step or any other configurations that might not directly be visible and you consider as useful to see directly.

3.2.2 Use groups

Procedures with many steps are hard to read and understand if the actions are not logically grouped. So independently of running several actions only under certain conditions – and therefore putting them into a dedicated group to be addressed by an IF THEN ELSE action – it always makes sense to structure the process by creating logical groups. This might also be useful for debugging, so certain parts can easily be cut out by simply disabling the got to group action step.

3.2.3 Avoid redundant actions

Let’s assume a case where a set of identical dataflows needs to be executed multiple times, but for different selections in the same procedure. To avoid redundancy, it is advisable to outsource those dataflows in a dedicated group. This also increases the maintainability as changes in the dataflow logic only need to be updated once for that case and not multiple times.

3.2.4 Consider concurrency

For every procedure that might be executed at the same time by multiple users, it should be considered that users are accessing or changing the same or overlapping cube cells. This can especially happen during calculations, extracting and reloading data.

• Dataflows always run in the applied selection context. That means two users running a calculation for two different cost centers do not affect each other directly. Temporary cubes (see chapter 3.1.3) can be used for intermediate results as they are created for each procedure instance; if that result is required for an action that does not support temporary cubes (especially in version 12.5.0 or earlier) or the result is needed in another procedure, a physical cube is required that contains a user dimension (and the User-selection is applied by security).
• Extracts save the content of an entity, tree, cube or layout to a specified path and filename. To avoid users extracting under the same file name, the path should include the substitution formula @user (which adds the username to the filename); if that file is loaded afterward again via a data reader, the source path in the according procedure step also needs the @user referenced.
• Clear cube should be done with applied selection to avoid clearing cube slices of other users, that are relying on the same cube content at the same time.

3.2.5 Selections

3.2.5.1 Avoid fixed selections / refer to

Fixed selections should be avoided if possible and feasible and replaced by Select Entity Based On cube instead. As selections are pointing to the IDx (every element in the entity has an internal ID) and not the code of the element, selections might be wrong after clearing and reloading an entity. Fixed selections are useful for rather small and stable entities, technical or pointer entities (e.g. planning year, planning version). A detailed view of the different selection options in procedures can be found here: Selection Options in Procedures — Board Community.

It is also recommended to avoid “Refer to” in dataflow layouts for the same reasons. Usage of a temporary cube instead is more transparent and could increase the performance of the calculation as well as reduces the dataflow layout complexity.

3.2.5.2 Remove selection

If selections are applied in a specific context they should be removed after that context is completed and more actions are following where selections are relevant. This helps to enhance clarity and keep visible control of applied selections in complex procedures.

Having multiple selections on different entities within the same tree also needs to be treated with care to get the correct results as they usually return intersections and are not replacing previous selections applied in the tree (except on the same entity).

3.2.5.3 Selections and “run as administrator”

Applying or removing selections (static and dynamic) can be extended by using the additional checkbox for “run as administrator”. This should be treated with caution as it allows to apply a selection which is outside the scope determined by the security profileof the user who started the procedure. It should only be used when necessary (mostly due to process reasons, e.g. allocations between cost centers) and assured, that the correct security selection is restored as soon as possible based on the process.

Center of Excellence

Thanks @Bernhard Nöhreiter for the insights on this article!

Neha Hasija

Thank you for summarizing all best practices for the procedures.I liked the idea including @user while extracting the file

Krisztina Zappert

Thank you for the documenation!

One thing that has worked for us was adding a disabled step (usually Refresh screen, but can be anything) as the first step to every procedure, and document a "procedure overview", "Created date and by whom", "Updated date and by whom" in its comments. The overview describes what the procedure does (in broad terms, focusing on the outcome) and why.