You can create an OpenDocument report from a ViewModel and use MDriven Designer to find the OCL expressions and model elements that the report depends on; this part is for designers building their first data-driven document.
What you build
In this part, you create a report for one business object, such as a rent bill for a billable period. The report is an OpenDocument template that MDriven fills with values from a dedicated ViewModel.
For example, a rent bill can contain:
- the apartment number;
- the tenant name;
- the rent amount;
- the billable period start and end dates; and
- a repeating list of other people in the same house.
The report ViewModel is rooted in the object that represents the report's subject. In this example, root it in BillablePeriod, not LeaseContract, because a bill is generated for one specific period. This decision determines which data is directly available to the report.
Create the report ViewModel
- In MDriven Designer, add a ViewModel for the report. Name it for its purpose, for example
RentBillReport. - Set the ViewModel root to the business object for which the report is generated. For a monthly bill, use the billable-period object.
- In the ViewModel context menu, select Add column and then Add columns needed for report. This adds the report infrastructure columns, including the template location and output file name.
- Add columns for every value that the template must show. Follow associations from the root object as needed.
- Select the ViewModel and clear Use placing hints. A report ViewModel provides data to a template; layout hints for an automatically generated UI are not needed.
For the rent-bill example, add columns such as ApartmentNumber, Rent, TenantName, PeriodStart, and PeriodEnd. If the root is BillablePeriod, expressions that previously started at the lease contract may need to navigate from the billable period to its lease contract before accessing apartment or tenant data.
Set the template and output name
Set the report columns so that MDriven can locate the template and name the generated document.
| Column | Purpose | Example |
|---|---|---|
TemplateUrl
|
Location of the OpenDocument template. | c:\\temp\\mytemplate.odt during local development, or a content URL when the template is deployed as an asset.
|
ReportFileName
|
Name of the generated file, including its OpenDocument extension. | RentBill.odt
|
For template storage options, deployed assets, supported formats, and the report operations, see Documentation:OpenDocument. For a complete template-storage walkthrough, see Training:Microsoft office and OpenDocument as a Report generator.
Discover and place template tags
Create an .odt template in an Office application that supports OpenDocument format. Add %meta% to the template and generate the report once. The generated output lists the tags available from the report ViewModel.
- Put
%meta%in the template as the first string in its element. - Generate the report.
- Copy the required tag names, including both percent signs, from the generated metadata output.
- Replace
%meta%in the template with the tags you want to display. - Save and close the template, then generate the report again.
A direct value tag uses the ViewModel column name. For example, if the ViewModel has an ApartmentNumber column, use:
Bill for apartment %ApartmentNumber%
Please pay %Rent% for the period from %PeriodStart% to %PeriodEnd%.
You can use the same tag more than once in a document. Apply normal document styling in the template to control the presentation of the resulting report.
Tag recognition is case-sensitive. Copy tags from the metadata output rather than retyping them. Office editors can add invisible formatting or control information to edited tags, which prevents merging. In particular, font changes and line breaks in an ODT tag can interfere with tag detection; replace a problematic tag by pasting it as plain text.
Add repeating report data
A report can include nested ViewModel data, such as the people living in the same house. Add a nested column or nested data set to the report ViewModel for the collection, then place its generated tag in a table row in the template.
Use the collection tag to identify the row that repeats, and put the child-value tags in cells in that row. For example, a table headed Other people in the house can repeat one row per person and show each person's full name. Generate a report after adding the nested data and use %meta% to obtain the exact collection and child tags for your ViewModel.
This approach keeps the template responsible for document layout and the ViewModel responsible for selecting report data.
Generate the report
Create an action on the business object that starts the report. The action supplies the report ViewModel to the OpenDocument reporting operation.
The report operation can return the generated file as a byte array or show the resulting HTML in the browser. The reporting reference shows both forms, including an action expression using opendocumentreportshow. See Documentation:OpenDocument for the exact operations and examples.
Test the action with an object that has complete report data. In the rent-bill example, create a billable period with a start date, end date, connected lease contract, apartment number, tenant, and rent. Generate the report, inspect the output, adjust the template or ViewModel, and generate it again.
Format values intentionally
A report prints the value supplied by its ViewModel column. If a date-time value includes a time but the document should show only a date, add a report column that formats the value as the required string rather than placing the raw date-time column in the template.
For example, use the expression editor to create a display-oriented column for a period date, then use that column's generated tag in the template. This keeps formatting decisions explicit in the report ViewModel.
For spreadsheet reports, use the documented ViewModel naming suffixes when a cell must be interpreted as a number or percentage. Without the relevant suffix, an .ods template can interpret merged values as text. See Documentation:OpenDocument for the supported conversion rules.
Get help with report expressions
A ViewModel column expression is an OCL expression that navigates the model from the ViewModel root. Use the expression editor to build the navigation rather than relying on memory.
For example, when a report rooted in BillablePeriod needs the lease-contract rent, start with the billable period and navigate to its lease contract before selecting Rent. If an expression becomes invalid after you change the ViewModel root, revisit each navigation step from the new root.
Use the model browser and expression assistance to inspect the available properties and associations at each step. This is particularly important for report data because an apparently suitable root object may not represent the business event being reported.
Use cross-references before changing the model
MDriven Designer cross-references show where a model element is used. Use them before renaming, moving, or changing an attribute that supplies report data.
For example, if you select a Rent attribute, its cross-references can show that it is used by both a house ViewModel and the RentBillReport ViewModel. You can follow a cross-reference to select the owning model element and inspect related constraints or expressions. This helps you identify the effect of a model change before it breaks a report.
Troubleshooting
| Symptom | Check |
|---|---|
| The report generation fails while reading the template. | Close the template in Word or another editor. An open template can be locked. |
| A tag remains unchanged in the generated document. | Verify case, copy the exact tag from %meta% output, and replace the tag as plain text to remove hidden formatting.
|
| The report shows the wrong data or an expression is invalid. | Confirm that the ViewModel root represents the report subject, then correct the OCL navigation from that root. |
| An ODS value is treated as text. | Review the spreadsheet numeric and percentage naming rules in Documentation:OpenDocument. |
| An ODS download is corrupt. | Review the OpenDocument notes about template creation and download behavior in Documentation:OpenDocument. |
Next step
Continue with Documentation:Part 7 Files and images in reports and UI to work with files and images in reports and the UI.