RtReports Template Reference Version 3.2

Transcription

1 RtReports Template Reference Version OSIsoft, Inc. All rights reserved

2 OSIsoft, Inc. 777 Davis St., Suite 250 San Leandro, CA USA (01) (main phone) (01) (fax) (01) (support phone) Houston, TX Johnson City, TN Longview, TX Mayfield Heights, OH Philadelphia, PA Phoenix, AZ Savannah, GA Seattle, WA Yardley, PA OSIsoft Australia Perth, Australia Auckland, New Zealand OSI Software GmbH Altenstadt, Germany OSI Software Asia Pte Ltd. Singapore OSIsoft Canada ULC Montreal, Canada Calgary, Canada OSIsoft, Inc. Representative Office Shanghai, People s Republic of China OSIsoft Japan KK Tokyo, Japan OSIsoft Mexico S. De R.L. De C.V. Mexico City, Mexico OSIsoft do Brasil Sistemas Ltda. Sao Paulo, Brazil Sales Outlets/Distributors Middle East/North Africa Republic of South Africa Russia/Central Asia South America/Caribbean Southeast Asia South Korea Taiwan OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, grecipe, srecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind. RESTRICTED RIGHTS LEGEND Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS Published: 5/30/2008

3 Table of Contents Chapter 1 Introduction to the RtReports Template Reference...1 The RtReports Documentation Set...1 Chapter 2 Report Template Reference...3 Create a New Report Template in the Editor...3 Open an Existing Report Template in the Editor...6 Chapter 3 Data Template Reference...9 Data Template...9 Journal Actions...9 Context...9 Template Hierarchy...10 Data Template Edit...11 Report Parameters...39 Chapter 4 Data Toolbox...47 Objects Tab...47 Predefined Tab...47 Scratch Pad Tab...49 Chapter 5 Data Journal Reference...51 View the Data Journal...51 Navigate the Data Journal from the Data Template...53 Journal Search Window...53 Data Journal Objects...53 Chapter 6 Journal Action Edit...61 Create Journal Actions...61 Action Parameters...62 Action Options...66 Action States...68 Action Results...70 Result Definition...72 Journal Action Expression Syntax...96 Chapter 7 Format Template Reference...99 Format Template Tree...99 Report Edit Window Section Elements RtReports Template Reference iii

4 Table of Contents Entry Elements Drawing Elements Format Strings Chapter 8 Format Toolbox Objects Style Sheets Scratch Pad Tab Chapter 9 Apply the Data Journal to the Format Template Define Source Expressions in Dynamic Drawing Elements Build Source Expressions Source Expression Advanced Techniques Iterator Expressions Condition Expressions Appendix A Technical Support and Resources Before You Call or Write for Help Index iv

5 Chapter 1 Introduction to the RtReports Template Reference The RtReports Template Reference explains how to use the RtReports Editor to define the Report Templates from which users can generate reports. It is part of the RtReports Documentation Set. The RtReports Documentation Set The RtReports Documentation Set includes three manuals. Updated manuals that provide upto-date information are available for download from the OSIsoft Technical Support Web site. The manuals in this documentation set are: Title RtReports User Guide RtReports Administrator Guide RtReports Template Reference Subject An overview of RtReports, how it works, and instructions for using it to define and generate reports. Instructions for the System Administrator to install and manage RtReports. Comprehensive information and instructions for using the RtReports Editor to plan, create, and maintain the Report Templates that define report specifications. RtReports Template Reference 1

6

7 Chapter 2 Report Template Reference Reports are generated from report templates. Report templates are specifications designed through the RtReports Editor. A report template comprises of data specifications, called the data template, and formatting rules, known as the format template. Each report template is built using four tabbed panes: Data Template (page 9) - Specifies the data and processing rules for retrieval Journal - Shows the retrieved data in an unformatted state, called the data journal (page 51). Format Template (page 99) - Specifies the formatting rules for the report Report - Previews the actual report, including live data Create a New Report Template in the Editor To create a new report template, click File > New, then select the type of report template you wish to create: Batch (page 3), Time-based (page 4), or Case Report (page 5) Template. Create a Batch Report Template If you select File > New > Batch Report Template, the Batch Report Template Details dialog appears. RtReports Template Reference 3

8 Report Template Reference Name: The name of the report template. This name must be unique. Description: A description of what the report template is. This description is shown when the report template is listed in the RtReports Generator. Criteria: Defines any batch report criteria for the report template. Report criteria define the relationship between the context and the Format Template. For batch reports, criteria can be defined for Recipe, Product, Equipment, Subbatch, and Unit Classes. Note: Report criteria and advanced security settings for the report template can also be set after the report template has been created by right-clicking the root node of the Format Template tree and selecting Property. Create a Time-based Report Template If you select File > New > Time Report Template, the Time Report Template Details dialog is shown. 4

9 Create a New Report Template in the Editor Name: The name of the report template. This name must be unique. Description: A description of what the report template is. This description is shown when the report template is listed in the RtReports Generator. Recurrence Pattern: Time based reports can define a time recurrence, to establish how often the report should be run. This aids the user who will generate the report to run the report against a correct time range. Available recurrence patterns are Minutes, Hourly, Daily, Weekly, Monthly, Yearly or None. Note: Report criteria and advanced security settings for the report template can also be set after the report template has been created by right-clicking the root node of the Format Template tree and selecting Property. Create a Case Report Template If you select File > New > Case Report Template, the Case Report Template Details dialog appears. RtReports Template Reference 5

10 Report Template Reference Name: The name of the report template. This name must be unique. Description: A description of what the report template is. This description is shown when the report template is listed in the RtReports Generator. Criteria: Defines any case report criteria for the report template. Report criteria define the relationship between the context and the Format Template. For case reports, criteria can be defined for the Model and Analysis. Open an Existing Report Template in the Editor To open an existing Report Template: 1. Click File > Open. The Open Report dialog appears. 6

11 Open an Existing Report Template in the Editor This window lists all the current report templates. You can sort the list by any of the columns by clicking the column heading. Notice that the listing is wider than the window; there are additional columns of information at the right. 2. Double-click the report you want to use. Alternatively, you can select a report and click OK. RtReports Template Reference 7

12

13 Chapter 3 Data Template Reference A data template consists of context elements and journal actions. Data Template A data template stores rules that control how the RtReports Generator retrieves data from the PI Archive or external data sources. The RtReports Generator interprets the rules defined in the Report Template, executes them, and creates a result set called the data journal, which appears in the Journal tab in the RtReports Editor. The data template can gather data from the PI Batch Database, the PI Archive, the PI Module Database, the AF Database, or external relational and web service data sources. Journal Actions A journal action stores rules that control how the RtReports Generator includes time series data in a generated report. The rules can contain calculated logic in PI Performance Equation format that determine the subsequent action. A journal action calculates results from raw data in one of two ways: Action Results use the start and end time of the parent context to retrieve a result definition. Action States define a series of start and end times for which to retrieve a result definition. A journal action must always be contained in a context element. Context The context is the set of key events from which a report presents information. There are three report contexts: batch, time, and AF case. For example, you can present all of the information in the report based on the batch from which the data comes, the time at which it you collected it, or from a specific model analysis. Each data template has a time context and a data context. The time context defines the earliest and latest time on which to report. The data context defines where the report data comes from. RtReports Template Reference 9

14 Data Template Reference Template Hierarchy You can create a context structure to resemble your process model. Children nodes inherit the properties of the parent node(s) in the structure unless the child has an independent definition of the property. Batch Hierarchy A batch context can have a Unit template, Time-Based template, Element template, or Journal Action at the first level of the hierarchy. Other template elements, such as the Subbatch template and the Module template fit into the hierarchy as follows: Time Hierarchy A time based context can have a child Time Based template, Module template, Element template or Journal Action at the first level of the hierarchy. The time hierarchy can have the following structure. 10

15 Data Template Edit Case Hierarchy An AF case context can have a Time Based template, Element template or Journal Action at the first level of the hierarchy. The case hierarchy can have the following structure. Data Template Edit The Data Template Edit dialogs are where you define the criteria that the Report Template uses to select the data for a report. The definition of a data template depends on its context (Batch, Time, or Case). Batch Report Context Batch Reports define the Report Template context as PI Batches. The start and end times of the batch define the time context of the report. You define the data context in the Data Template, Unit Template, and SubBatch Template. RtReports reports data for a single batch only, not for multiple batches at the same time. You can define a placeholder in the Batch Template for specifying a batch when the report is generated. Data Template Root Edit The root node of the Data Template can be accessed by right-clicking the Data Template Root node in the Data Template tree and selecting Property. RtReports Template Reference 11

16 Data Template Reference This launches the Data Template Root Edit dialog. For batch report templates, the Data Template Root Edit dialog serves two functions. It allows you to enable the ability to report on multiple batches (on the Batch tab) and it allows you to define report parameters for the batch report template (on the Parameters tab). Parameters 12

17 Data Template Edit For information on defining report parameters for a report template, please refer to Report Parameters (page 39). Batch Multiple Batches Select this box to define a Batch Report Template that spans multiple batches with the same Batch ID. This functionality merges the start and end times of all the batches. Minimum Batches Enter the number of batches to combine as one batch. Batch Template Edit For batch report templates, the node directly under the Data Template Root node is a Batch Template node. To configure this object, right-click and select Property. RtReports Template Reference 13

18 Data Template Reference The Batch Template Edit window has two tabs: Layout (page 14) and Framework (page 14). Layout Name The name for the batch template that appears in the Data Journal. Display Name The display name for the batch template that appears in the Data Journal. Description The description for the batch template that appears in the Data Journal. Framework 14

19 Data Template Edit The Framework tab allows you to designate an Analysis Framework Server and Database, if you wish to include Element Templates in your Batch report. For more information on Element Templates, see the Element Template section. AFServer The name of the Analysis Framework server from which to pull AF Element data. This value can either be a static string, or a report parameter in square brackets []. Simply select the server you wish to use to populate the AFServer field. Database The name of the Analysis Framework database from which to pull AF Element data. This value can either be a static string, or a report parameter in square brackets []. You can also search for an AF database by clicking the magnifying glass icon. You can also search for an AF server by clicking the magnifying glass icon. RtReports Template Reference 15

20 Data Template Reference Select the database you wish to use to populate the Database field. Unit Template Edit The Unit Template Edit window is where you define which PI Unit Batches to include in a generated report. These unit batches are represented in the data journal as UnitBatchJournal objects. A Unit Template object can be created by right-clicking on a Batch Template object and selecting Insert > Unit Template: 16

21 Data Template Edit There are several ways to specify which unit batches to include: Layout (page 17) tab to define name pattern matching for the unit batches you wish to return. UnitClass (page 19) tab to pull unit batches from a defined unit class. Spanning (page 20) tab to create a time span that will bridge the unit batches of the parent PI Batch, or to further filter the unit batches returned as a result of name pattern matching defined on the Layout tab. Layout The Layout tab is where you specify the name of the PI Units to include in a Unit Template. The most common way to specify which PI Units to include is by name. RtReports Template Reference 17

