IBM Rational Change Perl API

© Copyright IBM Corporation 2000, 2011
US Government Users Restricted Rights--Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents


What is the Rational Change Perl API?

The IBM® Rational® Change Perl API is a command line interface (CLI) to Rational Change. The Perl API can be run from both Windows and Unix. Rational Change Perl API scripts are easily called by other scripts/executables and require only a simple text editor to create. The Rational Change Perl API implements almost all of the features of the User interface, and a portion of the features of the Admin interface.

Where is the Rational Change Perl API located?

Rational Change ships and installs Perl version 5.8.6. Perl is installed into CHANGE_APP_HOME/WEB-INF/perl. The actual Rational Change Perl API is installed into CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/site_perl/5.8.6/ChangeSynergy. The command to execute Perl is not perl as per normal installations of Perl; the command is instead ratlperl

How do I use the Rational Change Perl API?

You must make the following changes in order to use the Rational Change Perl API.

1. Set environment variables.

The system path must include the location of Rational Change's Perl executable. On Windows the PERL5LIB environment variables must be empty and on UNIX it must be set two different directories. Finally on UNIX the LD_LIBRARY_PATH must be set to multiple directories one of which is platform specific. If any of these steps are skipped, the Rational Change API and Perl will not work.

2. Instruct Perl to include the Rational Change perl module csapi.

Csapi is the main module of the Rational Change Perl API, it is where all the methods for interacting with the Rational Change server are located.

Add the following line at the top of all Perl scripts written to use the Rational Change Perl API.

use utf8;
use ChangeSynergy::csapi;

3. Define the Rational Change server.

The script must know specific information about the Rational Change server in order to function correctly. First, create a new instance of the csapi module

my $csapi = new ChangeSynergy::csapi();

Now that the script has access to the csapi module, you can set up the connection to the Rational Change server. Identify the hostname, port number and protocol being used.

$csapi->setUpConnection("http://your_hostname:port/your_context");

4. Create a user object (apiUser)

This enables a user to successfully login to the Rational Change Server.

my $aUser = $csapi->Login("user name", "user's password", "Rational Change Role (interface)", "Database path");

Now the script is ready to fully implement and use the Rational Change Perl API.

How do triggers use the Rational Change Perl API?

When a trigger is fired, Rational Change calls the trigger and sends an XML document as the last argument to the trigger. This XML document contains basic information about the Rational Change server, such as the protocol, port number, and hostname. It also contains more detailed information about the trigger, such as the user's name, database, any modified attributes, and from and to states if the trigger is for a transition.

The Rational Change Perl API has a perl module to help retrieve all of this information from the XML document. This is the TriggerParser module.

You must make the following changes in order to use the Rational Change Perl API.

1. Create a reference to the module.

In order to use this module in a perl script, you must reference it with a "use" statement in the script.

use ChangeSynergy::TriggerParser;

2. Create an instance of the TriggerParser module passing in as the only parameter the location of the XML document.

my $trigger = new ChangeSynergy::TriggerParser($ARGV[-1]);

In the above code, the TriggerParser module is created by passing in $ARGV[-1]. This is Perl syntax for passing the last argument that was supplied to the script when it was executed. The last argument to all triggers is always going to be the XML document.

3. Access the Rational Change API, as required.

Not all trigger scripts require access to the Rational Change API. It depends on what type of actions the script needs to perform. If the script needs to call back to the Rational Change server, then access to the Rational Change API is needed. The steps to do this are nearly identical to the steps used in "How do I use the Rational Change Perl API?". Note: Rational Change takes care of setting the environment variables (PATH and PERL5LIB) correctly when calling a trigger, so this step can be skipped.

Add the following line at the top of all Perl scripts written to use the Rational Change Perl API.

use utf8;
use ChangeSynergy::csapi;


This line tells Perl that it must include the Rational Change perl module csapi. Csapi is the main module of the Rational Change Perl API; it is where all the methods for interacting with the Rational Change server are located.

4. Define the Rational Change server.
The script must also know specific information about the Rational Change server in order to function correctly. First, create a new instance of the csapi module.

my $csapi = new ChangeSynergy::csapi();

Now that the script has access to the csapi module, you can set up the connection to the Rational Change server. All of this information is passed into the trigger via the XML document. Identify the URL to be used.

$csapi->setUpConnection($trigger->get_base_url());

5. Create a user object (apiUser).
Since the user that fired the script has already logged in, this user's information can be used to create the user object.

my $user = new ChangeSynergy::apiUser($trigger->get_user(), "", $trigger->get_role(), $trigger->get_token(), $trigger->get_database());

Now the script is ready to fully implement and use the Rational Change Perl API.

How do I run a query/report and save it?

