HCL DevOps Plan REST API サーバーのユーザーオンボーディング

2024/3/31 - 読み終える時間: 3 分

User Onboarding on HCL DevOps Plan REST API Server の翻訳版です。

---

HCL DevOps Plan REST API サーバーのユーザーオンボーディング

2024年3月26日

著者: Deepak Shintre / Senior Software Configuration Management

HCL DevOps Plan REST API Server（略称：API Server）は、HCL DevOps Planソフトウェアの最新のWebサーバーコンポーネントであり、従来のCompass Web Serverコンポーネントと同等です。しかし、この2つのコンポーネントではデプロイ手順が全く異なります。

DevOps Plan API Serverでユーザーをアプリケーションにオンボーディングするプロセスには、主に2つのパートがあります：

パート1: DevOps Plan REST API サーバーでメールサーバーの設定 パート2: ユーザー招待のライフサイクルの完了

パート-1: DevOps Plan REST API Server上のメールサーバーの設定

API Serverでは、ユーザー管理の一環としてEmail Serverを設定することができる。これは、ユーザーに電子メール通知を送信するために必要です。

重要な注意事項

• 以下のスクリーンショットは、「DefectTracking/SAMPL」アプリケーション用に設定されたメールサーバーを示しています。ただし、これはすべてのDevOps Planアプリケーションで同じです。
• メール通知とユーザー管理をシームレスに機能させるために、これらのサーバー間で必要な通信が確立されていることを確認するために、メールサーバーのAPIサーバー（ホスト名またはIPアドレスのいずれか）をホワイトリストに登録する必要があります。

スーパーユーザー（管理者）権限でDevOps Plan API Serverにログオンします。Configuration (構成)] > [Server Setup (サーバー・セットアップ)] オプションをクリックして、サーバー構成ページに移動します。サーバー設定ページの右側のセクションには、メールサーバーの設定が表示されています。

Email Server Setup'の各項目について、以下に簡単に説明します。

SMTPサーバーホスト： SMTPサーバーホスト: 組織で設定されているSMTPサーバー/メールサーバーの完全修飾ドメイン名(FQDN)またはIPアドレスです。

Port: メールサーバーの設定に使用するポート番号です。

暗号化： メールサーバーの暗号化を設定している場合は、ここにその旨を入力します。なし（暗号化しない場合）、SSL/TLS、STARTTLSのオプションがあります。

送信元アドレス： これは、ユーザ管理の一環として、ユーザに電子メール通知を送信する電子メールアドレスです。既存のメールアドレスを使用することも、新しいメールアドレスを指定することもできます。

ユーザ名: メールサーバに設定されているユーザ名です。

パスワード: 上記のユーザー名に対応するパスワード

SMTPサーバー証明書： Type」ドロップダウンメニューには、「None（なし）」、「Certification Authority（認証局）」、「Self-signed（自己署名）」の3つのオプションがあります。これらの名前が示すように、サードパーティCAからセキュリティ証明書を受け取った場合は、認証局を選択する必要があります。自己署名証明書を作成した場合は、同じオプションを選択します。適切なオプションを選択したら、証明書をホスト上に保存されているパスからアップロードする必要があります。

これらの詳細をすべて入力し、[保存]ボタンをクリックすると、すべての設定が保存され、画面の右側に確認のポップアップが表示されます。これでメールサーバーの設定は完了です。

Part 2: ユーザー招待のライフサイクルの完了

メールサーバーのセットアップが完了したら、DevOps Planアプリケーションのユーザー管理の一部でもあるユーザーオンボーディングプロセスを開始できます。

管理者権限でAPIサーバーにログオンし、画面の左側から「ユーザー管理」アイコンを選択します。Invite User」をクリックし、招待する必要があるユーザーのメールIDを入力します。正しいEメールIDが入力されると、以下のスクリーンショットに示すように、ユーザーを識別し、そのユーザーを選択できるようになります：

ユーザーを選択すると、そのユーザーに与えたい権限を選択することができます。ユーザを選択すると、そのユーザに与える特権を選択することができます。権限の選択例を以下に示します。権限を選択したら、'Add User'をクリックしてください：

ユーザが正常に招待されたことを確認するポップアップが表示されます。

これで、ユーザーには、件名「Join DefectTracking on DevOps Plan」、本文「admin has invited you to DefectTracking on DevOps Plan」のメールが表示されます。また、「招待を承認する」というリンクもあります。

ユーザーが'Accept Invitation'リンクをクリックすると、同じAPIサーバーURLにリダイレクトされ、First Name、Last Nameを入力し、このアプリケーションのパスワードを設定することができます。すべての情報を入力したら、「Sign Up」をクリックして手続きを完了する。電子メールIDとユーザー名はグレーアウトされていますが、これはこれらの詳細を編集／変更できないためです。

サインアップ」をクリックすると、アカウントの作成が完了したことが確認されます。ログイン」をクリックすると、追加したアプリケーションにログオンできます。

ログインをクリックすると、「DefectTracking/SAMPL」アプリケーションのホームページが表示されます：

DevOps Plan ホームページの右上隅に、自分のユーザープロファイルが表示されます。

これらのステップとベストプラクティスに従うことで、HCL DevOps Plan REST API Serverへのユーザーのオンボーディングプロセスを効果的に管理することができ、ユーザーがプラットフォームをうまく活用するために必要な知識とリソースを確実に身につけることができます。

HCL DevOps Planの詳細については、HCLSoftware のウェブサイトをご覧ください。

HCL Compass と HCL VersionVault Express との SCM 連携・統合 (Webhook based)

2022/6/20 - 読み終える時間: 11 分

SCM Integration of HCL Compass with HCL VersionVault Express – (Webhook based) の翻訳版です。

---

HCL Compass と HCL VersionVault Express との SCM 連携・統合 (Webhook based)

はじめに

