IBM Rational Change Perl API

© Copyright IBM Corporation 2000, 2011

目次


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 version 5.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 環境では 2 つの異なるディレクトリーを設定する必要があります。 UNIX の場合は最後に、プラットフォーム固有のディレクトリーを含む複数のディレクトリーを LD_LIBRARY_PATH に設定する必要があります。 これらのステップのいずれかを省略した場合、IBM Rational Change API は機能しません。

2. Rational Change Perl モジュール csapi をインクルードするように、Perl に指示します。

Csapi は、Rational Change Perl API のメイン・モジュールです。Rational Change サーバーと情報をやりとりをするためのすべてのメソッドがこのモジュールに含まれています。

Rational Change Perl API を使用するには、記述するすべての Perl スクリプトの先頭に以下の行を追加します。

use utf8;
use ChangeSynergy::csapi;

3. Rational Change サーバーを定義します。

Perl スクリプトが正しく機能するには、Rational Change サーバーに関する特定の情報を認識している必要があります。 最初に、csapi モジュールの新しいインスタンスを作成します。

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

これでスクリプトは csapi モジュールにアクセスできるようになり、Rational Change サーバーへの接続を設定できます。 使用するホスト名、ポート番号およびプロトコルを指定します。

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

4. ユーザー・オブジェクト (apiUser) を作成します。

このオブジェクトにより、ユーザーは Rational Change サーバーにログインできます。

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 サーバーに関する基本情報が含まれています。トリガーが遷移用の場合、この XML ドキュメントには、ユーザー名、データベース、変更された属性、遷移元と遷移先の状態などの詳細な情報が含まれます。

Rational Change Perl API には、XML ドキュメントからのすべての情報の取り出すために使用する Perl モジュールがあります。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 へのアクセスが必要となります。 これを実行するための手順は、 『IBM Rational Change Perl API の使い方』で用いる手順とほとんど同じです。. 注記: トリガーを呼び出すとき、Rational Change が環境変数 (PATH と PERL5LIB) を正しく設定するので、このステップは省略可能です。

Rational Change Perl API を使用するには、記述するすべての Perl スクリプトの先頭に以下の行を追加します。

use utf8;
use ChangeSynergy::csapi;


この行は、Rational Change の Perl モジュール csapi をインクルードする必要があることを、Perl に指示します。 Csapi は、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 のもっとも有用な機能の 1 つに、クエリーとレポートの実行機能があります。 Rational Change のウェブ・インターフェースと同様に、クエリーとレポートの実行にも複数の方法が用意されています。 次の例は、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 ページとしてではなく、XML ドキュメントとして返されます。この XML ドキュメントは、Rational Change API によって自動的に構文解析が行われます。 これにより、スクリプトは、レポートを実行して返されるデータを調べ、必要に応じてその結果のデータに基づいた動作をすることができます。

次の例は、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 $@;
	}
	
このスクリプトを実行した結果を以下に示します。
	
	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
	

トリガーの扱い方

Rational Change と同梱のデフォルトのトリガーは <CHANGE_APP_HOME>/WEB-INF/wsconfig/triggers に格納されています。 作成した新しいトリガーをこのディレクトリーに直接格納してはいけません。 トリガーの使用方法にしたがってプロセス・パッケージまたはカスタム・パッケージを使用し、<CHANGE_APP_HOME>/WEB-INF/wsconfig/triggers ディレクトリーに作成されるようにします。

新しいトリガーがライフサイクルに固有な場合は、新しいトリガーはそのライフサイクルのパッケージ・テンプレートに格納する必要があります。 こうしておくと、ライフサイクルがパッケージ作成時にパッケージ・テンプレートとマージされる際に、作成されたパッケージに正しいスクリプトが含まれるようになります。 そして、このパッケージをインストールしたときに、スクリプトが正しい場所にインストールされます。 パッケージを削除すると、同じトークンによって、そのスクリプトも削除されます。