One of the most useful features of the Rational Change API is its ability to run queries and reports. There are several methods available for running queries and reports, just as in the Rational Change web interface. The following example shows how to use the Rational Change API to run a report with a custom query and save the results to a file. Read through the API documentation get further information on different types of queries and reports that can be run.
	
	#Include the Rational Change csapi module.
	use utf8;
	use ChangeSynergy::csapi;

	#Create a new instance of the csapi object.
	my $csapi = new ChangeSynergy::csapi();

	#Create the queryString variable.  Query for all problems that are assigned to u00001.
	my $queryString = "(cvtype='problem') and ((resolver = 'u00001') and (crstatus='assigned'))";

	#Eval block is used for error handling.
	eval
	{
		#Setup the connection parameters for connecting to the Rational Change Server.
		#Note however that no connection to the server is made at this point.
		$csapi->setUpConnection("http://your_hostname:port/your_context");

		#Login to the ChangeSynegy server. (user, password, role, database);
		my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\your_hostname\\ccmdb\\cs1");

		#Run the ImmediateQueryHtml method to recieve an HTML page.  
		#Pass in the user object, report name, query string, query name and the title for the report.
		my $results = $csapi->ImmediateQueryHtml($aUser, "Basic Summary", $queryString, undef, "Report of my assigned CR's");

		#Open a file called report.html for output.
		open (OUTPUT, ">report.html");

		#Write the contents of the returned result to the report.html file.
		print(OUTPUT $results->getResponseData());

		#Close the output stream.
		close(OUTPUT);
	};

	#If any errors occured, print them to the screen.
	if ($@)
	{
		print $@;
	}
	

How do I run a query/report and get information from it?

In addition to running queries/reports and saving of HTML files, the Rational Change API can run queries/reports in a data format view. What this means is that the results are not returned in an HTML page, but as an XML document which is parsed automatically by the Rational Change API. This allows scripts to run reports, examine in the data returned by the report and act on the data if needed.

The following example shows how to use the Rational Change API to run a data report with a custom query and a custom-defined list of attributes to return. The script then reads all of the returned data and displays it to the screen in a readable format. This shows how to extract useful information from a data report.

	
	#Include the Rational Change csapi module.
	use utf8;
	use ChangeSynergy::csapi;

	#Create a new instance of the csapi object.
	my $csapi = new ChangeSynergy::csapi();

	#Create the queryString variable.  Query for all problems that are assigned to u00001.
	my $queryString = "(cvtype='problem') and ((resolver = 'u00001') and (crstatus='assigned'))";

	#Create the requested attributes variable. 
	my $requestedAttrs = "problem_number|crstatus|problem_synopsis|severity";

	#Eval block is used for error handling.
	eval
	{
		#Setup the connection parameters for connecting to the Rational Change Server.
		#Note however that no connection to the server is made at this point.
		$csapi->setUpConnection("http://your_hostname:port/your_context");

		#Login to the ChangeSynegy server. (user, password, role, database);
		my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\your_hostname\\ccmdb\\cs1");

		#Run the QueryData method to recieve a data report.  
		#Pass in the user object, report name, query string, query name, report title, template name and attribute list.
		my $results = $csapi->QueryData($aUser, "Basic Summary", $queryString, undef, "Example Data report", undef, $requestedAttrs);

		print "\nTotal number of CR's assigned to u00001: " . $results->getDataSize() . "\n\n";

		#Loop over each returned result, in this case each problem
		for(my $i = 0; $i < $results->getDataSize(); $i++)
		{
			#Get the data for the current problem
			my $reportData = $results->getDataObject($i);

			#Loop over each returned attribute
			for(my $j = 0; $j < $reportData->getDataSize(); $j++)
			{
				#Get the data for the current attribute
				my $attributeData = $reportData->getDataObject($j);

				#Print the attribute name and its value
				print $attributeData->getName() . ": " . $attributeData->getValue() . "\n";
			}

			#Print a blank line between each problem
			print "\n";
		}
	};

	#If any errors occured, print them to the screen.
	if ($@)
	{
		print $@;
	}
	
Below are the results of running this script.
	
	Total number of CR's assigned to u00001: 2

	problem_number: 1
	crstatus: assigned
	problem_synopsis: Create a new lifecylce image for the internal process.
	severity: Showstopper

	problem_number: 2
	crstatus: assigned
	problem_synopsis: Add a new state to the internal lifecycle.f
	severity: Medium
	

How should I manage my triggers?

The default triggers that are shipped with Rational Change are located in CHANGE_APP_HOME/WEB-INF/wsconfig/triggers. New triggers that are created should not be placed directly into this directory. Triggers should populate the CHANGE_APP_HOME/WEB-INF/wsconfig/triggers directory via a process package or a custom package, depending upon how the triggers are to be used.

If the new triggers are specific to a lifecycle, then they should be placed in a package template for that lifecycle. This way, when the lifecycle is merged with the package template during package creation, the generated package will have the correct scripts contained within it. When this package is installed, the scripts will be installed in the correct location. By the same token, when the package is removed, the scripts will be removed as well.

On the other hand, if the new triggers are not specific to a lifecycle (more general in nature), then they should be placed in a separate package. This package should be installed so the scripts will be available for use by the currently installed or soon-to-be-installed CR Process.

Using this method will help you keep track of which scripts were shipped and which were installed separately. It also allows the run area to be updated by the correct means, which is by the package installer. This helps prevent the accidental deletion of a trigger and keeps the run area in a more controlled environment.

How do I run triggers asynchronously?

What does it mean to run a trigger asynchronously? This means that the trigger will be fired off in a separate thread and the end user will not have to wait for the trigger to be completed before the server responds. For example, a post modify trigger that sends email would normally make the user wait until the email has been formulated and sent before the user can perform their next action. But if the trigger is run asynchronously, the user will not be impacted by the time it takes the trigger fire and complete.