このブログでは、HCL Compass 2.1.0とHCL VersionVault Express 2.1.0のSCM統合をWebhookベースの方法で設定するために必要な主要ステップのスナップショットを紹介します。この統合により、HCL Compass側の特定の不具合やレコードに対応するHCL VersionVault Express側のアクティビティに関連する変更セットを追跡できるようになります。この記事の最後には、HCL VersionVault ExpressとHCL Compassの統合を実際に示す例もあります。

以下は、この記事で扱うトピックのリストです。

1.統合の前提条件 - HCL VersionVault ExpressとHCL Compassの必要なコンポーネントとバージョン

2.CompassのDBにSCM統合パッケージのインストール

3.Restサーバーの起動

4.CompassのスキーマとDBにSSOとSCMの設定

5.Compass上でSCMの設定の定義

6.VersionVault Express側でWebhookの設定

7.最終的な統合の実行

もっと読む

HCL Compass Search for REST API サーバーの設定

2022/5月/26 - 読み終える時間: 2 分

SETUP HCL COMPASS SEARCH FOR REST API SERVER の翻訳版です。

---

HCL Compass Search for REST API サーバーの設定

2022年5月25日

著者: Nandeesh Shankarappa / Senior Software Engineer, HCL

前提条件

HCL Compass があなたのマシンにインストールされ、リポジトリにログインするための有効なクレデンシャルがあることを確認してください。

HCL Compass Search のインストール

1. 管理者モードでコマンドプロンプトを実行し、compassがインストールされているパスに移動します。(私のパス: C:\Program Files\HCL\Compass).

2. 以下のコマンドを実行します（ユーザー名はadmin、パスワードなし、レポ名はCompass、DB名はSAMPLとします）。

cqperl cpsearch.pl initSearch -username admin -password "" -dbset Compass -userdb SAMPL -searchHome C: \CPSearch.Home -solrHome C: \CPSolr.Home -solrPort 8984

注1: 別のユーザー DB に Search を追加する場合、同じ "CPSearch.Home" と "CPSolr.Home" を使用します。この方法で、すべての Search デプロイが同じディレクトリの 1 か所に配置されます。

注2: もし、追加のユーザーDBにSearchをデプロイする場合は、異なるポート番号を使用してください。 8985や8986など、次の利用可能なポートを使用してください。 どのポートが次に利用可能かわからない場合は、"CPSearch.Home "ディレクトリの下にある、既存の各サーチデプロイメントの "AboutThisSearch.txt "ファイルを見てください。

3. コマンドが成功すると、以下のようなメッセージが表示されます。

4. CompassSearchがインストールされているパスに移動します。(私のパス: C: \CPSearch.HomeCompass_SAMPL)

5. 手順4で作成したEntityファイル(FileName: Entity_Compass_SAMPL.txt)を開く。検索したいレコードタイプのフィールドに「&」を追加し、ファイルを保存sします。

6. コマンドプロンプトに戻り、以下のコマンドを実行します（ユーザー名は「admin」、パスワードなし、レポ名は「Compass」、DB名は「SAMPL」であると仮定します）。

cqperl cpsearch.pl deploySearch -username admin -password "" -dbset Compass -userdb SAMPL -searchHome C: \CPSearch.Home

7. コマンドの実行に成功したら、ブラウザでアプリケーションを開き、リポジトリにログインしてください。上部に検索バーが表示されているはずです。

happy searching!

HCL Compass with REST-server (トライアルバージョン) をインストールする

2022/5月/20 - 読み終える時間: 9 分

INSTALL HCL COMPASS WITH REST-SERVER (TRIAIL VERSION) - HCL SW Blogs https://blog.hcltechsw.com/compass/install-hcl-compass-with-rest-server-trail-version/

---

HCL Compass with REST-server (トライアルバージョン) をインストールする

2022年5月19日

著者: Nandeesh Shankarappa / Senior Software Engineer, HCL

* 説明

この記事は、HCL CompassをRESTサーバー上で動作するマシンにインストールし、設定するのに役立ちます（WASなし）。

* 前提条件

• インストールとセットアップはWindowsマシンで行われるため、Windows OSがインストールされている必要があります。
• データを格納するためのMS_Accessデータベース。
• Java がマシンにインストールされていること。

インストールマネージャーのインストール

もっと読む

HCL Compass Webhooks の活用法

2022/3/17 - 読み終える時間: 8 分

HCL Compass Webhooks in Action の翻訳版です。

---

HCL Compass Webhooks の活用法

はじめに

この記事では、HCL CompassのWebhooksについて説明します。Webhookとは、何かがトリガーされたときにアプリから送信される自動化されたデータに他なりません。この場合、HCL Compass は Webhook データを送信するアプリで、これは Payload とも呼ばれます。Webhook は Compass アプリケーションを購読し、特定の条件が満たされるまで待機し、ペイロードを送信します。ペイロードは通常、レコードデータを含む JSON で、HTTP POST リクエストとして送信され、サードパーティーアプリケーションまたはカスタムスクリプトでキャッチして、有用な処理を行えます。これはRESTAPIとは異なり、アプリケーションからCompassにリクエストを送信し、特定の情報を得たり、特定のアクションを実行したりできます。Compass Webhook レコードで定義された条件に基づいて、Compass から一定間隔でデータが送信されるのを待ちます。

このデモを行うために、まずHCL CompassインスタンスでWebhookを有効にするつもりです。これを行うために必要な手順を説明します。すべての設定が完了したら、シンプルな Python Flask アプリケーションを使用して、Compass Webhooks からの POST リクエストをリスンし、それを表示することで、その動作を証明します。

CompassでWebhooksを有効にする

HCL compassでWebhooksを有効にする方法について順を追って説明します。これらの手順のほとんどはWindowsに特有のものですが、UNIX環境でも同じように変換できます。

• Webhooksを使用するためには、HCL CompassのRESTAPIサーバーコンポーネントをインストールする必要があります。

Start -> Programs -> IBM Installation Manager -> View Installed Packages で確認できます。

ページが開いたら、以下のように表示され、RESTAPIサーバーがインストールされていることを確認します。

