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.

Attribute Name	Description
mainType	The main type of the entity on which the report is based. For each main type you are required to create a 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 will find only one record per entity and the report table will only include 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 form the reporting table too See also: Single Value Compared to Reference in System Properties below.
tableName	The name of the database table that will contain the reported data in the reporting database. Note: tableName will not be validated. Therefore ensure that this name conforms to the underlying database naming convention. Otherwise the create report CLI command will fail. Important! If you want to use reserved words as table names, you will have to escape them. For ORACLE, table names and column names have a limit of 30 characters, longer names will produce ORA-00972 error.

Type Elements

Within a single report 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’s 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.

Element Name	Attribute Name	Description
Type	customType	The name of your 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 .
	columnName (optional)	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 will not validate the column names, so if column names is not valid for the underlying database, report creation will fail. 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 will have to escape them. For ORACLE, table names and column names have a limit of 30 characters, longer names will produce ORA-00972 error.
	type (optional)	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 below.

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 will try to convert the property at run-time 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 will result in a NVARCHAR(255) column, which is the type for the system_name column property.

Notes:

• For Date and DateTime properties, date and time stamps 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

Additionally, a column ID is generated. ID is not the CDA object ID. It is 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. This means that you cannot map those names as column names to any other property.

Example:

CDA will reject 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"/>