CA Agile Central データベース コネクタ (Postgres)

概要

CA Agile Central データベース コネクタでは、Agile Central (AC)のエンティティ アイテム情報が取得され、CSV ファイルまたは Postgres データベース テーブルに書き込まれます。Agile Central データベース コネクタは、一方向および 1 回限りのメカニズムとして分類されます。コネクタは、Windows、Linux、または Mac で実行されます。Agile Central 内の情報は変更されません。情報は、ターゲット データベース内のテーブルへの入力に使用される CSV ファイルにのみ書き込まれます。Agile Central データベース コネクタは、目的のスケジュールに従ってご使用のプラットフォーム上で実行するソフトウェアで構成されています。コネクタの設定は、YAML テキスト ファイルで表されます。設定ファイルでは、指定される各エンティティが、Agile Central データ モデルのリーフ エンティティである限り、1 つまたは複数の Agile Central エンティティの一覧を指定できます。一般的なエンティティは、ストーリー、ディフェクト、タスク、リリース、およびユーザです。AC エンティティとデータ モデルについては、AC ヘルプ ドキュメント、特に WSAPI に関するサブドキュメントを参照してください。

データベースの要件および考慮事項

  • データベースはすでにインストールおよびセットアップされ、稼働できる状態である必要があります。このコネクタによってデータベースが作成されることはありません。コネクタは、データベースが存在するのと同じホスト上でインストールまたは実行する必要はありません。データベースは、コネクタをインストールするネットワーク上でアクセス可能なホスト上に存在している必要があります。設定ファイルの DB セクションで指定したユーザは、データベース テーブルを作成する権限を持っている必要があります。
  • コネクタは、ターゲット データベースにテーブルを一括でロードするための CSV ファイルを生成し、CSV/ ディレクトリに保存します。データベース名は、設定ファイルの DB セクションの Name プロパティに設定されます。CSV/default ディレクトリは、CSV のみのモードで作成される CSV ファイル用に予約されているため、データベースに default という名前は付けないでください。
  • データが取得され、ターゲット データベースにロードする CSV ファイルに書き込まれるようにするには、設定ファイルの DB セクションに、必要なすべてのエントリおよび任意のエントリが含まれている必要があります。デフォルトでは、このモードで、データベース テーブルに CSV ファイルの情報がいったんロードされると CSV ファイルは削除されます。この動作は、設定ファイルの DB セクションでの設定によって変更できます。
  • デフォルトでは、コネクタの実行時に、エンティティの CSV ファイルが書き込まれてから、データベース テーブルにそのデータがロードされる前に、コネクタはターゲット テーブルを削除して再作成します。この動作は、設定ファイルの DB セクションで変更できます。これは、データベース テーブル内のデータの適合性と一貫性について影響があることに注意してください。
  • ほとんどのデータベースの実装では、テーブルのエイリアスを使用できます。このエイリアスの機能は、データベース テーブル名にタイムスタンプが含まれるように指定する場合に使用できます。それにより、コネクタを実行するたびに、テーブルの完全に新しいセットが作成され、コネクタによって取得された AC データが入力されます。エイリアス(通常は、タスク(Task)などの AC エンティティの名前)は、最新の 値を持つデータベース テーブル Task_ を参照します。これにより、エンティティの名前だけを使用してクエリやレポートを実行できます。
  • コネクタでは、データベースの一括挿入の権限が必要です。この問題についてサポートが必要な場合は、データベース管理者にご相談ください。

このガイドの内容は以下のとおりです。

ソフトウェア要件

  • Postgres データベースがインストール済みであること。
  • Python 3.5 または 3.6 (Windows の 64 ビット バージョンをお勧めします)。インストーラを www.python.org からダウンロードします。

コネクタのダウンロード

コネクタをダウンロードするには、ここの手順に従います。

インストール

Postgres のインストール

サンプル コンテンツ

LICENSE         # CA 著作権ファイル
README-Postgres.txt      # このファイル
ac2db # コネクタ起動スクリプト(これが実行するファイルになります)
configs         # このコネクタで使用する設定ファイルを保持
     sample_postgres.yml # 参照の基準として使用するサンプル設定ファイル
csv             # コネクタの実行によって生成される CSV ファイルを保持
dbeif           # dbeif モジュールのルート ディレクトリ
log             # コネクタの実行によって生成されるログ ファイルを保持


セットアップ

一般的な推奨事項

