Name

ChangeSynergy::ReportEntry


Description

The ChangeSynergy::ReportEntry class is used as part of a set of classes when a report is imported or exported from the server. All ReportEntry objects contain a QueryEntry object and one or more SubReportEntry objects. These set of objects make up a standard Change report configuration entry. This class represents a CCM_REPORT entry as shown below for the 'Column' report.

 [CCM_REPORT]
 	[NAME]Column[/NAME]
 	[QUERY]All CRs[/QUERY]
 	[PROBLEM_DEF]column_cr[/PROBLEM_DEF]
 	[EXPORT_FORMAT]HTML[/EXPORT_FORMAT]
 	[INCREMENTAL]true[/INCREMENTAL]
 	[INCREMENT_SIZE]20[/INCREMENT_SIZE]
 	[IMAGE_PATH]columnFormat.png[/IMAGE_PATH]
 	[CUSTOM_DISPLAY_ORDER]0[/CUSTOM_DISPLAY_ORDER]
 	[DESCRIPTION]
 		Custom report format that allows you to select a list 
 	 	of problem attributes. Problem number and status are linked to other forms.
 	 [/DESCRIPTION]
 [/CCM_REPORT]

While it may be possible to create all three of these classes by hand, it is best to just export a report, modify it and then import it, or export it to a file and modify it and then import it. While all of the settings in these three classes can be changed many of them should not be changed unless you are sure of what you are doing. Changing these items is just like changing the configuration file settings for the predefined system reports.

Example:

 eval
 {
 	$csapi->setUpConnection("http", "machine", 8600);
	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\machine\\ccmdb\\cm_database");
	#Construct a new Globals object.
	my $globals = new ChangeSynergy::Globals();
		
	#Export a CR report named 'Column' from the sysetm configuration 
	my $reportEntry = $csapi->exportAReport($aUser, "Column",  $globals->{PROBLEM_TYPE}, $globals->{SYSTEM_CONFIG});
	
	print "\nreportEntry->getName          : " . $reportEntry->getName();
	print "\nreportEntry->getBaseName      : " . $reportEntry->getBaseName();
	print "\nreportEntry->getReportTemplate: " . $reportEntry->getReportTemplate();
	print "\nreportEntry->getExportFormat  : " . $reportEntry->getExportFormat();
	print "\nreportEntry->getMaxQuery      : " . $reportEntry->getMaxQuery();
	print "\nreportEntry->getMaxString     : " . $reportEntry->getMaxString();
	print "\nreportEntry->getDescription   : " . $reportEntry->getDescription();
	print "\nreportEntry->getIncrementSize : " . $reportEntry->getIncrementSize();
	print "\nreportEntry->getIncremental   : " . $reportEntry->getIncremental();
	print "\nreportEntry->getStyle         : " . $reportEntry->getStyle();
	print "\nreportEntry->getCustomDisOrder: " . $reportEntry->getCustomDisplayOrder();
	print "\nreportEntry->getImagePath     : " . $reportEntry->getImagePath();
 };
 if ($@)
 {
	print $@;
 }

Method Summary