一方、新しいトリガーがライフサイクルに固有でない (より一般的な) 場合、トリガーは別のパッケージに格納する必要があります。 このパッケージをインストールすると、現在インストールされているか、またはすぐにインストールされる CR プロセスでスクリプトを使用できるようになります。

この方法を使用すれば、どのスクリプトが出荷されたか、どのスクリプトが個別にインストールされたかを、簡単に追跡、把握できるようになります。 また、パッケージ・インストーラーという正しい手段を使用して、実行領域を更新できます。 この方法により、トリガーを誤って削除することがなくなり、 実行領域をより管理された環境に保つことができます。

トリガーを非同期に実行する方法

「トリガーを非同期に実行する」とは、 トリガーが別のスレッドで起動され、エンド・ユーザーがトリガーの完了まで待機することなく、サーバーの応答を得られることを意味します。 たとえば、E メールを送信する post modify トリガーは、通常、E メールが作成されて送信されるまでユーザーを待機させるため、ユーザーが次の動作を実行できるのはメールの送信後になります。 しかし、トリガーを非同期で実行する場合は、トリガーの起動から完了までの時間がユーザーに影響を与えなくなります。

非同期にできるのは、post modify、post submit、および post transition のポスト・トリガーのみです。 プレトリガーは、トリガーからの戻りコードが動作の成否に影響を及ぼすので、非同期にするべきではありません。

トリガーを非同期にするには、トリガーの先頭に async: を付けます。
	
	async:perl crAssignEmail.pl
	

適切な文字エンコードを確実に使用する方法

Rational Change は UTF-8 文字エンコードを使用します。Perl スクリプトおよびトリガーも同じエンコードを使用して、 非 ASCII 文字が壊れないようにする必要があります。 これを行うには、以下の 2 つの手順を実行します。
  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
変更 状態の切り替えではなく、明示的な状態の設定を行うために、ToggleDebug に enable というブール値の新しいオプション・パラメーターを追加しました。
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_<現在の日時>.ldif) にエクスポートします。 このファイルは、API ImportProjectSecurityData を通じてインポートできます。 この API を使用できるのは、Rational Change Admin ユーザーだけです。
パラメーター:
	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 に格納されている必要があります。 この API を使用できるのは、Rational Change Admin ユーザーだけです。
パラメーター:
	apiUser aUser     : 現在の API ユーザーのログイン・データ。
	スカラー  importFileName: インポートする LDIF ファイルの名前。
	スカラー  isUpdate: データの更新/RDS への追加を実行する場合は「true」。RDS に新規データを追加するだけで、既存のデータを更新しない場合は「false」。

戻り値: 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

LDAP サーバーと Rational Synergy データベースの両方に新規ユーザーを追加し、指定された 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