インストールされていない場合は、Installation Managerからインストールする必要がありますが、次のステップに進みます。

• 次のステップは、Webhooks 1.0 パッケージをスキーマリポジトリにインストールすることです。Compass Designerを起動し、スタート->プログラム->HCL Compass-> Compass Designerをクリックします。

• スキーマリポジトリに認証情報を使って接続し、スキーマ -> バージョン -> パッケージ - > パッケージを適用 をクリックします。

• Webhooks パッケージ 1.0 を選択し、適用します。

• パッケージで有効にするレコードの種類を選択します。

• パッケージが適用されたら、スキーマをチェックインし、データベースをアップグレードします。

Webhookの設定を作成する

Webhooks パッケージを使用すると、レコードに対して特定のアクションが実行されたり、レコードの状態が変化するなど、特定の条件が満たされたときに、他のシステムが Compass レコードに関する JSON ペイロードを受信できるようになります。

パッケージが正常に適用されたら、Webhooks を稼働させるために必要なレコードを作成する時間です。

Administratorアカウントでcqwebにログインし、WebhookMasterというタイプのレコードを追加します。WebhookConfig レコードの作成を許可するグループを追加します (これは必須ではありません)。このグループのユーザーは WebhookConfig を作成できます。また、コールバックURLを指定する必要がありますが、これはCompass Rest APIのURL以外の何物でもありません。私たちはそれをマシン上にローカルに置いているので、localhostという名前になっています。基本的に、Compassはサードパーティーのアプリケーションにデータを送信し、メッセージが配信されているかどうかを確認するために待機しています。そのため、コールバックURLにはその応答が期待されます。

次のステップは、WebhookConfigレコードの作成です。

ここでは、Webhookを起動するための有効なレコードの条件や、サードパーティーアプリケーションへのURLなど、Webhookのパラメータを定義する場所です。以下のスクリーンショットのように、DefectはWebhookを有効にする必要があるレコードタイプなので、compassdefectという名前を入力しました。ここでは任意の名前を付けられます。次のフィールドは URL で、サードパーティーアプリケーションが Compass Webhooks からの POST リクエストをリッスンするための URL です。 この例では、compassdefect ルートをリッスンするシンプルな Python Flask アプリケーションです。アプリケーションはCompassと同じシステムで動作しているので、127.0.0.1がループバックアドレスです。あなたの場合、これは別のIPまたはホスト名かもしれません。オプションで SECRET フィールドがありますが、これは Webhook データを保護するために使用されます。本番環境では有効にしておくことを強くお勧めします。あなたが提供する秘密は、HMAC-SHA1 ハッシュ関数を使用してペイロードをハッシュ化し、ペイロードと一緒に署名ヘッダーを介して送信されるために使用されます。アプリケーションでは、ハッシュ関数に秘密を渡し、ヘッダでCompassから提供されたものと一致するかどうかを確認する必要があります。

また、DescriptionフィールドにWebhookのDescriptionを指定できます。追跡が必要なレコードタイプを指定します。この場合、これは「欠陥」です。Webhookの種類をCommitかNotificationから選択します。Commit はコントロールに記載されたアクションが成功した場合のみペイロードを送信し、Notification はステータスに関係なくペイロードを送信することになっているという違いがあります。この場合、Commit が選択されています。

コントロール]タブでは、この場合、選択されているアクションは[投稿]、状態は[投稿]です。つまり、Defectレコードを投稿すると、FlaskサーバーにWebhookペイロードがトリガーされることになります。また、Controlsタブに関連した不具合もあり、その対処方法は以下のドキュメントに記載されています。

https://help.hcltechsw.com/compass/2.0.3/com.hcl.compass.doc/webhelp/oxy_ex-1/com.ibm.rational.clearquest.oslc_cmrest_api.doc/topics/t_create_webhook.html

PostmanなどのAPIクライアントを使用して、REST APIサーバーのhooksetupエンドポイントにHTTP POSTリクエストを作成します。このために、まずRESTAPIサーバを起動する必要があります。 Compassのインストールディレクトリに移動し、コマンドラインで以下のパスに移動し、start.batを実行します。

RESTサーバを起動すると、Server is NOT configured for Webhooksのような行が表示されるはずです。

サーバーが立ち上がったら、APIクライアントから、以下のエンドポイントを指定してHTTP POST Requestを実行します。

Method : POST

URL : https://localhost:8190/ccmweb/rest/hooksetup

Body : {

“username”: “admin”,

“password”: “”,

“repo”: “Gitintegration”,

“db”: “GITIN”

}

この場合、GITintegrationがスキーマ・リポジトリ、GITINがユーザー・データベースで、adminはパスワードのないユーザーです。

この場合、RESTサーバは同じマシン上で動作しているため、localhostという名前になっています。Compassで必要なアクションを実行できるシステムユーザーを作成することで、Webhooksパッケージで使用するためのサーバーを有効にします。

RESTAPIサーバーを再起動します。

今度はWebhooksがEnableになったことが確認できます。

Webhooksの実行

ここからは、すべて自動で行われるはずです。Compassは、新しいレコードが送信された瞬間にWebhookのペイロードのトリガーをかけます。このペイロードが正常に送信され、Flaskアプリケーションで読み込めるかどうかを確認します。この作業を行うには、RESTAPIサーバが稼働している必要があり、Flaskアプリケーションも同様に稼働していることを忘れないでください。

• Compassで新しい不具合を作成します。

• RESTAPI サーバが起動していない場合は起動し、Webhooks が動作していることを確認します。

そして、Flask Applicationでも同じようにデータを受信していることが確認できます。

Webhooksのトラブルシューティングはどのように行うのですか？

Compassでクエリを作成し、Webhooksを追跡できます。クエリのベースとなるのは、WebhookDataというレコードタイプにする必要があります。このクエリを実行すると、配信待ちのWebhookがあるかどうか、何回アプリケーションに配信しようとしたか、エラーがあるかどうかを確認できます。