scalar getBaseName()
Gets the name of the report that this report is based off of. If not based off of any report then it will return the same thing as getName does.
scalar getCustomDisplayOrder()
Gets the order that an adhoc report format should be displayed in the interface starting from 0.
scalar getDescription()
Gets the description for the report.
scalar getExportFormat()
Gets export format of the report, this defines the file extention for the report results.
scalar getIncremental()
Gets if this report uses pagination or not, value is true or false.
scalar getIncrementSize()
Gets the number of items per page in a pagination report.
scalar getMaxString()
Gets the maximum number of characters to be retrieved for attributes with the TEXT data type.
scalar getMaxQuery()
Gets the maximum number of results from the database this report will allow to be returned.
scalar getName()
Gets the name of the report, in the configuration example above this is the data in the NAME tag. This is the name users will see in the reporting interface.
scalar getQueryEntry()
Gets the L object that represents the CCM_QUERY configuration definition this report is linked to.
scalar getReportTemplate()
Gets the name of the template that is loaded when the report name is clicked from the reporting interface.
scalar getStyle()
Gets the style type of the report, currently only used for charts and matrix reports.
array getSubReports()
Gets the array of L objects that define the PROBLEM_DEF, TASK_DEF and OBJECT_DEF entries for this report.
void setBaseName(scalar baseName)
Sets the name of the report that this report is based off of. For importing and exporting reports this does not need to be set as exporting and importing a report exports all the configuration entries so no base report entries need to be looked up.
void setCustomDisplayOrder(scalar baseName)
Sets the order that an adhoc report format should be displayed in the interface starting from 0.
void setDescription(scalar description)
Sets the description for this report, this is the text end users shall see in the reporting interface when they select the report.
void setExportFormat(scalar exportFormat)
Sets the export format of the report, this defines the file extention for the report results. For example, "HTML" or "TXT".
void setIncremental(scalar incremental)
Sets if this report uses pagination or not, value is true or false.
void setIncrementSize(scalar incrementSize)
Sets the number of items per page in a pagination report.
void setMaxString(scalar maxString)
Sets the maximum number of characters to be retrieved for attributes with the TEXT data type.
void setMaxQuery(scalar maxQuery)
Sets the maximum number of results this report will allow the query function to return.
void setName(scalar reportName)
Sets the name of the report, in the configuration example above this is the data in the NAME tag. This is the name users will see in the reporting interface.
void setQueryEntry(scalar queryEntry)
Sets the L object that represents the CCM_QUERY configuration definition this report is linked to.
void setReportTemplate(scalar reportTemplate)
Sets the name of the template that is loaded when the report name is clicked from the reporting interface. An example of a report template is "TrendWithBreakdown".
void setStyle(scalar style)
Sets the style type of the report, currently only used for charts and matrix reports.
void setSubReports(array subreports)
Sets the array of L objects that define the PROBLEM_DEF, TASK_DEF and OBJECT_DEF entries for this report.
void toXml(scalar xmlData)
Converts the ReportEntry, QueryEntry and all SubReportEntries into an XML string that can be saved out to the file system and reloaded to reconstuct the ReportEntry object.


Methods


getBaseName

Gets the name of the report that this report is based off of. If not based off of any report then it will return the same thing as getName does.

 Returns: scalar
	The name of the base report.


getCustomDisplayOrder

Gets the order that an adhoc report format should be displayed in the interface starting from 0.

 Returns: scalar
	The order an ad hoc report should be diplayed in the interface starting from 0.


getDescription

Gets the description for the report. The description is visible in the Change reporting interface when the user clicks on the report.

 Returns: scalar
	The description of the report.


getExportFormat

Gets export format of the report, this defines the file extention for the report results.

 Returns: scalar
	The export format, or file extension.


getIncremental

Gets if this report uses pagination or not, value is true or false.

 Returns: scalar
	True if the report uses pagination, false otherwise.


getIncrementSize

Gets the number of items per page in a pagination report.

 Returns: scalar
	The maximum number of items to display on a paginated report.


getMaxString

Gets the maximum number of characters to be retrieved for attributes with the TEXT data type.

 Returns: scalar
	The maximum number of characters to return for an attribute.


getMaxQuery

Gets the maximum number of results from the database this report will allow to be returned.

 Returns: scalar
	The maximum number of results to return.


getName

Gets the name of the report, this is the name that users will see in the Change reporting interface.

 Returns: scalar
	The name of the report.


getQueryEntry

Gets the QueryEntry object that represents the CCM_QUERY configuration definition this report is linked to.

 Returns: scalar
	The query entry for the report.


getReportTemplate

Gets the name of the template that is loaded when the report name is clicked from the reporting interface. A report template usually asks the user to supply more information before the report can be run. An example of a report template is "TrendWithBreakdown".

 Returns: scalar
	The name of the report template.


getStyle

Gets the style type of the report, currently only used for charts and matrix reports.

 Returns: scalar
	The style of the report.


getSubReports

Gets the array of SubReportEntry objects that define the PROBLEM_DEF, TASK_DEF and OBJECT_DEF entries for this report.

 Returns: array
	The array of subreport entries.