Only post-triggers should be made asynchronous; post modify, post submit and post transition. Pre-triggers should not be made asynchronous as the return code from the trigger has an impact on if the action is successful or not.

To make a trigger run asynchronously add async: to the beginning of the trigger.
	
	async:perl crAssignEmail.pl
	

How do I ensure the proper character encoding is used?

Rational Change uses the UTF-8 character encoding, and Perl scripts and triggers must do the same to prevent corruption of non-ASCII characters. There are two steps to doing this:
  1. Add the following line at the top of all Perl scripts and triggers:
    use utf8;
  2. Save the script or trigger file as UTF-8 in your text editor.

Helpful trigger debugging tips

When a trigger is fired in Rational Change, an XML file is created in the file system. This file is created in CHANGE_APP_HOME/WEB-INF/wsconfig/tmpdir and is deleted after the script has finished executing. However, when Rational Change is running in "Debug" mode, these XML files are not deleted. Running in debug mode also displays extra information about a trigger when it is fired.

To take advantage of this capability:

1. Open an Admin window and show the debug tab, then open a User window.

2. Before performing the action which will cause the trigger to fire, turn on debugging and clear the log file.

3. Perform the action and turn off debugging.
This leaves the log file with information about the event and the trigger, and it leaves the XML file on the operating system. The XML file contains the user's name which caused the trigger to fire, and a sequence of random numbers. Its best to rename this to something easy to remember.

4. Start the script from the command line. This makes it easier and much faster to fix syntax errors and other programming errors without having to make the trigger fire from the GUI every time.

5. After the script executes completely with no errors, check the work the trigger performed in the GUI to make sure it is accurate.

Also note that any messages printed to standard out or standard error during the execution of a trigger will be printed to the pt.log file. This can be used for debugging, or as general logging for the trigger.

Perl API changes between releases (since 4.7)

Goto version: 

5.3.0.2, 5.3.0.1, 5.3, 5.2.0.5, 5.2.0.4, 5.2.0.3, 5.2.0.2, 5.2.0.1, 5.2, 5.1, 5.0
Release Type of Change Affected APIs
5.3.0.1 to 5.3.0.2 None  
5.3 to 5.3.0.1 None  
5.2 to 5.3 Added All fix pack changes from the previous release.
ExportProjectSecurityData
ImportProjectSecurityData
5.2.0.4 to 5.2.0.5 None  
5.2.0.3 to 5.2.0.4 Added reloadAppProperties
AddUser
AddUsers
5.2.0.2 to 5.2.0.3 None  
5.2.0.1 to 5.2.0.2 None  
5.2 to 5.2.0.1 Added addFolder
createReport
deleteFolder
deleteReport
exportAReport
exportReportsFromFolder
getFolderSecurityRule
importAReport
listFolders
moveFolderMembers
renameFolder
setFolderSecurityRule
SwitchUser
Modified The variables $url_to_connect, $queryConfigType and $reportConfigType were global variables of util.pm. They are moved to csapi class so they are instance variables of the csapi class.
5.1 to 5.2 Added createProcessPackage
Modified setUpConnection(protocol, host, port) deprecated; replaced with setUpConnection(url)
5.0 to 5.1 Removed AttributeModifyTaskData
Modified Added an optional new paramater to ToggleDebug, a boolean called enable, to explicitly set the state rather than toggle it.
Use ratlperl.
4.7 to 5.0 Added GetDatabaseSettings
GetHostSettings
GetListBoxDefaultValue
Logout
ServerVersion
SyncDatabase
Deprecated CreateUserSecurityData (does nothing except return deprecated message)
Removed ImportUsersFromAllDatabases
ImportUsersFromCSLDAPSserver
ImportUsersFromAFile
AddUser
AddUsers
ResetLDAPPool

API - ExportProjectSecurityData

Exports the project security definitions (including roles and global assignments) from RDS to an LDIF file: CHANGE_APP_HOME/WEB-INF/wsconfig/tmpdir/import_<current date and time>.ldif. This file may be imported via the API ImportProjectSecurityData. Only Rational Change Admin users can use this API.
Parameters:
	apiUser aUser : The current api user's login data..

Returns: apiData
	Message about the success or failure of the export.
 
Example:

Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");

	my $tmpstr = $csapi->ExportProjectSecurityData($aUser);
	print $tmpstr->getResponseData() . "\n";
};

if ($@)
{
	print $@;
}

API - ImportProjectSecurityData

Imports the data from an LDIF file created through ExportProjectSecurityData to the RDS connected to Rational Change. The file must reside in CHANGE_APP_HOME/WEB-INF/wsconfig/tmpdir. Only Rational Change Admin users can use this API.
Parameters:
	apiUser aUser : The current api user's login data.
	scalar  importFileName: The name of the LDIF file to be imported.
	scalar  isUpdate: "true" to update / add the data to RDS, "false" to just add new data to RDS and not update the existing data.

Returns: apiData
	Message about the success or failure of the import.
 
Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");

	my $tmpstr = $csapi->ImportProjectSecurityData($aUser, "import_12_07_2010_12_41_12.ldif", true);
	print $tmpstr->getResponseData() . "\n";
};

if ($@)
{
	print $@;
}

API - AddUser

