Legacy Word reports

Note: Legacy Word reports are no longer being developed as it is strongly recommended to work with Office Reports , which are cloud-ready, performant, and can generate PDF, Word, and Excel files.

Vertec’s legacy Word reporting mechanism allows custom reports to be designed in MS Word and run directly from Vertec, beyond Word’s built-in mail merge capabilities.

A Legacy Word report is always based on a document template in Word. This report template contains, in addition to normal text, special elements that are evaluated as it runs. These are described below:

Ribbons

Ribbons are the foundation of Legacy Word reports. Everything that is printed is in a ribbon.

A band is represented in the report template by a text bookmark. The name of the text bookmark is the band name.

Where you want to create a band, create a sample text in the desired layout (e.g. a table, tabbed rows, etc.). Then select this text and click on “Insert – Bookmark...”. The window will open where you can specify the name of the bookmark. It is advisable to choose a name that recognises what it is (i.e. not Band1, Band2, etc.). This will make it easier to customize the bands and expressions in the expressions later.

The ribbons can be nested freely. However, each report template must contain a standard ribbon. This is a ribbon that includes everything else. So, after you create the template, you can select everything and enclose it with another bookmark. The name of that bookmark does not play a role.

A tape can be printed once or more times when a report is run. So when a tape is run on a list, the tape is printed as many times as there are items in the list.

Bookmarks that are not deleted

Markers whose name begins with trg or src are not deleted by the Vertec reporting mechanism. So if you need markers in your document that remain after execution, call them trg.. or src...

Band Definitions

Depending on how a ribbon’s bookmark is defined, the scope of the ribbon is interpreted slightly differently in Office and Vertec-generated reports. The differences typically relate to the treatment of empty paragraphs. For more information, see Differences between office and vertec-generated legacy word reports .

Fields

A field is a commented text within a band that is replaced by data from Vertec when the report runs.

To create such a field, select any text you want to insert the data from Vertec in the future, and click Review – New Comment. The corresponding comment must contain an OCL expression that is valid at the appropriate location.

To edit a field, right-click on it and select Edit comment.

Example of fields with associated comment in Word:

Band Expressions

Band expressions are also commented areas of text within a band. They differ from fields in that the highlighted text always begins with the name of the band to which the expression refers. The following band expressions are possible (bndXXX means the name of the band):

• bndXXXExp: Band main expression. If specified, the value of the band is calculated based on this expression. The expression refers to the root object of the report or to the value of the next outer band. If the result of this expression matches a list, the band is duplicated for each entry in the list.

• bndXXXCond: Band Conditional Expression. If specified, this expression is evaluated each time the band occurs (i.e. if the band is duplicated within a list, for each object). The result of the expression must be a Boolean value (True/False). Depending on this result, the band is printed or not printed.

Region-Specific Number Formatting

With so-called locale bands, as of Vertec 6.1, it is possible to specify in the Legacy Word report according to which locale number and date values should be formatted within the band.

The following band expression can be used to set the locale:

bndXXXLocale: A comment on <band-name>Locale specifies the locale. This can be done as follows:

• Specifying a country code as a locale expression: de-CH
• Specify an OCL expression (from Vertec 6.2) that returns a country code as a string: 'de-CH'

Example

A comment on rchMasterLocale with content de-DE sets the locale for the entire master band to German, Germany.

Within this band, all numbers and date values are displayed in the corresponding regional representation.

A table of country codes is available at: https://docs.microsoft.com/en-us/previous-versions/commerce-server/ee825488(v=cs.20).

Number formatting in Vertec versions before 6.2

In versions prior to Vertec 6.2, only the values formatted according to the VBA Format feature (texts starting with a \) are formatted in the locale settings specified in the locale band:

Insert images into legacy word reports

Images can be inserted into legacy Word reports. These can either come from Vertec (e.g. receipt images on expenses) or from the file system (only Office-generated).

For this purpose, there are special fields that are replaced by other data rather than text when the report is run. To create such a field, the text marked by a comment must begin with a specific string. These special fields are explained below.