配信するものがない場合、レコードは表示されません。

以下は失敗の例です。今回はFlaskサーバーが起動していないため、レスポンスコードが500、リトライが1となっています。

FLASKアプリケーションのサンプルコードです。

まとめ

注：これはあくまでデモンストレーション用のサンプルコードであり、本番で使用するものではないことに注意してください。

上記からわかるように、このアプリケーションはコンソールにデータを出力する以外には何もしていません。DBに格納したり、ウェブページに表示するために他の目的に使用するなど、他の多くのことを行うことができました。しかし、現実の世界では、サードパーティーアプリケーションとHCL Compassの統合をセットアップすることで、可能性は無限に広がります。Webhooksを使い始め、HCL Compassのデータと連携する可能性を探るきっかけになれば幸いです。

参考文献

https://help.hcltechsw.com/compass/2.0.3/com.hcl.compass.doc/webhelp/oxy_ex-1/com.ibm.rational.clearquest.oslc_cmrest_api.doc/topics/c_webhooks.html

HCL VersionVault Express と HCL Compassを統合するための Webhook (ウェブフック) の使用

2021/11/15 - 読み終える時間: 2 分

Using web hooks to integrate HCL VersionVault Express and HCL Compass の翻訳版です。

---

HCL VersionVault Express と HCL Compassを統合するための Webhook (ウェブフック) の使用

2021年11月12日

著者: Brett Markowitz / Software Developer

HCL Software が DevOps 分野で提供する最新の製品 HCL VersionVault Express は、Web UI や REST API などを一新して最近発売されました。VersionVault Expressは、VersionVault の基盤をベースにしており、HCLのセキュアなバージョン・コントロールと構成管理ソフトウェアに関するすべての情報を提供するとともに、簡単に立ち上げることができます。

HCL Compass 2.0 は昨年、同様に外観と機能を一新して発売され、その新しいREST APIとWebhook 機能により、VersionVault Express の完璧なコンパニオンとなっています。

その好例が、オープンソースのサンプル統合です。Node-Redで構築され、VersionVault ExpressとCompassを接続する2つのWebhookレシーバーを素早く作成することができました。

この統合に必要なCompass用Webhooksパッケージのインストール方法については、[]をご覧ください。

CompassでFeature、Task、Storyが作成されてユーザーに割り当てられると、VersionVault Expressのそのユーザーのストリームに対応するアクティビティが作成されるというシンプルな統合です。

そして、そのアクティビティがプロジェクトの統合ストリームに配信されると、Compassのレコードが更新され、追加、変更、削除されたファイルのリストがノートとして表示されます。

統合を含むフローを表示するには、GitHubリポジトリから「flowers.json」ファイルを取得し、Node-RedのWebインターフェイスを開きます（Node-Redがデプロイされている場所であれば、例えばhttps://localhost:1880）。

画面右上のハンバーガーメニューから「インポート」→「クリップボード」を選択し、ファイルをブラウズして開きます。

Compass/VVE Integration」という名前のフローがあるはずで、ここですべてが行われます。

SF_Constantsサブフローでは、統合の設定を行います。

ここには "Set Flow Constants "ノードがあり、VersionVault ExpressとCompassのインスタンスに関連する様々なプロパティを設定することができます。これらは非常に簡単なものですが、それぞれの詳細についてはGitHubリポジトリのREADMEをご覧ください。

フローをデプロイして、定数が設定され、Webhookエンドポイントがペイロードをリッスンしていることを確認してください。

次に、2つの「HTTP in」ノードがあることに注目してください。1つは「[POST] /compass」、もう1つは「[POST] /vve」と表示されており、それぞれが表示されている製品からのWebhookペイロードを処理します。

Compassからペイロードが送られてくると、フローはいくつかのことを順に行います。

• VersionVault Expressで認証します。
• レコードが割り当てられたユーザー名と、レコードが追加されたソリューション名を取り出します。
• ソリューション名を使用して、VersionVault Express内のプロジェクトを検索します。
• プロジェクト名とユーザ名から開発ストリームを取得します。
• CompassのレコードIDを名前にして、そのストリームにアクティビティを作成します。

アクティビティを配信すると、VersionVault ExpressのWebhookレシーバーにペイロードが送信され、以下のシーケンスが開始されます。

• CompassとVersionVault Expressで認証します。
• 配信された各アクティビティについて。
  • チェンジセットを取得し、どのファイルが追加、変更、削除されたかを確認します。
  • アクティビティの名前を使って、関連するCompassレコードを修正し、ファイル情報をメモとして追加する。

重要なのは、このサンプルを意図的にシンプルにしたことです。そのために、いくつかの仮定を組み込んでいます。

• VersionVault ExpressとCompassの両方にユーザーが存在し、そのユーザー名は両方で同じであること。
• ユーザーは、1つのプロジェクト内に1つの開発ストリーム（<プロジェクト名>_<ユーザー名>という名前のフォーマット）しか持たず、アクティビティが作成されるのはそのプロジェクトであること。
• VersionVault Expressのプロジェクトは、Compassで使用されているソリューションと一致する必要があります。

VersionVault ExpressとCompassの最新リリースでは、様々なWebhookイベントが利用できるため、単純な通知受信や複数製品間の複雑な統合など、機能拡張が容易に行えます。

HCL Compass Rest API の活用

2021/9/23 - 読み終える時間: 18 分

HCL Compass Rest APIs In Action の翻訳版です。

---

HCL Compass Rest API の活用

2021年9月20日

著者: Pradeesh S P / Technical Specialist, HCL Software

はじめに

この記事では、HCL Compass 2.0.2バージョンで提供されるRESTFULサービスについて説明します。HCL Compassでは、ウェブやデスクトップ・インターフェースの他に、Perl APIやJava Native Interfaceを使用することができます。これらの2つのオプションは、複雑で柔軟性に欠けているため、Compassを中心としたアプリケーションや統合の構築が難しく、時間がかかります。

