Reporting

Owned by David Stavisski
Last updated: Oct 18, 2021
10 min read

The reports in IT-Conductor use IT-Conductor XML markup identified by itc namespace prefix. At this time the XML is not validated against IT-Conductor schema.

Global Variables

variables ${self/....}, ${report/...} are supported in any parameter or selector they are resolved with report's values

Qualifiers:

self - Report Object 

report - report specific variables

Section

Dynamic Sections - behaves the same way as <query> producing a list of objects based on select criteria:

<itc:section
  <itc:parameter name="OBJECT_ClassName">class-name</itc:parameter>
  <itc:select name="attr-name" [oper="Operator"]>value</itc:select>
    ...
  <itc:select ... > ...
  <itc:parameter name="maintenance">true|false</itc:parameter> - Optional, allows for selection of objects based on the effective Maintenance Mode
  <itc:parameter name="linkClassName">Link Target Class</itc:parameter>                - Optional, if the intent is to return a list of linked objects,
                                                                                         this is the class of the link objects
  <itc:parameter name="linkAttrName">Link target object attribute name</itc:parameter> - Optional, if the intent is to return a list of linked objects
                                                                                         and the selection targets Links, this attribute contains 
                                                                                         the target object id in the link, normally LINK_LinkedObjectId or LINK_ObjectId
                                                                                         the opposite of what is used in the select criteria
  ...
</itc:section>

Where content can be any other construct including another <section>

The essence of section is that for each object found in the query the content will be replicated and if ${context/...} variables are used in any of the parameters they will be resolved with the query result Object attribute 

nested <section> push the context into a FIFO stack so all children will have the new object instance set as a context...

<itc:section>
<a>${context/OBJECT_Name}</a>
<p>
   <itc:chart context="${context/OBJECT_Id}"> ... </itc:chart>
</p>
</itc:section>

Assuming section query find 3 objects - will create the following construct:

<p>
  <p>
     <a>Object 1</a>
     <p><img for chart 1...></p>
  </p>
  <p>
    <a>Object 2</a>
    <p><img for chart 2...></p>
  </p>
  <p>
     <a>Object 3</a>
     <p><img for chart 3...></p>
   </p>
</p>

Variable

Set report variable:

<itc:vriable name="<var name>">Value</itc:variable>

The variable can be accessed as ${report/<var name>}

If

Conditional block

<itc:if>
  <itc:parameter name="mode">context|variables</itc:parameter>
  <itc:select name="name" [oper="Operator"]>value</itc:select>
    ...
  <itc:select ... > ...
   ... any content ...
</itc:if>

The optional  mode parameter (defaults to "context") - determines what the condition criteria (selects) is applied to:

context: the current context object (report external context or section-derived context)

variables: report variables (assigned with <itc:variable>)

If the criteria (all <itc:select> elements)  evaluates to true the content of the if is included and evaluated according to report type supported elements, otherwise it is skipped

Icon

Insert Icon 

<itc:icon>
  <itc:parameter name="name"><Icon Name></itc:parameter>
</itc:icon>

for available icon names see: https://service.itconductor.com/iconList

Path

Display service element path

<itc:path>
 <itc:parameter name="OBJECT_Id"><Object Id></itc:parameter>
</itc:path>


for PDF reports this is the only <itc:...> construct currently supported inside heading markup <h..></h..>

Object & Context Selectors

In all constructs we now support dynamic object and context selectors in addition to parameters OBJECT_Id & context:

<Object Selector />
<Context Selector />

See detail in "Where"

Chart

Reports Chart