Imagedata

Such fields are used to insert images stored in Vertec into Legacy Word reports.

The text marked by a comment must begin with the string ImageData. The OCL expression included in the comment must return the contents of an image field in Vertec.

Imagepath (vertec-generated legacy word reports only)

These fields are used to insert images stored on the file system into legacy Word reports. Text marked by a comment must begin with the string ImagePath.

The OCL expression must provide an absolute path to an image file stored in the file system. Word will then insert the image file located in that location.

As an OCL expression, the path can also be specified directly, in single quotation marks:

If the result of the OCL expression is an empty string, the comment is simply deleted in Word and nothing is shown. If the image does not exist at the specified location, an error message is inserted in the report instead of the image.

Scaling of inserted images

To control the displayed size of the inserted images in Word, it is recommended to show them in a table as in the examples shown. The scaling in the table is as follows:

The inserted images will not be scaled up, either horizontally or vertically. However, the images will be scaled down if necessary:

• If an image is wider than the table cell, it is scaled down when the table auto-resize is turned off.
• If an image is higher than the table row, the row is enlarged, unless the row height is set to an exact value in the table properties. If the row height is set to an exact value and auto-resize is turned off, the image is scaled down to fit the cell.

Here is an overview of the scales:

Line height fixed	Allow resizing	Effects on the image
No.	No.	Scaled: yes. Changes the row height of the table. The row width remains.
No.	Yes	Scaled: no. Changes row height and row width (the image will be scaled to the maximum width of the table – page width)
Yes	No.	Scaled: yes. Does not change row height or row width.
Yes	Yes	Scaled: no. Changes the line width. The line height remains, the image overlaps.

Insert text blocks (html) into legacy word reports

In the same way as the pictures (see above), HTML-formatted text, e.g. from text blocks, can be inserted into legacy Word reports from version 6.0.

Htmltextblock

This field is used to insert HTML formatted text into legacy Word reports. For example, this can come from a Vertec word block, but you can also specify any text field that contains formatted text. In Word, you can insert this text as follows:

The text marked by a comment must begin with the string HtmlTextBlock. The OCL expression included in the comment must result in HTML-formatted text. Here is the text field of a text block:

The value resulting from the evaluation of the OCL (comment) is interpreted as formatted HTML text and the result is written to the report.

The elements described in the article Text modules are supported, including OCL expressions calculated within the HTML.

Ocl variables for legacy word reports

Before running a Legacy Word report, the following OCL variables are created:

• rootObj: The object on which the report is executed
• optArg: The optional additional argument (e.g. address entry)
• regarding: The subject of the report Dialogue
• comment: The comment from the report Dialogue

These variables are defined in OCL and can only be accessed within an OCL expression (rootObj and optArg can also be evaluated from the method parameters (AfterReport3)).

The variables would return the following values for the example above:

Expression	Result
Vertec.eval(“rootObj”)	Returns the invoice (16070001, COMINSTALL).
Vertec.eval(“optArg”)	Returns the optionally entered address (Eliwag AG). If no address is optionally entered in this dialog, this variable returns the standard street address (Comtelsat AG).
Vertec.eval(“subject”)	Returns the string invoice June 2016.
Vertec.eval(“comment”)	This invoice is returned once to the company Eliwag AG.

 

Local ocl variables in legacy word reports

Starting with version 5.3.0.29, local OCL variables can be used in legacy Word reports. Using a Var expression, a variable can be created and reused later in the report. In particular, this prevents recalculation of values that are used more than once.

Var expressions are comments on texts of the form

<bandname><varname>

where varname must begin with “var”.

Example

In an accounting report, services are to be grouped by service type. For this purpose, the services are first determined and then a list of services is output per service type. This means that the services have to be filtered with an expression of the type bndMaster.leistungen->select(typ=self). The list can now be loaded into the variable and processed further (e.g. varLeistList.wertext->sum).

Access via com