Add a new user to both the LDAP server and the Rational Synergy database with the given set of Rational Synergy roles. The new user can login in after this call completes.
The return result is an instance of the L<apiData> class.

Note: DO NOT call this function in a loop. Instead use the L<AddUsers|"AddUsers">() api function.
Parameters:
	apiUser aUser   : The current api user's login data.
	apiUser aNewUser: The new user's data.

Returns: apiData
	the return message from the server.
 
Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");
	
	my $aNewUser = new ChangeSynergy::apiUser("jsmith", "password", "developer|ccm_admin|pt_admin",
											  "\\\\your_hostname\\ccmdb\\cm_database");
	
	my $tmpstr = $csapi->AddUser($aUser, $aNewUser);
};

if ($@)
{
	print $@;
}

API - AddUsers

Add a set of new users to both the LDAP server and the Rational Synergy database with the given set of Rational Synergy roles. The new users can login in after this call completes.
The return result is an instance of the L<apiData> class.
Parameters:
	apiUser  aUser   : The current api user's login data.
	@apiUser aNewUser: A array of new user data
	scalar   iCount  : The size of the array of new users.

Returns: apiData
	the return message from the server.
 
Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");

	my $i;
	my $j=100;

	my @newUsers;

	for($i=0; $i < $j; $i++)
	{
		push @newUsers, new ChangeSynergy::apiUser("ATestUser" . $i ,"ATestUser",
												   "developer|ccm_admin|pt_admin",
												   "\\\\your_hostname\\ccmdb\\cm_database");
	}

	my $tmpstr = $csapi->AddUsers($aUser, \@newUsers, $j);
};

if ($@)
{
	print $@;
}

API - reloadAppProperties

Reloads the files WEB-INF/wsconfig/system/app.properties and WEB-INF/wsconfig/system/app.user.properties.
The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser: The current API user's login data.

Returns: apiData
	the return message from the server.
 
Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");

	my $tmpstr = $csapi->reloadAppProperties($aUser);
};

if ($@)
{
	print $@;
}

API - addFolder

Adds a new empty query, report format or report folder to the server. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser     : The current api user's login data.
	scalar  folderName: The name of the folder to add.
	scalar  objectType: The object type for the folder.
	scalar  formatType: The format type of the folder: report, query or report format.
	scalar  configType: The configuration location for the report.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE

Valid format types (Constants defiend in Globals.pm):
 		QUERY
        REPORT
        REPORT_FORMAT
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE
        
Returns: apiData
	the return message from the server.
 
Example:
	
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\machine\\ccmdb\\cm_database");
	
	my $globals = new ChangeSynergy::Globals();
	
	#Create a new shared CR Report folder called 'API Folder'.
	my $addResults = $csapi->addFolder($aUser, "API Folder", $globals->{PROBLEM_TYPE}, $globals->{REPORT}, $globals->{SHARED_PROFILE});
	print $addResults->getResponseData();
};

if ($@)
{
	print $@;
}

API - createReport

Create a new Change report that is based off of an existing Change report. The return result is an instance of the L<apiData> class.
The ChangeSynergy::CreateReportDefinition class is used with the L<csapi> createReport API to create new Change reports based off of an already existing report.
Parameters:
	apiUser aUser              : The current api user's login data.
	scalar  reportDefinition   : An instance of a ChangeSynergy::CreateReportDefinition object.
	scalar  objectType         : The object type the report is querying for.
	scalar  configType         : The configuration location the report will end up in, valid types are user and shared only.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        USER_PROFILE

Returns: apiData
	results on if the creation was successful.

Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\machine\\ccmdb\\cm_database");
	
	#Create an instance of the CreateReportDefinition class.
	my $reportDef = new ChangeSynergy::CreateReportDefinition();

	#Set the required attributes.
	$reportDef->setName("API Created Report");
	$reportDef->setBaseReport("Column");
	$reportDef->setQueryString("(cvtype='problem') and (crstatus='entered')");
	
	#Set optional attributes
	$reportDef->setDescription("This report was created via the Perl API");
	$reportDef->setIncrementSize(7); #Only see 7 items per page.
	$reportDef->setFolderName("API Folder"); #Place the report into a folder named 'API Folder'
	
	#Change the list of attributes from a column report. Initial attributes are problem_number, crstatus and problem_synopsis.
	#Changing to just be problem_number and enterer.
	my @attributeLists = ();
	push @attributeLists, "problem_number:0:false|enterer:1:false";
	$reportDef->setAttributes(\@attributeLists);
	
	#Sort first by enterer as a string and secondarily sort the problem number.
	my @sortOrderList = ();
	push @sortOrderList, "enterer:string:A|problem_number:intb:A";
	$reportDef->setSortOrder(\@sortOrderList);
	
	#Create an instance of the Globals calls.
	my $globals = new ChangeSynergy::Globals();
	
	#Call the 'createReport' API and add the new report to the Shared CR queries.
	$csapi->createReport($aUser, $reportDef, $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
};

if ($@)
{
	print $@;
}

API - deleteFolder

Delete a query, report format or report folder and all members from the server. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser     : The current api user's login data.
	scalar  folderName: The name of the folder to delete.
	scalar  objectType: The object type for the folder.
	scalar  formatType: The format type of the folder: report, query or report format.
	scalar  configType: The configuration location for the report.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE

Valid format types (Constants defiend in Globals.pm):
 		QUERY
        REPORT
        REPORT_FORMAT
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE
        
Returns: apiData
	the return message from the server.
 
Example:
	
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\machine\\ccmdb\\cm_database");
	
	my $globals = new ChangeSynergy::Globals();
	
	#Delete a shared CR Report folder called 'API Folder'.
	my $deleteResults = $csapi->deleteFolder($aUser, 'API Folder', $globals->{PROBLEM_TYPE}, $globals->{REPORT}, $globals->{SHARED_PROFILE});
	print $deleteResults->getResponseData();
};

if ($@)
{
	print $@;
}

API - deleteReport

Delete a CR or task report from a users preferences or from shared data. Will throw an exception if the named report cannot be found to be deleted. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser      : The current api user's login data.
	scalar  reportName : The name of the report to delete.
	scalar  objectType : The object type for the report.
	scalar  configType : The configuration location for the report, valid types are user and shared only.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        USER_PROFILE
 
Returns: apiData
	The delete status message.
	
Example:
 
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\machine\\ccmdb\\cm_database");

	my $globals = new ChangeSynergy::Globals();
	
	#Delete a CR report named 'My column report' from the shared preferences and print the results.
	my $deleteResults = $csapi->deleteReport($aUser, "My column report", $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	print $deleteResults->getResponseData();
};

if ($@)
{
	print $@;
}

API - exportAReport

Export a named CR or task report from either the shared preferences or a users preferences. The return result is an instance of the L<ReportEntry> class.
Parameters:
	apiUser aUser      : The current api user's login data.
	scalar  reportName : The name of the report to export from the server.
	scalar  objectType : The object type for the report.
	scalar  configType : The configuration location for the report.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE
        
Returns: ReportEntry
	a report entry object which contains all the information about a report.
 
Example 1:
 	
#Print all data about a report.
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	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 'My Report' from the shared preferences 
	my $reportEntry = $csapi->exportAReport($aUser, "My Report",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	
	#Print all information about the report, query and subreport.
	print "--------------- Report Entry ---------------------\n";
	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();
	
	print "\n\n";
	print "--------------- Query Entry ---------------------\n";
	my $queryEntry = $reportEntry->getQueryEntry();

	print "Name        : " . $queryEntry->getName() . "\n";
	print "Query String: " . $queryEntry->getQueryString() . "\n";
	print "Desc        : " . $queryEntry->getDescription() . "\n";
	print "Prompting   : " . $queryEntry->getPromptingQueryXml() . "\n";
	print "Template    : " . $queryEntry->getTemplate() . "\n";
	
	print "--------------- Sub Report Entries ---------------------\n";
	
	my @subreports = $reportEntry->getSubReports();
	
	for my $subReportEntry (@subreports)
	{
		print "--------------- Sub Report Entry ---------------------\n";
		print "getName                  :" . $subReportEntry->getName() . "\n";
		print "getMainTemplate          :" . $subReportEntry->getMainTemplate() . "\n";
		print "getHeaderTemplate        :" . $subReportEntry->getHeaderTemplate() . "\n";
		print "getAttributeTemplate     :" . $subReportEntry->getAttributeTemplate() . "\n";
		print "getImageTemplate         :" . $subReportEntry->getImageTemplate() . "\n";
		print "getGroupTemplate         :" . $subReportEntry->getGroupTemplate() . "\n";
		print "getAutoAttributeTemplate :" . $subReportEntry->getAutoAttributeTemplate() . "\n";
		print "getFooterTemplate        :" . $subReportEntry->getFooterTemplate() . "\n";
		print "getGroupBy               :" . $subReportEntry->getGroupBy() . "\n";
		print "getCustomWslet           :" . $subReportEntry->getCustomWslet() . "\n";
		print "getXmlContent            :" . $subReportEntry->getXmlContent() . "\n";
		print "getSpanAttributeTemplate :" . $subReportEntry->getSpanAttributeTemplate() . "\n";
		print "getLabelTemplate         :" . $subReportEntry->getLabelTemplate() . "\n";
		print "getAutoLabelTemplate     :" . $subReportEntry->getAutoLabelTemplate() . "\n";
		print "getAttributes            :" . $subReportEntry->getAttributes() . "\n";
		print "getSortOrder             :" . $subReportEntry->getSortOrder() . "\n";
		print "getRelation              :" . $subReportEntry->getRelation() . "\n";
		print "getDefinitionType        :" . $subReportEntry->getDefinitionType() . "\n\n";
	}
};

if ($@)
{
	print $@;
}
	
Example 2:
 
#Save report XML to file.
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	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 'My Report' from the shared preferences 
	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);
};

if ($@)
{
	print $@;
}

Example 3:
 
#Load saved XML results back into a L<ReporEntry> object.

my $file = "report.xml";
open (INPUTFILE, "$file") or die "Could not open the file!";
my $filecontents = "";
my $buffer = "";

while ($buffer = readline *INPUTFILE)
{
	$filecontents .= $buffer;
}

close(INPUTFILE);

my $reportEntryFactory = new ChangeSynergy::ReportEntryFactory();
my $reportEntry = $reportEntryFactory->createReportEntryFromXml($filecontents);

