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.

目录


什么是 Rational Change Perl API?

IBM® Rational® Change Perl API 是 Rational Change 的命令行界面 (CLI)。Perl API 可以在 Windows 和 Unix 中运行。其他脚本/可执行文件可以轻松地调用 Rational Change Perl API 脚本,而且只需要一个简单的文本编辑器就可以创建该脚本。 Rational Change Perl API 可以实现用户界面的几乎所有功能,以及管理界面的部分功能。

Rational Change Perl API 位于何处?

Rational Change 提供并安装 Perl V5.8.6。Perl 安装到 CHANGE_APP_HOME/WEB-INF/perl。 实际的 Rational Change Perl API 安装到 CHANGE_APP_HOME/WEB-INF/perl/lib/perl5/site_perl/5.8.6/ChangeSynergy 中。 每次正常安装 Perl 时,执行 Perl 的命令不是 perl,而是 ratlperl

如何使用 Rational Change Perl API?

您必须进行以下更改才能使用 Rational Change Perl API。

1. 设置环境变量。

系统路径必须包含 Rational Change 的 Perl 可执行文件所在的位置。在 Windows 中,环境变量 PERL5LIB 必须为空,而在 UNIX 中,必须将它设置为两个不同的目录。 最后,在 UNIX 中将 LD_LIBRARY_PATH 设置为多个目录,而且其中一个目录为特定于平台的目录。 如果跳过这些步骤中的任何步骤,则 Rational Change API 和 Perl 将不能工作。

2. 指示 Perl 包含 Rational Change perl 模块 csapi

Csapi 是 Rational Change Perl API 的主模块,它包含与 Rational Change 服务器交互的所有方法。

在所有编写的 Perl 脚本最上面添加以下行, 以使用 Rational Change Perl API。

use utf8;
use ChangeSynergy::csapi;

3. 定义 Rational Change 服务器。

脚本必须了解关于 Rational Change 服务器的特定信息,才能确保正确运行。 首先,创建 csapi 模块的新实例

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

既然脚本已拥有 csapi 模块的访问权,您可以设置与 Rational Change 服务器的连接。 标识使用的主机名、端口号和协议。

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

4. 创建一个用户对象(apiUser)

这将使用户成功登录 Rational Change Server。

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

到此为止,脚本已准备就绪,可以充分实现并使用 Rational Change Perl API。

触发器如何使用 Rational Change Perl API?

当触发器触发时,Rational Change 调用触发器并将 XML 文档作为最后一个参数发送到触发器。该 XML 文档包含关于 Rational Change 服务器的基本信息,例如协议、端口号和主机名。还包含关于触发器的更多详细信息,例如用户名称、数据库、任何修改的属性以及初始状态和目标状态(如果触发器用于转换)。

Rational Change Perl API 包含一个 perl 模块,以帮助检索 XML 文档中的所有此类信息。这就是 TriggerParser 模块。

您必须进行以下更改才能使用 Rational Change Perl API。

1. 创建模块引用。

为了在 perl 脚本中使用该模块,您必须在脚本中采用“use”语句来引用它。

use ChangeSynergy::TriggerParser;

2. 创建作为 XML 文档位置唯一参数传入的 TriggerParser 模块实例。

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

在上面的代码中,通过传入 $ARGV[-1] 创建 TriggerParser 模块。 这是执行脚本时,传递提供给脚本的最后一个参数的 Perl 语法。 所有触发器的最后一个参数始终为 XML 文档。

3. 根据需要访问 Rational Change API。

并不是所有触发器脚本都需要访问 Rational Change API。这取决于脚本需要执行的操作类型。如果脚本需要回调 Rational Change 服务器,则需要访问 Rational Change API。操作步骤与 “如何使用 Rational Change Perl API?”中所用的步骤几乎完全相同。注意:当调用触发器时,Rational Change 负责正确设置环境变量(PATH 和 PERL5LIB),因此这个步骤可以跳过。

