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.
Rational Change ships and installs Perl version 5.8.6. Perl is installed intoCHANGE_APP_HOME/WEB-INF/perl
. The actual Rational Change Perl API is installed intoCHANGE_APP_HOME/WEB-INF/perl/lib/perl5/site_perl/5.8.6/ChangeSynergy
. The command to execute Perl is notperl
as per normal installations of Perl; the command is insteadratlperl
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.
- Windows
c:\>set PATH=CHANGE_APP_HOME\WEB-INF\perl;%PATH%
c:\>set PERL5LIB=
Clear PERL5LIB on Windows as Perl can figure this out on its own.- UNIX
$ setenv PATH CHANGE_APP_HOME/WEB-INF/perl:$PATH
$ setenv PERL5LIB CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/5.8.6:CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/site_perl/5.8.6
- AIX
$ setenv LD_LIBRARY_PATH CHANGE_APP_HOME/WEB-INF/perl:CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/5.8.6/aix-multi/CORE
- Linux
$ setenv LD_LIBRARY_PATH CHANGE_APP_HOME/WEB-INF/perl:CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/5.8.6/i686-linux-multi/CORE
- Solaris
$ setenv LD_LIBRARY_PATH CHANGE_APP_HOME/WEB-INF/perl:CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/5.8.6/sun4-solaris-multi/CORE
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.
3. Define the Rational Change server.
Add the following line at the top of all Perl scripts written to use the Rational Change Perl API.
use utf8;
use ChangeSynergy::csapi;
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
4. Create a user object (apiUser)
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");
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.
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.
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 $@; }
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.
Below are the results of running this script.#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 $@; }
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
The default triggers that are shipped with Rational Change are located inCHANGE_APP_HOME/WEB-INF/wsconfig/triggers
. New triggers that are created should not be placed directly into this directory. Triggers should populate theCHANGE_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.
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 addasync:
to the beginning of the trigger.async:perl crAssignEmail.pl
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:
- Add the following line at the top of all Perl scripts and triggers:
use utf8;
- Save the script or trigger file as UTF-8 in your text editor.
When a trigger is fired in Rational Change, an XML file is created in the file system. This file is created inCHANGE_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.
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 |
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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);
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }
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"; }
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"; }
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 $@; }
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 $@; }
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 $@; }
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 $@; }