API - exportReportsFromFolder

Export all of the CR or task reports from a named folder in either the shared preferences or a users preferences. The return result is an array of L<ReportEntry> classes.
Parameters:
	apiUser aUser      : The current api user's login data.
	scalar  folderName : The name of the folder to export all report from.
	scalar  objectType : The object type for the report.
	scalar  configType : The configuration location for the report.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

Returns: ReportEntry
	an array of report entry objects which contains all the information about each report.
 
Example:
 	
#Print all data about a report.
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\machine\\ccmdb\\cm_database");

	#Construct a new Globals object.
	my $globals = new ChangeSynergy::Globals();
	
	#Export all CR reports from the folder 'My Folder' from the shared preferences 
	my @reportEntries = $csapi->exportReportsFromFolder($aUser, "My Folder",  $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
	
	foreach my $reportEntry (@reportEntries)
	{
		#See the exportAReport above or the L<ReportEntry> class for how to interact with a ReportEntry object.
	}
};

if ($@)
{
	print $@;
}

API - getFolderSecurityRule

Gets the folder security information for a given folder. The folder security information consists of the name of the folder, the read security members and the write security members. The return result is an instance of the L<FolderSecurityRule> class.
Parameters:
	apiUser aUser      : The current api user's login data.
	scalar  folderName : The name of the folder to get the security for.
	scalar  objectType : The object type for the folder.
	scalar  formatType : The format type of the folder: report, query or report format.
	scalar  configType : The configuration location for the report.

Returns: FolderSecurityRule
	a FolderSecurityRule object that represents the rule.
 
Example:
 
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\angler\\ccmdb\\cm_database");
	my $globals = new ChangeSynergy::Globals();
	
	#Get the folder security rule for the "all" CR Shared query folder.
	my $folderRule = $csapi->getFolderSecurityRule($aUser, "", $globals->{PROBLEM_TYPE}, $globals->{QUERY},
					 $globals->{SHARED_PROFILE});
	
	print "Folder Name: " . $folderRule->getFolderName() . "\n";
	
	my @readMembers = $folderRule->getReadMembers();

	print "Current readers \n";
	
	foreach my $member (@readMembers)
	{
		print "Reader: '$member'\n";
	}
	
	print "Finished printing readers: \n";
	
	my @writeMembers = $folderRule->getWriteMembers();

	print "Current writers: \n";
	
	foreach my $member (@writeMembers)
	{
		print "Writer: '$member'\n";
	}
	
	print "Finished printing writers: \n";
};

if ($@)
{
	print $@;
}

API - importAReport

Import a Change report that was exported using either the exportAReport or exportReportsFromFolder APIs. If the name of the report to import already exists on the server then this method will fail and throw an exception. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser          : The current api user's login data.
	ReportEntry reportEntry: A report entry that contains all the information about a report.
	scalar  objectType     : The object type for the report.
	scalar  configType     : The configuration location for the report, valid types are user and shared only.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        USER_PROFILE

Returns: apiData
	information on if the import was successful or not.
 
Example 1:

#Create a copy of an existing report and change the query.
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\machine\\ccmdb\\cm_database");
	my $globals = new ChangeSynergy::Globals();
	
	#Export the 'Column' report from the system config data.
	my $reportEntry = $csapi->exportAReport($aUser, "Column",  $globals->{PROBLEM_TYPE}, $globals->{SYSTEM_CONFIG});
	
	#Change the name
	$reportEntry->setName("My column report");
	
	#Set a new query string in the query entry.
	$reportEntry->getQueryEntry->setQueryString("(cvtype='problem') and (crstatus='assigned')");
	
	#Get the subReports from the report entry.
	my @subReports = $reportEntry->getSubReports();
	
	#The column output only has a single subreport definition, CCM_PROBLEM.
	my $subReport = $subReports[0];
	
	#Get the original attributes and append submitter and severity as new attributes, must be in config file format.
	$subReport->setAttributes($subReport->getAttributes() . "|submitter:3:false|severity:4:false");

	#Import the report back to the server.
	my $result = $csapi->importAReport($aUser, $reportEntry, $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
};

if ($@)
{
	print $@;
}
	
Example 2:

#Import a report from a file.
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\machine\\ccmdb\\cm_database");

	#Open a file named 'report.xml' and read in all the contents.
	my $file = "report.xml";
	open (INPUTFILE, "$file") or die "Could not open the file!";
	my $filecontents = "";
	my $buffer = "";
	
	while ($buffer = readline *INPUTFILE)
	{
		$filecontents .= $buffer;
	}
	
	close(INPUTFILE);
	
	#Create a new instance of the ReportEntryFactory so we can create our new data from the XML data read from file.
	my $reportEntryFactory = new ChangeSynergy::ReportEntryFactory();
	my $reportEntry = $reportEntryFactory->createReportEntryFromXml($filecontents);
	
	#Import the report back to the server.
	my $result = $csapi->importAReport($aUser, $reportEntry, $globals->{PROBLEM_TYPE}, $globals->{SHARED_PROFILE});
};

if ($@)
{
	print $@;
}

API - listFolders