在所有编写的 Perl 脚本最上面添加以下行, 以使用 Rational Change Perl API。

use utf8;
use ChangeSynergy::csapi;


该行告诉 Perl 必须包含 Rational Change perl 模块 csapiCsapi 是 Rational Change Perl API 的主模块;它包含与 Rational Change 服务器交互的所有方法。

4. 定义 Rational Change 服务器。
脚本还必须了解关于 Rational Change 服务器的特定信息,才能确保正确运行。 首先,创建 csapi 模块的新实例。

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

既然脚本已拥有 csapi 模块的访问权,您可以设置与 Rational Change 服务器的连接。所有此类信息都将通过 XML 文档传递到触发器中。标识要使用的 URL。

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

5. 创建一个用户对象 (apiUser)。
由于触发脚本的用户已经登录,该用户的信息可用于创建用户对象。

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

到此为止,脚本已准备就绪,可以充分实现并使用 Rational Change Perl API。

如何运行查询/报告并保存它?

Rational Change API 最有用的一个功能是能够运行查询和报告。正如在 Rational Change Web 界面中一样,提供了多种运行查询和报告的方法。 下面的示例显示如何使用 Rational Change API 来运行包含定制查询的报告并将结果保存到文件中。浏览 API 文档以获取关于可运行的各种查询和报告的详细信息。
	
	#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 $@;
	}
	

如何运行查询/报告并从中获取信息?

除了运行查询/报告并保存 HTML 文件外,Rational Change API 还可以在数据格式视图中运行查询/报告。这意味着结果将不返回到 HTML 页面中,而返回 Rational Change API 自动对其进行语法分析的 XML 文档。 这样允许脚本运行报告、检查报告返回的数据并在需要时对数据进行操作。

下面的示例显示如何使用 Rational Change API 来运行包含定制查询的数据报告并返回自定义属性列表。然后脚本将读取所有返回数据,并以可读格式显示在屏幕上。这显示如何提取数据报告的有用信息。

	
	#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 $@;
	}
	
下面是该脚本的运行结果。
	
分配给 u00001 的 CR 总数:2

	problem_number: 1
	crstatus:已分配
	problem_synopsis:为内部流程创建新的生命周期图像。
	severity: Showstopper

	problem_number: 2
	crstatus:已分配
	problem_synopsis:为内部 lifecycle.f 添加新状态
	severity:中等
	

应该如何管理触发器?

Rational Change 包含的缺省触发器位于 CHANGE_APP_HOME/WEB-INF/wsconfig/triggers。 创建的新触发器不应直接放在该目录下。 触发器应该根据其使用方式,通过流程包或定制包填充 CHANGE_APP_HOME/WEB-INF/wsconfig/triggers 目录。

如果新触发器特定于生命周期,那么应该将其放入该生命周期的包模板中。这样当在创建包期间将生命周期与包模板合并时,生成的包将包含正确的脚本。安装该包时,脚本将安装到正确的位置。通过采用同一标记,当除去包时,脚本也将被除去。

另一方面,如果新触发器不是特定于生命周期(更通用),则应该将其放入单独的包。应该安装该包,从而当前安装或即将安装的 CR 过程可以使用脚本。

使用这种方法将帮助您跟踪提供的脚本和单独安装的脚本。还允许包安装程序采用正确的方法更新运行区域。这样帮助防止意外删除触发器,并使运行区域保持在更可控的环境中。

如何异步运行触发器?

异步运行触发器是什么意思?意味着触发器将在单独的线程中触发,而最终用户在服务器响应之前不需要等待触发器完成操作。例如,发送电子邮件的后置更改触发器一般在编辑电子邮件时让用户等待,直到发出电子邮件才允许用户执行下一步操作。 但是如果触发器异步运行,用户将不受触发器触发和触发完成时间的影响。

仅限后置触发器异步运行;后置更改、后置提交和后置转换。前置触发器不应异步运行,因为触发器的返回码将决定操作能否成功。

