ユーザ情報をローカルデータと同期させる（準備編）

常に Questetra BPM Suiteに登録するユーザ情報を社員名簿と合わせておくのは、手動ではかなり面倒でしょう。新しい社員が入ってきたら手入力でユーザ追加、社員が退職したら手作業でユーザ削除という方法でもいいですが、自動で手元の社員名簿と同期できれば管理はずっと楽になります。この記事では、Questetra BPM Suite のユーザ情報をローカルの TSV (Tab-separated values) データと同期させる Java プログラムを紹介します。

Questetra BPM Suite の Web API について

Questetra BPM Suite には、外部プログラムからシステム設定を操作できる Web API が用意されています。この API を用いることで、ブラウザから Questetra BPM Suite を操作せずともシステム設定の変更を行うことができます。今回はこの API を利用して、ユーザ情報の操作を行うプログラムを作成します。こちらで用意した Java ライブラリをインポートすることで、API アクセスに便利なクラスが利用できるようになります。

また、外部プログラムからシステム設定 API にアクセスする際には、Basic 認証か OAuth による認証が必要です。今回は Basic 認証を用いるので、あらかじめ Questetra BPM Suite のシステム設定で Basic 認証を有効にしておくための手順も紹介します。

開発環境

Java 1.8 + Maven 3 を使用します。また、Maven を用いて、以下の Questetra BPM Suite API クライアントライブラリをインポートします。

Questetra/qbpms-client-swagger: Questetra BPM Suite API Client Library for Java
- com.questetra:bpms.client.swagger:12.3.1 : The Central Repository Search Engine

Questetra BPM Suite の Basic 認証を有効にする

外部プログラムから Questetra BPM Suite へアクセスする際の認証として、今回は Basic 認証を利用します。Questetra BPM Suite の Basic 認証はデフォルトでは無効になっているため、設定で有効化する必要があります。

Basic 認証の有効化には、システム権限の一種であるシステム管理権限が必要です。また、Questetra BPM Suite 上のユーザ情報の操作には、システム権限の一種であるユーザ管理権限が必要です。各種システム権限をどのアカウントが持っているかは「システム設定 > システム権限」から確認できます。

まずはシステム管理権限を持っているアカウントで「システム設定 > API クライアント」を開き、「Basic 認証による API アクセスを有効にする」にチェックを入れて保存してください。

Basic 認証が有効になると、ユーザ管理権限を持っているアカウントで「アカウント設定 > パスワード」から Basic 認証用パスワードが確認できます。

以降、Questetra BPM Suite API を利用する際の Basic 認証情報として、ユーザ管理権限を持っているアカウントのメールアドレスと、そのアカウントの Basic 認証用パスワードを用いることができます。

Maven で新規プロジェクトを作成

本記事では Java プログラムの作成に Maven 3 を使用します。まだインストールしていない方はインストールをお願いします。

Maven – Welcome to Apache Maven

用意ができたら Maven で新規プロジェクトを作成してください。Eclipse や IntelliJ IDEA など、Maven に対応した IDE（統合開発環境）を使用するのがおすすめです。

POM.xml の編集

Maven プロジェクトでは、使用するライブラリを POM.xml に記述することになっています。先述した Questetra BPM Suite API クライアントライブラリ com.questetra.bpms.client.swagger を POM.xml に追記してください。POM.xml はプロジェクトディレクトリ直下にあります。

<!--?xml version="1.0" encoding="UTF-8"?-->
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemalocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <modelversion>4.0.0</modelversion>

    <groupId>questetra</groupId>
    <artifactId>swagger-java</artifactId>
    <version>1.0-SNAPSHOT</version>

    <properties>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
    </properties>

    <dependencies>
        <dependency>
            <groupId>com.questetra</groupId>
            <artifactId>bpms.client.swagger</artifactId>
            <version>12.3.1</version>
            <scope>compile</scope>
        </dependency>
    </dependencies>

</project>

太字の dependency 要素が追記部分です。

ユーザの検索を行うクラスを実装してみる

では、実際に Questetra BPM Suite から API を利用してみましょう。Java プログラムから Questetra BPM Suite のユーザ情報を変更する前に、まずはユーザの検索を行うところから始めましょう。

Questetra BPM Suite の API クライアントライブラリである com.questetra.bpms.client.swagger には、ユーザ情報を操作するための QuserApi クラスが用意されています。

qbpms-client-swagger/QuserApi.md at master ・ Questetra/qbpms-client-swagger