HCL Compass REST APIは、開発者がHTTPベースのREST APIを使用してHCL Compassと対話することを可能にします。REST APIは、レコードの表示や修正、クエリの作成と編集、テキスト検索など、HCL Compassの多くの機能を実行するために使用できます。REST APIの機能は、コンポーネントとしてHCL Compassのインストールに含まれています。これは、Apache Tomcatインスタンス上に展開され、CQwebサービスから独立して実行されます。一度インストールすれば、あとはサービスを起動するだけで使い始めることができます。このブログでは、REST APIを利用してHCL Compassのデータと対話するPythonスクリプトを開発します。このスクリプトを作成しながら、一般的に使用されているRESTAPIのいくつかを紹介します。

この記事の内容

この記事は、プログラミングや、特定のタスクを実現するためのコードを提供するものではありません。単に、Compassデータと対話するためにREST APIを実用的な文脈で使用する方法を紹介するものです。もちろん、Pythonスクリプトを書くには、関数を使うなど、もっと簡単で効率的な方法があります。データ操作のコードの一部はスニペットに含まれておらず、ほとんどがREST APIと対話するためのリクエストモジュールの使い方を扱っています。

このスクリプトの役割

スクリプトを実行すると、システムで利用可能なリポジトリのリストを表示します。 パラメータとしてユーザー名、パスワード、データベースを入力することで、認証するリポジトリをリストから選ぶことができます。 選択したリポジトリに関連するデータベースを一覧表示します。 ユーザーにデータベースの提供を求め、そのユーザーに割り当てられたレコードを表示するためのクエリを構築する。 クエリを実行して、結果セットを表示します。 クエリを削除します。 REST サーバーからログアウトします。

このスクリプトで使用されるAPI

Repos API - Schema Repositories のリストを取得します。 Authenticate API - CCM REST サーバーへの認証を行います。 Databases API - スキーマリポジトリに関連付けられたデータベースを一覧表示する。 Folders API - クエリを作成する親フォルダーをリストアップする。 QueryDefs API - クエリ定義を作成する。 ResultSets API - クエリ定義を実行して、結果セットを構築します。 ResultSet API - 以前に実行された Query Definition の単一ページを取得します。 QueryDef API - クエリ定義を削除するためのものです。 Authenticate API - CCM Rest Server からログオフする。

では、これらのAPIを詳細に確認しながら、スクリプトを作成していきましょう。

1. スキーマリポジトリのリストの取得

最初のタスクは、ユーザーがスキーマリポジトリを選択できるように、スキーマリポジトリのリストを取得することです。これには、REPOS API、特にエンドポイントである/ccmweb/rest/repos を使用します。この目的のためには、GET HTTPリクエストを使用する必要があります。このデモでは、Python Requests モジュールを使用してREST APIスクリプトを作成します。そのためには、スクリプトにモジュールをインポートする必要があります。そして、request.get()関数を使用して、このAPIリクエストを送信します。request.get関数は、リポジトリのエンドポイントをURLとして受け取り、ヘッダを引数として渡します。この特定のAPIでは、期待されるヘッダーは次のとおりです。

'Content-Type': "application/json"

ヘッダー情報は headers という変数に保存され、URL は repo_endpoint という変数に保存されます。これは、Rest APIのリクエストを行うために、このスクリプト全体でrequestモジュールにパラメータを渡すための、標準的なテンプレートになります。

cont_type = “application/json”

headers={‘Content-Type’: cont_type}

repo_endpoint = “https://servername:8190/ccmweb/rest/repos”

response = requests.get(

repo_endpoint,

headers=headers

)

上記のコードは、システムで利用可能なリポジトリのリストを取得します。

2. CCM RESTサーバーへの認証

システムでリポジトリが利用できるようになり、ユーザーがログインするリポジトリを選択できるようになったので、認証を行う必要があります。REST サーバーへの認証には、/ccmweb/rest/authenticate をエンドポイントとする Authenticate API を使用します。使用するHTTPリクエストはPOSTです。まず、ユーザーにユーザー名、パスワード、リポジトリ名、ログインしたいデータベースを入力してもらいます。以前のREPOS APIとは異なり、Authenticate APIでは、上記の情報をJSON形式でボディに送信する必要があります。ヘッダーとURLの他に、今回はボディデータもrequests.postメソッドで提供しなければなりません。また、リクエストが何らかの例外やエラーメッセージを発生させたかどうかを知る必要があり、そのために raise_for_status() メソッドを使用します。すべてがうまくいけば、このリクエストは認証トークンをJSON形式で出力します。これは、Compassのデータを取得または変更するための今後のAPIリクエストに使用する必要があります。このデータを操作してトークンを取得するためには、このJSON出力を処理してPythonの辞書データ構造に変換する必要があります。そのために、.json()メソッドを使用します。Json.dumps関数は、Pythonで処理できるようにjsonデータを文字列に変換します。前回のAPIコールと同じヘッダーを今回も渡していることに注目してください。

期待されるヘッダーは、「Content-Type」。"application/json"

eponame = input(“\nEnter Repository Name : “)

auth_url = “https://servername:8190/ccmweb/rest/authenticate”

username = input(“\nEnter your username : “)

password = input(“\nEnter your password : “)

db1name = input(“\nEnter db name : “)

body_data={“username”:username,

“password”:password,

“repo”:reponame,

“db”:db1name

}

auth_response = requests.post(auth_url,headers=headers,data=json.dumps(body_data))

auth_response.raise_for_status()

auth_data=auth_response.json()

3. スキーマ・リポジトリに関連するデータベースの一覧表示

スキーマ・リポジトリに関連するデータベースの一覧を表示するには、エンドポイントがccmweb/rest/repos/repository name/databasesのDatabases APIを使用します。HTTPリクエストは GET です。今回は、先ほどのAPIコールのヘッダーとは別に、Authentication Token（先ほどのAPIコールの後に出力として受け取ったもの）を以下のフォーマットで送る必要があります。