Returns a list of all query, report format or report folders under a top level folder. The return result is an instance of the L<apiListObject> class.
Parameters:
	apiUser aUser        : The current api user's login data.
	scalar  objectType   : The object type for the root folder.
	scalar  formatType   : The format type of the root folder: report, query or report format.
	scalar  configType   : The configuration location for the root folder.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE

Valid format types (Constants defiend in Globals.pm):
 		QUERY
        REPORT
        REPORT_FORMAT
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE
        
Returns: apiListObject
	the list of folders under a root folder.
 
Example:
	
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\machine\\ccmdb\\cm_database");
	
	my $globals = new ChangeSynergy::Globals();
	
	#Get a list of all the shared CR report folders.
	my $folders = $csapi->listFolders($aUser, $globals->{PROBLEM_TYPE}, $globals->{REPORT}, $globals->{SHARED_PROFILE});

	for (my $i = 0; $i < $folders->getListSize(); $i++)
	{
		print $folders->getLabel($i) . "\n";
	}
};

if ($@)
{
	print $@;
}

API - moveFolderMembers

Moves members of a query, report format or report folder to a new folder of the same type. The server will find the current folder the reports are a member of an move them to the newly specified folder. All members in the list must exist for any move to be completed. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser        : The current api user's login data.
	scalar  folderName   : The name of the folder to move the report too.
	scalar  memberList   : A pipe delimited list of reports to move from one folder to another.
	scalar  objectType   : The object type for the folder.
	scalar  formatType   : The format type of the folder: report, query or report format.
	scalar  configType   : The configuration location for the report.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE

Valid format types (Constants defiend in Globals.pm):
 		QUERY
        REPORT
        REPORT_FORMAT
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE
        
Returns: apiData
	the return message from the server.
 
Example:
	
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\machine\\ccmdb\\cm_database");
	
	my $globals = new ChangeSynergy::Globals();
	
	#Moves the reports 'API Test 1' and 'API Test 2' to the folder 'API Folder'.
	my $moveResults = $csapi->moveFolderMembers($aUser, "API Folder", "API Test 1|API Test 2", $globals->{PROBLEM_TYPE}, $globals->{REPORT}, $globals->{SHARED_PROFILE});
	print $moveResults->getResponseData() . "\n";
};

if ($@)
{
	print $@;
}

API - renameFolder

Renames a query, report format or report folder on the server. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser        : The current api user's login data.
	scalar  folderName   : The current name of the folder.
	scalar  newFolderName: The new name for the folder.
	scalar  objectType   : The object type for the folder.
	scalar  formatType   : The format type of the folder: report, query or report format.
	scalar  configType   : The configuration location for the report.

Valid object types (Constants defiend in Globals.pm):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE

Valid format types (Constants defiend in Globals.pm):
 		QUERY
        REPORT
        REPORT_FORMAT
 
Valid configuration types (Constants defiend in Globals.pm):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE
        
Returns: apiData
	the return message from the server.
 
Example:
	
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\machine\\ccmdb\\cm_database");
	
	my $globals = new ChangeSynergy::Globals();
	
	#Renames a shared CR Report folder called 'API Folder' to 'API Folder Renamed'
	my $renameResults = $csapi->renameFolder($aUser, "API Folder", "API Folder Renamed", $globals->{PROBLEM_TYPE}, $globals->{REPORT}, $globals->{SHARED_PROFILE});
	print $renameResults->getResponseData();
};

if ($@)
{
	print $@;
}

API - setFolderSecurityRule

Sets the folder security information for a given folder. The folder security information consists of the name of the folder, the read security members and the write security members. You can also empty the rule by supplying the folder name with no readers or writers. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser            aUser      : The current api user's login data.
	FolderSecurityrule folderRule : The folder security rule object for the folder.
	scalar             objectType : The object type for the folder.
	scalar             formatType : The format type of the folder: report, query or report format.
	scalar             configType : The configuration location for the report.

Returns: apiData
	a apiData with a message about the success or failure of the update.
 
Example:
 
my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\angler\\ccmdb\\cm_database");
	my $globals = new ChangeSynergy::Globals();
	
	#Get the folder security rule for the "all" CR Shared query folder.
	my $folderRule = $csapi->getFolderSecurityRule($aUser, "", $globals->{PROBLEM_TYPE}, $globals->{QUERY},
					 $globals->{SHARED_PROFILE});
	
	$folderRule->addReadMember("someone");
	$folderRule->addWriteMember("someone else");
	
	my $result = $csapi->setFolderSecurityRule($aUser, $folderRule, $globals->{PROBLEM_TYPE}, $globals->{QUERY}, $globals->{SHARED_PROFILE});
	print $result->getResponseData() . "\n";
};

if ($@)
{
	print $@;
}

API - SwitchUser

Allows the local admin user to switch to an arbitrary user. The return result is an instance of the L<apiUser> class.
Parameters:
    apiUser localAdminUser: The login data of the local admin user.
	scalar targetUserName : The name of the target user.
	scalar targetRole     : The role (interface) for the target user.
	scalar targetDatabase : The IBM Rational Synergy database path for the user.

Returns: apiUser
	a new instance of a apiUser class with the specified information.

Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $localAdminUser = $csapi->Login("admin", "localAdminPassword", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");
	
	my $aTargetUser = $csapi->SwitchUser($localAdminUser, "u00002", "User", "\\\\your_hostname\\ccmdb\\cm_database");
};