要异步运行触发器,在触发器的开头部分添加 async:
	
	async:perl crAssignEmail.pl
	

如何确保采用了合适的字符编码?

Rational Change 使用 UTF-8 字符编码,而 Perl 脚本和触发器必须使用该编码才能防止非 ASCII 字符出现乱码。 以下两个步骤可以完成该操作:
  1. 在所有 Perl 脚本和触发器的最上面添加以下行:
    use utf8;
  2. 在文本编辑器中将脚本或触发器文件另存为 UTF-8。

非常有用的触发器调试技巧

在 Rational Change 中触发触发器时,将在文件系统中创建一个 XML 文件。 该文件创建在 CHANGE_APP_HOME/WEB-INF/wsconfig/tmpdir 中,并在执行完脚本后删除。但是当 Rational Change 在“调试”方式下运行时,不会删除这些 XML 文件。在调试方式下运行还显示触发器触发时的其他信息。

要利用该功能:

1. 打开“管理”窗口并显示调试选项卡,然后打开“用户”窗口。

2. 执行导致触发器触发的操作之前,打开调试并清除日志文件。

3. 执行操作并关闭调试。
这会将关于事件和触发器的信息保留在日志文件中,并将 XML 文件保留在操作系统上。XML 文件包含导致触发器触发的用户名称,以及随机数序列。 最好将其重命名为容易记住的名称。

4. 从命令行启动脚本。这样便于简便、快捷地修订语法错误和其他编程错误,而不需要每次都从 GUI 触发触发器。

5. 脚本完全执行后(无错误),请检查 GUI 中触发器执行的操作,以确保触发器正确无误。

还需要注意,在触发器执行期间打印到的标准输出或标准错误的任何消息都将打印到 pt.log 文件中。这可用于调试,或作为触发器的一般记录。

不同 Perl API 发行版之间的更改(从 4.7 开始)

转到版本: 

5.3.0.25.3.0.15.35.2.0.55.2.0.45.2.0.35.2.0.25.2.0.15.25.15.0
发行版 更改类型 受影响的 API
5.3.0.1 到 5.3.0.2  
5.3 到 5.3.0.1  
5.2 到 5.3 已添加 先前发行版中的所有修订包变更。
ExportProjectSecurityData
ImportProjectSecurityData
5.2.0.4 到 5.2.0.5  
5.2.0.3 到 5.2.0.4 已添加 reloadAppProperties
AddUser
AddUsers
5.2.0.2 到 5.2.0.3  
5.2.0.1 到 5.2.0.2  
5.2 到 5.2.0.1 已添加 addFolder
createReport
deleteFolder
deleteReport
exportAReport
exportReportsFromFolder
getFolderSecurityRule
importAReport
listFolders
moveFolderMembers
renameFolder
setFolderSecurityRule
SwitchUser
修改 变量 $url_to_connect、$queryConfigType 和 $reportConfigType 是 util.pm 的全局变量。 将它们移到 csapi 类,从而成为 csapi 类的实例变量。
5.1 到 5.2 已添加 createProcessPackage
修改 不推荐使用 setUpConnection(protocol, host, port) ;替换为 setUpConnection(url)
5.0 到 5.1 除去 AttributeModifyTaskData
修改 将一个可选的新参数(名为 enable 的布尔值)添加到 ToggleDebug,用于明确设置状态,而不是切换状态。
使用 ratlperl。
4.7 到 5.0 已添加 GetDatabaseSettings
GetHostSettings
GetListBoxDefaultValue
Logout
ServerVersion
SyncDatabase
不推荐 CreateUserSecurityData(除返回不推荐消息之外,不执行任何操作)
除去 ImportUsersFromAllDatabases
ImportUsersFromCSLDAPSserver
ImportUsersFromAFile
AddUser
AddUsers
ResetLDAPPool

API - ExportProjectSecurityData