期待されるヘッダーは ‘Content-Type’: “application/json”,

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

requests.get関数では、URLとヘッダを渡しています。また、resay_for_status()を行い、.json関数でレスポンスを読み込んでいます。このAPIでは、必須のボディデータはありません。データベースを辞書として取得し、それを処理してユーザーがCompassデータへのアクセスを選択できるように表示する必要があります。

auth = “Bearer”+” “+auth_data[‘token’]

headers1={‘Content-Type’: cont_type,

‘Authorization’: auth

}

db_url = f”https://servername:8190/ccmweb/rest/repos/{RespositoryName}/databases”

dbname_response = requests.get(db_url,

headers=headers1

)

dbname_response.raise_for_status()

dbnames = dbname_response.json()

4. 親フォルダのDBIDを取得してクエリを作成する

ワークスペース内のあるフォルダにクエリを作成する必要があります。そのためには、ルートワークスペースにどのようなフォルダがあるかを調べる必要があります。この例では、クエリは一時的なものなので、「Public Queries」フォルダに保存します。そのため、ワークスペース内の「Public Queries」フォルダの DBID を調べる必要があります。この目的のために Folders API を使用し、エンドポイントを /ccmweb/rest/repos/ リポジトリ名 /databases/ データベース名 /workspace/folders とします。 使用する HTTP リクエストは GET です。

期待されるヘッダーは、'Content-Type': "application/json",

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

requests.get関数にパラメータを渡し、いつものようにraise_for_status関数を使い、.json関数を使って出力されたレスポンスをキャッチする必要があります。このJSONデータをjson.dumps関数に渡します。この出力から、次のAPIで必要となるdbIdデータに興味があります。

parent_url = f”https://servername:8190/ccmweb/rest/repos/{RepositoryName}/databases/{DatabaseName}/workspace/folders”

parent_dbid_response = requests.get(parent_url ,headers=headers1)

parent_dbid_response.raise_for_status()

parent_dbid_higher = parent_dbid_response.json()

parent_dbid = parent_dbid_higher[1][‘dbId’]

5. クエリ定義の作成

ユーザーからアクセスが必要なデータベースと親DBIDの入力を得たら、スクリプトの目的は、そのデータベース内のどの欠陥が所有されているかをユーザーに表示することです。このため、最初のステップでは、ログインユーザが所有するすべての欠陥を表示するためのクエリ定義を作成する必要があります。この目的のために、QueryDefs API を使用します。エンドポイントは /ccmweb/rest/repos/リポジトリ名/データベース名/workspace/queryDefs で、使用する HTTP リクエストは POST です。このAPIでは、従来のAPIと同様のヘッダが必要ですが、構築されるクエリの構造を形成するボディデータが必須となります。

期待されるヘッダは ‘Content-Type’: “application/json”,

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

本体のデータは以下のようになり、変数query_dataに格納されます。

query_data={ “name”: “MyDefects”,

“dbIdParent”: parent_dbid,

“primaryEntityDefName”: “Defect”,

“queryFieldDefs”: [

{

“fieldPathName”: “Headline”,

“isShown”: “true”

}

],

“filterNode”: {

“boolOp”: “BOOL_OP_AND”,

“fieldFilters”: [

{

“fieldPath”: “Owner”,

“compOp”: “COMP_OP_EQ”,

“values”: [username],

“stringExpression”: “= username”

}

]

}

}

ボディデータをもう少し詳しく見てみましょう。いつものように、ボディデータはJSON形式です。

name – Name of the query.

dbIdParent – The dbid of the parent directory where the query is to be created.

primaryEntityDefName – Record type name.

queryFieldDefs – fieldPathName is the field name.

isShown : true – To display the specific field in the result set.

filterNode – boolOp – AND – Operator for adding multiple filters to the query.

fieldFilters – These are the fields to provide as filters.

fieldPath : Owner – Field name of the filter

compOp – COMP_OP_EQ – Denotes Equal to

values : [username] – ユーザー名は、ユーザーの実際のユーザー名に置き換えられます。この条件では、フィールドOwnerが提供されたユーザー名と等しくなっています。したがって、クエリはオーナーが提供されたユーザー名であるすべてのDefectをリストアップする必要があります。

API用のパラメータの準備ができたので、これらを requests.post 関数に渡し、いつものように raise_for_status 関数を使用して、.json 関数を使用して出力レスポンスをキャッチします。json.dumps関数でJSONデータを渡します。この出力から、次のAPIで必要となるdbIdのデータに興味があります。

query_db = input(“\nEnter Database name to build query : “)

query_data={ “name”: “MyDefects”,

“dbIdParent”: parent_dbid,

“primaryEntityDefName”: “Defect”,

“queryFieldDefs”: [

{

“fieldPathName”: “Headline”,

“isShown”: “true”

}

],

“filterNode”: {

“boolOp”: “BOOL_OP_AND”,

“fieldFilters”: [

{

“fieldPath”: “Owner”,

“compOp”: “COMP_OP_EQ”,

“values”: [username],

“stringExpression”: “= username”

}

]

}

}

query_url = f”https://servername:8190/ccmweb/rest/repos/{RepositoryName}/databases/{DatabaseName}/workspace/queryDefs”

query_response = requests.post(query_url,headers=headers1,data=json.dumps(query_data))

query_response.raise_for_status()

query_out = query_response.json()

query_dbid = query_out[‘dbId’]

6. クエリ定義の実行と結果セットの構築

前のステップで Query Dbid を受け取ったので、これを使ってクエリの実行と結果セットの構築を行う必要があります。これらの操作はいずれも ResultSets API で行います。使用する HTTP リクエストは POST です。この目的のために、次のエンドポイントを使用します。/ccmweb/rest/repos/repositoryname/databases/databasename/workspace/queryDefsquerydbid/resultsets。使用するヘッダーは、前のステップと同じです。

期待されるヘッダーは ‘Content-Type’: “application/json”,

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