最初はシンプルにします。

  • 処理する 1 つまたは 2 つのエンティティを特定します。
  • 目的のフィールドの最小数を指定します。
  • クエリ設定アイテムを使用して、取得または書き込みを行う Agile Central エンティティ レコードの量を制限します。
  • Service の Preview: True 設定を使用して、適切かつ実用的なレコード数を確認します。

データベース テーブルの命名ポリシーを決定します。

  • AC エンティティ名をデータベース テーブルの名前として使用すると最も簡単です。
  • 実行ごとに一般的なタイムスタンプがテーブル名に含まれるように指定できますが、そのためには、データベース内に十分な容量が確保されている必要があります。古いテーブルを削除しない限り、データベースでは実行ごとに n 個の新しいテーブルを追加します。n は設定ファイルで指定した異なる AC エンティティの数です。

変更は段階的に行います。

  • シンプルな設定が機能することを確認したら、エンティティ、フィールド、セレクタなどを、目的の達成のために必要に応じて追加できます。

初期の段階でログ ファイルをレビューし、エラーまたは警告があるかどうかを確認します。適切な操作を確認した後、ログ ファイルの自動モニタリングを設定することもできます。

セットアップ

  1. configs * サブディレクトリを特定します。
  2. sample_postgres.yml ファイルを、環境に合わせて名前が付けられたファイルにコピーします。たとえば cp sample_postgres.yml から product_x.yml などです(または他の適切な名前が付けられた拡張子が .yml のファイル)。
  3. product_x.yml ファイルを編集します。認証情報、ワークスペース、プロジェクト、サーバ、名前のサンプル値を、お使いの環境に有効で関連する値に変更します。

* 設定ファイルの構文については、「付録 A」を参照してください。


操作

手動

ターミナル ウィンドウまたはコンソールを使用して以下を実行します。

  1. cd コマンドを使用して、インストールのルート ディレクトリに移動します(たとえば、/opt/local/sw/dbeif-1.1.0)。
  2. python3.6 ac2db acdata.yml

このソフトウェアでは、設定ファイルが configs サブディレクトリ内に存在している必要があります。コマンド ラインでファイルのベース名を指定します。コマンド ライン引数でサブディレクトリを指定しないでください。

スケジュール済み

cron、launchctl、または Windows タスク スケジューラを使用します。このソフトウェアを実行する対象の環境が、以下を実行できるよう適切に設定されていることを確認してください。

python3.6 $DBEIF/ac2db_connector your_config_file_name

$DBEIF は、ソフトウェアがインストールされているディレクトリへの完全修飾パスを含む環境変数への参照です。たとえば、パッケージを /opt/local/sw に解凍する場合は、DBEIF を以下のように設定します。

export DBEIF=/opt/local/sw/dbeif-1.1.0


トラブルシューティング

コネクタは、常に設定ファイル名に基づいてログ ファイル名を書き込みます。ログ ファイルは、ベース インストール ディレクトリの下の log サブディレクトリに書き込まれます。設定ファイル内で、ログ ファイルに書き込まれるログ情報の量を決定する LogLevel を設定できます。LogLevel を DEBUG に設定した場合、完全なログ メッセージを取得できます。これは、問題が発生した箇所を突き止めたり、異常が発生した時点で処理されていた情報を特定したりするのに役に立ちます。

最初の設定では、コネクタをプレビュー モードで実行します。これにより、データベース テーブルを作成および入力しなくても、Agile Central とデータベースへの接続が確立され、正しく初期化および検証することができます。このモードでは、Agile Central のエンティティごとのレコード数が表示されます。これはデスティネーション CSV ファイルまたはデスティネーション データベース テーブルに書き込まれます。


エラー

  • フィールドがフェッチで 2 回記述されているエラー
    解決策: STATE フィールドのいずれかをフェッチから削除します。
    
            .....
              DEBUG: AgileCentralConnection.createFieldCategories - ACConn.createFieldCategories has pi_state_fields: [] and field_categories['pi_state'] of: [] 
              ERROR: DBConnector.run - RallyResponseError in DBConnector.run processing entity: Story -- Unable to retrieve 10 chunks of data 
            .....
    
  • 読み取り専用アクセスで APIKey を使用するエラー
    解決策: 完全なアクセス権を持つ APIKey を使用します。
           .....  
    FATAL: AgileCentralConnection.connect(128) -  Unable to connect to Agile Central at rally1.rallydev.com: 403 b'\n

     

  • EnvironmentalKey の ident_vector が有効でないエラー
    解決策: DB と CA Agile Central の両方に対してユーザ ID とパスワードを再入力します。
           .....
              FATAL: SecurityManager.decrypt(51) -  EnvironmentalKey ident_vector not valid for decryption target value.  Reset all credential values to clear text in config file!
            .....

     

 