将项目安全性定义(包括角色和全局分配)从 RDS 导出到 LDIF 文件:CHANGE_APP_HOME/WEB-INF/wsconfig/tmpdir/import_<current date and time>.ldif。可通过 API ImportProjectSecurityData 导入此文件。 只有 Rational Change 管理员用户才能使用该 API。
参数:
	apiUser aUser :当前 api 用户的登录数据。

返回:apiData
有关导出成功还是失败的消息。
 
示例:

示例:

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

将数据从通过 ExportProjectSecurityData 创建的 LDIF 文件导入到与 Rational Change 连接的 RDS。该文件必须位于 CHANGE_APP_HOME/WEB-INF/wsconfig/tmpdir 中。 只有 Rational Change 管理员用户才能使用该 API。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  importFileName:要导入的 LDIF 文件的名称。
	scalar  isUpdate:“true”表示将数据更新/添加到 RDS,“false”表示只将新数据添加到 RDS,而不更新现有数据。

返回:apiData
有关导入成功还是失败的消息。
 
示例:

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

使用指定的 Rational Synergy 角色集向 LDAP 服务器和 Rational Synergy 数据库添加新用户。新用户可以在此调用完成之后登录。
返回的结果为 L<apiData> 类的实例。

注:在循环中,请勿调用此函数。而是应当使用 L<AddUsers|"AddUsers">() api 函数。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	apiUser aNewUser:新用户的数据。返回:apiData
来自服务器的返回消息。	
 
示例:

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

使用指定的 Rational Synergy 角色集向 LDAP 服务器和 Rational Synergy 数据库添加一组新用户。新用户可以在此调用完成之后登录。
返回的结果为 L<apiData> 类的实例。
参数:
	apiUser  aUser   :当前 api 用户的登录数据。
	@apiUser aNewUser:新用户数据的数组
	scalar   iCount  :新用户的数组大小。返回:apiData
来自服务器的返回消息。	
 
示例:

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

重新装入文件 WEB-INF/wsconfig/system/app.properties 和 WEB-INF/wsconfig/system/app.user.properties。
返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser:当前 API 用户的登录数据。

返回:apiData
来自服务器的返回消息。	
 
示例:


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

向服务器添加新的空查询、报告格式或报告文件夹。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  folderName:要添加的文件夹的名称。
	scalar  objectType:文件夹的对象类型。
	scalar  formatType:文件夹的格式类型:报告、查询或报告格式。
	scalar  configType:报告的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效格式类型(常量定义在 Globals.pm 中):
 		QUERY
        REPORT
        REPORT_FORMAT


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:apiData
来自服务器的返回消息。
示例:
	

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

创建基于现有 Change 报告的新 Change 报告。 返回的结果为 L<apiData> 类的实例。
同时使用 ChangeSynergy::CreateReportDefinition 类和 L<csapi> createReport API,以根据现有报告创建新的 Change 报告。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  reportDefinition   :ChangeSynergy::CreateReportDefinition 对象的实例。
	scalar  objectType         :报告所要查询的对象类型。
	scalar  configType         :报告最终将位于的配置位置,有效类型只有 user 和 shared。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        USER_PROFILE

返回:apiData
仅当创建成功时,才返回结果	

示例:
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

从服务器中删除查询、报告格式或报告文件夹及所有成员。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  folderName:要删除的文件夹的名称。
	scalar  objectType:文件夹的对象类型。
	scalar  formatType:文件夹的格式类型:报告、查询或报告格式。
	scalar  configType:报告的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效格式类型(常量定义在 Globals.pm 中):
 		QUERY
        REPORT
        REPORT_FORMAT


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:apiData
来自服务器的返回消息。
示例:
	

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

从用户首选项或从共享数据删除 CR 或任务报告。如果找不到要删除的指定报告,将抛出异常。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  reportName :要删除的报告的名称。
	scalar  objectType :报告的对象类型。
	scalar  configType :报告的配置位置,有效类型只有 user 和 shared。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        USER_PROFILE