The corresponding method on IvtcSession is called

EvalToVariable(root as IVtcObject, expression as String, varname as String)

This allows you to load values into variables in code, for example in an Excel report, which can later be used in OCL expressions. In particular, you can also write results of expressions that are only generated by the expression and are not present in Vertec to a variable (for example, the result of a summation, a date value using encodedate, etc.).

For example, in an Excel report you want to show the services from a certain point in time. Instead of looking for the services in the way “openServices->select(date >=” & encodeDate(2012, 08, 01) & “) “ you can first set a variable and then use it:

Vertec.EvalToVariable(Vertec.argobject, "encodeDate(2012,08,01)", "varVon")

and then in the expression:

offeneLeistungen->select(datum >= varVon)

Differences between office and vertec-generated legacy word templates

Legacy Word templates work basically the same, whether they are generated by Vertec or by Office, with the following differences:

No BeforeReport / AfterReport support

Vertec-generated Legacy Word reports do not support custom code, so they do not run Before and AfterReport macros.

Because these are often used to write values to headers or footers, an alternative approach has been developed, which is described in the section Data fields in headers and footers in the article Differences between Office and Vertec-generated Legacy Word reports.

Insert images only with ImageData

Inserting images in Vertec-generated legacy reports only works with ImageData, not ImagePath.

The Word templates of Legacy Office reports basically work the same regardless of whether they are generated by Vertec or by Office, with the following differences:

Headers and footers

Vertec-generated legacy word reports

Insert data fields in headers and footers

Starting with Vertec 6.1, data fields are supported in Vertec-generated Legacy Word reports to enable insertion of data into headers and footers.

The fields are managed in the advanced properties in the Word document, menu File > Information > Properties > Advanced Properties > Customize:

The field name must contain var start. The field value contains the Ocl expression . Type is always text.

Integration in header and footer

In the edit mode of the header or footer row, the desired variable can be applied as a field by using Insert > Quick Blocks > Field in the DocProperty field:

The expressions of the document properties are evaluated once on the up-to-date vertec object (argobject) when created. The OCL expression is replaced by its result, applying multi-line text as well.

Support of expressions

Starting with Vertec 6.3.0.4, Vertec-generated Legacy Word reports support the ability to insert header and footer expressions.

Expressions in double curly brackets are interpreted as OCL expressions, as in advanced Office reports, and populated with the corresponding data when run.

Example

{{TimSession.allinstances->first.login}} 

inserts the name of the user logged in to Vertec in the header or footer.

Size limitation

The contents of fields in Word can be a maximum of 255 symbols. Longer texts are therefore truncated to 255 symbols when evaluating the field expression.

Office-generated Word reports

In headers and footers of Office-generated Word reports, OCL cannot be evaluated because comments cannot be inserted. If you want to use values from Vertec, you can:

Insert variable in header or footer

In versions prior to Vertec 6.1 there is the following workaround via the macro code:

As a variable, a text is inserted that can be clearly retrieved later in the code. In the example below, the text is xProjectcode:

The example would like to show the project code in the header or footer of an invoice. For this to work, a macro with the name BeforeReport2 or AfterReport3 needs to be created on this invoice template. Macros with this name are automatically triggered when a report is called from within Vertec (see the Event Macros section in Word Reports).

The code to replace the text in the header and footer for this example is as follows:

Sub AfterReport3(vertec As Object, dok As Object, root As Object, optarg As Object, akt As Object)
Dim i as integer
For i = 1 To dok.Sections.Count
  'Setzte den Wert im Header
   dok.Sections(i).Headers(wdHeaderFooterPrimary).Range.Find.Execute FindText:="xProjektcode", ReplaceWith:=root.Eval("projekt.code"), Replace:=wdReplaceAll
'Setzte den Wert im Footer
  dok.Sections(i).Footers(wdHeaderFooterPrimary).Range.Find.Execute FindText:="xProjektcode", ReplaceWith:=root.Eval("projekt.code"), Replace:=wdReplaceAll