if ($@)
{
	print $@;
}

API - createProcessPackage

Create a CR Process package using an XML file already on the server and potentially a package template that also already exists on the server. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser           : The current api user's login data.
	scalar  xmlFileName     : The name of the CR Process XML file in the WEB-INF\cr_process directory.
	scalar  packageTemplate : The name of a package template to merge with that is 
	                          in the WEB-INF\package_templates directory.

Returns: apiData
	results The name of the package which was created.

Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $globals = new ChangeSynergy::Globals();

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\machineA\\ccmdb\\cm_database");

	my $response = $csapi->createProcessPackage($aUser, "dev_process.xml", "dev_template");
	print $response->getResponseData();
};

if ($@)
{
	print $@;
}

API - setUpConnection

Set up the connection information for calling API functions.
Parameters:
	scalar URL: URL of the application

Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");
};

if ($@)
{
	print $@;
}

API - GetDatabaseSettings

Gets the current settings for all database, including disabled databases.
Parameters:
	apiUser user: The current API user's login data.

Returns: 
	List of hash references where each hash represents a database.
	Each hash has these keys: path, enabled, description, max_sessions, min_sessions,
	and users_per_session. All values are strings, except 'enabled', which is a truthy/falsey value.
 
Example:
 
my @databases = $csapi->GetDatabaseSettings($user);

foreach my $db (@databases)
{
	print "Path:          $db->{path} \n";
	print "Enabled:       " . ($db->{enabled} ? "yes\n" : "no\n");
	print "Label:         $db->{label} \n";
	print "Description:   $db->{description} \n";
	print "Max Sessions:  $db->{max_sessions} \n";
	print "Min Sessions:  $db->{min_sessions} \n";
	print "Users/Session: $db->{users_per_session} \n\n";
}

API - GetHostSettings

Gets the current settings for all hosts, including disabled hosts.
Parameters:
	apiUser user: The current API user's login data.

Returns: 
	List of hash references where each hash represents a host.
	Each hash has these keys: hostname, type, enabled, description, max_sessions, priority,
	and threshold. All values are strings, except 'enabled', which is a truthy/falsey value.
	Host types are "NT" or "UNIX".
 
Example:
 
my @hosts = $csapi->GetHostSettings($user);

foreach my $host (@hosts)
{
	print "Hostname:     $host->{hostname} \n";
	print "Type:         $host->{type} \n";
	print "Enabled:      " . ($host->{enabled} ? "yes\n" : "no\n");
	print "Description:  $host->{description} \n";
	print "Max Sessions: $host->{max_sessions} \n";
	print "Priority:     $host->{priority} \n";
	print "Threshold:    $host->{threshold} \n\n";
}

API - GetListBoxDefaultValue

Get the Listbox Default Value. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser   : The current api user's login data.              

Returns: apiData
 	The Listbox default value set in the configuration file.

Example:

my $csapi = new ChangeSynergy::csapi();

 eval
 {
		$csapi->setUpConnection("http://your_hostname:port/your_context");

		my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\your_hostname\\ccmdb\\cm_database"); 

		my $tmpStr = $csapi->GetListBoxDefaultValue($aUser);

		print $tmpStr->getResponseData();
  };

  if ($@)
  {
		print $@;
  }

API - Logout

Logs out a user by releasing their checked out license immediately (without any license linger time).
Parameters:
	apiUser aUser : The current api user's login data.
 
Returns: apiData
	the return message from the server.

Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\your_hostname\\ccmdb\\cm_database");

	my $tmp = $csapi->Logout($aUser);
};

if ($@)
{
	print $@;
}

API - ServerVersion

Get the server version number. It is a tokenless api. The return result is an instance of the L<apiData> class.
Parameters:
	apiUser aUser: The current api user's login data.

Returns: apiData
	The version number string.
 
Example:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "User", "\\\\your_hostname\\ccmdb\\cm_database");

	my $tmpstr1 = $csapi->ServerVersion();
};

if ($@)
{
	print $@;
}

API - SyncDatabase

In central server mode, waits for the central server to finish syncing all its CRs into a particular database. This call is never required, since central CRs are automatically synced to all other databases, but this allows you to wait for all pending updates to complete.

For example, if a script quickly modifies a large number of CRs, it may take a while for these changes to be synced. If subsequent actions in the script depend on a particular database being in sync with the the central database, the script can call this function to wait for all those changes to sync. Once up-to-date, this call function will return and the script can proceed. Changes made after this function call--even while this is waiting--are ignored.

Times out if the database is online, but hasn't synced any CRs in a while.

Parameters:

	apiUser user:     The current API user's login data.
	scalar  database: The database to sync and wait for. Must be online.
 
 Returns: 
	Nothing. Returns silently once the sync has completed. If no updates
	are pending, returns immediately.

Ecxample:

my $csapi = new ChangeSynergy::csapi();

eval
{
	$csapi->setUpConnection("http://your_hostname:port/your_context");

	my $aUser = $csapi->Login("u00001", "u00001", "Admin", "\\\\your_hostname\\ccmdb\\cm_database");
	
	$csapi->SyncDatabase($aUser, "\\\\your_hostname\\ccmdb\\cm_database");
};

if ($@)
{
	print $@;
}