返回:apiData
删除状态消息。
	
示例:


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

从共享首选项或用户首选项导出指定的 CR 或任务报告。 返回的结果为 L<ReportEntry> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  reportName :要从服务器导出的报告的名称。
	scalar  objectType :报告的对象类型。
	scalar  configType :报告的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:ReportEntry
包含报告所有信息的报告项对象。
示例 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 $@;
}
	
示例 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 $@;
}

示例 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

从共享首选项或用户首选项中的指定文件夹导出所有 CR 或任务报告。返回的结果为 L<ReportEntry> 类的数组。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  folderName :要从中导出所有报告的文件夹的名称。
	scalar  objectType :报告的对象类型。
	scalar  configType :报告的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:ReportEntry
包含每个报告所有信息的报告项对象数组。	
示例:
 	
#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

获取给定文件夹的文件夹安全信息。文件夹安全信息包含文件夹名称、读安全性成员和写安全性成员。 返回的结果为 L<FolderSecurityRule> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  folderName :要获取其安全性的文件夹的名称。
	scalar  objectType :文件夹的对象类型。
	scalar  formatType :文件夹的格式类型:报告、查询或报告格式。
	scalar  configType :报告的配置位置。

返回:FolderSecurityRule
表示规则的 FolderSecurityRule 对象。
 
示例:
 

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

导入使用 exportAReport 或 exportReportsFromFolder API 导出的 Change 报告。如果服务器上已存在要导入的报告的名称,那么该方法将失败并抛出异常。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	ReportEntry reportEntry:包含报告所有信息的报告项。
	scalar  objectType     :报告的对象类型。
	scalar  configType     :报告的配置位置,有效类型只有 user 和 shared。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        USER_PROFILE

返回:apiData
不管导入是否成功,都返回信息。	

示例 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 $@;
}
	
示例 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

返回顶级文件夹下所有查询、报告格式或报告文件夹的列表。 返回的结果为 L<apiListObject> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  objectType   :根文件夹的对象类型。
	scalar  formatType   :根文件夹的格式类型:报告、查询或报告格式。
	scalar  configType   :根文件夹的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效格式类型(常量定义在 Globals.pm 中):
 		QUERY
        REPORT
        REPORT_FORMAT


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:apiListObject
根文件夹下的文件夹列表。
示例:
	

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

将查询、报告格式或报告文件夹的成员移至同一类型的新文件夹。服务器将找到报告所属的当前文件夹,并将这些报告移至新指定的文件夹。任何移动都必须在列表中的所有成员都存在的情况下才能完成。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  folderName   :要将报告移至的文件夹的名称。
	scalar  memberList   :要从一个文件夹移至另一个文件夹的报告的列表(以竖线定界)。
	scalar  objectType   :文件夹的对象类型。
	scalar  formatType   :文件夹的格式类型:报告、查询或报告格式。
	scalar  configType   :报告的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效格式类型(常量定义在 Globals.pm 中):
 		QUERY
        REPORT
        REPORT_FORMAT


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:apiData
来自服务器的返回消息。
示例:
	

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

重命名服务器上的查询、报告格式或报告文件夹。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  folderName   :文件夹的当前名称。
	scalar  newFolderName:文件夹的新名称。
	scalar  objectType   :文件夹的对象类型。
	scalar  formatType   :文件夹的格式类型:报告、查询或报告格式。
	scalar  configType   :报告的配置位置。


有效对象类型(常量定义在 Globals.pm 中):
        PROBLEM_TYPE
        TASK_TYPE
        OBJECT_TYPE


有效格式类型(常量定义在 Globals.pm 中):
 		QUERY
        REPORT
        REPORT_FORMAT


有效配置类型(常量定义在 Globals.pm 中):
        SHARED_PROFILE
        SYSTEM_CONFIG
        USER_PROFILE

返回:apiData
来自服务器的返回消息。
示例:
	

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

