You can add the Calendar package to an MDriven model to link dated business data to reusable Day, Week, Month, and Year dimensions for filtering, grouping, and statistical analysis.
What the Calendar package provides
The Calendar package is a reusable model package that prepopulates calendar dimensions in the database. It contains calendar objects for days, weeks, months, and years, together with links between those objects.
Link your own dated objects to a calendar Day rather than repeatedly calculating date ranges in each query. From that Day, your data can reach its related month, year, and generated week. This gives reports and diagrams stable dimensions to group by.
For example, if each Account has a link to the Day on which it was created, you can group accounts by that Day's month or year when preparing data for a chart. The package does not provide chart components; it provides the calendar dimensions that make chart data easier to summarize.
Download and add the package
Download CalendarPackage.modlr and merge it into your model using TKLiveView.
A package is a container for a section of your model. For package concepts and import/export behavior, see Documentation:Package. If you use the package as a referenced package, you can add associations to its classes but cannot edit its contents unless you adopt it; see Documentation:Referenced package.
Calendar dimensions
| Dimension | Purpose in your model | Example use |
|---|---|---|
| Day | The primary connection point between your data and the Calendar package. | Link an Account created on a particular date to its Day. |
| Week | A generated weekly grouping based on a configured WeekDefinition. | Count Accounts per week. |
| Month | A monthly grouping connected to its days. | Show monthly account creation totals. |
| Year | A yearly grouping connected to its months and days. | Compare totals for different years. |
| HourOfDay | An hour dimension that you can derive from a DateTime value. | Group Accounts by the hour in which they were created. |
The calendar objects use integer ordinals. An ordinal is a stable integer position in time that the package uses when calculating how far apart calendar objects are.
Initialize the calendar data
Before linking business data to calendar dimensions, create the calendar range that your application needs.
- Start the application.
- Open the DataStructureBrowser ViewModel.
- Run the Fixup Calendar action.
- Create the years you need, then use FixupCalendar to create and connect their months and days.
- Configure a WeekDefinition before relying on week-based analysis, then generate or correct the calendar again with FixupCalendar.
You can run FixupCalendar repeatedly. It updates or corrects the calendar structure without losing existing calendar data.
Configure weeks and days off
Week conventions differ between countries and organizations. The WeekDefinition class defines the first day of the week used when weeks are generated. It can also identify recurring days off, such as Saturday and Sunday.
Use the country setting to choose the default WeekDefinition for your users. Do not assume that a week definition is universal: configure it to match the reporting convention your application requires.
Link your classes to Day
For each class whose records you want to analyze by date, create a unidirectional association from that class to Day. Day is the standard link from your business data into the calendar dimensions.
Example: analyze Account creation dates
Assume that Account has a DateTime attribute named CreateTime.
- Create a unidirectional association from Account to Day.
- Ensure the calendar has been initialized for the dates that Accounts can contain.
- Set the Day association when an Account is created, or populate it from an existing DateTime value.
Once linked, an Account can be analyzed through its Day and the Day's related calendar objects. For example, the Account's linked Day lets a query or presentation reach the relevant month and year rather than deriving those groupings independently for every Account.
Set the Day when creating a record
Calendar is a singleton. Use Calendar.SO as the short form for its singleton object.
To link a newly created record to today, use this OCL in the Account class's OnCreate function body, assigning it to the Account's Day association:
Calendar.SO.TodayCalendar.SO.Today returns the Day object for the current date.
Link existing records from a DateTime attribute
When records already have a DateTime value, use the Day helper method GetDayForDate to find the corresponding Day and assign the result to the Day association. The method builds a dictionary for quick lookup.
For an Account whose existing timestamp is self.CreateTime, use Day.GetDayForDate() with that date value when populating the association. This approach connects historical data to the already-created calendar structure.
If you need to compare dates without their time portion, use the date OCL operator; see Documentation:OCLOperators date.
Analyze by hour of day
To analyze when during the day records occur, create a unidirectional association from your class to HourOfDay in the Calendar package.
- Create the unidirectional association from Account to HourOfDay.
- Set the association to Derived.
- Set its DerivationOcl so that it calculates the HourOfDay from the Account's DateTime attribute, for example
self.CreateTime.
A derived association avoids storing a separate hour value when the hour can be calculated from the source DateTime. The package contains the HourOfDay dimension; configure the derivation against the DateTime attribute in your own class.
Use the helper operations
Use the helper operations on Calendar and its calendar classes when you need to locate a Day for a date, move to the next or previous day, week, or month, or calculate the time between calendar objects. Prefer these operations over duplicating calendar-navigation logic in each business class.
For example:
- Use
Calendar.SO.Todaywhen a new object should be linked to today's Day. - Use
Day.GetDayForDate()when assigning a Day from an existing DateTime value. - Use the next/previous helper operations when a user moves from one calendar period to the adjacent period.
Reporting use
The package supports analytics by giving your data common, connected time dimensions. A report can aggregate Accounts through their linked Day, then group the result by Week, Month, or Year. This is especially useful when preparing summarized data for a table or diagram.
The Calendar package is a model pattern for calendar-based aggregation. For other reusable model examples, see Documentation:Model Examples Old.