<itc:chart>
  <Object Selector><!-- Optional see OBJECT_Id above -->
  <itc:parameter name="context"><context id></itc:parameter><!-- Optional see Context Selector -->
  <Context Selector /><!-- Optional see context above -->
  <itc:parameter name="width">100%</itc:parameter>
  <itc:parameter name="timeScale">HOUR</itc:parameter>
  <itc:parameter name="title">true|false</itc:parameter> <!-- Display Chart Title, default: true -->
  <itc:parameter name="titleText">New Text</itc:parameter> <!-- Override Chart Title -->
  <itc:parameter name="annotations">true|false</itc:parameter> <!-- Disable /enable annotation in charts and tables, default: true --> 
  <itc:parameter name="legend">none|left|right|top|bottom</itc:parameter> <!-- Display Legend in the position relative to the chart, default: as specified in the chart object --> 
  <itc:parameter name="valuesOnly">true|false</itc:parameter> <!-- Disable /enable suppression of thresholds, severity & annotations, default: false -->
  <itc:parameter name="excludeCategory">Category id</itc:parameter>  <!-- Exclude Chart Category (if chart Supports category exclusion -->
  <itc:parameter name="range">Range, see below</itc:parameter>
  <itc:parameter name="annotations">true|false</itc:parameter>  <!-- disable /enable annotation in charts and tables, default: true -->
  <itc:parameter name="excludeCategory.<category id>">true|false</itc:parameter>  <!-- Exclude Chart Category (if chart Supports category exclusion -->
  <itc:parameter name="table">false</itc:parameter> <!-- Show as Table or Plot default: false -->
  <!-- When table=true -->
  <itc:parameter name="header">true|false</itc:parameter> <!-- disable/enable chart table header row, default: true -->
  <itc:parameter name="categoryHeader">Text</itc:parameter> <!-- set category column header text, default: none -->
  <itc:parameter name="valueHeader">Text</itc:parameter>   <!-- set value column header text, default: none -->
  <itc:parameter name="tableTime">true|false</itc:parameter> <!-- disable/enable chart (time-series nly) table Time column, default: true -->
  <itc:parameter name="tableCategories">true|false</itc:parameter> <!-- disable/enable chart table Category column, default: true -->
</itc:chart>

where

Category id - is either category Object Id (for multi-line graphs) or "Alarm", "Warning", "Severity", "itconductor.Annotations", "itconductor.Summary"

Threshold

Locates & Reports a threshold, based on target Object ID and value Attribute Name.

Only Regular Thresholds are supported Collection Thresholds should be accessed using <chart> construct

 <itc:threshold>
  <Object Selector> <!-- Optional see THRESHOLD_ObjectId above -->
  <itc:parameter name="THRESHOLD_AttributeName">OBJECT_Availability</itc:parameter>
  <itc:parameter name="table">false</itc:parameter>
  <itc:parameter name="width">100%</itc:parameter>
  <itc:parameter name="timeScale">HOUR</itc:parameter>
  <itc:parameter name="title">true|false</itc:parameter> <!-- Display Threshold Title, default: true -->
  <itc:parameter name="titleText">New Text</itc:parameter> <!-- Override Chart Title -->
  <itc:parameter name="annotations">true|false</itc:parameter> <!-- Disable /enable annotation in charts and tables, default: true --> 
  <itc:parameter name="legend">none|left|right|top|bottom</itc:parameter> <!-- Display Legend in the position relative to the chart, default: depends on the threshold type --> 
  <itc:parameter name="valuesOnly">true|false</itc:parameter> <!-- Disable /enable suppression of thresholds, severity & annotations, default: false -->
  <itc:parameter name="range">Range, see below</itc:parameter>
  <itc:parameter name="scale">Value scale, Decimal</itc:parameter>
  <itc:parameter name="unit">Unit Name, String</itc:parameter> 
  <itc:parameter name="format">Value Format, Java Formatting:  %,.2f</itc:parameter> 
  <itc:parameter name="details">true|false</itc:parameter> <!-- For Consolidator Thresholds enables Details mode display ->
  <itc:parameter name="collector">Collector ObjectId</itc:parameter> <!-- For Consolidator Thresholds if Details mode, use collector for a specific component details ->
</itc:threshold>

parameters THRESHOLD_ObjectId and THRESHOLD_AttributeName allow for the selection of the relevant threshold (search is performed)

if parameter OBJECT_Id is specified - it overrides the above and the construct behaves fully as <chart>

Parameters scale, unit, format - are threshold specific and allow to override how the value is charted

Otherwise <threshold> behaves exactly like <chart>

Alerts

Report Alerts for the selected criteria

<itc:alerts>
  <!-- Target Alerts Criteria -->
  <itc:parameter name="className">Alert</itc:parameter> <!-- Target Class Name, optional, default "Alert" -->
  <itc:parameter name="ALERT.Status">Status</itc:parameter> <!-- Optional, Default - All, Overridden by itc:select for the same attribute-->
  <itc:parameter name="table">false</itc:parameter>
  <itc:parameter name="width">100%</itc:parameter>
  <itc:parameter name="timeScale">HOUR</itc:parameter>
  <itc:parameter name="range">Range, see below</itc:parameter>
  <!-- Search Criteria -->
  <itc:select name="export">true|false</itc:select>   <!-- Columns reported based ListExport flag not TableView flag (default) -->
  <itc:select name="select">Comma-separated column Attributes</itc:select>   <!-- Specific Columns to display, supersedes "export" -->
  <itc:select name="sortAttr">attribute name</itc:select> <!-- default ALERT.Time -->
  <itc:select name="sortOrder">DESC|ASC</itc:select> <!-- default ASC -->
</itc:alerts>

Service Query

Query on a service tree (applies the search criteria to each element in the sub-tree)

 <itc:servicequery>
  <!-- root Service node selector -->
  <itc:select  ..
  <!-- Target Objects Criteria -->
  <itc:target> 
    <itc:parameter name="className">Target Object Class</itc:parameter> <!-- Target Class Name , optional - default "Service" -->
    <itc:parameter name="serviceAttr">ALERT.ContextService</itc:parameter> <!-- Target Class Attribute  in the search criteria set with the service element ID , Required --> 
    <itc:parameter name="timeAttr">ALERT.Time</itc:parameter> <!-- Target Class Time Attribute, Optional --> 
    <!-- Query Criteria -->
    <itc:select 
  </itc:target>
  <itc:parameter name="table">false</itc:parameter>
  <itc:parameter name="width">100%</itc:parameter>
  <itc:parameter name="timeScale">Time Scale</itc:parameter><!-- Optional, Default HOUR -->
  <itc:parameter name="range">Range</itc:parameter> <!-- Optional, only evaluated if timeAttr is specified-->
  <itc:parameter name="startTime">Time</itc:parameter><!-- Optional, Override Range, only evaluated if timeAttr is specified -->
  <itc:parameter name="endTime">Time</itc:parameter>  <!-- Optional, Override Range, only evaluated if timeAttr is specified-->
  <itc:parameter name="export">true|false</itc:parameter>   <!-- Columns reported based ListExport flag not TableView flag (default) -->
  <itc:parameter name="select">Comma-separated column Attributes</itc:parameter>   <!-- Specific Columns to display, supersedes "export" -->
  <itc:parameter name="sortAttr">attribute name</itc:parameter>
  <itc:parameter name="sortOrder">DESC|ASC</itc:parameter>
</itc:servicequery>

Query

Free-form object query

<itc:query>
  <Object Selector>
  <itc:parameter name="export">true|false</itc:parameter>   <!-- Columns reported based ListExport flag not TableView flag (default) -->
  <itc:parameter name="select">Comma-separated column Attributes</itc:parameter>   <!-- Specific Columns to display, supersedes "export" -->
  <itc:parameter name="linkAttrName">Link target object attribute name</itc:parameter> <!-- Optional, if the intent is to return a list of linked objects 
                                                                                           and the selection targets Links, this attribute contains 
                                                                                           the target object id in the link, normally LINK_LinkedObjectId or LINK_ObjectId
                                                                                           the opposite of what is used in the select criteria -->
  <itc:parameter name="linkClassName">Linked object Class Name</itc:parameter> <!-- If linkAttrName is not specified - ignore, otherwise mandatory, specifies the target object Class --> 
  <itc:parameter name="sortAttr">attribute name</itc:parameter> <!-- Target (final) object sorting attribute name, must visible as the table column, otherwise ignored -->
  <itc:parameter name="sortOrder">DESC|ASC</itc:parameter>
</itc:query>

Object Details

Display all visible object attributes as a vertical table with Name:Value rows

<itc:details>
  <Object Selector>
</itc:details>

Counter

Object counter based on query - return the number of objects in the query result

<itc:counter>
  <Object Selector>
  <itc:parameter name="title">Label</itc:parameter> <!-- if specified displayed as: Label <Count> -->
</itc:counter>

Saved Search

<itc:savedsearch>
  <itc:parameter name="OBJECT_Id">Saved Search Object ID</itc:parameter>
  <Context Selector>
  <itc:parameter name="export">true|false</itc:parameter>   <!-- Columns reported based ListExport flag not TableView flag (default) -->
  <itc:parameter name="select">Comma-separated column Attributes</itc:parameter>   <!-- Specific Columns to display, supersedes "export" -->
</itc:savedsearch>

Audit Log

Report Audit Log events

<itc:auditlog>
  <Object Selector> <!-- If any objects matched, the auditlog will be queried for those objects, if none found and className is not specified, global tenant search is performed -->
  <itc:parameter name="severity">Min Severity</itc:parameter>   <!-- Minimum event severity to include, Optional -->
  <itc:parameter name="request">Request Name</itc:parameter>   <!-- Event Request (update,delete,maintenance,...), Optional -->
  <itc:parameter name="range">Range, see below</itc:parameter>
  <itc:parameter name="sortAttr">Timestamp|ObjectId|ObjectName|ObjectClass|AuthorId|AuthorName|Request|Severity</itc:parameter> <!- Optional, Default=Timestamp -->
  <itc:parameter name="sortOrder">DESC|ASC</itc:parameter>
</itc:auditlog>

Subscriptions

Report Tenant Subscriptions' effective subscribers' emails as a table

<itc:subscriptions />

Attribute Text

Display object attribute text based on the attribute Display format. For HTML report it is wrapped with <p>value</p>, for PDF: a paragraph created with the value (avoid HTML content - it is not converted to PDF)

<itc:attributetext>
  <itc:parameter name="name">EXTERNAL_ACTIVITY.Log</itc:parameter>
  <Object Selector>
</itc:attributetext>

Where

Object Selector:

 <itc:parameter name="OBJECT_Id">${context/OBJECT_Id}</itc:parameter><!-- If specified, the rest is ignored, Optional -->
 <itc:parameter name="className">Object Class</itc:parameter> <!-- Target Class Name, optional -->
 <itc:select name="AttrName" [oper="Operator"]>value</itc:select>
 <itc:select>...</itc:select>


Context Selector:

<itc:parameter name="context">Context ID</itc:parameter> <!-- Optional, if not specified see below →
<itc:context>  <!-- Optional, if not specified see above →
  <itc:parameter name="className">Object Class</itc:parameter> 
  <itc:select name="AttrName" [oper="Operator"]>Value</itc:select>
  <itc:select>...</itc:select>
<itc.context>

Operator: EQ|NE|GT|GE|LT|LE|MATCH|NOT_MATCH|IN|NOT_IN|NULL|NOT_NULL  default: EQ

Time Scale: MIN|5MIN|QUARTER_HOUR|HALF_HOUR|HOUR|DAY|WEEK|MONTH|QUARTER|YEAR

Range: 

  • YTD - year to date
  • QTD - quarter to date
  • MTD - month to date
  • WTD - week to date
  • DTD - day to date
  • M# - last # full month (M12 - last 12 month)
  • D# - last # full days  (D1 - yesterday, D7 - last 7 days)
  • H# - last # full hours
  • LY - Last year
  • LM - Last Month
  • LW - Last week
  • LD - Last Day/Yesterday
  • MH1 - First half (1-15) of the prior or current month (if current month day is after 15)
  • MH1P - First half (1-15) of the prior month (even if current month day is after 15)
  • MH2 - Second half (16-30/31) of the prior month

Time:   


Parameter width and height

For HTML reports Chart/Threshold parameters width and height now accept UOM: 100%, 5em, 10ex, 100px etc. If no UOM is provided and only the number is supplied the PX is assumed

Output type CSV

Reports now support CSV output. In this mode:

  • All graphical constructs are ignored
  • Charts/Thresholds are displayed as tables regardless of "table" parameter value
  • Headers (h1/h2/...) rendered as a line of text 
  • Other HTML (non itc:) markup is exploded but not rendered (if you specify <p><itc:chart>....</p>, the <itc:chart> will be rendered without any formatting associated with <p>)

Examples

The following example will produce a report that includes Availability (Table and Chart) for each SAP System with Development application role.

This work in both PDF and HTML mode (<pbr /> is a page-break and only rendered in PDF)

<itc:report xmlns:itc="urn:itconductor">
  <itc:parameter name="fontSize">4</itc:parameter>
  <h1>Development SAP Systems Availability Report</h1>
  <itc:section>
    <itc:parameter name="OBJECT_ClassName">SAP</itc:parameter>
    <itc:select name="APPLICATION_Role">DEV</itc:select>
    <pbr />
    <h2>${context/OBJECT_Name}</h2>
    <itc:threshold>
      <itc:parameter name="THRESHOLD_ObjectId">${context/OBJECT_Id}</itc:parameter>
      <itc:parameter name="THRESHOLD_AttributeName">OBJECT_Availability</itc:parameter>
      <itc:parameter name="table">false</itc:parameter>
      <itc:parameter name="width">100%</itc:parameter>
      <itc:parameter name="timeScale">HOUR</itc:parameter>
      <itc:parameter name="range">LD</itc:parameter>
    </itc:threshold>
    <itc:threshold>
      <itc:parameter name="THRESHOLD_ObjectId">${context/OBJECT_Id}</itc:parameter>
      <itc:parameter name="THRESHOLD_AttributeName">OBJECT_Availability</itc:parameter>
      <itc:parameter name="table">true</itc:parameter>
      <itc:parameter name="timeScale">HOUR</itc:parameter>
      <itc:parameter name="range">LD</itc:parameter>
    </itc:threshold>
  </itc:section>
</itc:report>