setBaseName

Sets the name of the report that this report is based off of. For importing and exporting reports this does not need to be set as exporting and importing a report exports all the configuration entries so no base report entries need to be looked up.

 Parameters:
	scalar: The name of the base report.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setBaseName("Column");


setCustomDisplayOrder

Sets the order that an adhoc report format should be displayed in the interface starting from 0. This setting only has any impact for report formats that are displayed when the "new" link is clicked in the interface.

 Parameters:
	scalar: What number the report should be displayed in.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setCustomDisplayOrder("12");


setDescription

Sets the description for the report, the text end users will see in the Change reporting interface.

 Parameters:
	scalar: The description for the report.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setDescription("HTML");


setExportFormat

Sets the export format of the report, this defines the file extention for the report results. For example, "HTML" or "TXT".

 Parameters:
	scalar: The export format type.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setExportFormat("HTML");


setIncremental

Sets if this report uses pagination or not, value is true or false.

 Parameters:
	scalar: True if the report uses pagination, false otherwise.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setIncremental("true");


setIncrementSize

Sets the number of items per page in a pagination report.

 Parameters:
	scalar: The maximum number of results to display per page on a pagination report.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setIncrementSize("20");


setMaxString

Sets the maximum number of characters an attribute with the data type of TEXT may return. If an attribute has more characters than the maximum the characters over the maximum will be truncated. If this setting is omitted then the report will use the MAX_STRING defined in pt.cfg file.

 Parameters:
	scalar: The maximum number characters allowed for TEXT types.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setMaxString("32000");


setMaxQuery

Sets the maximum number of results this report will allow the query function to return. If the query finds more results than the maximum and error will be returned to the user telling them that too many results were found. If this setting is omitted then the report will use the MAX_QUERY defined in pt.cfg file.

 Parameters:
	scalar: The maximum number of results to allow.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setMaxQuery("2000");


setName

Sets the name of the report, this is the name that users will see in the Change reporting interface. The report name must be unique or the csapiimportAReport will fail.

 Parameters:
	scalar: The name the report will have when it is imported.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setName("Imported Report");


setQueryEntry

Sets the QueryEntry object that represents the CCM_QUERY configuration definition this report is linked to. A report must have a query entry as the query entry contains the query string the report will use to be run.

 Parameters:
	scalar: The query entry that contains the query information for this report.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	my $queryEntry = new ChangeSynergy::QueryEntry();
	$queryEntry->setName("query");
	$queryEntry->setQueryString("()cvtype='problem')");
	$reportEntry->setQueryEntry($queryEntry);


setReportTemplate

Gets the name of the template that is loaded when the report name is clicked from the reporting interface. A report template usually asks the user to supply more information before the report can be run. An example of a report template is "TrendWithBreakdown".

 Parameters:
	scalar: The name of the report template.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setReportTemplate("TrendWithBreakdown");


setStyle

Sets the style type of the report, currently only used for charts and matrix reports. Valid values are VBarChart, HBarChart, LineChart, PieChart and Matrix.

 Parameters:
	scalar: The style of the report.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	$reportEntry->setStyle("VBarChart");


setSubReports

Sets the array of SubReportEntry objects that define the PROBLEM_DEF, TASK_DEF and OBJECT_DEF entries for this report. All reports must have at least one subreport entry.

 Parameters:
	array: The list of subreport entries.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	my @subReports = ();
	push @subReports, new ChangeSynergy::SubReportEntry(CCM_PROBLEM, CCM_TASK or CCM_OBJECT entry);
	$reportEntry->setSubReports(\@subreports);


toXml

Converts the ReportEntry, QueryEntry and all SubReportEntries into an XML string that can be saved out to the file system and reloaded to reconstuct the ReportEntry object.

 Returns: array
	The XML data representing the object.
 Example:
	
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	my $file = $reportEntry->getName() . ".xml";
		
	open(OUTPUT, ">$file");
	print(OUTPUT $reportEntry->toXml());
	close(OUTPUT);