このAPIでは、ボディデータの受け入れが必須となっています。もし特定のパラメータがない場合は、以下のように空の json を渡すことができます。

query_exec_data={

}

これ以外にも、URL、データ、ヘッダーが requests.get 関数に渡されます。いつものように、ここでも raise_for_status、json.dumps、.json の各関数を使います。出力結果から、次のAPIリクエストに渡すための「result_set_id」が得られることを期待しています。

query_exec_url = f”https://servername:8190/ccmweb/rest/repos/{RepositoryName}/databases/{DatabaseName}/workspace/queryDefs/{Querydbid}/resultsets”

query_exec_data={

}

query_exec_response=requests.post(query_exec_url,headers=headers1,data=json.dumps(query_exec_data))

query_exec_response.raise_for_status()

query_exec_results = query_exec_response.json()

resultset_id = query_exec_results[‘result_set_id’]

7. クエリの結果セットのユーザーへの表示

いよいよ結果セットをユーザーに表示します。これには、ResultSet API を使用し、エンドポイントとして /ccmweb/rest/repos/repositoryname/databases/databasename/workspace/queryDefs/querydbid/resultsets/resultsetid を指定します。前のステップの出力としてresultsetidを取得しました。HTTPリクエストはPOSTです。パラメータとしてURLとヘッダを指定するだけです。

期待されるヘッダは ‘Content-Type’: “application/json”,

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

Python Prettytableパッケージを使って、結果を表形式で表示します。結果セットの出力は、辞書形式で提供されます。そこから行の値を取得して、必要な値をPythonのリストとして抽出します。クエリ構成データでは、表示フィールドにHeadlineというフィールドのみを要求しましたが、出力にはデフォルトでdisplayNameが含まれており、これはレコードのID以外の何物でもありません。

result_set_url = f”https://servername:8190/ccmweb/rest/repos/{RepositoryName}/databases/{DatabaseName}/workspace/queryDefs/{Querydbid}/resultsets/{Resultsetid}”

result_set_response = requests.get(result_set_url,headers=headers1)

result_set_response.raise_for_status()

resultset_results = result_set_response.json()

second_final = resultset_results[‘rows’]

headline_value = []

id_value = []

for i in second_final:

headline_value.append(i[‘values’])

id_value.append(i[‘displayName’])

x.add_column(“ID”,id_value)

x.add_column(“Headline”,headline_value)

print(x)

8. クエリ定義の削除

次の作業は、作成したクエリを削除して、スクリプトを実行するたびに新しいクエリが作成されるように、Compass のデータベースに表示されないようにすることです。これには QueryDef API を使用し、エンドポイントを /ccmweb/rest/repos/reposittoryname/databases/databasename/workspace/queryDefs/querydbid とします。このためのHTTPリクエストはDELETEです。パラメータとしてurlとheadersを受け取ります。

期待されるヘッダーは ‘Content-Type’: “application/json”,

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

これまでのAPIリクエストで使われていた通常の機能とは別に、今回の違いは、何の出力も受け取らないということです。この場合、クエリが正常に削除されたかどうかをどうやって知ることができるでしょうか？それには、HTTPステータスコードを利用します。通常、HTTPレスポンスコードが200の範囲にあれば、リクエストが成功したことを意味します。そこで、HTTPレスポンスからステータスコードを取得するために、response.status_code関数が必要になります。これを条件文に渡すことで、クエリの削除が成功したかどうかを検証することができます。

remove_query_url = f”https://servername:8190/ccmweb/rest/repos/(RepositoryName}/databases/{DatabaseName}/workspace/queryDefs/{Querydbid}”

remove_query_response = requests.delete(remove_query_url,headers=headers1)

remove_query_response.raise_for_status()

remove_query_final_response = str(remove_query_response.status_code)

if remove_query_final_response.startswith(’20’):

print(“\nRemoving Query Successful”)

else:

print(“\nRemoving query failed! Please manually remove”)

9. CCM REST サーバーからのログオフ

クエリの出力をユーザーに表示することができたので、意図したタスクはすべて完了しました。あとは、セッションを蓄積してサーバに負荷をかけないようにするために、サーバからログオフするだけです。この目的のために、Authenticate APIを使用し、エンドポイントを/ccmweb/rest/authenticate/logoff とします。HTTPリクエストはPOSTです。先ほどのAPIリクエストと同様に、パラメータとしてURLとヘッダーのみを受け取ります。前のステップで行ったように、ログアウトが成功したかどうかを知るための出力はありませんので、ステータスコードも調べます。

期待されるヘッダーは 'Content-Type': "application/json",

Authorization: Bearer eyJhbGciOiJIUzUxMiJ9.eyJzdWIiOiJhZG1pbiIsInJlcG8iOiIxMC4wLjAiLCJleHAiOjE1NzM2NjE5NDUsImlhdCI6MTU3MzU3NTU0NSwiZGIiOiJTQU1QTCJ9.Lgdk9gPm6mFFGEnr6mRt7Vrq-nTnlP86ARKc16bP4syeTIvKQ55JX5r6aFXVC20xC2NwsjqbvAhd2f1r2PiIUA

logout_url=”https://servername:8190/ccmweb/rest/authenticate/logoff”

logout_response = requests.post(logout_url,headers=headers1)

logout_response.raise_for_status()

logout_final_response = str(logout_response.status_code)

if logout_final_response.startswith(’20’):

print(“\nLogout Successful”)

else:

print(“\nLogout Failed!”)

スクリプトの完全な出力

スクリプトの完全な出力は以下の通りです。システム内のリポジトリの一覧が表示されます。RESTサーバへの認証のために、ユーザ名、パスワード、データベースを入力する必要があります。

次に、ユーザが所有するレコードをリストアップするためのクエリを作成するために親ディレクトリを見つけます。レコードを作成して表示した後、クエリを削除してRESTサーバーからログアウトし、途中でエラーが発生した場合は報告します。

The repositories available on this server are

———————————–

CadenceTest RestAPIDemo

Authenticating to Compass Rest API server!

