General Structure of Report Definitions

Default location: Automic\Release.Manager\ReportDefinitions

Report Definition XML File

The report definition has the following general structure:

<Report mainType="Application" 
        includeHistoricData="true" 
        tableName="GenericApp"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="report.xsd">
  
  <Type customType="Generic" typeVersion="5.0">
    <Property name="system_name" columnName="Name"/>
    <!-- Additional properties-->
  </Type>

  <Type customType="Major" typeVersion="4.0">
    <Property name="system_name" columnName="Name"/>
    <!-- Additional properties-->
  </Type>

  <Type customType="Tools" typeVersion="3.0">
    <Property name="system_name" columnName="Name"/>
    <!-- Additional properties-->
  </Type>

</Report>

Root element must be Report.

xmlns:xsi and xsi:noNamespaceSchemaLocation can be omitted.

This report definition specifies reporting for the following custom types:

  • Generic
  • Major
  • Tools

Report Elements

Report Element

The Report element represents the root element of the report definition and is mandatory.

  • mainType

    The main type of the entity on which the report is based.

    For each main type, you are required to create an individual report definition.

    Important! Check in CDA System Properties Reference, if your main type and its custom types are available in reports.

  • includeHistoricData

    In the report, you can find a record for each entity. For the case when a property changes, you can define whether the record is updated (no history available) or a new record is added (history available).

    Options:

    • True: in a change, a new record is created and added to the report table - together with the existing records, you can report all changes for an entity from the moment you created the reporting job

      Examples:

      • When a property changes, a new record is inserted
      • If an entity is deleted, a new record is inserted with empty values and the system_is_deleted column set to true
    • False: in a change, the existing record is overwritten with the most recent state. You find only one record per entity and the report table only includes data that reflects the current state of your entities

      Examples:

      • When a property changes, the corresponding record in the reporting table is updated with the new values
      • If an entity is deleted, the corresponding record is deleted from the reporting table too

    See also:Single Value Compared to Reference in System Properties.

  • tableName

    The name of the database table that will contain the reported data in the reporting database.

    Note: tableName is not validated. Therefore ensure that this name conforms to the underlying database naming convention. Otherwise the create report CLI command fails.

    Important! If you want to use reserved words as table names, you have to escape them. For ORACLE, table names and column names have a limit of 30 characters, longer names cause ORA-00972 error.

Type Elements

Within a single report that is defined by the Root element, you can export multiple custom types of a single base type. If you have multiple versions of a custom type, you have to specify all versions separately which should be included in the report.

Each type can have multiple property elements. A property element maps an object property with a column in the table.

Important! Within each Type element, a column name must be unique.

Note: A column may appear in one Type element but not in another.

  • Type

    • customType

      The name of the custom type.

    • typeVersion

      The version of your custom type.

  • Property

    For each custom type, you have to specify all properties which should be exported.

    • name

      The name of your property which should be exported. If the given property name is not found at runtime, a warning is logged and the column value is set to NULL.

      Note: All system properties start with system_. Properties that do not start with system_ are considered as custom properties .

      Mandatory: yes

    • columnName

      The name of the column in the reporting table that should hold the values of the property. The database column type is inferred automatically based on your type definition. If not set, the name of the property is used as column name.

      Important! CDA does not validate the column names, so if column names arenot valid for the underlying database, report creation fails.

      Mandatory: no

      Notes:

      • Properties of multiple types can refer to the same columns, if their types are the same data type.
      • If you want to use reserved words as column names, you have to escape them. For ORACLE, table names and column names have a limit of 30 characters, longer names cause ORA-00972 error.

    • type

      The type of the property (for example, Single line text) that determines the column type in the reporting table.

      The attribute should only be set for reference properties of related entities (for example, system_release.my_property), because the type cannot be determined automatically in these cases.

      See also:Data Types.

      Mandatory: no

Single Value Compared to Reference in System Properties

A single value is a primitive value like number or literal text.

Examples:

  • system_name is a text property
  • system_id is a number property

A reference property is a complex object which can also include other reference properties.

Examples:

For a component, system_application is a reference property of type Application, which is resolved to the application of the component.

  • To get the application name, you can use

    <Property name="system_application.system_name" columnName="AppName"/>

  • You can even access properties of references:

    <Property name="system_application.system_folder.system_name"
              columnName="AppFolderName"/>

Data Types

If you define the data type explicitly, the system tries to convert the property at runtime into that type. If you do not define the data type explicitly, the data type of a column is defined by the first property that you map to the column. If no explicit type is given and the type cannot be determined by the system automatically, Single line text is assumed as property type.

For extra property mappings to the same reporting table column, all extra values are converted to the implicit or explicit data type.

If a conversion fails, a NULL value is inserted.

For reference properties, the data type for the report column is taken from the last segment of the property name.

Example: system_application.system_name property results in an NVARCHAR(255) column, which is the type for the system_name column property.

Notes:

  • For Date and DateTime properties, date and timestamps are stored as UTC values in the reporting table.
  • For custom properties, the data type depends on the type of the custom property.

Default Fields for Reporting

You cannot add the following elements to a report definition as they are always added automatically:

  • system_id
  • system_custom_type (for custom-types of a main type only)
  • system_custom_type_version (for custom-types of a main type only)
  • system_date_changed
  • system_is_deleted

Also, a column ID is generated. ID is not the CDA object, but the unique identifier of the report entry and is used as the primary key of the report table. The CDA object id column is system_id.

The column names ID and system_id are reserved names. You cannot map those names as column names to any other property.

Example:

CDA rejects the report definition with the following property, as this report tries to redefine the system_id column:
<Property name="system_application.system_id" columnName="system_id"/>