Custom Time Entities – Generic Month example
1. Abstract
Custom time entities are a subset within the time range section in the BOARD database.
They are mainly adopted during the application to intercept those time analyses which cannot be implemented with only the standard time function available by default in the BOARD data model.
Since they are limited in BOARD, they must be carefully managed.
Moreover, regardless of the just-mentioned limitation, it is important to keep them updated and integrated to always get a consistent time tree, which is one of the main dimensions of each BOARD data model.
The purpose of this document would be to give best practices on the custom time entities definition and to explain how to use them.
2. Context
Sometimes the company may need to handle customized time dimensions to generate very specific time analyses.
During the requirement gathering, one of the first decisions is whether to implement the business request with the creation of a custom time entity or with an entity outside the time range.
Custom time entities are limited, with 4 slots available in BOARD and therefore during the analysis phase, the developer must open a discussion before taking a decision based on the pros and cons of having it.
This is a crucial decision, as it will affect the entire data model and make the maintenance of the application based on it a bit more complex.
3. Content
With custom time entities you can define ad-hoc time entities.
For instance, you might encounter a company’s request where the company may need to handle very specific analyses by generic month (Jan, Feb, March, etc), 4-4-5 weeks, Season or Promotion, and so on.
After discussion with the customer on the needs and output to be achieved in Board, a technical challenge comes up.
The custom time entity must be set up and integrated with the existing time tree, which implies the definition and the maintenance over the time of the relationship between the custom time entity and the existing time schema.
3.1 Definition and population
Let us see how to create and inject the ‘generic’ month as a custom time entity into Board.
Open the time range tile.
Click custom entities, pick up the first custom time entity named as ‘_Time1’ and then provide a valid name.
Add manually the new members. Here the developer has two options:
- insert the members manually;
- copy and paste members from an existing file.
At this stage, you need to do a couple of things:
1. Click custom relationships and set up the relationship by placing the generic month on top of the month.
By doing this you are creating a new branch for the generic month, but month members still are not linked to it.
Click Save changes.
Note that all direct and indirect relationships must be always defined, no orphan (stand-alone) entities are allowed.
In the rather unlikely but possible scenario, if at some point in the project it is necessary to discharge the ‘generic’ month, it is not enough to remove the relationship, one must also empty the entity.
In general, the above statement must be applied against any given custom time entity.
A direct relationship is a one-level child → parent relationship.
In our example, Month → Generic Month is a direct relationship.
An indirect relationship is a child → grand-parent relationship, for instance, if the Day entity is enabled for this database, then Month is a parent of the Day, therefore you must define also the indirect relationship Day → Generic Month.
2. Once complete we can go within the Data reader section to feed the relationship up in Board.
Click new data reader to get access the Data reader configuration and select the data source Text File.
The file to be read looks like the following:
3. Within the data reader, map the month and generic month entities with their counterpart taken from the file.
Click save changes and run the data reader protocol.
At this stage, the entity is populated and the relationships are defined, therefore the entity can be used.
NOTE: if we want to use this entity in combination with the standard time functions available in Board (i.e. Prev. Year, offset, etc .) we would need to define also the “mask” setting. Please refer to the Board Manual to see how this can be done.
4. Point of attention
Since the ‘generic’ month is injected into the time tree of the data model, please note that from this moment onward any increase applied to the time range (i.e., increase of the ‘To Year’ value) implies even updating the relationship for the new month members in scope.
In practice, you must:
- Open the file to be read in BOARD and update accordingly with the time range definition, this means adding the new combinations between month and generic month.
- Get back to the second step of the process and follow the remaining steps.