LDAP サーバーと Rational Synergy データベースの両方に新規ユーザーのセットを追加し、指定された Rational Synergy ロールのセットを割り当てます。新規ユーザーは、この呼び出しが完了するとログインできるようになります。
返される結果は L<apiData> クラスのインスタンスです。
パラメーター:
	apiUser aUser     : 現在の API ユーザーのログイン・データ。
	@apiUser aNewUser: 新規ユーザーのデータの配列
	スカラー   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 ユーザーのログイン・データ。
	スカラー  folderName: 追加対象のフォルダーの名前。
	スカラー objectType: フォルダーのオブジェクト・タイプ。
	スカラー formatType: フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー  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 ユーザーのログイン・データ。
	スカラー reportDefinition   : ChangeSynergy::CreateReportDefinition オブジェクトのインスタンス。
	スカラー objectType         : レポートのクエリー対象となるオブジェクト・タイプ。
	スカラー 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 ユーザーのログイン・データ。
	スカラー folderName: 削除対象のフォルダーの名前。
	スカラー objectType: フォルダーのオブジェクト・タイプ。
	スカラー formatType: フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー  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 ユーザーのログイン・データ。
	スカラー  reportName : 削除対象のレポートの名前。
	スカラー  objectType : レポートのオブジェクト・タイプ。
	スカラー  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 ユーザーのログイン・データ。
	スカラー  reportName : サーバーからエクスポートするレポートの名前。
	スカラー  objectType : レポートのオブジェクト・タイプ。
	スカラー  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 ユーザーのログイン・データ。
	スカラー  folderName : すべてのレポートをエクスポートするフォルダーの名前。
	スカラー  objectType : レポートのオブジェクト・タイプ。
	スカラー  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 ユーザーのログイン・データ。
	スカラー  folderName : セキュリティーを取得する対象のフォルダーの名前。
	スカラー  objectType : フォルダーのオブジェクト・タイプ。
	スカラー  formatType : フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー  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: レポートに関するすべての情報を含むレポート・エントリー。
	スカラー  objectType : レポートのオブジェクト・タイプ。
	スカラー  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 ユーザーのログイン・データ。
	スカラー objectType   : ルート・フォルダーのオブジェクト・タイプ。
	スカラー formatType   : ルート・フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー 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 ユーザーのログイン・データ。
	スカラー  folderName   : レポートの移動先フォルダーの名前。
	スカラー  memberList   : フォルダー間を移動するレポートのパイプ区切りリスト。
	スカラー  objectType : フォルダーのオブジェクト・タイプ。
	スカラー  formatType : フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー  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 ユーザーのログイン・データ。
	スカラー  folderName   : フォルダーの現在の名前。
	スカラー  newFolderName: フォルダーの新しい名前。
	スカラー  objectType : フォルダーのオブジェクト・タイプ。
	スカラー  formatType : フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー  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 : フォルダーのフォルダー・セキュリティー・ルール・オブジェクト。
	スカラー  objectType : フォルダーのオブジェクト・タイプ。
	スカラー  formatType : フォルダーのフォーマット・タイプ: レポート、クエリーまたはレポート・フォーマット。
	スカラー  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: ローカル・アドミン・ユーザーのログイン・データ。
	スカラー targetUserName : ターゲット・ユーザーの名前。
	スカラー targetRole     : ターゲット・ユーザーのロール (インターフェース)。
	スカラー 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 ファイルと同じくサーバー上のパッケージ・テンプレートから CRProcess パッケージを作成します。 返される結果は L<apiData> クラスのインスタンスです。
パラメーター:
	apiUser aUser     : 現在の API ユーザーのログイン・データ。
	スカラー xmlFileName     : WEB-INF\cr_process ディレクトリーにある CR プロセス XML ファイルの名前。
	スカラー 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 関数を呼び出すための接続情報を設定します。
パラメーター:
	スカラー URL: アプリケーションの URL。

例:


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

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

if ($@)
{
	print $@;
}

API - GetDatabaseSettings

無効になっているデータベースも含めて、すべてのデータベースの現在の設定を取得します。
パラメーター:
	apiUser user:     現在の API ユーザーのログイン・データ。

戻り値: 各ハッシュ値が 1 つのデータベースを現しているハッシュ参照のリスト。
	各ハッシュは次のキーを持ちます。path、enabled、description、max_sessions、min_sessions、
	および users_per_session。値はすべてストリングです。ただし「enabled」は truthy/falsey 値です。
 
例:
 
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 ユーザーのログイン・データ。

戻り値: 各ハッシュ値が 1 つのホストを現しているハッシュ参照のリスト。
	各ハッシュは次のキーを持ちます。hostname、type、enabled、description、max_sessions、priority、
	および threshold。値はすべてストリングです。ただし「enabled」は truthy/falsey 値です。
	ホスト・タイプは「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

リスト・ボックスのデフォルト値を取得します。 返される結果は 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 $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 ユーザーのログイン・データ。
	スカラー  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 $@;
}