Enter Repository Name : RestAPIDemo

Enter your username : admin

Enter your password :

Enter db name : RESTD

Listing the Databases for the repository RestAPIDemo

The database name(s) are as follows

RESTD

restn

Building a Query to display records assigned to you

Enter Database name to build query : RESTD

Executing the Query

Displaying the Result Set

+—————+———————————–+

| ID | Headline |

+—————+———————————–+

| RESTD00000041 | [‘Testing RestAPI Demo Record 1’] |

| RESTD00000042 | [‘Testing RestAPI Demo Record 2’] |

+—————+———————————–+

Removing the Query

Removing Query Successful

Logging off

Logout Successful

結論

これで、COMPASS HTTP REST APIの使用を実演するための簡単なスクリプトを作成するという、我々がやろうとしたことは達成されました。これが、HCL Compassのデータを使ったより複雑なアプリケーションやインテグレーションの開発に役立つことを期待しています。

参考文献

https://help.hcltechsw.com/compass/2.0.2/com.hcl.compass.doc/webhelp/oxy_ex-1/com.ibm.rational.clearquest.oslc_cmrest_api.doc/topics/c_rest_api_introduction.html

HCL Compass の eSignature パッケージ機能

2021/9/23 - 読み終える時間: 4 分

eSignature package feature in HCL Compass https://blog.hcltechsw.com/compass/esignature-package-feature-in-hcl-compass/

HCL Compass の eSignature パッケージ機能

2021年9月20日

著者: Garima Hans / HCL TECHNICAL SPECIALIST

eSignatureとは？

電子署名（e-signature）とは、署名者を識別するための信頼できる方法を提供し、その人を電子文書の内容に拘束する電子的手段のことです。

なぜeSignatureが重要なのか？

電子署名は、コンパスの問題を解決するために、ユーザー認証とアクティビティの追跡を提供することで、データ・セキュリティの向上に役立ちます。 例えば、電子署名は、Compass環境を米国FDAに準拠させるために必要となる場合があります。

• すべてのレコードタイプにアクセスするためのユーザー認証を、各移行や変更の前に実施できます。
• 承認記録の承認/拒否時に電子署名を要求することをサポートします。
• トランジションの履歴とその作成者を専用パネルに表示します。

このような仕組みになっています。 あるレコードタイプにeSignatureパッケージを適用する。 そのレコードタイプのレコードには、eSignatureフィールドの新しいタブが含まれます。ユーザー名」「パスワード」「署名ログ」「Is Current」です。署名が必要な場合、ユーザー名とパスワードは必須フィールドとなり、そうでない場合は読み取り専用となります。

eSignatureパッケージはどのように適用できるのか

パッケージを適用できるのは、スキーマ管理者権限を持つユーザーまたはスーパーユーザー/コンパス管理者のみです。Compass管理ツールがインストールされているマシンから適用する必要があります。

1. HCL Compass Designerを起動します。
2. eSignatureパッケージを適用したいスキーマリポジトリに接続します。

3. スキーマバージョンを右クリックし、パッケージの適用をクリックします。

4. 適用する eSignature パッケージとそのバージョンを選択します。

5. 有効にしたいレコードタイプを選択します。

6. 完了をクリックして、選択したパッケージをインストールする。

7. インストールが完了したら、最新のスキーマバージョンの変更を確認して、ユーザーDBをアップグレードする必要があります。この作業は元に戻すことができませんので、DBA と共にバックアップを取ることを忘れないでください。

WebUIでレコードタイプにeSignatureを設定する

次のステップは、CompassのWebUIで行います。 あなた(または指定されたユーザー)は、選択したレコードタイプとデジタル署名を取得するアクションのためにeSig_Configを作成する権限を持っている必要があります。必要なオプションを選択し、保存をクリックします。

eSig_Configレコードには、署名するレコードタイプを選択するためのフィールドと、そのタイプのレコードがいつ署名されるかを示すために使用する2つのオプションが用意されています。ステート」と「アクション」です。レコード タイプがステートフルの場合は、State と Action の両方のオプションが使用できます。レコードタイプがステートレスの場合は、アクションのみが利用可能です。レコード タイプを変更すると、ステートとアクションの選択はクリアされます。

eSig_Config レコードに対してアクションベースの基準とステートベースの基準の両方を選択した場合、指定したタイプのレコードがいずれかの基準を満たす場合には、署名が必要となります。

署名が必要な場合、ここで入力されたユーザー名とパスワードは、HCL Compass環境へのログインに使用されたユーザー名とパスワードと比較されます。アイデンティティが一致した場合、変更が受け入れられ、署名が記録されます。IDが一致しない場合は、エラーメッセージが表示され、データベースへの変更は行われません。

セットアップが完了すると、誰かが既存のレコードや新しいレコードを変更した場合、変更を保存するためにeSignatureのユーザー名とパスワードのフィールドが必須となります。

eSignature Logに表示される情報は以下の通りです。

• 記録に署名した人のユーザー名。
• ユーザーの印刷名
• ユーザーのグループ・メンバーシップ
• 実行中のアクション。
• レコードの最終状態。
• アクションのタイムスタンプ。

署名は、署名が適用されてからレコードが変更されていない場合にのみ有効です。読み取り専用のフィールドIs Currentには、レコードへの最後の変更に署名が含まれている場合は値「True」が、そうでない場合は値「False」が格納されます。

eSignature」タブには、レコードの署名履歴を表示するフィールド「eSignature Log」があります。このフィールドには、署名が行われた変更のみが含まれます。

eSigログはカスタマイズも可能です。詳しいカスタマイズ方法については、https://help.hcltechsw.com/compass/2.0.2/com.hcl.compass.doc/webhelp/oxy_ex-1/com.ibm.rational.clearquest.schema.ec.doc/topics/sch_pkgs/c_customize_esig.html を参照してください。

あなたの組織では、スキーマにeSigパッケージのような同様の要件がありますか？下記のディスカッションにご参加ください。