22 Data Template Reference Name The PIUnit name of the PI UnitBatch objects to include in the Unit Template. The default value is *, which returns all unit batches within the PI batch. Possible values for the Name field: Pattern Match Example Values Returned Exact name match TRAREACTOR Returns all unit batches with name TRAREACTOR (the match is not case-sensitive. Single-character wildcard match (?) Multi-character wildcard search (*) Report parameter substitution (square brackets) Procedure Name TRAREACTOR? TRA* [LocParam]REACTOR Returns unit batches TRAREACTOR1, TRAREACTOR2, TRAREACTOR3, but not TRAREACTOR123 Returns all unit batches with names beginning with TRA At runtime, RtReports will substitute the parameter value for report parameter LocParam into the Name field. If the value of LocParam is defined as PHL, RtReports will return unit batches with a name of PHLREACTOR. 18

23 Data Template Edit Supply a procedure name if you wish to filter the collection of unit batches specified in the Name field further, by limiting the returned collection to unit batches with particular procedure names. If no value is entered, all unit batches currently in the collection are returned. All pattern matching that can be applied to the Name field can also be applied to the Procedure Name (exact name, single- and multi-character wildcard, and report parameter match). Display Name The display name for the unit template that appears in the Data Journal. Description The description for the template that appears in the Data Journal. UnitClass The UnitClass tab is where you specify the class and version of the PI Unit Batches to include in the batch context report template. Unit Classes allow you to group similar equipment and create reports based on the type of unit rather than a specific unit. For example, if you have ten identical units, you can build one report template for the unit class. This reduces the amount of work, because you would maintain one Report Template rather than separate ones. Select the Use Unit Class check box to enable the Class and Version fields. Class The name of the unit class. Version RtReports Template Reference 19

24 Data Template Reference The version of the unit class. Values can either be manually entered for Class and Version, or you can click the magnifying glass icon to select a Unit Class from the collection defined on the RtReports server. Note: You must create a Unit Class and populate it with units by clicking Tools > Unit Class Editor. If the Use Unit Class check box is selected, all specifications in the Layout and Spanning tabs are ignored. Spanning The Spanning tab has two uses: to define a time span across PI units to further filter the unit collection defined on the Layout tab DEFINE A SPAN The goal of spanning is to define a span start time and a span end time. This is accomplished by choosing a unit batch from which to base the span start time, then choosing another unit batch from which to base the span end time. 20

25 Data Template Edit For example, if you want to Trend the pressure over three units, you can define spanning to start at the start or end time of the first unit and then end at the start or end time of the third unit. 1. Click the Spanning tab. 2. Define the Span Start. Process Step Defines a collection of unit batches from which to select the basis for the span start time. This field operates the same as the Name field in the layout tab, meaning you can supply either a unit name, single-character wildcard (?), multi-character wildcard (*), or report parameter definition. Select Once a collection of unit batches has been defined in the Process Step field, the Select field can be used to select the particular unit batch from which to base the span start time. Select Option First Last Index (value n) Value Returned Returns the first unit from the collection. Returns the last unit from the collection. Returns the n'th value from the collection. RtReports Template Reference 21

26 Data Template Reference Note: Until the Process Step in the Span End section is entered, an All option appears in the Select field. Once the Process Step field in Span End is defined, this option disappears, as it has no meaning when defining a span from one unit to another. The All entry is used only for double-filtering. See Using the Spanning tab to further filter the unit collection. Evaluate From Once a unit has been selected to base the span start time on (based on the values in the Process Step and Select fields), you can then choose whether to base the span start time on the Start or End time of the selected unit. Condition A PI Performance Equation which is executed by the RtReports Generator at the start of each PI UnitBatch that meets the previous criteria. If the PI Performance Equation returns true, the PI UnitBatch is included in the report. If the equation returns false, then the PI UnitBatch is excluded. For example, you can exclude any batch that contains a digital state of SHUTDOWN. 3. Define the Span End. EXAMPLES Here are two examples of defining spans for a unit template: To define a span that has a span start time of the start time of the first unit named UNIT1, and a span end time of the end time of the first unit named UNIT2: 22

27 Data Template Edit To define a span that has a span start time of the end time of the second unit starting with TRA, and an span end time of the start time of the fourth unit which ends in REACTOR (note the changed definitions in the Evaluate From fields): RtReports Template Reference 23

28 Data Template Reference Note: A defined span will return only one UnitBatchJournal object in the Data Journal, with a start time of the span start time, and an end time of the span end time. FILTER THE UNIT Another use of the Spanning tab is to further filter the collection of units already defined on the Layout tab. This is done by specifying only the Span Start section of the Spanning tab. Process Step Defines a filter on which to narrow down the unit collection defined on the Layout tab. This field operates the same as the Name field in the layout tab, meaning you can supply either a unit name, single-character wildcard (?), multi-character wildcard (*), or report parameter definition. Select Once a collection of unit batches has been defined in the Process Step field, the Select field can be used to select the particular unit batch from which to base the span end time. Select Option First (value n) Last (value n) All Index (value n) Value Returned Returns the first n units from the collection. Returns the last n units from the collection. Returns all units from the collection Returns only the n th unit from the collection. Condition A PI Performance Equation which is executed by the RtReports Generator at the start of each PI UnitBatch that meets the previous criteria. If the PI Performance Equation returns true, the PI UnitBatch is included in the report. If the equation returns false, then the PI UnitBatch is excluded. For example, you can exclude any batch that contains a digital state of SHUTDOWN. EXAMPLES Here are some examples of multiple filters on a unit template definition. If the Layout tab is defined to return all units in the batch that begin with Unit": 24

29 Data Template Edit That definition returns the following nine units: UnitA1, UnitB1, UnitC1, UnitA2, UnitB2, UnitC2, UnitA3, UnitB3, UnitC3 On the Spanning tab, an additional filter can be defined to return only the first two units that contain an A (in this example, it would return UnitA1 and UnitA2: RtReports Template Reference 25

30 Data Template Reference Similarly, we can also double-filter and return only the last two units in the collection that end in Unit2 (in this case, UnitB2 and UnitC2). Note the single-character wildcard: 26

31 Data Template Edit SubBatch Template Edit The SubBatch Template Edit window is where you specify which PI SubBatches to include in a generated report. These subbatches are represented in the data journal as SubBatchJournal objects. A SubBatch Template object can be created by right-clicking on a Unit Template object and selecting Insert > SubBatch Template: You can specify the Name in the Layout tab or specify Select and Condition criteria on the Spanning tab, similar to the fields in the Unit Template Edit (page 16) dialog. Batch Template Wizard The Batch Template Wizard window builds a data template structure for a batch that has already been processed by the plant. The wizard provides searchable access to the PI Batch Database. You can search for batches that meet your criteria. Once you find the batch, you select it and select the processing steps to include in the report. 1. Right-click anywhere in the Data Template docked window and choose Batch Template Wizard. 2. Specify your search criteria. 3. Click Search. The wizard populates the table with the batches that meet your criteria. 4. Double-click the Batch ID to see the processing hierarchy in the pane to the right. RtReports Template Reference 27

32 Data Template Reference 5. Select the processing steps to include in the data template. 6. Click OK to save the data template hierarchy. Time Report Context Time Reports define the Report Template context by using time and module templates. The time templates define the time context of the report and the modules templates define the data context of the report. A Report Template can have multiple time templates and module templates. Time Template Edit For time report templates, the node directly under the Data Template Root node is a Time Template node. To configure this object, right-click and select Property. 28

33 Data Template Edit The Time Template Edit window is where you define the time context of a time context Report Template. The time context Report Template can be defined by a relative time span or a fixed duration. The Time Template Edit window has two tabs: Layout (page 29) and Time (page 31). Layout The Layout tab is where you specify the name of the PI Units to include in a Time Template. RtReports Template Reference 29

34 Data Template Reference Name The name for this time template that appears in the Data Journal. Display Name The display name for the unit template that appears in the Data Journal. Description The description for the template that appears in the Data Journal. AFserver If you wish to include Element Templates in your time-based report template, you can specify an Analysis Framework server from which to base all AF Element definitions. You can either enter a server name or click the magnifying glass icon to select an AF server from a list. 30

35 Data Template Edit Database If you wish to include Element Templates in your time-based report template, you can specify an Analysis Framework database from which to base all AF Element definitions. You can either enter a database name or click the magnifying glass icon to select an AF server from a list. Time - Relative Time Span The content on the Time tab depends on whether the time is defined by a relative time span or a fixed duration. RtReports Template Reference 31

36 Data Template Reference Start and end time are inputs into Time Report Templates. In the RtReports Generator, the user inputs the time, which goes into the root Time Template. This time propagates through to the child Time Templates. You can modify the time by using an offset in the time template definition. On the Time tab, select Relative Time Span to allow the Time Report Template to determine the start time and the end time independently of each other. Start Time Context The only choice in this list is the Parent Start Time, which is the start time of the parent template. If this is the root Time Template then the Parent Start Time is the start time entered by the user running the report in the RtReports Generator. Offset 32

37 Data Template Edit Select this button to enter an offset to the reference date and time. Fixed Time Select this button to enter a specific start time for the report template. End Time Context The only choice in this list is the Parent End Time, which is the end time of the Parent template. Offset Select this button to enter an offset to the reference date and time. Fixed Time Select this button to enter a specific end time for the Report Template. Interval Number/Interval Iterator Select the number of time intervals between data samples. For example, a Time Report Template has a duration of 8 hours. The start time is June 14, :00 pm and the end time is June 14, :00 pm. If the interval number is 2 and the interval iterator is hours there would be sixteen samples, two (interval number) for each hour (interval iterator). Time - Fixed Duration You can specify a fixed duration as an offset from a reference time or as a fixed time. Click the Time tab. On the Time tab, select Fixed Duration to allow the Report Template to determine the end time as a duration after the start time. RtReports Template Reference 33

38 Data Template Reference Available Reference Choose the reference for the start time of the template. The choices are Parent Start Time and Parent End Time. If this is the time template at the root of the Data Template, then this is the start or end time of the time entered by the user generating the report in the RtReports Generator. You can add an offset to the reference in the Reference Modifier. Offset Select this button to enter an offset to the reference date and time. Fixed Time Select this button to enter a specific start time for the report template. Duration 34

39 Data Template Edit Enter the total duration of the time context. This duration is added to the start time to define the end time of the time context. Interval Number/Interval Iterator Select the number of time intervals between data samples. Module Template Edit Use the Module Template Edit dialog to define the data context for a Time or Case Report Template. This window defines the location of a PI Module in the PI Module Database. From this module you are able to retrieve PI Aliases or PI Properties, which in turn point to data for the report template. Select a Time or Element Template object in the Data Template Tree where you would like to insert a Module Template. Right-click and select Insert > Module Template. RtReports Template Reference 35

40 Data Template Reference Name The path name of the PI Module in the form. The following path formats are accepted: Module Path Example Data Journal objects returned Absolute module path \\ServerName\ModuleName Returns a ModuleJournal object for that module. Relative module path \Module1\Module2 A relative path defined in a Module Template relies upon a parent Module Template for resolution. If a parent Module Template object is defined with the absolute module path of \\ServerName\ModuleName, and a child Module Template is defined with the relative module path \Module1\Module2, the returned ModuleJournal will resolve to \\ServerName\ModuleName\Module1 \Module2 Multi-character wildcard search (*) Report parameter substitution (square brackets) Display Name \\ServerName\Line*\Drier*\* \OSI Plant\[ModulePathName] The display name for the unit template that appears in the Data Journal. Description The description for the template that appears in the Data Journal. Returns a collection of Module Journal objects, one for each drier within each line. At runtime, RtReports will substitute the parameter value for report parameter ModulePathName into the module path. If the value of ModulePathName is defined as PHL, RtReports will return a ModuleJournal object resolving to \OSI Plant\PHL. 36

41 Data Template Edit Case Report Context Case reports define a report template context as Analysis Framework cases and elements. A Case Template (page 37) defines the time context of the report. Element Templates (page 38) define the data context of the report. Case Template Edit For case report templates, the node directly under the Data Template Root node is a Case Template node. To configure this object, right-click and select Property. The Case Template Edit window is where you define the time context of a case context Report Template. Name The name of the Analysis Framework case to include in the Report Template. Display Name RtReports Template Reference 37

42 Data Template Reference The display name for the unit template that appears in the Data Journal. Description The description for the template that appears in the Data Journal. Element Template Edit The Element Template Edit window is where you define the data context of a Case Report Template, or provide AF Element data context within a Batch or Time Report Template. 1. Right-click the node of the Data Template tree under which you wish to insert an Element Template. This can be a Case or Element Template in a case report template, a Time or Module Template in a time report template, or a Batch, Unit, or SubBatch Template in a batch report template. 2. Select Insert > Element Template.The Data Element Template Edit dialog appears. Name Name of the element to match. This can be a full name, or a wild card search that will result in a number of ElementJournal objects in the Data Journal. For example, you can enter MilkTank1 to return just the one AF element, or Milk* to create an ElementJournal object for each element that starts with Milk. You can also click the magnifying glass to open the Select Element window to select an element from a list. 38

43 Report Parameters Display Name The display name for the unit template that appears in the Data Journal. Type The type of AF element to match in the Analysis Framework database. Available values are Boundary, Flow, Measurement, Node, Transfer, Other, Any, and None. The default value is Any. Category The AF category of the element. The category can be a wildcard search. For example, if you define the name of a category Tut*, then the Generator retrieves all categories that start with Tut. Description The description for the template that appears in the Data Journal. Report Parameters Report parameters allow you to build reports with placeholders for data that are populated at report generation time. Parameters can be used in creating Journal Actions, Module and Element Templates. They are inserted into a Data Template or a report template in the Editor. RtReports Template Reference 39

44 Data Template Reference Configure report parameters to provide for more efficient report building and easier report viewing. A default parameter value is assigned when a report parameter is created. At report generation time, you have the opportunity to change the default value to something else that allows them to access the data they need. If you do not specify a report parameter when the report is generated, then the default value is used. In addition, you can create report parameters that allow a report viewer to choose a value from a list of defined parameter values. After viewing a report, you may choose to change one or more report parameter values and regenerate the report. Add Report Parameters to a Report Template In the Editor, you can configure report parameters for a report template by selecting Tools >Report Parameters, or by right-clicking the root node of the Data Template Tree and selecting the Parameters tab. The Report Parameter Edit window opens so that parameters can be added, removed, or modified. The current data template s existing report parameters are listed in the Parameters list on the left. Selecting a list item displays the parameter details on the right. The parameters are listed in the order they are added. A new parameter is added by clicking the + (add) button. Click the X (delete) button to remove the selected parameter. Parameters can be moved up and down in the list by clicking the arrow buttons. This order dictates the order in which the parameters are displayed in the RtReports Generator. Click the + button to add a report parameter. You can assign it a name in the Parameter Name list. This is the text displayed in the Parameters list. The name can be any length. Since all characters in the parameter name are encoded for the URL string, they can contain any 40

45 Report Parameters characters. However, due to constraints concerning the length of URL strings in Internet Explorer (the maximum length of a URL is 2,083 characters), it is suggested that parameter names use only alphanumeric characters, to minimize the length of the URL string. Prompt The text used to indicate to the user what to enter for the parameter. The prompt is displayed next to the report parameter name on the Report Viewer parameter interface. This text can provide additional information to the person generating a report. The prompt can be any length, but for viewing purposes in the Report Viewer, it might be useful to limit the length of the string to less than 50 characters. Since all characters in the parameter name are encoded for the URL string, the prompt can contain any characters. Accessibility This drop-down list has three values that determine how the parameter is resolved: Generator and URL string (Fully accessible), URL string only (not available in the UI) and Hidden (not shown in the UI or in the URL string) The Values group makes different options available based on the selection in this field. For URL-only and hidden accessible parameters (internal and hidden), the options are the same. The Values group determines the behavior of the parameter. For parameters that are not fully accessible, a multiple value list option is not offered, default values can be set and a validation type is selected. Data Type One of String, Numeric or List. Determines how the parameter value is validated. While all parameter values are stored as string values, users can specify a particular type that will cause RtReports Template Reference 41

46 Data Template Reference the report to error if a parameter value that is not of the specified type is entered, before the report is generated. If the List type is selected, a list of values for that parameter can be defined by clicking the ellipsis button. This will create a set of selectable values that will be selectable in the Report Viewer. Default Value Determines the value used to resolve the parameter if the user does not change it during report generation. For String and Numeric type parameters, clicking on the magnifying glass icon to the right of the Value box allows the user to search for various string values via a context menu: Click on any item of the context menu to launch the appropriate search dialog. For List type parameters, the list of values associated with this parameter are listed in a dropdown box. 42

47 Report Parameters Clicking the ellipsis button next to the drop-down allows the list of values to be edited in the Parameter List Builder dialog box: RtReports Template Reference 43

48 Data Template Reference List values are added by clicking the Add (+) button. Clicking the Delete () button removes the selected parameter. Parameters can be moved up and down in the list by clicking the arrow buttons. Parameter values can be searched for by clicking the magnifying glass icon in the top right corner, displaying the context menu for valid search types, as in the main Report Parameter dialog. When a value is selected in the search dialog, a new parameter value is created in the list with the selected value. Modify existing list values by double-clicking the row and editing the value. List Data Type List values can be restricted to certain types. Available types are String and Numeric. If a type is selected, values entered into the Parameter List Builder dialog box are validated against this type upon exiting. Additionally, attempts to insert a parameter value that is not of the assigned type via URL results in an error when report generation is attempted. Once all list values are added, click OK to return to the Report Parameter definition dialog box. Allow blank value This check box allows users to leave the parameter value blank. If a blank value is allowed for a parameter, supplying a blank value at runtime will substitute in a blank value in for that parameter indicator. If Allow blank value is not checked, any attempt to use a blank value for a report parameter will result in a report generation error. For report parameters of type Numeric, the Allow blank value check box is disabled. Numeric parameters require that a value be supplied at the time of generation, otherwise the report generation will fail. Click OK to accept all changes to all report parameters that were modified. Click Cancel to discard all changes (including those to list parameter value definitions) that were made. Test Report Parameters Users can test the report parameters defined in their report template in the Editor by clicking View >Test Report. If the report template has report parameters defined, a panel named Parameters is added to the bottom of the Test Batch Report, Test Time Report, or Test Case Report window, depending on the report template type. The Parameters pane is the same in all three windows. 44

49 Report Parameters The report parameters are shown with the Prompt value as the label and either an edit box (for non-list parameters) or a drop-down list (for List type parameters). This is the same format as will be seen when generating this report in the RtReports Generator. The parameters are shown in the same order as they are defined in the report template. To test the report, enter or select the appropriate values for the report parameters in the report template, and click OK to run the report. The Report pane in the Editor will display the report with the requested runtime parameter values. In addition, you can copy a sample URL string associated with the currently open report template to the clipboard by clicking the Tools > Copy Test URL to Clipboard. The URL contains the full list of report parameters associated with the report template and their default values, as would be seen in the RtReports Generator when generating this report against a given context. This information is useful when testing PI Notifications links. RtReports Template Reference 45

50

51 Chapter 4 Data Toolbox The Data Toolbox is a window that provides access to data template objects and predefined objects that have been created and stored centrally on the PI Server. The Data Toolbox contains three tabs, the Data Objects (page 47) tab, Predefined (page 47) tab, and the Scratch Pad (page 49) tab. Objects Tab The Objects tab provides access to data objects that can be dragged and dropped into the Data Template tree. Drag and drop to insert objects into a corresponding data template node. This action then displays the object for editing. The data objects in the toolbox are viewable in small and large icon format. Right click the object area and select Large Icon or Small Icon from the context menu to change this setting. Predefined Tab The Predefined tab provides read and write access to data template items that have been shipped with the system or created by users of the system, called predefined actions. The primary use of a predefined action is to create re-usable logic. Predefined actions are stored in the PI Module Database. There are two types of predefined actions: System and Custom. System actions have been shipped with the system and cannot be deleted or modified. Custom types are created by users of the system and can be deleted any time by selecting the Delete option from the context menu. The user can import or export predefined actions using the Export/Import context menu option. Predefined actions can be viewed in Detail and Icon format. Right click the view area and select Detail or Icon from the context menu for the desired display. The detail view displays Name, Version, Description and Type. The Icon view displays only the Icon with its name. You can drag and drop items from the Predefined tab into the appropriate level of the Data Template tree; and similarly, you can drag and drop items from the Data Template tree to create new predefined actions to be stored in the PI Server. For example, the PI Alias Limit Check predefined action contains journal action logic to monitor an Alias between two limits, an upper and lower limit. As with all journal actions, it will use the start and end times of its parent context element. This logic can be set up using parameters so that once the logic is established, all you must do is assign parameters to their correct value. RtReports Template Reference 47

52 Data Toolbox The following predefined actions are included with RtReports: Predefined Journal Action Name PI Tag Limit Check PI Tag Limit Check with Tag Limits PI Alias Limit Check PI Alias Limit Check with Alias Limits Duration Check Limit Check Description This action monitors a PI Tag data source between numeric limits entered as parameters. Enter a valid PI Tag in the Data source parameter and a valid high and low numeric number in the Value column for the LowLimit and HighLimit parameters. This action monitors a PI Tag data source between PI Tag limits entered as parameters. Enter a valid PI Tag in the Data source parameter and valid PI Tags for the HighLimit and LowLimit parameters. This action monitors a PI Alias data source between numeric limits entered as parameters. Enter a valid PI Alias in the Data source parameter and a valid high and low numeric number in the Value column for the LowLimit and HighLimit parameters. This action monitors a PI Alias data source between PI Alias limits entered as parameters. Enter a valid PI Alias in the Data source parameter and valid PI Aliases for the HighLimit and LowLimit parameters. Checks the duration of period between 2 limits Level limit check. 48

53 Scratch Pad Tab Predefined Journal Action Name PI Tag Limit Check Time to Target Check Description This action monitors a PI Tag data source between numeric limits entered as parameters. Enter a valid PI Tag in the Data source parameter and a valid high and low numeric number in the Value column for the LowLimit and HighLimit Checks the time it takes to reach a specific target value. Scratch Pad Tab The Scratch Pad tab mimics the clipboard functionality of Microsoft Windows. If you wish to use the scratch pad as a temporary storage between two reports, simply drag and item onto the Scratch Pad, open another report, and drag and drop that item into the newly opened report. The Scratch Pad items are cleared out when user logs out of the session. The Scratch Pad items can be viewed in small icon and large icon format. Right click the view area and select Large Icon or Small Icon from the context menu for the desired display. You can use the context menu to delete items from the Scratch Pad. RtReports Template Reference 49

54

55 Chapter 5 Data Journal Reference Data Templates describes the logic for retrieving data from the PI Server. The result of executing the Data Template logic against a particular data context is a tree structure of raw data elements, collectively known as the Data Journal. View the Data Journal When building a report template in the RtReports Editor, the Data Journal (page 51) for that report template is viewable by clicking the Journal tab, after the report has been tested in the Editor by selecting View > Test Report from the menu. For batch reports, the root node of the Data Journal is a BatchJournal node. For time reports, it is a TimeBasedJournal node, and for case reports, it is a CaseJournal node. The contents of the Data Journal are directly relational to the data items defined in the Data Template-as it has been noted, the various Data Template tree objects can be defined to return one or many corresponding Data Journal nodes, which represent the actual data objects RtReports Template Reference 51

56 Data Journal Reference defined for the data context against which the report template was run, as opposed to the abstract definitions in the Data Template. Data Template object Batch Template Unit Template SubBatch Template Time Template Module Template Case Template Element Template Journal Action Data Journal node BatchJournal UnitBatchJournal SubBatchJournal TimeBasedJournal ModuleJournal CaseJournal ElementJournal JournalEvents For instance, a batch report may contain in its Data Template a Batch Template object at the root of the Data Template and a Unit Template object beneath it, which returns all of the units contained within that batch. When this report template is run against a particular batch with four units within it, the corresponding Data Journal will have, at its root, a BatchJournal node, and within that node have four UnitBatchJournal nodes corresponding to each of the five units contained within the PI Batch. Each Data Journal node has its own set of attributes, which can be referenced in the report template by using them in the Format Template definition. 52

57 Navigate the Data Journal from the Data Template Navigate the Data Journal from the Data Template In the RtReports Editor, the Data Template (page 9) and the Data Journal (page 51) are linked. You can view the instances of a Data Template node within the Data Journal by clicking the appropriate element in the Data Template tree. The Data Journal opens to the first corresponding element in the Data Journal associated with that Data Template item. You can also locate instances of Journal Actions in the Data Journal in this manner. Journal Search Window The Journal tree contains a search function. When the Journal tree has focus, pressing Ctrl-F displays the Journal Search window. Use the Journal Search window to search for specific text within the Journal tree. Enter a string in the Find what box representing the Name of the Journal Element you need. To search forward in the tree, click Forward. To search backward, click Reverse. When you are finished using the Journal Search window, click OK. Data Journal Objects BatchJournal The root node of the Data Template for a batch report is the Batch Template. This node contains the information which defines how the Data Journal is formed. The Batch Template maps to a Data Journal node called a BatchJournal. When a Data Template is executed against a PIBatch, the resultant data describing the batch is contained within the BatchJournal element. For example, the PI Batch ID, start time and end time are contained at this level of the Data Journal. RtReports Template Reference 53

58 Data Journal Reference The Batch Template element can contain collections of two other Data Template elements-- Unit Templates and Journal Actions. When the Data Template is executed, the resultant information for these elements is contained within two collections in the Data Journal attached to the BatchJournal element: UnitBatchJournals (page 54) and JournalEvents (page 57). Therefore, for each Journal Action defined for the Batch Template, a corresponding JournalEvent is created within the Data Journal within the JournalEvents collection. For each UnitBatchTemplate defined for the BatchTemplate, a corresponding UnitBatchJournal is created within the DataJournal within the UnitBatchJournals collection. UnitBatchJournal The Unit Template (page 16) element in the Data Template (page 9) defines the mapping rules to include certain PIUnitBatch objects in the Data Journal. When the Data Template is executed, the resultant information (the successfully mapped unit batches) is contained within UnitBatchJournal elements in the Data Journal. Each successfully mapped unit batch is represented by one UnitBatchJournal element within the Data Journal. The UnitBatchJournal element contains properties such as unit name, start time and end time. The Unit Template element in the Data Template can contain collections of two other Data Template elements-subbatch Templates and JournalActions. When the Data Template is executed, the resultant information for these elements is contained within two collections in the UnitBatchJournal-SubBatchJournal and JournalEvents. 54

59 Data Journal Objects Therefore, for each SubBatch returned from the SubBatch Template definition beneath the Unit Template, a corresponding SubBatchJournal is created in the Data Journal in the SubBatchJournals collection for that UnitBatchJournal. Similarly, for each Journal Action defined for the Unit Template, a corresponding JournalEvent is created in the Data Journal within that UnitBatchJournal. SubBatchJournal A SubBatchTemplate in the Data Template (page 9) defines the mapping rules to include certain PISubBatch objects in the Data Journal. When the Data Template is executed, the resultant information is contained within SubBatchJournal elements in the Data Journal, one for each PISubBatch returned by the SubBatch Template's definition. The SubBatchJournal element contains properties such as SubBatchName, StartTime, EndTime, etc. A SubBatch Template element in the Data Template can contain two collections of other Data Template elements--journal Actions and child SubBatch Templates. These collections are the same as the collections associated with the Unit Template element. They affect and correspond to a different level of hierarchy contained within your process and PI Batch Database. RtReports Template Reference 55

60 Data Journal Reference TimeBasedJournal A Time Template in the Data Template (page 9) will map to a TimeBasedJournal in the Data Journal. If the Time Template is the root node of the Data Template, it will map to a TimeBasedRootJournal object, the root node of the Data Journal. The TimeBasedRootJournal is a superset of attributes of a TimeBasedJournal object, containing additional root-level information, such as whether the time range used to generate the report is an official time range. All TimeBasedJournal objects have information such as the start time, end time and duration. The TimeBased element in the Data Template can contain collections of Journal Actions, as well as other Data Template elements, like child Time Templates, Unit Templates, SubBatch Templates, Module Templates, and Element Templates. The contents and sub-levels of the TimeBasedJournal in the Data Journal will depend on the corresponding sub-levels of the Time Template node in the Data Template. ModuleJournal A Module Template node in the Data Template (page 9) will map to a ModuleJournal node in the Data Journal. A ModuleJournal object contains information on which PI Module was matched, and what start and end Time are in effect. As with Unit Templates and SubBatch Templates, if the Module Template returns more than one PI Module based on the data context of the run report template, multiple ModuleJournal nodes may be shown in the Data Journal. 56

61 Data Journal Objects A Module Template in the Data Template can contain collections of Journal Actions, as well as other Data Template elements, like child Module Templates, Time Templates, Unit Templates, SubBatch Templates and Element Templates. The contents and sub-levels of the ModuleJournal in the Data Journal will depend on the corresponding sub-levels of the Module Template node in the Data Template. CaseJournal The root node of the Data Template (page 9) for case reports is the Case Template. This node contains the information which will place information into the Data Journal regarding the Analysis Framework case against which the report template is run. The Case Template maps to a Data Journal node called CaseJournal. When a Data Template is executed against an AF case, the resultant data about the case is contained within the CaseJournal element, such as case name, model, start time and end time. A Case Template node in the Data Template can contain collections of Journal Actions, as well as other Data Template elements, including Element Templates, Time Templates, Unit Templates, SubBatch Templates and Module Templates. The contents and sub-levels of the CaseJournal in the Data Journal will depend on the corresponding sub-levels of the Case Template node in the Data Template. RtReports Template Reference 57

62 Data Journal Reference ElementJournal An Element Template in the Data Template (page 9) will map to one or many ElementJournal nodes in the Data Journal. An ElementJournal has information on which Analysis Framework element was matched, and what start and end time are in effect. The Element element in the Data Template can contain collections of Journal Actions, as well as other Data Template elements, including child Element Templates, Time Templates and Module Templates. The contents and sub-levels of the ElementJournal in the Data Journal will depend on the corresponding sub-levels of the Element Template node in the Data Template. JournalEvents For each BatchJournal, UnitBatchJournal, SubBatchJournal, TimeBasedJournal, ModuleJournal, CaseJournal and ElementJournal node in the Data Journal, a JournalEvents collection is created. When the Data Template (page 9) is executed, a JournalEvent element is created for each Journal Action element in the same relationship context that it was defined in the Data Template. A JournalEvent node in the Data Journal is comprised of three collections: TerminalStates, SequenceEntries and Parameters. The TerminalStates collection organizes events by the state in which they occurred. The SequenceEntries collection organizes events in chronological order. Both the TerminalStates and SequenceEntries collection contain the same information. 58

63 Data Journal Objects When a Journal Action is executed, there are three main results. The first is what Action States were reached during execution. Once an Action State has been reached, this initiates a JournalEntry element within the Data Journal. This JournalEntry is created in two places within in the Data Journal--it is created in the JournalEntries collection of the TerminalState that represents it, and also in the SequenceEntries collection in chronological order: For each occurrence of a state, a JournalEvent\TerminalStates\JournalEntries\JournalEntry and a JournalEvent\SequenceEntries\JournalEntry are created. When a change of state occurs, all Action State Result Definitions are executed and for each one, a corresponding Result element in the Journal is created and attached to the Results collection of the JournalEntry object. Again, these Result elements are duplicated in both the TerminalStates and SequenceEntries collections: After processing all the Action States, the Action Result Definitions are executed and for each one, a corresponding Result element in the Data Journal is created. These Results are included in a JournalEntry which is created in the TerminalStates and SequenceEntries collection with the name specified in the Data Template. RtReports Template Reference 59

64

65 Chapter 6 Journal Action Edit In addition to the data provided by the base Data Template objects, you may wish to display additional data, based on the time ranges established by the various data elements already defined in your report template (such as a PI Batch, PI Unit Batch or Time Template). In RtReports, these additional data items are called journal actions. The Journal Action Edit window is where you define criteria that the report template uses to select the time series data for a report. Create Journal Actions Journal Actions can be inserted under any Data Template object. There are three ways to open the Journal Action Edit (page 61) window: Select a context element in the Data Template tree and select Insert > Journal Action from the main Editor menu. Select a context element in the Data Template tree, right click and select Insert > Journal Action. Drag a Journal Action element from the Data Toolbox to a context element in the Data Template tree. The Journal Action Edit window has a left panel for Action Parameters (page 62) and a right panel with three tabs: Action Options (page 66), Action States (page 68), and Action Results (page 70). RtReports Template Reference 61

66 Journal Action Edit Action Parameters Action Parameters are variables or place holders that launch search controls for finding data within their native data stores, like PI Tags or PI Properties. Action parameters are visible from, regardless of the tab selection in the right pane of the Journal Action Edit (page 61) window. 1. Click the green Add button (+) to add a row to the Action Parameter list. 2. Double click the Name field in the row to edit it. 3. Enter a name for the action parameter. 4. Double click the Type field and select the type of parameter from the list. Depending on your selection, a corresponding select or search window appears. Literal (page 63) PITag (page 63) PIProperty (page 63) PIAlias (page 65) PIAttribute (page 65) 62

67 Action Parameters Literal A static number or string value. Selecting Literal will not open a search window. Enter a static number or string in the Value field and Yes in the Dynamic field. Literal parameters always have a Dynamic value of Yes, meaning the string entered in the Value field is used as the placeholder for this action parameter. PITag A PI Tag name. Selecting this type opens the PI Tag Search window. Select a PI Tag, then click OK to put the PI Tag in the Value field. Refer to the PI SDK online help for more information on using this window. PI Tag action parameters can have a Dynamic value of Yes or No. If Dynamic is set to Yes, then the PI tag name specified in the Value field is used for the placeholder substitution. If Dynamic is set to No, then the corresponding value for the PI tag specified in the Value field at the start time is used as the placeholder for executed action states and result definitons. PIProperty A property value of a module in the PI Module Database. This can be an absolute PIProperty that maps to a dedicated path within the Module Database, or a unit relative PIProperty that changes path relative to the current Module Template context. Selecting this type will open the PI Property picker window. RtReports Template Reference 63

68 Journal Action Edit Select a PI Property and whether the action parameter value should be an Absolute Path or a Relative Path. If Absolute Path is selected, the value will be a fully qualified path to the PI Property, in the format: \Module\Submodule\Submodule PropertyName SubPropertyName In this example, the absolute path is: \OSIsoft Chemicals\North America\Pennsylvania\Philadelphia\Factory 1\T401 HighLimit If Relative Path is selected, the value will be the property name, to be resolved relative to the parent context where the journal action resides. PI Property type always has a Dynamic value of No, meaning the property value is always resolved before being used by executed action states and result definitions. 64

69 Action Parameters PIAlias This can be an absolute alias that maps to a dedicated path within the PI Module Database or a unit relative alias that changes path relative to the current Unit Template context. Selecting this type will open the PI Alias Search window. Search for the alias and click OK to place the PIAlias in the Value field. Refer to the PI SDK online help for more information on using this window. PI Alias action parameters can have a Dynamic value of Yes or No. If Dynamic is set to Yes, then the PI alias name specified in the Value field is used for the placeholder substitution. If Dynamic is set to No, then the corresponding value for the PI alias specified in the Value field at the start time is used as the placeholder for executed action states and result definitons. PIAttribute An attribute of an element in an Analysis Framework database. This can be an absolute PIAttribute that maps to a dedicated path within the AF Database, or a context relative PIAttribute that changes path relative to the current Element Template context. Selecting this type will open the PI Attribute picker window. Select an AF Element, then select one or more Attributes in the bottom pane. Selecting multiple attributes will create multiple action parameters, one for each attribute. Then select whether the action parameter value should be an Absolute Path or a Relative Path. If Absolute Path is selected, the value will be a fully qualified path to the PI Attribute, in the format: RtReports Template Reference 65

70 Journal Action Edit DatabaseName\Element\SubElement\..\Attribute If Relative Path is selected, the value will be the property name, to be resolved relative to the parent context where the journal action resides. PI Attribute action parameters can have a Dynamic value of Yes or No. If Dynamic is set to Yes, then the PI attribute name or path specified in the Value field is used for the placeholder substitution. If Dynamic is set to No, then the corresponding value for the PI Attribute specified in the Value field at the start time is used as the placeholder for executed action states and result definitons. Modify an Action Parameter Manual 1. Click a cell in the list. 2. Change the value. Wizard 1. Select the parameter. 2. Click the magnifying glass button. This opens the search or select window for the type. 3. Select the new value. The wizard puts makes the change in the action parameters list. Move an Action Parameter To move an action parameter, select the row and use the up and down arrows to rearrange the order of the parameter list. Delete an Action Parameter To delete an action parameter, select the row and click the Remove button (X). Action Options Action Options apply to the entire Journal Action (page 9). 66

71 Action Options Interval The Interval defines the logic for retrieving the interval timestamps for the transition equations. There are three possible values: -1: Uses the recorded value call of the PI SDK to execute the transition equations. The equations execute at specific times that have data in the PI Archive. [Integer Value]: Defines the time interval, in seconds, between the executions of the transition equations from the period start time to the end time. [Tag Name]: The name of the PI tag that defines the time interval between the executions of the transition equations. This tag does not have to be included in the transition equations defined for individual states. Monitoring Expression The PI PE Expression that determines which time intervals to include. This expression is evaluated at intervals defined in Interval. Start Percent of Time Select this box to interpret the value entered in the Suppress From Start field as a percent. Suppress From Start Integer value indicating the amount of time to suppress the action logic from the start of the period. This value is in seconds, unless you select the Start Percent of Time check box. End Percent of Time Select this box to interpret the value entered in the Suppress From End field as a percent. RtReports Template Reference 67

72 Journal Action Edit Suppress From End Integer value for the amount of time to suppress the the action logic from the end of the period. This value is in seconds, unless you select the End Percent of Time check box. Start Time Offset The amount of time applied to the start time to determine the actual start time. The offset is signed (+ or -) and entered in seconds. End Time Offset The amount of time applied to the end time to determine the actual end time. The offset is signed (+ or -) and entered in seconds. Sample at Start Select this box to sample at the start of the time period. Sample at End Select this box to sample at the end of the time period. Output Type Select Optional to have the report log a message to the PI Server and continue executing if there is a problem with this journal action. Select Required to have the report log a message and stop executing if there is any error with this journal action. Action States The context element defines the time range for a Journal Action (page 9). Action states are the individual stages run within a context element. Each action state has a transition equation that is run when it is in that state. The transition equation returns the next state number. The time intervals for execution of these equations are defined by the Interval on the Action Options tab. At each state transition, the result definitions for that state are generated. 68

73 Action States 1. Click the Add button (+) to add a row in the Action States list. 2. Double-click the State Name column of the new row and enter the name of the new state. 3. Although you can make any state the default state, for readability it is better to make the first state the default state. Select the Default State check box to make the state the default state. This means that the journal action will evaluate this state's transition equation first. 4. You can make this state visible to the Result Set or hide it. To hide the state from the Journal, make sure the Hidden check box is selected. 5. Enter the PI Performance equation that will define your Transition Equation. Following are some suggestions and examples of transition equations: Transition Equations must be in the form of: IF {expression1} Then {statenumber1} Else If {expression2} Then {statenumber2} Else {statenumber3} Transition Equations follow the basic syntax of PI Performance Equations. For a general reference on Performance Equation Syntax, see the Performance Equation chapter in the PI Server documentation. 6. Create result definitions associated with each state by selecting the Action State row and clicking the Add button (+) in the Result Definitions section. See the Action Results (page 70) for information on how to configure result definitions. RtReports Template Reference 69

74 Journal Action Edit Move Action States You can rearrange the action states by editing the Index numbers. Editing these values affect the transition equations that reference the index. Delete Action States To delete an action state, select the row and click the Remove button (X). Action Results After you have defined the Action States (page 68), you need to define Result Definitions (page 72), either associated with the defined Action States (in the Result Definitions section of the Action States tab) or associated with the entire journal action (in the Action Results tab). Result Definitions are the defined data sets returned based on a state or action being triggered. 1. Click the Add button (+) above the Result Definitions list. This creates a new row in the list. 2. Double click the Name field in the row and enter a name for the result definition. 3. Double click the Type field to select a type. The available types of Result Definitions are as follows. 70

75 Action Results Type Simple Trend Compressed Values Exact Time Value Summary Value Profile PI Batch Property Interpolated Values Calculation Time Value Calculation Recorded Values Summaries Value Expression Summaries EVT Interface Event Tag RtBaseline Services Dataset RtBaseline Services Analysis Framework Dataset Description Data specifications for passing string values and resolving aliases Defines the data specifications to populate a trend over a time range for a data source(s) Defines the data specification to retrieve recorded values over a time range for a data source(s) Data specifications to retrieve the value at a timestamp for a data source(s) Data specifications to retrieve summary values (minimum, maximum, mean, average, total, etc.) for a data source(s) Data specification to retrieve Start, End, Minimum, and Maximum over a time range for a data source(s) Data specifications to retrieve PI Batch Property values populated by the EVT Interface Data specifications to retrieve the evenly spaced values over a time range for a data source(s) Data specifications to execute a PI Performance equation at a timestamp Data specifications to execute a PI Performance equation at a certain time. Data specifications to retrieve multiple summary calculations Data specifications to retrieve multiple expression summary calculations Data specifications to retrieve data from string pool tags populated by the EVT Interface Data specification to retrieve data from RtBaseline dataset. Data specification to retrieve data from RtBaseline Analysis Framework dataset. This puts the Type in the Result Definition list. 4. If Time parameters exist for the type that you chose, enter them. Use the following information to guide you: Context Start - the Result Definition start time uses the start time of the parent context element of the Journal Action. Context End - the Result Definition end time uses the end time of the parent context element of the Journal Action. State Start - the Result Definition start time uses the start time of the state for which it is defined. State End - the Result Definition end time uses the end time of the state for which it is defined. Offset - allows you to offset the time used. The time format for the offset is PI Time short notation. For example, -1s for minus 1 second, +2m for plus 2 minutes, etc. RtReports Template Reference 71

76 Journal Action Edit 5. If Data Parameters exist for the type that you chose, enter them. To use an Action Parameter (page 62) as a value of a Data parameter, simply drag and drop the Action Parameter into the Data Parameter field. 6. Repeat steps 1-5 for all Result Definitions that you want defined. Move Action State Result Definitions To move an action state result definition, click a cell in the list and use the up and down arrow buttons to re-arrange the result definitions. Delete Action State Result Definitions To delete an action state result definition, select the row and click the Remove button (X). Result Definition Result Definitions define specific logic for retrieval of data using defined time contexts based on Data Journal objects and State transition times. RtReports supports the following Result Definitions and settings for the properties grid. Each Result Definition has time parameters and data parameters. Simple Result Definition The Simple result definition allows you to return static or PI Tag data to the report. Data Parameters: 72

77 Result Definition Literal Select this option to use the Value field as a literal string. PE Select this option to use the Value field as a PI Performance Equation expression. PI Tag Select this option to use the Value field as the value of a particular PI Tag. Value The value of the result. You can drag a dynamic parameter to this field or click the magnifying glass button to search (if Literal is not selected). Trend Result Definition The Trend result definition creates the data configuration to include a trend on the final report: Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. RtReports Template Reference 73

78 Journal Action Edit Data Source - The PI Tag/Alias for which to retrieve trend values. Global Tab The Global properties tab for the Global element allows you to turn display elements on or off for the entire trend. Visible elements Legend: If checked, the trend will display the legend element. Scroll bar: If checked, the trend will display a scroll bar on the horizontal axis. Gridlines: If checked, the trend will display gridlines on the trend area. If unchecked, no gridlines will be displayed. If you wish to have some gridlines turned on (e.g., horizontal major) and not others (e.g., horizontal minor), the check box can display a third state (a checkmark with a grayed background). Markers: If checked, the trend will display markers on all traces. If unchecked, the trend will not display any markers. If you wish to have markers turned on for some traces and not others, the check box displays a third state (a checkmark with a grayed background). Trend title Text: The text used for the trend title. Visible: Check this box to display the trend title. Legends Tab The legend requires sufficient space to be displayed; otherwise, elements may be missing from the trend presentation. 74

79 Result Definition Legend Elements Tag name: Turns the display of the tag name on or off for each trace in the legend. Description: Turns the display of the tag description on or off for each trace in the legend. Last value: Turns the display of the tag value on or off for each trace in the legend. Engineering units: Turns the display of the tag engineering units on or off for each trace in the legend. Markers: Turns the display of the trace marker on or off for each trace in the legend. Horizontal Scale Tab The Horizontal Scale options determine where the X-axis of the trend appears as well as how the time scale appears on the axis. RtReports Template Reference 75

80 Journal Action Edit Configuration Tracking mode - Specifies how traces with different start times and end times appear. The options are: Use first trace - The first trace's start and end time determines the trend start and end time. Other traces will only show that portion of their data that falls between the first trace's start and end time. This option is useful for traces with disparate start times, end times and durations. Align start times - The first trace's start time determines the trend start time. The end time of the trend is calculated as the start time plus the duration of the longest trace. Furthermore, the start of each trace is made to line up with the beginning of the plot. Note that the trace start times are not actually changed. Instead an offset is applied so that the traces can be visually compared. This behavior is similar to the Batch Trend. Show all times - The start and end times are determined by inspecting the start and end times of all of the traces. The start time of the trend corresponds to the earliest trace start time. The end time of the trend corresponds to the latest trace end time. Thus, all trace data is shown on the Trend. End times of * are aligned. This option is useful to show the full range of traces with disparate start times, end times and durations. Align end times - The first trace's end time determines the trend end time. The start time of the trend is calculated as the end time minus the duration of the longest trace. Furthermore, the end of each trace is made to line up with the right side of the plot. This option is the "factory default" setting. Note that the trace end times are not actually changed. Instead an offset is applied so that the traces with disparate start times and durations can be visually compared. Labels - Specifies the format of the scale labels. Options include Full time, Partial time, and Relative time. Units - Specifies the maximum time units for the scale labels. Options include Auto, Years, Days, Hours, Minutes, and Seconds. Vertical Scale Tab The Vertical Scale options determine how the scale for the Y-axis of your trend is configured. You can configure either a single scale or separate scales for each trace. 76

81 Result Definition General Single scale: When selected, a single scale is configured for the trend. Multiple scales: When selected, multiple scales are configured for the trend. Scale Format: Determines the number format of the scale. Position: Determines the position of the scale relative to the Y-axis. Min: Controls how the minimum number of the scale is calculated. Max: Determines how the maximum number of the scale is calculated. Visible: Turns the display of the scale title on or off. Compressed Values Result Definition The Compressed Values result definition retrieves the recorded values for single or multiple tags, based on the time context settings for each data source definition. RtReports Template Reference 77

82 Journal Action Edit Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters DataSource - The PI Tag/Alias to retrieve the desired Compressed Values. FilterContext - A valid PIPE expression to filter returned Compressed Values. Filter - A valid PIPE Expression to filter returned compressed values. Annotations Select Yes to return PI tag annotation data to the Data Journal. Select No to not return this data. 78

83 Result Definition Exact Time Value Result Definition The Exact Time Value result definition retrieves the interpolated value of a PI tag at a specified timestamp context. Timestamp Context The time context to use for the timestamp. The possible values are: ContextStart - Use the start time of the Data Journal object for the timestamp. StateStart - Use the start time of the current state for the timestamp. ContextEnd - Use the end time of the Journal object for the timestamp. StateEnd - Use the end time of the current state for the end time. OffSet - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. Data Parameters DataSource - The PI Tag/Alias for which to retrieve the Exact Value.DataSource - The PI Tag/Alias for which to retrieve the Exact Value. Annotations Select Yes to return PI Tag annotation data to the Data Journal. Select No to not return this data. Summary Value Result Definition The Summary Value result definition retrieves summary values for a PI Tag. The supported summary values are Minimum, Maximum, Total, Average, Standard Deviation, Range and Mean. RtReports Template Reference 79

84 Journal Action Edit Start Time Context - The time context to use for the start time. The possible values are: ContextStart - use the start time of the Journal object for the start time StateStart - use the start time of the current sate for the start time OffSet Time offset from the Start Time Context. Must be in the form of PI Short time, +/-10s. End Time Context - The time context to use for the end time The possible values are: Context End - use the end time of the Journal object for the end time State End - use the end time of the current state for the end time. OffSet -- Time offset from the EndTime. Should be in the form of PI Short time, +/- 10s. Data Parameters DataSource - The PI Tag/Alias for which to retrieve Summary Values 80

85 Result Definition Display Digits - Not implemented. Specify numeric formatting using the data object and the NumericFormat property. See Numeric Format Strings in the Format Template Reference. Conversion Factor - If the engineering units for a tag do not match default time units for the PI Server, the resulting value must be properly adjusted using this conversion factor. Finally, select Yes for each of the following values to return it to the Data Journal: Maximum - Maximum value for time range. Minimum - Minimum value for time range. Average - Average value over the time range. Total - Total value over time range. Interval - Long integer specifying the number of summary calculation intervals. Range - Range of values over the time range. Standard Deviation - Standard deviation over the time range. Mean - Discrete average over the time range. Event Weighted Selecting Yes produces an event-weighted result. Selecting No produces a time-weighted result. Profile Result Definition The Profile result definition retrieves the Start Value, End Value, Maximum Value, and Minimum Value of single or multiple tags between the Context Start and Context End. Time Parameters Start Time RtReports Template Reference 81

86 Journal Action Edit Context - The time context to use for the start time. The possible values are: Context Start - Use the start time of the Data Journal object for the start time. State Start - Use the start time of the current sate for the start time. Offset - Time offset from the Start Time Context. Must be in the form of PI Short time, such as +/-10s. End Time Context - The time context to use for the end time. The possible values are: Context End - Use the end time of the Data Journal object for the end time. State End - Use the end time of the current state for the end time. Offset - Time offset from the End Time. Must be in the form of PI Short time, such as +/- 10s. Data Parameters DataSource - The PI Tag/Alias to retrieve Profile Values. Display Digits - Not implemented. Specify numeric formatting using the data object and the NumericFormat property. See Numeric Format Strings in the Format Template Reference. Finally, select Yes for each of the following values to return it to the Data Journal: Start - The value at the start of the time range. End - The value at the end of the time range. Maximum - Maximum for time range. Minimum - Minimum for time range. PI Batch Property Result Definition The PI Batch Property result definition allows you to retrieve PI Batch Properties from a PI Batch object populated by the Event File Interface. The Event File Interface processes EVT files produced by certain batch execution engines. These systems output an EVT file, which is a log file of all events that happened during the manufacturing process. The Event File Interface processes this file and creates a nested set of PI Properties associated with the PI Batch object within the PI Batch database. The key columns within the EVT files are the Event Type, Description and Value columns. The PI Batch Property Result Definition allows you to extract information from these PI Batch properties based on settings that relate to these columns. 82

87 Result Definition Data Parameters Description - The description column matches the name of the description you wish to retrieve. This can be the exact description name or a wildcard character (*). Event - The event column matches the name of the event that you wish to retrieve. This must be the exact event type that you want to retrieve. Value Filter - Use this column to place a filter on the Value column. This can be the exact string match or a wildcard character (*). Type 0 - Uses only the Event field 1 - Uses the combination of Event and Description 2 - Uses the Value Filter Interpolated Values Result Definition The Interpolated Values result definition retrieves a series of interpolated values for single or multiple tags. These values are based on the time context settings for each data source definition and an interval setting. RtReports Template Reference 83

88 Journal Action Edit Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters DataSource - The PI Tag/Alias for which to retrieve interpolated values. Interval - A string, in PI short time format, representing the sampling interval. For example, 1s, 1m, or 1h. Filter - A valid PIPE Expression to filter returned interpolated values. Calculation Time Value Result Definition The Calculation Time Value allows you to run a PI Performance Equation at a specified timestamp. 84

89 Result Definition Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters Calculation String - A valid calculation expression. Display Digits - Not implemented. Specify numeric formatting using the data object and the Numeric Format property. See Numeric Format Strings (page 152) in the Format Template Reference. Interval - A string, in PI short time format, representing the sampling interval. For example, 1s, 1m, or 1h. The default is 10m. Synchronize Time - The time for which to evaluate the Interval in the form of HH:MM, where HH is the hour in 24 hour military time and MM is minutes. For example, an Interval set to 10m and Synchronize Time set to 14:00 gets the Min, Max, and Average for a PI Tag in 10-minute increments starting from 2:00pm. Snap Shot - Select Yes to return values for the last time period closest to the end time used RtReports Template Reference 85

90 Journal Action Edit Calculation Recorded Value Result Definition The Calculation Recorded Value result definition runs a PI Performance Equation between the Context Start and Context End. Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters Calculation String - A valid calculation expression. Display Digits - Not implemented. Specify numeric formatting using the data object and the Numeric Format property. See Numeric Format Strings (page 154) in the Format Template Reference. 86

91 Result Definition Summaries Value Result Definition The Summaries result definition implements the Summaries method in the PI SDK. It computes multiple summary calculations over a time period specified in an interval. It is similar to the Summary Value result definition (page 79). Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. RtReports Template Reference 87

92 Journal Action Edit Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters DataSource - The PI Tag/Alias for which to compute summary calculations. Interval - long integer specifying the number of summary calculation intervals. Display Digits - Not implemented. Specify numeric formatting using the data object and the NumericFormat property. See Numeric Format Strings (page 154) in the Format Template Reference. Conversion Factor - If the engineering units for a tag do not match default time units for the PI Server, the resulting value must be properly adjusted using this conversion factor. Synchronize Time - The time for which to evaluate the Interval in the form of HH:MM, where HH is the hour in 24 hour military time and MM is minutes. For example, an Interval set to 10m and Synchronize Time set to 14:00 gets the Min, Max, and Average for a PI Tag in 10-minute increments starting from 2:00pm. Select Yes for each value to return to the journal: Maximum - Maximum value for time range. Minimum - Minimum value for time range. Total - Total value over time range. Average - Average value over the time range. Standard Deviation - Standard deviation over the time range. Range - Range of values over the time range. Percentage Good - Returns the percent good. Snap Shot - Returns summary values for the last time period closest to the end time used. Running Summary - If Yes is selected, then when executed against a running batch, the last incomplete time period will be computed and returned in the Data Journal Event Weighted - Selecting Yes produces an event-weighted result. Selecting No produces a time-weighted result. 88

93 Result Definition Expression Summaries Result Definition The Expression Summaries result definition creates a data stream from an arbitrary expression and calculates one or more summaries on the expression result. This result definition implements the ExpressionSummaries method in the PI SDK. Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. RtReports Template Reference 89

94 Journal Action Edit Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters Calculation String - A valid calculation expression. Interval - long integer specifying the number of summary calculation intervals. Display Digits - Not implemented. Specify numeric formatting using the data object and the NumericFormat property. See Numeric Format Strings in the Format Template Reference. Conversion Factor - If the engineering units for a tag do not match default time units for the PI Server, the resulting value must be properly adjusted using this conversion factor. Synchronize Time - The time for which to evaluate the Interval in the form of HH:MM, where HH is the hour in 24 hour military time and MM is minutes. For example, an Interval set to 10m and Synchronize Time set to 14:00 gets the Min, Max, and Average for a PI Tag in 10-minute increments starting from 2:00pm. Select Yes for each value to return to the journal: Maximum - Maximum value for time range. Minimum - Minimum value for time range. Total - Total value over time range. Average - Average value over the time range. Standard Deviation - Standard deviation over the time range. Range - Range of values over the time range. Percentage Good - Returns the percent good. Snap Shot - Returns summary values for the last time period closest to the end time used. Running Summary - If Yes is selected, then when executed against a running batch, the last incomplete time period will be computed and returned in the Data Journal. Event Weighted - Selecting Yes produces an event-weighted result. Selecting No produces a time-weighted result. EVT Interface Event Tag Result Definition The EVT Interface Event Tag Result Definition retrieves data from a String Pool tag that is populated by the Event File Interface. 90

95 Result Definition The Event File Interface inserts data into these tags in a concatenated format. It creates a union of all columns in the EVT File, concatenated by a pipe. Use the following settings to determine which Events you want retrieve, and which columns you want included in the Data Journal. For example, suppose the configuration of your Event File Interface has the Use Event message logging to String Tag (/logtotag command line) option enabled and Comment enabled (#7). To retrieve comments for a batch processed by the Event File Interface, you would add Event and in the Event Name column, specify Comment, then check all columns and set PValue filter to Error. This would retrieve all comments that have a value starting with Error. Columns This list is a complete list of all columns contained in the EVT File. If you want to include data from that column in the Journal, check the button. To exclude a column, cancel the selection. Following is a list of columns for which you can retrieve the data. RtReports Template Reference 91

96 Journal Action Edit Recipe Description Event Pvalue EU Area ProcCell Unit Phase PhaseDesc UserID UniqueID Events Event Name is the name of the Event for which you want to retrieve data. The following list assumes that you have already configured your Event File Interface to log this event to a tag. Active Binding Active Step Change Active Step Change Commencing Arbitration Batch Deletion Bind Comment Creation Bind Event File Name Formula Header Mode Change Mode Command Operator Prompt Owner Change Param Download Verified Phase Link Permissive Received Phase Link Permissive Sent Phase Logic Arbitration Prompt Prompt Response Recipe Arbitration Recipe Data Recipe Data Changed Recipe Header Recipe Value Recipe Value Change Report Scale Factor State Change State Command Step Activity System Message Filter String You can specify a string for each of the columns to be used in a like comparison to filter data from the Journal. Both the * and % can be used interchangeably for wildcards in a LIKE comparison. A wildcard is allowed at the beginning and end of a pattern, or at the end of a pattern, or at the beginning of a pattern. For example: 92

97 Result Definition *error* - Returns all items that have an error string in the column error* - Returns all items that start with error in the column *error - Returns all items that end with an error string in the column RtBaseline Services Dataset Result Definition The RtBaseline Services Dataset Result Definition creates a data stream from the dataset. When this result type is first selected, the Dataset Selection window opens. Name: Name of database or dataset. Listings in red have no parameters. Note that if the Analysis Framework server is installed then the PIAF entry appears in the list. This allows the selection of AF data structures. Type: Indicates the source of the database or dataset. Description: The description of the database or dataset. Cancel: Closes the window without making any selection and returns to the result definition. OK: Closes the window and enters the selected dataset in the Data Source field on the result definition. RtReports Template Reference 93

98 Journal Action Edit Start Time Context - The time context to use for the start time. The possible values are: ContextStart - use the start time of the Journal object for the start time StateStart - use the start time of the current sate for the start time OffSet - Time offset from the Start Time Context. Must be in the form of PI Short time, +/-10s. End Time Context - The time context to use for the end time. The possible values are: Context End - use the end time of the Journal object for the end time State End - use the end time of the current state for the end time OffSet - Time offset from the EndTime context. Should be in the form of PI Short time, +/- 10s. Data Parameters This group box varies depending upon the parameters needed for the selected dataset. If a placeholder has a default value, it may be seen by displaying a ToolTip for the field. The default value is only available for reference the first time the dataset is selected. RtBaseline Services Dataset Configuration Datasets provide a uniform way of obtaining data from various sources for use with RtReports. Datasets must be defined before users and administrators can construct reports using data obtained through RtBaseline Services. RtBaseline Services supports datasets based on four sources of data. These sources are PI Calculations, relational data stores, web services, and PI tag lists, i.e., lists of alias in the PI module database that resolve to a list of PI tag names. The task of configuring datasets is begins at the RtBaseline Services Administration Page. This page is typically found at where machine_name is the name of the server hosting RtBaseline Services. Please refer to the RtBaseline Services Administration Guide or the online help provided through the RtBaseline Services Administration Pages. RtBaseline Services Analysis Framework Dataset Result Definition The RtBaseline Services Analysis Framework Dataset result definition creates a data stream from AF Attributes values. This result definition requires an AF server. 94

99 Result Definition Start Time Context - The time context to use for the start time of the trend. The possible values are: ContextStart - Use the start time of the Data Journal object for the start time of the trend. StateStart - Use the start time of the current sate for the start time of the trend. Offset - Time offset from the Start Time context. Must be in the form of PI Short time, for example, +/-10s. End Time Context - The time context to use for the end time of the trend. The possible values are: ContextEnd - Use the end time of the Data Journal object for the end time of the trend StateEnd - Use the end time of the current state for the end time of the trend. Offset - Time offset from the EndTime. Must be in the form of PI Short time, for example, +/- 10s. Data Parameters Data Source This read-only field displays PIAF as the selected Data Source. Mode This drop-down list field controls how data is queried using the AF SDK. Selections are ModeSingleton, ModeEvents and ModeRawValues. ModeSingleton calls Attribute.GetValue; ModeEvents and ModeRawValues call Attribute.GetValues. Attr path Sets the path to the attributes. Examples of paths that can be entered include: \\SERVER\DATABASE\ELEMENT1\ELEMENT2\...\ATTRIBUTE RtReports Template Reference 95

100 Journal Action Edit file://\\\server\\database\\element1\\element2\\...\\attribu te \DATABASE\ELEMENT1\SUBELEMENT1\...\ATTRIBUTE SUBELEMENT1\SUBELEMENT2\ATTRIBUTE The second two types of paths are relative and require a context. UOM This drop-down list controls the unit of measure to use. This list is populated by the AFDatabase.UOMs collection. If the user does not have a database to work with, the desired UOM can be typed in. Leaving this field blank uses the default UOM for the attribute. Journal Action Expression Syntax RtReports relies heavily on the PI Performance Equation Subsystem and uses the PI PE syntax. All State Transition Equations and Suppress Monitoring Equations must comply with PI PE syntax. The expression used for the Calculation Time Value must also comply with PI PE syntax. For a complete reference on PI PE syntax, see your PI Server Documentation. RtReports allows you to use Action Parameters within these equations using the {} notation. If you enter a parameter into one of the equations and surround it with {}, before passing the equation to the Performance Equation Subsystem, RtReports will parse the equation and substitute the values of the parameters into the Equation. Once this parsing occurs, the system will must comply strictly with PI PE syntax. As with Action Parameters, RtReports provides a number of predefined variables which can be used in expressions. At run time, the variables are replaced before the performance equation is sent to the PI Server for parsing and evaluation. These variables must be enclosed in square brackets [ ]. Since PI PE syntax has no expression for Aliases, you will must enclose Aliases within square brackets so that RtReports can resolve the alias before passing it the Performance Equation subsystem. The following table lists the valid predefined variables that can be used in Journal Action equations. Predefined Variable Explanation Context [Any Alias} The RtReports execution engine will resolve Absolute and Unit relative aliases before passing the equation for processing. All 96

101 Journal Action Expression Syntax Predefined Variable Explanation Context [periodstart] The time stamp at the start of the period for which the action is defined (unit batch, operation, phase, step). This variable is replaced by the PI time string representing the start of the period. This allows date arithmetic such as tagval('le:f420', periodstart + 60) which would return the value of tag le:f420 one minute after the start of the period. The expression is equivalent to: tagval('le:f420', periodstart + '+1m'). Note the + sign in '+1m'. Computations of time periods from two timestamps are also supported by PI-PE, such as in [periodend] - [periodstart]. All (except Case) [periodend] The timestamp at the end of the period for which the action is defined (unit batch, operation, phase, step). Durations of a period can be calculated: duration = periodend - periodstart Both variables are replaced by PI formatted dates thus giving the duration of the period in seconds. All (except Case) [statestart] Time stamp at the start of the current state. All [stateend] Time stamp at the end of the current state. All [prevstateno] The number of the previous state. All [currstateno] The number of the current state. All '*' The current evaluation time. Note that the usage is the same as in PI DataLink. [unitbatchstart] Time stamp at the start of the current unitbatch. Batch/UnitBatch [unitbatchend] Time stamp at the end of the current unitbatch. Batch/UnitBatch [UnitBatchSeqNr] Occurrence of the current unitbatch. Batch/UnitBatch [UnitName] Unit Name of the current unitbatch. Batch/UnitBatch [SubBatchStart] Time stamp at the start of the current subbatch. Batch/SubBatch RtReports Template Reference 97

102 Journal Action Edit Predefined Variable Explanation Context [SubBatchEnd] Time stamp at the end of the current subbatch. Batch/SubBatch [SubBatchSeqNr] Occurrence of the current subbatch. Batch/SubBatch [SubBatchName] Name of the current subbatch. Batch/SubBatch [SubBatchNameFull] Path to current Subbatch Batch/SubBatch [SubBatchName.N] Subbatch Name at the depth N. Batch/SubBatch [BatchStart] Time stamp at the start of the current batch. Batch [BatchEnd] Time stamp at the end of the current batch. Batch [BatchID] Batch Id of the current Batch Batch [Product] Product Name of the current Batch Batch [Recipe] Recipe Name of the current Batch Batch [ElementName] Name of the current Element Case [ElementPath] Path to the current Element. Case [CaseName] Name of the current Case. Case [SeqNr] Occurrence of the current Module/Time. Module/Time 98

103 Chapter 7 Format Template Reference The Format Template defines the format of the report. You define the report layout as a tree structure in the Format Template tab. You build a Format Template by inserting formatting elements or by dragging elements from the Format Toolbox (page 161) to the Format Template Tree. The hierarchical relationship mimics the display of the final report output. The Format Template tab and the Report tab are linked. Clicking an element in the Report tab opens the format template tree to that element, and vice versa. The formatting elements can contain organizational logic, static text and images, and dynamic data coming from the Data Journal. The elements must follow certain rules. The Format Template is reusable. You can apply it to different result sets. This tab is a dockable window. Format Template Tree When a report template is created, the following structure is populated into the Format Template tree. A default Format Template consists of a root node (indicated by the name of the report template) and five standard report template sections: CoverSheet, ReportHeader, PageHeader, PageFooter and ReportFooter. RtReports Template Reference 99

104 Format Template Reference The root node of the Format Template tree is where you define global settings which determine how the Format Template interacts with the RtReports Generator. To modify these settings: Right-click the root node of the Format Template tree and select Property to launch the Report Edit window. Report Edit Window The Report Edit window has four tabs: Format Root (page 100) Print Setup (page 102) Criteria (page 103) Effective Dates (page 110) Format Root Tab The Format Root tab is where you specify root attributes for the Report Template. 100

105 Report Edit Window Name The name of the Report Template. Description An optional description of the Report Template. Verification Allow Verifications Check to allow a user with appropriate security privileges to verify this section. This only applies if the section is NOT a subsection of another Section object. Allow Comments Check to allow a user with appropriate security privileges to comment this section. This only applies if the section is NOT a subsection of another Section object. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Background Color Choose the default background color for the element. Note: Font settings are applied to all Format Template nodes beneath a node in which they are defined, unless the child nodes have explicit font settings defined. This feature is useful if you wish to specify a common font size and style for all the formatted elements of your report. RtReports Template Reference 101

106 Format Template Reference Print Setup Tab This tab contains settings that control how the report is printed. Page Orientation - Controls whether the report will be printed in Landscape or Portrait mode. Page Numbering - Controls whether cover page, page headers and page footers are displayed on the first printer page. Skip First Page prints page numbers on all pages except the first. Number All Pages prints page numbers on all pages. Page Units - Controls the units the margin settings are defined as, either Inches or Millimeters. Top Margin - Controls the width of the top margin of the printed report. Bottom Margin - Controls the width of the bottom margin of the printed report. Left Margin - Controls the width of the left margin of the printed report. Right Margin - Controls the width of the right margin of the printed report. Printer Name - The designated printer used for Official Print functionality. Official Mark - Text to be shown as the official mark on an official print. PDF Settings Output Directory - Controls the destination directory of reports printed to Adobe PDF. Official Output Directory - Controls he destination directory of reports officially printed to Adobe PDF. PDF Settings - File Name These settings allow you to select report properties to include in the file name of the generated Adobe PDF file. The options vary for different types of report templates (Batch, Time or Case). Report Name - Name of the report template. This must be included in the file name. Report Version - Version of the report template. This must be included in the file name. 102

107 Report Edit Window Report Type - Type of the report, either Batch, Time or Case. Data Server - PI server supplying the data for the report. Start Time - Start time of data context. End Time - End time of data context. BatchID - For batch repots, the Batch ID of the data context. Product - For batch repots, the product of the data context. Recipe - For batch repots, the recipe of the data context. Criteria Tab Report criteria define the relationship between the data context and the Format Template. Use the following criteria settings to associate a Format Template with specific batch, time or case criteria. Batch Report Criteria Enter batch information for batch reports. Recipe - Choose <Add New Item> and enter the Recipe Name. Product - Choose <Add New Item> and enter the Product Name. Equipment - Choose <Add New Item> and enter the Equipment name. SubBatch - Choose <Add New Item> and enter the SubBatch name. Unit Class - Click the green button and select a valid Unit Class, then click OK. RtReports Template Reference 103

108 Format Template Reference Time Report Criteria Select a recurrence pattern and enter criteria for time reports. Recurrence Select the recurrence pattern for the time report in Minutes, Hours, Days, Weeks, Months, Years or None. The options available change according to the selection. Minutes Recurrence Specify a report run to recur every N minutes from the start time, where N is number of minutes. Reference Start - Enter the start time for the report. Report Duration - Specify the duration over which data should be reported: Reference End - Specify an end time for the report. Total Time - Specify N units, where N is number of seconds or minutes past the reference start time. Hours Recurrence 104

109 Report Edit Window Specify a report run to recur every N hours from the start time, where N is number of hours. Reference Start - Enter the start time for the report. Report Duration - Specify the duration over which data should be reported: Reference End - Specify an end time for the report. Total Time - Specify N units, where N is number of seconds, minutes or hours past the reference start time. Days Recurrence RtReports Template Reference 105

110 Format Template Reference Choose one of two options: Specify a report run to recur every N days from the start time, where N is number of days. Specify a report run to recur Every weekday. Reference Start - Enter the start time for the report. Report Duration - Specify the duration over which data should be reported: Reference End - Specify an end time for the report. Total Time - Specify N units, where N is number of seconds, minutes, hours or days past the reference start time. Weeks Recurrence 106

111 Report Edit Window Specify a report run to recur every N weeks from the start time, where N is number of weeks, and then select the days on which the recurrence should happen using the check boxes. Reference Start - Enter the start time for the report. Report Duration - Specify the duration over which data should be reported: Reference End - Specify an end time for the report. Total Time - Specify N units, where N is number of seconds, minutes or hours, days or weeks past the reference start time. Months Recurrence RtReports Template Reference 107

112 Format Template Reference Choose one of two options: Specify a report run to recur every Nth calendar day every N months, where N is the number of months from the start time. For example, every 3 months on the 15th. Specify a report run to recur every Mth occurrence of a specified weekday, every N months, where N is the number of months from the start time. For example, on the second Wednesday of every fourth month. Report Duration - Specify the duration over which data should be reported: Reference End - Specify an end time for the report. Total Time - Specify N units, where N is number of seconds, minutes or hours, days, weeks or months past the reference start time. Years Recurrence 108

113 Report Edit Window Choose one of two options: Specify a report run to recur every Nth calendar day of a specific month going forward from the start time. For example, every April on the 23rd. Specify a report run to recur every Mth occurrence of a specified weekday of a specified month going forward from the start time. For example, on the first Monday of December. Report Duration - Specify the duration over which data should be reported: Reference End - Specify an end time for the report. Total Time - Specify N units, where N is number of seconds, minutes or hours, days, weeks, months or years past the reference start time. Case Report Criteria Enter criteria for case reports. RtReports Template Reference 109

114 Format Template Reference Model - Choose <Add New Item> and enter the Model Name. Analysis - Choose <Add New Item> and enter the Analysis Name. Effective Dates Tab Effective dates specify the validity of a report over a specific time range. 110

115 Report Edit Window Disable Effective Dates - Select to use default effective dates, which are determined by the report version. Effective Start Time Beginning of Time - Select to use the default effective start date (the beginning of time), or enter a different date/time as the effective start time for the report. Effective End Time End of Time - Select to use the default effective end date (the end of time), or enter a different date/time as the effective end time for the report. Advanced Template Settings The Report Template Advanced Settings window controls the security, review, and approval settings of a Report Template. Each setting can only be defined for a group. You can define group privileges when you create a new Report Template or as an edit to an exiting report. To open the Report Template Advanced Settings window: Click Advanced in the Report Edit dialog. The window has three tabs, Security, Reviews, and Approvals, which you use to assign permissions and privileges to groups. Refer to the Security section of the RtReports User Guide for information about user-based security. Security Tab The Security tab defines whether to allow or deny edit or execute permission to a Report Template. Each permission is defined by group. RtReports Template Reference 111

116 Format Template Reference Report Edit Report Edit security controls the permission to edit the definition of a Report Template. Allow Select this box to give members of a group permission to open a Report Template and edit its configuration. Deny Select this box to give members of a group permission to open and review a Report Template but not edit it. Report Execute Report Execute security controls the permission to generate a Report Template. Allow Select this box to give members of a group permission to run a Report Template. Deny Select this box to exclude a Report Template from the list of reports viewed in the Generator by members of this group. 112

117 Report Edit Window Reviews Tab The Reviews tab defines the review cycle for a Report Template. The review cycle is the workflow for moving a Report Template from editing status to released status. A Report Template must be released before it can be used to generate reports. If a Report Template has no review cycle defined, then any member of a group that has edit privileges for that template can move the report template from In Edit status to Approved status. 1. Click the Reviews tab. 2. Click the add button (+) to add a new row in the review cycle. 3. Select the group to review the Report Template from the Reviewing Group drop-down list. A group must have Review security permission to appear in the list. Refer to the Security section of the RtReports User Guide for information about user-based security. 4. Repeat these steps to configure all groups that participate in the review cycle. The Generator enforces the sequence of this review list. You can alter the sequence of the list. 5. Select a row. 6. Click the up button or the down button to move a line up or down the list. You can delete a line from the list. 7. Select a row. 8. Click the red delete button (X) to remove the row from the list. RtReports Template Reference 113

118 Format Template Reference Approvals Tab The Approvals tab defines the steps, reviewers, and types of approval required in the approval plan. The approval plan defines the process for approving a Report Template for use in production. 1. Click the Add button (+) to add a new row in the approval cycle. 2. Select the group to approve the Report Template from the Approving Group drop-down list. A group must have Approve security permission to appear in the list. Refer to the Security section of the RtReports User Guide for information about user-based security. 3. Repeat these steps to configure all groups that participate in the Approval Plan. The Generator enforces the sequence of this approval list. You can alter the sequence of the list. 4. Select a row. 5. Click the up button or the down button to move a line up or down the list. You can delete a line from the list. 6. Select a row. 7. Click the red delete button (X) to remove the row from the list. Note: Assign Approval Plan, Save Approval Plan, Approval Type, Approval Role, and Step Type are not active. 114

119 Section Elements Section Elements The main organizational elements of a Format Template are Section elements. Five specialized sections are created automatically: Cover Sheet (page 115), Report Header (page 115), Page Header (page 117), Page Footer (page 118), and Report Footer (page 116). Unlike user-created Sections, you cannot insert another Section element within these default Sections; only Entry elements (page 123) can be inserted inside these Sections. CoverSheet Section The CoverSheet section is used to display content shown on the cover sheet of the report. Note: When testing the report in the RtReports Editor, the cover sheet appears in the report preview in the Report tab. However, when running the report in the RtReports Generator, the cover sheet is not displayed. When the report is printed, the cover sheet is printed with the report. Configuration is not required to use the CoverSheet section, but an Entry element (page 123) must be associated with it. To insert an entry element: Right-click the Section and select Insert > Entry. ReportHeader Element ReportHeader sections are used to display content shown at the top of a report: Right-click the ReportHeader element and click Property to open the ReportHeader Edit window. RtReports Template Reference 115

120 Format Template Reference Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. ReportFooter Element The ReportFooter section displays content shown at the bottom of a report. Right click the ReportFooter element and click Property to open the ReportFooter Edit window. 116

121 Section Elements Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. PageHeader Element The PageHeader section displays content shown at the top of each page of a report. Right click the PageHeader element and click Property to reach the PageHeader Edit window. RtReports Template Reference 117

122 Format Template Reference Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. PageFooter Element The PageFooter section displays content shown at the bottom of each page of a report. Right click the PageFooter section and click Property to open the PageFooter Edit window. 118

123 Section Elements Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. SectionHeader Element SectionHeader sections display content shown at the top of report sections: Right click the SectionHeader element and click Property to open the SectionHeader Edit window. RtReports Template Reference 119

124 Format Template Reference Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. SectionFooter Element Right click the SectionFooter element and click property to open the SectionFooter Edit window. 120

125 Section Elements Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. Create Additional Sections You can build up the content structure of a report by adding additional sections to the Format Template to break up your report into logical groups: 1. Right-click the root node of the Format Template Tree, or right-click an existing section and select Insert > Section to add more sections. 2. Right-click the newly inserted section in the tree and select Property to open the Section Edit window. Layout Tab Use the Layout tab to define properties for the new section. RtReports Template Reference 121

126 Format Template Reference Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Alignment Horizontal Align Set a horizontal alignment position for the element. Verification Allow Verifications Check to allow a user with appropriate security privileges to verify this section. This only applies if the section is NOT a subsection of another Section object. Allow Comments Check to allow a user with appropriate security privileges to comment this section. This only applies if the section is NOT a subsection of another Section object. Expressions Tab Use the Expressions tab to describe how the section is used in the report. 122

127 Entry Elements Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. Entry Elements Along with other Section elements (page 115), you can also add Entry elements underneath other Section elements. An entry element organizes and groups drawing elements into logical parts. 1. Right-click on a Section and select Insert > Entry to create an Entry. 2. Right-click the Entry and select Property to open the Entry Edit window. Use the Layout tab to define properties for the entry element. RtReports Template Reference 123

128 Format Template Reference Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Tab Use the Expressions tab to define properties for the new section. 124

129 Drawing Elements Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. Drawing Elements Once an Entry element is inserted in the Format Template, you can add any number of drawing elements within the Entry. To insert a drawing element within an Entry: Right-click the Entry and select Insert. Drawing elements fall into two categories: static and dynamic. Static drawing elements include: Text (page 126) draws static text on the report. Line (page 127) draws a horizontal line on the report. Image (page 128) object that provides the inclusion of a graphic within the report. Page Break (page 129) object that provides page breaks within the printed report. Not visible through Generator. Page Num (page 129) objects that provide page position within the printed report. Not visible through Generator. Table (page 130), Table Row (page 132), and Table Data (page 135) objects that allow you to build tables within the report. Dynamic drawing elements extract information from the Data Journal, and include: RtReports Template Reference 125

130 Format Template Reference Data (page 137) adds numeric and string data from the Data Journal to the report. Time (page 141) adds a Time object from the Data Journal to the report. UTC Time (page 142) adds a UTC Time string from the Data Journal to the report. Duration (page 140) adds a duration string from the Data Journal to the report. Paragraph (page 138) provides formatting within an Entry. Trend (page 143) adds a Trend to the report. Trace Set (page 145) adds a table directly from data within the Data Journal to the report. Report Info (page 151) adds report information like name, version, user who last modified the report, time last modified, author, etc. For details on using dynamic drawing elements to format the report, see Applying the Data Journal to the Format Template (page 165). Static Drawing Elements Text Element Text elements are used to output static text in a report. Text Enter the name of the element displayed in the format template tree. Expressions Condition Enter a condition expression (page 176) for the report element. Font Set font properties for text that appears in the element. Field Name Font Size Meaning Select the name of the default font for the element. Select the default size of the font for this element. 126

131 Drawing Elements Field B I U Color Meaning Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Line Element Line elements create horizontal lines on a report. Width Specify Width Select to override the default Size setting for the width of the line. Size Specify the numeric value for the width of the line. Pixel Select to specify line size in pixels. Percent Select to specify line size as a percentage. Height Size Specify a numeric value for the height (length) of the line. Alignment Horizontal Align Specify the horizontal alignment of the line. Color Line Color Specify the color used of the line. Expressions Condition Enter a condition expression (page 176) for the report element. RtReports Template Reference 127

132 Format Template Reference Image Element Image elements are used to insert static images into a report. Image files referenced by an image element must be located on the RtReports server in RtReports\Images. Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Source A relative path to an image file located in the RtReports\Images directory on the RtReports Server. The image you want to display must reside in this directory to be included in a report. To reference a file in this directory use the syntax..\images\imagename.extension, for example,..\images\osilogo.jpg. Appearance Width Specify Width Select to override the default Size setting for image width. Size Specify a numeric value for the display width of the image. Pixel Select to evaluate the Size setting in pixels. Percent Select to evaluate the Size setting as a percentage of the image file dimensions. Height Specify Height Select to override the default Size setting for image height. Size Specify a numeric value for the display height of the image. Pixel Select to evaluate the Size setting in pixels. 128

133 Drawing Elements Percent Select to evaluate the Size setting as a percentage of the image file dimensions. Margin Horizontal Specify the amount of horizontal spacing in pixels between the image and other format elements on the rendered report. Vertical Specify the amount of vertical spacing in pixels between the image and other format elements on the rendered report. Border Specify the width of a border around the image, in pixels. Expressions Condition Enter a condition expression (page 176) for the report element. Page Break Element Page Break elements force page breaks in the printed report. Expressions Condition Enter a condition expression (page 176) for the report element. Page Number Element Page Number elements provide page numbers in the printed report. Layout Type Specify the layout of page numbers on the report: RtReports Template Reference 129

134 Format Template Reference Page prints a page number only. Total Pages prints the total number of pages only. Page of Total Pages prints the page number 'of' the total number of pages. Expressions Condition Enter a condition expression (page 176) for the report element. Table Element Table elements are used to place tables in a report. Table Tab Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Rows Specify the number of rows in the table. Columns Specify the number of columns in the table. Border Tab 130

135 Drawing Elements Rule Specify the ruling style for table lines between cells. Frame Specify the style of line used. Cell Padding Specify the amount of size in pixels between the border of a table cell and its contents. Cell Spacing Specify the amount of space in pixels between table cells. Border Width Specify the width of the line used for the table border. Border Color Color Select a color for the border line. 3D Light Select a light color to be used in a 3D border. 3D Dark Select a dark color to be used in a 3D border. Layout Tab Alignment - Specify the alignment of items contained in the table. RtReports Template Reference 131

136 Format Template Reference Background Color Choose the default background color for the element. Width Specify Width Select to override the default Size setting for the width of the element. Size Specify a numeric value for the width of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total width. Height Specify Height Select to override the default Size setting for the height of the element. Size Specify a numeric value for the height of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total height. Expressions Tab Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. Table Row Element Table Row elements add rows to a table. Layout Tab 132

137 Drawing Elements Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Background Color Choose the default background color for the element. Width Specify Width Select to override the default Size setting for the width of the element. Size Specify a numeric value for the width of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total width. Height Specify Height Select to override the default Size setting for the height of the element. Size Specify a numeric value for the height of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total height. Border Tab RtReports Template Reference 133

138 Format Template Reference Border Color Color Select a color for the border line. 3D Light Select a light color to be used in a 3D border. 3D Dark Select a dark color to be used in a 3D border. Alignment Tab Alignment Horizontal Align Set a horizontal alignment position for the element. Vertical Align - Set a vertical alignment position for the element. Expressions Tab 134

139 Drawing Elements Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. TableData Element Table Data elements add columns to a table. Layout Tab Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Column Span Specify the number of table columns the column should span. RtReports Template Reference 135

140 Format Template Reference No Wrap Select to disable text wrapping in the column.background Color Choose the default background color for the element. Width Specify Width Select to override the default Size setting for the width of the element. Size Specify a numeric value for the width of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total width. Border Tab Border Color Color Select a color for the border line. 3D Light Select a light color to be used in a 3D border. 3D Dark Select a dark color to be used in a 3D border. Alignment Tab 136

141 Drawing Elements Alignment Horizontal Align Set a horizontal alignment position for the element. Vertical Align - Set a vertical alignment position for the element. Expressions Tab Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. Dynamic Drawing Elements Data Element Data elements are used to output one or more Journal elements on the report. RtReports Template Reference 137

142 Format Template Reference Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Numeric Format - Enter a numeric format string (page 154) used to format data. Source Enter a source expression (page 165) used to retrieve an object from the Data Journal. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. Paragraph Elements Paragraph elements are used to control alignment within an Entry. Layout Tab 138

143 Drawing Elements Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Alignment Horizontal Align Set a horizontal alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Tab RtReports Template Reference 139

144 Format Template Reference Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. Duration Element Duration elements display duration data from the Journal. 140

145 Drawing Elements Layout Time Format Enter a valid time format (page 152) string. Source Enter a source expression (page 165) used to retrieve an object from the Data Journal. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. Time Element Time elements are used to display time data from the Data Journal. Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Time Format Enter a valid time format (page 152) string. RtReports Template Reference 141

146 Format Template Reference Source Enter a source expression (page 165) used to retrieve an object from the Data Journal. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. UTCTime Element UTCTime elements display time elements from the Journal represented in UTC time. Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. 142

147 Drawing Elements Time Format Enter a valid time format (page 152) string. Source Enter a source expression (page 165) used to retrieve an object from the Data Journal. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Expressions Condition Enter a condition expression (page 176) for the report element. Trend Element Trend elements insert a formatted Trend chart into a report using data from a Trend Result Definition in the Journal. The Source expression should reference the Value element of the Trend Result definition. RtReports Template Reference 143

148 Format Template Reference Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Source Enter a source expression (page 165) used to retrieve an object from the Data Journal. Appearance - Image Height Specify Height Select to override the default Size setting for the height of the element. Size Specify a numeric value for the height of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total height. Width Specify Width Select to override the default Size setting for the width of the element. Size Specify a numeric value for the width of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total width. Margins 144

149 Drawing Elements Horizontal Select the horizontal spacing between the image and other format elements on the rendered report, in pixels. Vertical Select the vertical spacing between the image and other format elements on the rendered report, in pixels. Border Select the border size around the image. Appearance - Trend When these settings are adjusted, the approximate size in pixels is indicated in the accompanying fields. Width - Specify the width of the Trend within the Editor and Generator. Height - Specify the height of the Trend within the Editor and Generator. Expressions Condition Enter a condition expression (page 176) for the report element. TraceSet Element TraceSet Table elements create a standard table to display data from a TraceSet Journal element. Table Tab Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Source Enter a source expression (page 165) used to retrieve an object from the Data Journal. RtReports Template Reference 145

150 Format Template Reference Header Tab Enable Auto Headers - Select to enable automatic header rows. Background Color Choose the default background color for the element. Alignment Horizontal Align Set a horizontal alignment position for the element. Vertical Align - Set a vertical alignment position for the element. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. Row Layout Tab 146

151 Drawing Elements Alignment Horizontal Align Set a horizontal alignment position for the element. Vertical Align - Set a vertical alignment position for the element. Border Color Color Select a color for the border line. 3D Light Select a light color to be used in a 3D border. 3D Dark Select a dark color to be used in a 3D border. Background Color Choose the default background color for the element. Cell Layout Tab RtReports Template Reference 147

152 Format Template Reference Width Specify Width Select to override the default Size setting for the width of the element. Size Specify a numeric value for the width of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total width. Border Color Color Select a color for the border line. 3D Light Select a light color to be used in a 3D border. 3D Dark Select a dark color to be used in a 3D border. Background Color Choose the default background color for the element. No Wrap Select to disable text wrapping in the column. Rows Definition Tab Columns Specify the source for the column. Format Specify a valid format string for the column. Align Specify the alignment for the column. Click to add row definition. Click to delete a row definition. Click to move the selected row definition up. Click to move the selected row definition down. Border Tab 148

153 Drawing Elements Rule Specify the ruling style for table lines between cells. Frame Specify the style of line used. Cell Padding Specify the amount of size in pixels between the border of a table cell and its contents. Cell Spacing Specify the amount of space in pixels between table cells. Border Width Specify the width of the line used for the table border. Border Color Color Select a color for the border line. 3D Light Select a light color to be used in a 3D border. 3D Dark Select a dark color to be used in a 3D border. Expressions Tab RtReports Template Reference 149

154 Format Template Reference Expressions Condition Enter a condition expression (page 176) for the report element. Iterators Iterator Enter an iterator expression (page 169) for the report element. Iterator Result Condition Enter a result condition for the iterator. Table Layout Tab Alignment - Specifies the alignment of items contained in the table. Background Color Choose the default background color for the element. Width Specify Width Select to override the default Size setting for the width of the element. Size Specify a numeric value for the width of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total width. Height Specify Height Select to override the default Size setting for the height of the element. Size Specify a numeric value for the height of the element. Pixel Select to evaluate the Size in pixels. Percent Select to evaluate the Size as a percentage of the total height. 150

155 Drawing Elements Report Info Element The Report Info element provides a way to add report-specific information to the template, including report name, version, effective dates, and the last time the report was modified or printed. Layout NodeName Enter an appropriate name for the element. The name labels the element in the Format Template tree. Time Format Enter a valid time format (page 152) string. Report Info type - Select the type of report information to be displayed. Font Set font properties for text that appears in the element. Field Name Font Size B I U Color Meaning Select the name of the default font for the element. Select the default size of the font for this element. Makes the element text bold. Makes the element text italic. Underline the element text. Select the default color of the font used for the element. RtReports Template Reference 151

156 Format Template Reference Expressions Condition Enter a condition expression (page 176) for the report element. Format Strings Different time and numeric format strings can be specified for data items included in the Report Template. Time Format Strings A Time Format controls how a time element appears in the final report. This table identifies characters you can use to format time values. Character Description (:) Time separator. In some locales, other characters may be used to represent the time separator. The time separator separates hours, minutes, and seconds when time values are formatted. The actual character used as the time separator in formatted output is determined by the system's LocaleID value. (/) Date separator. In some locales, other characters may be used to represent the date separator. The date separator separates the day, month, and year when date values are formatted. The actual character used as the date separator in formatted output is determined by your locale. (%) Used to indicate that the following character should be read as a singleletter format without regard to any trailing letters. Also used to indicate that a single-letter format is read as a user-defined format. See below for further details D Displays the day as a number without a leading zero (for example, 1). Use %d if this is the only character in your user-defined numeric format. Dd Displays the day as a number with a leading zero (for example, 01). Ddd Dddd M MM MMM MMMM gg h hh Displays the day as an abbreviation (for example, Sun). Displays the day as a full name (for example, Sunday). Displays the month as a number without a leading zero (for example, January is represented as 1). Use %M if this is the only character in your user-defined numeric format. Displays the month as a number with a leading zero (for example, 01/12/01). Displays the month as an abbreviation (for example, Jan). Displays the month as a full month name (for example, January). Displays the period/era string (for example, A.D.) Displays the hour as a number without leading zeros using the 12-hour clock (for example, 1:15:15 PM). Use %h if this is the only character in your user-defined numeric format. Displays the hour as a number with leading zeros using the 12-hour clock (for example, 01:15:15 PM). 152

157 Format Strings Character H HH m mm s ss f t tt y yy yyy yyyy z Description Displays the hour as a number without leading zeros using the 24-hour clock (for example, 1:15:15). Use %H if this is the only character in your user-defined numeric format. Displays the hour as a number with leading zeros using the 24-hour clock (for example, 01:15:15). Displays the minute as a number without leading zeros (for example, 12:1:15). Use %m if this is the only character in your user-defined numeric format. Displays the minute as a number with leading zeros (for example, 12:01:15). Displays the second as a number without leading zeros (for example, 12:15:5). Use %s if this is the only character in your user-defined numeric format. Displays the second as a number with leading zeros (for example, 12:15:05). Displays fractions of seconds. For example ff displays hundredths of seconds, where as ffff displays ten-thousandths of seconds. You may use up to seven f symbols in your user-defined format. Use %f if this is the only character in your user-defined numeric format. Uses the 12-hour clock and displays an uppercase A for any hour before noon; displays an uppercase P for any hour between noon and 11:59 P.M. Use %t if this is the only character in your user-defined numeric format. Uses the 12-hour clock and displays an uppercase AM with any hour before noon; displays an uppercase PM with any hour between noon and 11:59 P.M. Displays the year number (0-9) without leading zeros. Use %y if this is the only character in your user-defined numeric format. Displays the year in two-digit numeric format with a leading zero, if applicable. Displays the year in four digit numeric format. Displays the year in four digit numeric format. Displays the time zone offset without a leading zero (for example, -8). Use %z if this is the only character in your user-defined numeric format. zz Displays the time zone offset with a leading zero (for example, -08) zzz Displays the full time zone offset (for example, -08:00) Fraction of second, show trailing zeros # - ###### Fraction of second, no trailing zeros Example The following are examples of user-defined date and time formats for December 7, 1958, 8:50 PM, 35 seconds: Format Displays M/d/yy 12/7/58 d-mmm 7-Dec RtReports Template Reference 153

158 Format Template Reference Format Displays d-mmmm-yy 7-December-58 d MMMM 7 December MMMM yy December 58 hh:mm tt 08:50 PM h:mm:ss t 8:50:35 P H:mm 20:50 H:mm:ss 20:50:35 M/d/yyyy H:mm 12/7/ :50 Numeric Format String Standard numeric format strings are used to format common numeric types. A standard format string takes the form Axx where A is a single alphabetic character called the format specifier, and xx is an optional integer called the precision specifier. The format specifier must be one of the built-in format characters. The precision specifier ranges from 0 to 99 and controls the number of significant digits or zeros to the right of a decimal. The format string cannot contain white spaces. The following table describes the standard numeric format strings. Note that the result string produced by these format specifiers is influenced by the settings in the Regional Options control panel. Computers using different settings will generate different result strings. Format Specifier Name Description C or c Currency The number is converted to a string that represents a currency amount. The precision specifier indicates the desired number of decimal places. D or d Decimal This format is supported for integral types only. The number is converted to a string of decimal digits (0-9), prefixed by a minus sign if the number is negative. The precision specifier indicates the minimum number of digits desired in the resulting string. If required, the number is padded with zeros to its left to produce the number of digits given by the precision specifier. E or e Scientific The number is converted to a string of the form "- d.ddd...e+ddd" or "-d.ddd...e+ddd", where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. One digit always precedes the decimal point. The precision specifier indicates the desired number of digits after the decimal point. If the precision specifier is omitted, a default of six digits after the decimal point is used. The case of the format specifier indicates whether to prefix the exponent with an 'E' or an 'e'. The exponent always consists of a plus or minus sign and a minimum of three digits. The exponent is padded with zeros to meet this minimum, if required. 154

159 Format Strings Format Specifier Name Description F or f Fixed-point The number is converted to a string of the form "-ddd.ddd..." where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. The precision specifier indicates the desired number of decimal places. G or g General The number is converted to the most compact of either fixedpoint or scientific notation, depending on the type of the number and whether a precision specifier is present. If the precision specifier is omitted or zero, the type of the number determines the default precision, as indicated by the following list. Byte or SByte: 3 Int16 or UInt16: 5 Int32 or UInt32: 10 Int64 or UInt64: 19 Single: 7 Double: 15 Decimal: 29 Fixed-point notation is used if the exponent that would result from expressing the number in scientific notation is greater than -5 and less than the precision specifier; otherwise, scientific notation is used. The result contains a decimal point if required and trailing zeroes are omitted. If the precision specifier is present and the number of significant digits in the result exceeds the specified precision, then the excess trailing digits are removed by rounding. If scientific notation is used, the exponent in the result is prefixed with 'E' if the format specifier is 'G', or 'e' if the format specifier is 'g'. The exception to the preceding rule is if the number is a Decimal and the precision specifier is omitted. In that case, fixed-point notation is always used and trailing zeroes are preserved. N or n Number The number is converted to a string of the form "- d,ddd,ddd.ddd...", where each 'd' indicates a digit (0-9). The string starts with a minus sign if the number is negative. Thousand separators are inserted between each group of three digits to the left of the decimal point. The precision specifier indicates the desired number of decimal places. P or p Percent The number is converted to a string that represents a percent. The precision specifier indicates the desired number of decimal places. Example The following table provides examples of the Format specifiers described above. In the table, the Format column indicates the format string (specifier), the Culture column indicates the culture under which the value was formatted that is, the Locale set in the browser or in Windows, the Data type column indicates the data type used, the Value column indicates the value of the number being formatted, and the Output column indicates the result of formatting. RtReports Template Reference 155

160 Format Template Reference Format Culture Data type Value Output C en-us Double $12, C de-de Double ,68 DM D en-us Int D8 en-us Int E en-us Double E+004 E10 en-us Double E+004 E fr-fr Double ,234568E+004 e4 en-us Double e+004 F en-us Double F es-es Double ,68 F0 en-us Double F6 en-us Double G en-us Double G7 en-us Double G en-us Double E-6 G en-us Double G2 en-us Double E3 G en-us Double Math.PI N en-us Double , N sv-se Double ,68 N4 en-us Double ,456, P en-us Double % r en-us Double Math.PI x en-us Int32 0x2c45e 2c45e X en-us Int32 0x2c45e 2C45E X8 en-us Int32 0x2c45e 0002C45E x en-us Int bcd15 Custom Numeric Format Strings The following table shows the characters used to create custom numeric format strings and their definitions. Note: The result strings produced by some of these characters are influenced by the settings in the Regional Options control panel of the NumberFormatInfo object associated with the current thread. Computers using different cultures generate different result strings. 156

161 Format Strings Format character Name Description 0 Zero placeholder # Digit placeholder. Decimal point, Thousand separator and number scaling % Percentage placeholder If the value being formatted has a digit in the position where the '0' appears in the format string, then that digit is copied to the result string. The position of the leftmost '0' before the decimal point and the rightmost '0' after the decimal point determines the range of digits that are always present in the result string. The "00" specifier causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. For example, formatting 34.5 with "00" would result in the value 35. If the value being formatted has a digit in the position where the '#' appears in the format string, then that digit is copied to the result string. Otherwise, nothing is stored in that position in the result string. Note that this specifier never displays the '0' character if it is not a significant digit, even if '0' is the only digit in the string. It displays the '0' character if it is a significant digit in the number being displayed. The "##" format string causes the value to be rounded to the nearest digit preceding the decimal, where rounding away from zero is always used. For example, formatting 34.5 with "##" would result in the value 35. The first '.' character in the format string determines the location of the decimal separator in the formatted value; any additional '.' characters are ignored. The actual character used as the decimal separator is determined by the NumberDecimalSeparator property of the NumberFormatInfo that controls formatting. The ',' character serves two purposes. First, if the format string contains a ',' character between two digit placeholders (0 or #) and to the left of the decimal point if one is present, then the output has thousand separators inserted between each group of three digits to the left of the decimal separator. The actual character used as the decimal separator in the result string is determined by the NumberGroupSeparator property of the current NumberFormatInfo that controls formatting. Second, if the format string contains one or more ',' characters immediately to the left of the decimal point, then the number is divided by the number of ',' characters multiplied by 1000 before it is formatted. For example, the format string "0,," represents 100 million as simply 100. Use of the ',' character to indicate scaling does not include thousand separators in the formatted number. Thus, to scale a number by 1 million and insert thousand separators you would use the format string "#,##0,,". The presence of a '%' character in a format string causes a number to be multiplied by 100 before it is formatted. The appropriate symbol is inserted in the number itself at the location where the '%' appears in the format string. The percent character used is dependent on the current NumberFormatInfo class. E0 E+0 E-0 e0 e+0 e-0 Scientific notation If any of the strings "E", "E+", "E-", "e", "e+", or "e-" are present in the format string and are followed immediately by at least one '0' character, then the number is formatted using scientific notation with an 'E' or 'e' inserted between the number and the exponent. The number of '0' characters following the scientific notation indicator determines the minimum number of digits to output for the exponent. The "E+" and "e+" formats indicate that a sign character (plus or minus) should always precede the exponent. The "E", "E-", "e", or "e-" formats indicate that a sign character should only precede negative exponents. RtReports Template Reference 157

162 Format Template Reference Format character Name Description \ Escape character In C# and the Managed Extensions for C++, the backslash character causes the next character in the format string to be interpreted as an escape sequence. It is used with traditional formatting sequences like '\n' (new line). In some languages, the escape character itself must be preceded by an escape character when used as a literal. Otherwise, the compiler interprets the character as an escape sequence. Use the string "\\" to display '\'. Note that this escape character is not supported in Visual Basic; however, ControlChars provides the same functionality. 'ABC' "ABC" Literal string Characters enclosed in single or double quotes are copied to the result string literally, and do not affect formatting. ; Section separator The ';' character is used to separate sections for positive, negative, and zero numbers in the format string. Other All other characters All other characters are copied to the result string as literals in the position they appear. For fixed-point format strings (strings not containing an "E0", "E+0", "E-0", "e0", "e+0", or "e-0"), numbers are rounded to as many decimal places as there are digit placeholders to the right of the decimal point. If the format string does not contain a decimal point, the number is rounded to the nearest integer. If the number has more digits than there are digit placeholders to the left of the decimal point, the extra digits are copied to the result string immediately before the first digit placeholder. Example In the following table, the Format column represents the custom format string, the Data type column indicates the data type used, the Value column indicates the value of the number being formatted, and the Output column indicates the result of formatting. Format Data type Value Output ##### Double Double (###) ### - #### Double (123) #.## Double Double Double #,# Double ,234,567,890 #,, Double #,,, Double #,##0,, Double ,235 #0.##% Double % 0.###E+0 Double E+4 158

163 Format Strings Format Data type Value Output 0.###E+00 0 Double E ###E-000 Double E004 [##-##-##] Double [ ] ##;(##) Double ##;(##) Double (1234) RtReports Template Reference 159

164

165 Chapter 8 Format Toolbox The Format Toolbox provides drag and drop access to report formatting objects. The Format Toolbox has three tabs: Objects (page 161) Style Sheets (page 161) Scratch Pad (page 162) Objects The Objects tab contains drawing objects that you can drag into a format template tree. The Objects tab contains drawing objects that you can drag into a Format Template tree. These are the same elements that are available via context menu in the Format Template Tree, and from the Insert menu. Style Sheets The Style Sheets tab shows the list of style sheets available to drag and drop into the format template tree. RtReports Template Reference 161

166 Format Toolbox You can drag and drop a section from a format template tree and save it as a style sheet for the later use. The Style Sheets tab allows you to store sections of Format Template structures that you wish to reuse in different report templates. These objects are stored in the PI Module Database for future use. The Style Sheets tab shows the list of style sheets available to drag and drop into the Format Template Tree. To save a Format Template object (or group of nested objects) to the Style Sheets collection, simply drag it to the Style Sheets window in the Format Toolbox. You will then be prompted to supply a name and version of the new Style Sheet object. Click OK to save the style sheet. It is now available for use in other report templates. Scratch Pad Tab The Scratch Pad tab allows you to save elements for later use within the same session. The scratch pad is not saved between sessions. To save an element, drag it to the scratch pad window. To use it, drag it out. You can right-click an object to delete it from the Scratch Pad. 162

167 Scratch Pad Tab The Scratch Pad tab allows you to save elements for later use within the same session. The scratch pad is not saved between sessions. The Scratch Pad in the Format Toolbox is a different entity than the Scratch Pad in the Data Toolbox. To save an element to the Scratch Pad, drag it from the Format Template Tree to the Scratch Pad window. To use it, drag it out to the Format Template tree. You can right-click an object to delete it from the Scratch Pad. RtReports Template Reference 163

168

169 Chapter 9 Apply the Data Journal to the Format Template Now that you have built a Data Journal which contains the various data items you may wish to display in your report, you must apply these Journal items to the Format Template in order to make them visible to the report viewer. This is accomplished by defining queries of the Data Journal data via the Source and Iterator fields in the various dynamic drawing elements of the Format Template. Define Source Expressions in Dynamic Drawing Elements Dynamic drawing elements in the Format Template extract information from the Data Journal, which is an XML structure containing all of the data returned from the Data Template s various template objects and journal actions. Each dynamic drawing object supports a Source property, which defines the relative or absolute location of the element you want displayed in the Data Journal. This Source property is defined using XPath expression syntax. XPath (or XML Path) language provides syntax for addressing parts of an XML document. It is specified as an open standard in the W3C XPath specification. XPath enables you to locate any one or more nodes within an XML document (in this case, the Data Journal), often by using multiple alternate routes. In essence, XPath provides the syntax for performing basic queries upon your Data Journal to extract certain elements you want included in the report. For more detailed information, see the XPath Reference, located on Microsoft's web site at the following location: XML expressions defined in the Source field of Format Template objects are known as source expressions. In the RtReports Editor, there are two ways to populate the Source property: You can manually construct the expression. You can navigate to the Data Journal element you wish to reference, drag that element into the Source field of the Format Template object, and allow the Editor to automatically populate it. Example: Using the Source Text Box In this example, we want to add the PIUnitName element of the UnitBatchJournal to the report. 1. Add a Data object to the Format Template. RtReports Template Reference 165

170 Apply the Data Journal to the Format Template 2. Switch to the Journal tab, navigate to the first UnitBatchJournal, and select the PIUnitName element. 3. Drag the PIUnitName element and drop it in the Source text box. Build Source Expressions You will be able to use the drag and drop functionality to populate the Source field most of the time. Depending on the complexity of what you are trying to accomplish, you might have to manually edit the source expression to get the specific results you are looking for. This section will detail basic properties of building source expressions and provide examples for common expressions. A source expression uses a path notation (like those used in URLs) for addressing parts of the Data Journal. The expression is evaluated to yield a Data Journal element that is a boolean, number or string. For example, the expression BatchJournal/JournalEvents/JournalEvent will return all existing JournalEvent elements contained in JournalEvents element. In addition, source expressions can have predicates (filter expressions) or function calls. For example, the expression UnitBatchJournal[@Name= Unit1 ] refers to all UnitBatchJournal elements whose Name attribute is set to Unit1. The evaluation of a source expression depends on the context against which the expression operates. The context consists of the node against which the expression is evaluated and its associated environment. To better appreciate the concept of context, consider a tree containing nodes. Asking for all nodes named X from the root of the tree returns one set of 166

171 Source Expression Advanced Techniques results, while asking for those nodes from a branch in the tree returns a different set of results. Thus, the result of an expression depends upon the context against which it executes. Source expressions can match specific patterns at one particular context, rerun the results, and perform additional operations relative to the context of the returned nodes. Source Expressions are constructed using the operators and special characters shown in the following table: Operator Effect / Child operator; selects the immediate Attribute; prefix for an attribute name ( ) Groups operations to explicitly establish precedence [ ] Applies a filter pattern Example 1 To extract the PIUnitName element for a UnitBatchJournal, the syntax would be: BatchJournal/UnitBatchJournals/UnitBatchJournal/PIUnitName Example 2 To define the syntax for extracting the PIUnitName element for a UnitBatchJournal that contains the PIUnitName = TRA100L, it would be: BatchJournal/UnitBatchJournals/UnitBatchJournal[Name= TRA100L ]/PI UnitName Source Expression Advanced Techniques Example: Walk up the Journal Tree This example shows how to walk up the Journal tree to retrieve an item. To traverse the tree backward, use the following notation../ This notation will traverse the tree one node from the current context. The following is the source expression to walk up the tree from a UnitBatchJournal to a BatchJournal for the BatchID element:../../batchid RtReports Template Reference 167

172 Apply the Data Journal to the Format Template Example: Select an Item by Position in the Tree This example uses an XPath function within the source expression. The Data Journal may contain many JournalEvents. This source expression will select the last JournalEvent: BatchJournal/UnitBatchJournals/UnitBatchJournal/JournalEvents/Jour nalevent[last()] Example: Select Items with a Particular Property In the following example, we want to only include only those UnitBatchJournal objects that have a PIUnitName element that starts with TRA : BatchJournal/UnitBatchJournals/UnitBatchJournal[startswith(PIUnitName, TRA )] For more information on XPath functions, see the XPath Reference ( on Microsoft's web site. Example: Apply TraceSet Data in Source Expressions These examples show how to extract summary data from the Data Journal TraceSet element, which is unique in that it includes descriptive information about the data. Each value from a TraceSet Data Journal object can be obtained by specifying a particular Descriptor value. Each value from a TraceSet Data Journal object can be obtained by specifying a particular Descriptor value. Value Desired from Summary Result Definition Total Minimum Maximum Standard Deviation Range Average Mean Percent Good Start Value End Value Maximum Time Minimum Time Source Expression to retrieve that value TraceSet/Events/Properties/Property[(@Descriptor='22000')] TraceSet/Events/Properties/Property[(@Descriptor='22001')] TraceSet/Events/Properties/Property[(@Descriptor='22002')] TraceSet/Events/Properties/Property[(@Descriptor='22003')] TraceSet/Events/Properties/Property[(@Descriptor='22004')] TraceSet/Events/Properties/Property[(@Descriptor='22005')] TraceSet/Events/Properties/Property[(@Descriptor='22006')] TraceSet/Events/Properties/Property[(@Descriptor='22007')] TraceSet/Events/Properties/Property[(@Descriptor='22008')] TraceSet/Events/Properties/Property[(@Descriptor='22009')] TraceSet/Events/Properties/Property[(@Descriptor='22010')] TraceSet/Events/Properties/Property[(@Descriptor='22011')] 168

173 Iterator Expressions Example: Obtain Particular TraceSet Descriptors This TraceSet example shows how to extract the PI Tag Name, PI Tag Descriptor, or PI Tag Engineering Units from the Properties element: PI Tag Name PI Tag Descriptor PI Tag Engineering Units Example: Differentiate Among TraceSet Results If you define multiple data sources within a result definition, your Data Journal may contain several TraceSet elements with the same Result element. This example will show how to delineate between them: To select the TraceSet by name, specifically the Result.Tag TraceSet: Results/Result/Value/TraceSet[Name= Result.Tag ] To select the TraceSet by position, specifically the second TraceSet element: Results/Result/Value/TraceSet[position()=2] Iterator Expressions Most reports are repetitive by nature, such as production summary reports, clean utility reports, computer usage reports, etc. Often, you will want to show the same format for each phase on a report, or the same format for each hour of clean utility usage, etc. In all of these examples, you create a standard format and then apply it to a certain repeatable element in the Data Journal, such as a Unit, Phase, or even a particular type of action or result, such as an exception. To loop on a certain collection in the Data Journal, you can use an iterator expression. An iterator expression uses the same syntax as the source expression, but it controls the current context of the source expressions that are used. Example: Build Report Sections Using an Iterator In this example, suppose you want to create a section in the report for each PI UnitBatch. This means you must loop through the UnitBatchJournals collection within the Data Journal. To do this: 1. Right-click the root node of the Format Template tree and select Insert > Section to add a Section element to the Format Template. The Section Edit window appears. RtReports Template Reference 169

174 Apply the Data Journal to the Format Template 2. Select the Expressions tab. 3. While the Section Edit window is still open, switch to the Journal tab in the Editor. 4. Drag the first UnitBatchJournal element and drop it into the Iterator field in the Section Edit window. 170

175 Iterator Expressions At this point, the Section object that you just added to the report template will create a report section for every UnitBatchJournal element in the Data Journal. Furthermore, using the iterator sets the current source expression context. So, if you add a data element to this section, you only must use a relative reference to the element that you want to include from the Data Journal, because the current context is already set to the BatchJournal/UnitBatchJournals/UnitBatchJournal context. Example: Set the Current Context To further illustrate the concept of current context, expand the previous example and create a table that lists the PIUnitName, Start Time, End Time, and Duration in each section. 1. Add a Table element to the Entry element within the section that was created in Example Select Insert > Table Row to insert two Table Row elements in the Table object. 3. Select Insert > Table Data and insert four Table Data elements under each Table Row. RtReports Template Reference 171

176 Apply the Data Journal to the Format Template 4. Choose Insert > Text and add text objects PIUnitName, StartTime, EndTime, and Duration, respectively, into the four columns of the first row. 5. In the second row, first column, add a Data object. 172

177 Iterator Expressions 6. Switch to the Journal tab and drag the PIUnitName element from the UnitBatchJournal element into the Source field of the Data Edit window. The Editor should automatically detect an Iterator working on this table, strip the Iterator context and insert a relative source expression for the element. 7. In the second row, first column, add a Data object. RtReports Template Reference 173

178 Apply the Data Journal to the Format Template Note: The 'Smart Iterator' functionality works under most conditions. If the Editor cannot determine the proper Iterator acting on the source expression, it enters an absolute source expression. In that case you must manually edit the expression. 8. In the second row of the second column choose Insert > Time to insert a Time element. 9. Switch to the Journal tab and drag and drop the StartTime element from the UnitBatchJournal element into the Source field of the Time Edit window. 10. In the second row, third column, add an EndTime element from the UnitBatchJournal in the same manner. 11. In the second row, fourth column, add a Duration element from the UnitBatchJournal in the same manner. Click OK. 174

179 Iterator Expressions At this point, the table displays the PIUnitName, StartTime, EndTime, and duration of each UnitBatchJournal that is included in the report. 12. To view the report, click View > Refresh to see each section and the corresponding information. Only the source expression to the specific element is required because the iterator sets the current context to the UnitBatchJournal element in the Data Journal. RtReports Template Reference 175