Next
End Sub

The text you want to replace (xProject Code) must be typed directly into the header. If it is in a text box or table, the method described above will not find it.

Referencing Variables by Style

Another variant is to reference a specific piece of text within the report in the header or footer. This can be done as follows:

Initial situation: there is a master volume, and in it is a text project code. This text is marked with the comment code.

Select the text Project Code and then go to the styles. Select New Style. In the dialog box that appears, enter Project Code as the name, select Symbol for the style type and click OK.

Then navigate to the header (or footer) where you want to show the project code. Type project code and highlight this text. Click Insert > Quick Blocks > Field. For categories, select Links and References, and for the field name, StyleRef. Select Project code and click OK.

Nothing is visible at first glance, but when you run the document, the corresponding project code will be printed here.

Since this variant over StyleRef fields does not work with Vertec-generated Word reports with output format PDF, to know if a field is a StyleRef field, you can use the keyboard shortcut Shift-F9 to show the field code:

Insert line breaks in Word reports using VBA

In Word reports, a line break can be inserted via ASCII code chr(13) + chr(10):

txt1 = "Erste Zeile" & Chr(13) & Chr(10) & "zweite Zeile"
ActiveDocument.Range.Find.Execute FindText:="Text1", ReplaceWith:= txt1, Replace:=wdReplaceAll

If the variable you want to replace is in a table, this will not work. In this case, the newline must be inserted via ^p:

txt2 = "Erste Zeile" & "^p" & "zweite Zeile" ActiveDocument.Range.Find.Execute FindText:="Text2", ReplaceWith:=txt2, Replace:=wdReplaceAll

Band Definitions

Depending on how a ribbon’s bookmark is defined, Office and Vertec-generated reports interpret the scope of the ribbon slightly differently. The differences typically relate to the treatment of empty paragraphs.

There are 2 general types of differences:

Bands across document hierarchy levels

Unlike the VBA-based report builder of Office-generated reports, the server-based reporting system supports only tape definitions for Vertec-generated reports that start and end at the same level. This means:

Band start	Tape end	Vertec-generated reports
Text (normal paragraph)	Text (normal paragraph)	OK
Text (normal paragraph)	Text (within Table)	not OK
Text (normal paragraph)	End of table row	not OK
Start table row	End of table row	OK
Start table row	Text in a table cell, not at the end	not OK

To ensure that these conditions are met as well as possible, band start and band end are interpreted as generously as possible.

For example, if a band start is at the end of a paragraph that contains text but only includes the paragraph marker, this is not actually valid. For the report to work anyway, if the band end is at the end of a table row or paragraph, the band start is interpretatively moved forward to the beginning of the next item (paragraph or table):

This automatic adjustment naturally means that a paragraph change is displayed less. This is therefore visible in the output.

If possible, such bands should not be defined, but preferably whole sections or start and end within the text should be defined as bands.

If the start of the tape is even in the middle of the paragraph text, as shown in the figure below, an error message will appear regarding invalid tape definition.

Indistinguishable variants

There are cases of band definitions that cannot be distinguished in server-based code, although they are visually distinguishable in Word.

This is the case, for example, if a bookmark ends at the end of a blank paragraph that follows a table:

In this case, the end of the bookmark is inside the empty paragraph. However, if the ribbon ends at the end of the table, i.e. does not contain the empty paragraph, then the end of the bookmark is also inside the next paragraph.

Therefore, bookmark ends in an otherwise empty paragraph are always interpreted as the end of the preceding table.

If you want a blank paragraph after a table to explicitly belong to the ribbon, this can be done by inserting some text (e.g. a space) in the paragraph. Then the paragraph is interpreted as belonging to the ribbon.

Bands that start in a blank table row

If a band starts at the beginning of a blank table row, at least one space must be inserted in that table row:

Otherwise, an error message of the type: Invalid overlapping bands bndXY and bndYZ will appear.

Ocl variables for legacy office reports

Before running a Legacy Office report, the following OCL variables are created:

• rootObj: The object on which the report is executed
• optArg: The optional additional argument (e.g. address entry)
• regarding: The subject of the report Dialogue
• comment: The comment from the report Dialogue

These variables are defined in OCL and can only be accessed within an OCL expression (rootObj and optArg can also be evaluated from the method parameters (AfterReport3)).

The variables would return the following values for the example above:

Expression	Result
Vertec.eval(“rootObj”)	Returns the invoice (16070001, COMINSTALL).
Vertec.eval(“optArg”)	Returns the optionally entered address (Eliwag AG). If no address is optionally entered in this dialog, this variable returns the standard street address (Comtelsat AG).
Vertec.eval(“subject”)	Returns the string invoice June 2016.
Vertec.eval(“comment”)	This invoice is returned once to the company Eliwag AG.

 

No BeforeReport / AfterReport support

Vertec-generated Word reports cannot run Before and AfterReport macros.

Since these are often used to write values to headers or footers, an alternative rate has been developed, described in the section Insert data fields in headers and footers .

Generation of reports

In contrast to the Vertec-generated Word reports, the Office-generated version also requires a Word installed locally on the clients. Vertec-generated Word reports are cloud-ready and can therefore also run in the cloud app and the web app. Whereas Office-generated Word reports are less powerful and not cloud-ready.

When Report Registration a report, you can set whether the report is generated by Vertec or by Office.

Generation of reports by vertec

Word reports can be generated by Vertec and the resulting documents delivered to the apps. This means that Vertec Word reports are cloud-ready and therefore also run in the cloud app and the web app.

In most cases, running Vertec-generated Word reports is much faster than running on-premises, and no Office installation is required, either on the server or on the clients.

When registering a report, you can set whether the report is generated by Vertec or by Office.

Generation by office

Office generated Word reports are based on a special VisualBasic macro in the Word Standard template, which interprets certain elements in a report template and accesses the Vertec object system via COM or ActiveX.

Install the Word Report Macro Template

To run Vertec Word reports, Word requires special macro code. These macros are located in the VertecReport.dotm template document.

By default, this template document is stored in the Vertec installation directory. Vertec explicitly loads this macro file as a Word add-in if required, so no signature is required.

Event Macros

In the Office-generated Word report mechanism, it is possible to create VB macros that are called before and after the actual report. Macros with the following names are considered:

Beforereport2

Called by the Report Mechanism before using the data from Vertec in the report. This provides, for example, the ability to show a dialog that makes a certain preselection.

The declaration is as follows:

sub BeforeReport2(vertec As Object, dok As Object)
end sub

Access to Vertec is passed with the variable vertec. Vertec can therefore be accessed directly. Example:

sub BeforeReport2(vertec As Object, dok As Object)
dim projektliste as IVtcObjectList

set projektliste = Vertec.eval("projekt->select(aktiv)")

end sub

The Word report is passed with the variable dok.

Afterreport2

This macro is called after Vertec data has been inserted into the report.

The declaration is as follows:

sub AfterReport2(vertec As Object, dok As Object)
end sub

Access to Vertec is passed with the variable vertec.

The Word report is passed with the variable dok.

Afterreport3

Starting with version 5.5. This Word report event macro provides access to the associated activity. This is the activity that is created to link the report to the object in Vertec.

This macro is called after Vertec data has been inserted into the report.

The declaration is as follows:

sub AfterReport3(vertec as Object, dok as Object, root as Object, optarg as Object, akt as Object)
end sub

Arguments:

• vertec: Access to Vertec
• dok: the created Word document
• root: the Vertec object on which the report was executed
• optarg: the optional Vertec object (address)
• akt: the created activity

optarg and akt can also be empty, in VB it corresponds to “nothing”. The macro is called after the data from Vertec has been inserted into the report.

The passed activity has already set the intended path. Changing the path of the activity in the event macro affects the save path of the document.

The activity is created for this purpose before the report is run. If an error occurs anywhere, the activity is deleted.