CSV のみのモード

CSV ファイルにデータをエクスポートしてデータベースを使用する予定がない場合は、データを CSV ファイルにエクスポートするよう選択できます。この場合、データベースをインストールする必要はなく、設定ファイルのデータベース セクションは省略します。コネクタは、処理されるエンティティごとに CSV ファイル(ファイル名にタイムスタンプが含まれています)に書き込み、CSV/default フォルダに保存します。この方法で実行すると、コネクタは CSV サブディレクトリから CSV ファイルを削除しません。

たとえば、データベースへの入力は行われないため、DB セクションの下の設定は省略されます。Service セクションは任意です。このセクションがない場合は、そのプロパティはデフォルト値に設定されます。

AgileCentral:
        Server    :    rally1.rallydev.com
        APIKey    :    _abc123x
        Workspaces:
            - Workspace: Jazz
              Projects:
                  - Deep Cats
        Entities: HierarchicalRequirement,Defect
        Fetch: ObjectID,FormattedID,Name,ScheduleState,State,Project,Workspace
        ResolveUser: False

データベース テーブル

タイムスタンプ ファイル

Postgres のみ - CSV ファイルにデータをエクスポートしてデータベースを使用する予定がない場合は、データを CSV ファイルにエクスポートするよう選択できます。この場合、データベースをインストールする必要はなく、設定ファイルのデータベース セクションは省略します。コネクタは、処理されるエンティティごとに CSV ファイル(ファイル名にタイムスタンプが含まれています)に書き込み、CSV/default フォルダに保存します。この方法で実行すると、コネクタは CSV サブディレクトリから CSV ファイルを削除しません。

例: ファイルには処理されるエンティティに基づいて名前が付けられますが、実行時のタイムスタンプが付加されるか、またはエンティティのみにするかを選択できます。


TimeStampFiles: True または False

既存のテーブルの削除

処理されているエンティティに関して名前が付けられた既存のデータベース テーブルを、エンティティについて名前が付けられたテーブルを作成するかテーブルに入力する処理の前に削除するかどうかを制御します。(Postgres のみ - TimeStampFiles が False の場合のみ関連)


DropExistingTables: True または False

Agile Central に関する考慮事項

設定ファイルの AgileCentral セクションで ResolveUser プロパティを True に設定すると、コネクタはユーザを _refObjectName で表します。これは、AgileCentral ではデフォルトで DisplayName になります(DisplayName が空でない限り)。ResolveUser が True に設定されている場合、作業アイテム テーブルの[所有者]列には、「Wallace, Gromit」などの表示名が入力されます。ResolveUser が False に設定されている場合、作業アイテム テーブルの[所有者]列には、ObjectID が入力されます。AgileCentral のユーザ オブジェクトの表示名(DisplayName)フィールドは、一意である必要はありません。AgileCentral サブスクリプションでは、DisplayName が同じ Wallace である 2 人の異なるユーザが存在することができます。

ユーザを表示名に解決する代わりに、以下の方法を使用することができます。

  1. ResolveUser を False に設定します
  2. AgileCentral ユーザをデータベースのユーザ テーブルにエクスポートします
  3. AgileCentral 作業アイテムを、同じデータベースの対応するテーブル(タスク、ストーリーのテーブルなど)にエクスポートします
  4. コネクタの実行が完了した後、2 つのテーブル(タスクおよびユーザなど)の間で結合(Join)を使用できます

両方のテーブルから列を結合するタスクおよびユーザ テーブルの JOIN の例を以下に示します。

SELECT task.objectid, task.formattedid,task.owner, users.username AS "owner username", users.officelocation AS "owner officelocation" FROM task, users WHERE task.owner=users.objectid;

 objectid   | formattedid |    owner    |    owner username           |  owner officelocation