このクラスを利用して、Basic 認証 → ユーザ情報の各種操作を行うためのクラス UserDataManager クラスを実装します。Maven プロジェクトでは {プロジェクトディレクトリ}/src/main/java/ 以下にコードを配置します。UserDataManager.java もそこに作成してください。なお、このサンプルコードをそのまま利用する場合は URL・メールアドレス・Basic 認証用パスワードを環境に合わせて書き換えてください。メールアドレスと Basic 認証用パスワードは Basic 認証の項で触れた通り、ユーザ管理権限を持っているアカウントのものである必要があります。

// {プロジェクトディレクトリ}/src/main/java/UserDataManager.java
import com.questetra.bpms.client.swagger.model.*;
import com.questetra.bpms.client.swagger.ApiClient;
import com.questetra.bpms.client.swagger.ApiException;
import com.questetra.bpms.client.swagger.Configuration;
import com.questetra.bpms.client.swagger.auth.*;
import com.questetra.bpms.client.swagger.api.QuserApi;

class UserDataManager {
    private final QuserApi apiInstance;

    public UserDataManager() {
        ApiClient defaultClient = Configuration.getDefaultApiClient();
        // URL を設定
        defaultClient.setBasePath("https://example.questetra.net/");

        // Basic 認証
        HttpBasicAuth basic 
                = (HttpBasicAuth) defaultClient.getAuthentication("basic");
        basic.setUsername("{メールアドレス}");
        basic.setPassword("{basic認証用パスワード}");

        this.apiInstance = new QuserApi();
    }

    /**
     * 登録済のユーザから指定のユーザを検索する。見つからない場合は例外送出。
     * @param id ユーザID。わからない場合は{@code null}を渡す。{@code null}以外を渡した場合は{@code email}よりも優先される。
     * @param email 登録メールアドレス。わからない場合は{@code null}を渡す。
     * @return QuserWithPrimaryQgroupWrapper 検索されたユーザ。
     */
    public QuserWithPrimaryQgroupWrapper find(Long id, String email) {
        QuserWithPrimaryQgroupWrapper result = new QuserWithPrimaryQgroupWrapper();
        try {
            // ユーザを検索
            result = this.apiInstance.findQuser(id, email);
        } catch (ApiException e) {
            // 例外処理
            System.err.println("Exception when calling QuserApi#find");
            e.printStackTrace();
        }
        return result;
    }
}

UserDataManager クラスのメソッド find は、ユーザ ID（Long 型）かメールアドレス（String 型）でユーザを検索できます。ユーザ検索には QuserApi クラスのメソッド findQuser を用いています。

この find メソッドを用いて実際にユーザ検索をしてみましょう。次のような Test クラスを作成してください。

// {プロジェクトディレクトリ}/src/main/java/Test.java
import com.questetra.bpms.client.swagger.model.*;

class Test {
    public static void main(String[] args) {
        UserDataManager test = new UserDataManager();
        QuserWithPrimaryQgroupWrapper user = test.find(null, "{検索するユーザのメールアドレス}");
        System.out.println(user);
    }
}

UserDataManager クラスのインスタンスを作成し、find メソッドを実行するようになっています。ユーザ ID よりメールアドレスの方がわかりやすいので、サンプルコードではユーザ ID は null にしてメールアドレスを入力することにしています。該当のユーザが見つかれば標準出力にユーザ情報が表示されます。ビルドして実行してみましょう。

> class QuserWithPrimaryQgroupWrapper {
>     quser: class QuserWithPrimaryQgroup {
>         email: questetra+Canarias@gmail.com
>         id: 11
>         name: カナリア
>         primaryQgroup: class Qgroup {
>             email: 
>             id: 2
>             name: 10 管理部
>             parentQgroupEmail: 
>             parentQgroupId: 1
>             parentQgroupName: 00 全社
>         }
>     }
> }

このような表示が出ましたでしょうか。該当ユーザが見つからなかった場合は例外が送出されます。

このように、com.questetra.bpms.client.swagger をインポートすることで Questetra BPM Suite の API を利用できるようになります。次の記事ではこの UserDataManager クラスにユーザアカウント情報操作に必要なメソッドを追加し、ローカルの CSV ファイルと Questetra BPM Suite でユーザアカウント情報の同期を行うクラスを新しく実装します。

次: ユーザ情報をローカルデータと同期させる（ユーザ情報編）