设置给定文件夹的文件夹安全信息。文件夹安全信息包含文件夹名称、读安全性成员和写安全性成员。 您还可以通过提供没有任何读者或编写者的文件夹名称来清空规则。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	FolderSecurityrule folderRule :文件夹的文件夹安全规则对象。
	scalar  objectType   :文件夹的对象类型。
	scalar  formatType   :文件夹的格式类型:报告、查询或报告格式。
	scalar  configType   :报告的配置位置。

返回:apiData
包含关于更新成功与否消息的 apiData。
 
示例:
 

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

允许本地管理员用户切换为任意用户。 返回的结果为 L<apiUser> 类的实例。
参数:
    apiUser localAdminUser:本地管理员用户的登录数据。
	scalar targetUserName :目标用户的名称。
	scalar targetRole     :目标用户的角色(界面)
	scalar targetDatabase :用户的 IBM Rational Synergy 数据库路径。

返回:apiUser
包含指定信息的 apiUser 类的新实例。

示例:

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

使用服务器上已存在的 XML 文件(并且可能使用服务器上已存在的包模板)来创建 CR 过程包。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
	scalar  xmlFileName     : WEB-INF\cr_process 目录中 CR 过程 XML 文件的名称。
	scalar  packageTemplate :要合并的包模板的名称,位于
	                          WEB-INF\package_templates 目录中。
返回:apiData
结果:创建的包的名称。
示例:

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

设置用于调用 API 函数的连接信息。
参数:
	scalar URL:应用程序的 URL

示例:


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

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

if ($@)
{
	print $@;
}

API - GetDatabaseSettings

获取所有数据库(包括禁用的数据库)的当前设置。
参数:
	apiUser user:当前 API 用户的登录数据。

返回:
散列引用的列表 - 其中每个散列表示一个数据库。	
每个散列具有以下键:path、enabled、description、max_sessions、min_sessions
和 users_per_session。所有值都是字符串,但“enabled”除外,它是真/假值。
 
示例:
 
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

获取所有主机(包括禁用的主机)的当前设置。
参数:
	apiUser user:当前 API 用户的登录数据。

返回:
散列引用的列表 - 其中每个散列表示一个主机。	
每个散列具有以下键:hostname、type、enabled、description、max_sessions、priority
和 threshold。所有值都是字符串,但“enabled”除外,它是真/假值。
主机类型为“NT”或“UNIX”。
 
示例:
 

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

获取 Listbox 缺省值。 返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。

返回:apiData
配置文件中设置的 Listbox 缺省值。

示例:


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

通过立即释放用户的已检出许可证来注销该用户(没有任何许可证逗留时间)。
参数:
	apiUser aUser     :当前 api 用户的登录数据。
 
返回:apiData
来自服务器的返回消息。	

示例:


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

获取服务器版本号。它是一个无标记的 api。返回的结果为 L<apiData> 类的实例。
参数:
	apiUser aUser     :当前 api 用户的登录数据。

返回:apiData
版本号字符串。	
 
示例:


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

在中央服务器方式下,等待中央服务器将所有 CR 同步到特定数据库中。由于会自动将中央 CR 同步到所有其他数据库,因此从不需要此调用,但这允许您等待所有暂挂的更新完成。

例如,如果脚本快速修改大量 CR,可能需要 一段时间这些更改才能实现同步。如果脚本中的后续操作取决于正在与中央数据库同步的特定数据库,那么脚本可以调用此函数以等待所有这些更改都同步。 达到最新状态之后,该调用函数将返回,而脚本则可以继续。 将忽略该函数调用(即使正在等待)之后进行的更改。

如果数据库处于联机状态,但在一段时间内未同步任何 CR,那么将超时。

参数:

	apiUser user:当前 API 用户的登录数据。
	scalar  database:要同步和等待的数据库。必须处于联机状态。
 
返回:
不返回任何值。同步完成后,静默返回。如果没有任何更新
处于暂挂状态,将立即返回。
示例:


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 $@;
}