------------+-------------+-------------+-----------------------------+----------------------
86253669480 | TA93985     | 32429145056 | [email protected]   | 62 West Wallaby St
86253670264 | TA93986     | 32429145056 | [email protected]   | 62 West Wallaby St
86253670816 | TA93987     | 32429145000 | [email protected]  | 62 West Wallaby St
86253670827 | TA93999     | 32429147147 | [email protected]      | Mossy Bottom Farm
  • Agile Central の WebServices API で、Agile Central ユーザ エンティティのクエリを実行した場合、クエリ条件が指定されないとそのユーザのみが返されます。クエリ(ユーザ エンティティに対して BaseQuery または Selector として表現)を空にしない場合、複数のユーザが取得されます。

    例: BaseQuery: ((Disabled = True) OR (Disabled != True))

  • 1 つの設定ファイルを使用することはできますが、同じデータベースに複数の設定ファイルを使用する方が効率的な場合もあります。たとえば、タスク、ストーリー、フィーチャー、ユーザのテーブルを 1 つのデータベースに作成するとします。1 つの設定ファイルを使用することもできますが、異なるオブジェクトを 1 つの設定ファイルに混ぜ合わせると、Agile Central BaseQuery (分母の最小公倍数として機能)を作成するのが難しくなり、フェッチ(Fetch)リストも大き過ぎて扱いづらくなります。以下の 2 つの設定ファイルを作成することもできます。1 つの設定ファイルのエンティティ プロパティには、タスク、ストーリー、フィーチャーのリストを指定し、もう 1 つの設定ファイルのエンティティには、ユーザ オブジェクトのみのリストを指定します。ユーザ(User)は Postgres データベース内で予約済みのテーブル名であるため、コネクタは競合を回避するためにユーザ テーブルを作成します。これは自動的に行われます。設定ファイルのエンティティ プロパティでは、有効な AgileCentral エンティティ名である「ユーザ」を使用する必要があります。

  • Fetch でフィールド名のリストを指定する際、Agile Central WSAPI ドキュメントで示されている属性名を使用する必要があります。 ほとんどの場合、非カスタム フィールドでは最初の文字を大文字にする必要があります。ScheduleState など、複合語である属性の場合は、各単語の先頭を大文字にします。カスタム フィールドを指定する場合は、c_ のプレフィックスを使用します。以下に例を挙げます。
    Fetch: ObjectID,FormattedID,ScheduleState,FoundInBuild,c_ExternalID

  • 複数のエンティティに含まれている場合でも、Fetch 内にフィールドを重複して指定する必要はありません。たとえば、エンティティ リストに HierarchicalRequirement と Defect の両方が含まれている場合、ScheduleState を 1 度指定するだけで十分です。

  • コネクタでは、標準とカスタムの両方のポートフォリオ アイテム タイプがサポートされています。ポートフォリオ アイテム エンティティは、設定ファイルの AgileCentral セクションのエンティティ プロパティに指定する必要があります(PortfolioItem/ は含めません)。以下の例では、標準ポートフォリオ アイテム タイプのフィーチャー(Feature)と、カスタム ポートフォリオ アイテム タイプの戦略(Strategy)の両方が含まれます。

    Entities: Feature, Strategy

    コネクタは、カスタム ポートフォリオ アイテム タイプの名前が標準のエンティティ名に一致する場合、あいまいなユース ケースをサポートしません。たとえば、Agile Central の標準エンティティが task で、同様に名前が付けられたポートフォリオ アイテムが PortfolioItem/Task だとします。

    上記のこの制約は、あいまいに名前が付けられたアイテムを参照する場合でも適用されます。カスタム ポートフォリオ アイテム タイプが Agile Central システムの既存のエンティティと同じ名前である場合、このコネクタを使用することはできません。

付録 A: 設定ファイルの編集

Agile Central データベース コネクタは、YAML 形式のテキスト ファイルを使用します。簡潔にするため、このドキュメントでは最も重要ないくつかの構文アイテムを扱い、コネクタで使用できる有効な YAML 設定の 3 つのセクションについて説明しています。

説明が含まれる設定ファイルのサンプルについては、このページの下部にある「サンプルのダウンロード」を参照してください。

  • ファイルを編集するには、MS Word や Google ドキュメントではなく、テキスト エディタを使用してください
  • ファイルにはタブ文字を使用しないでください。YAML ではタブ文字が許可または認識されません
  • ファイルは UTF-8 形式で保存します
  • 等幅フォントを使用します
  • インデントには同じ数のスペースを使用するようにします(YAML ドキュメントでは通常 4 つのスペースをインデントに使用します)
  • 行では、引用符のない # 文字の最初のオカレンスはコメントであることを示し、# 文字とそれに続くすべての文字は処理の際に無視されます
  • セクションの順序は sample.yml ファイルと同じになるようにします
  • コロン(:)は重要なので注意してください。コロンによってキーと値が分離されます
  • ダッシュ(-)も重要です。ダッシュはリストの開始を示し、リストにはリスト アイテムを構成するキーと値のペアが 1 つ以上含まれます
  • 値にスペースが含まれている場合、通常は引用符で囲む必要はありません。# 文字が埋め込まれている場合は値を引用符で囲む必要があります

YAML 構文の詳細については、www.yaml.org/start.html の Web ページを参照してください。

template_config.yml ファイルの構造を以下に示します。

DatabaseConnector:
    AgileCentral:
        ...  # いくつかのキーと値のペアはこのセクションに関連します
    DB:
        ...  # いくつかのキーと値のペアはこのセクションに関連します
    Service:
        ...  # コネクタの全体的な処理に関連するいくつかのキーと値のペアは、このセクションに表示されます
        ...

AgileCentral セクションでは、Agile Central との接続の取得に使用する値を指定します。DB セクションでは、ターゲットのデスティネーション データベースとの接続の取得に使用する値を指定し、テーブルにタイムスタンプを追加する方法や、既存のテーブルを削除できるかどうかを制御するポリシーを指定します。Service セクションでは、全体的なコネクタ動作の一部の側面を制御します。


付録 B: Agile Central プロジェクト仕様

AgileCentral では、プロジェクト名は一意である必要はありません。コネクタは、同じ名前のプロジェクトを識別する仕組みを提供しています。


たとえば、プロジェクト ツリーの一部が以下のようになっているとします。

    |__ Biospheric
        |__ Salamandra
        |__ Corral
            |__ Salamandra

// シーケンスを使用してパスの要素を区切ります。

Salamandra プロジェクトの最初のオカレンスを指定するには、以下のようにします。

Biospheric // Salamandra

Salamandra プロジェクトの 2 番目のオカレンスを指定するには、以下のようにします。

Biospheric // Corral // Salamandra

デフォルトでは、コネクタはプロジェクトの親または子を含めません。プロジェクト名に /* を追加すると、プロジェクトの子プロジェクトまでが対象に含まれます。設定ファイルの AgileCentral セクションの例を以下に示します。

AgileCentral: 
       Server  : rally1.rallydev.com 
       APIKey  : _abc123x 
       Workspaces: 
           - Workspace: Jazz 
             Projects: 
                 - Deep Cats/* 
      Entities : HierarchicalRequirement 
      Fetch    : ObjectID,FormattedID,Name,Project,Workspace 
      ResolveUser: False


場合によっては、ワークスペースのスコープのみが必要とされ、プロジェクトの指定を AgileCentral セクションから完全に省略することもできます。AgileCentral ユーザ データを rallyusers データベースにエクスポートする設定ファイルの例を以下に示します。

     AgileCentral:
        Server    :  rally1.rallydev.com
        APIKey    : _abc123x
        Workspaces:
            - Workspace: N
        BaseQuery:  (LastLoginDate > 2017-05-01)
        Fetch: ObjectID,UserName,LastLoginDate
        Entities: User
        ResolveUser: False
     DB:
        Type: Postgres
        Name: rallyusers
        User      : postgres
        Password  : postgres
        Server: 127.0.0.1
        Port: 5432
        SaveCSV:  True
        Populate: True
        DropExistingTables: True
        TimeStampTables: False


付録 C: Postgres データベースのユーザ特権

DB セクションの Superuser プロパティが True に設定された場合、コネクタは SQL COPY コマンドを実行して csv の行をデータベースに一括でコピーします。次のエラーが発生した場合は、Superuser プロパティを False に設定してください: must be superuser to COPY to or from a file。ヒント: いずれのユーザでも、stdout へのコピーまたは stdin からのコピーは実行できます。psql の \copy コマンドも任意のユーザが実行できます。コネクタは psql の \copy コマンドを使用して一括コピーを試行します。

リビジョン履歴

  • 1.1.0-master --- 2018 年 1 月 25 日
    • 機能強化:
      • MS SQL Server をサポートします。
  • 1.0.1-master --- 2017 年 12 月 2 日
    • 修正:
      • スキーマでのスペースの不一致に対応しました。
  • 1.0.0-master -- 2017 年 6 月 22 日
    • 修正:
      • 初期リリース - Postgres DB で動作します。

サンプルをダウンロード

フィードバック

ヘルプをお求めですか?CA Agile Central コミュニティは、セルフサービスとサポートのワンストップ ショップです。CA Agile Central サポートにフィードバックを送信したり、答を見つけたり、他のユーザとのコラボレーションには CA Agile Central コミュニティ にご参加ください。