kickflow
kickflowを業務アセットとして接続するために必要な準備と、接続後に管理できる対象を説明します。接続には、kickflowで発行したAPIトークンが必要です。
概要
kickflowは、株式会社kickflowが提供するクラウド型の申請・承認サービスです。稟議や各種申請の起案から承認までをオンラインで進め、組織の意思決定プロセスをデジタル化します。
| 参照先 | リンク |
|---|---|
| 公式Webサイト | kickflow（キックフロー） |
| APIリファレンス | kickflow Developer |
管理できること
| 機能 | 対応 |
|---|---|
| アカウント作成 | ○ |
| グループ付与 | — |
| ロール付与 | ○ |
| アプリ | — |
| グループプッシュ | — |
接続方式は標準コネクタです。表の—は、対応していないことを表します。
管理する対象
| kickflowの対象 | YESODでの扱い |
|---|---|
| ユーザー | アカウントとして管理します |
| 管理者ロール | 割当として管理します。複数のロールを同時に付与できます |
| チーム | 割当ではなく、同期する項目で管理します |
| 組織図 | チームを操作するときの前提として参照します。組織図自体は操作しません |
チームを割当として扱わないのは、kickflowのチーム所属に役職ID（gradeIds）と上長フラグ（leader）の指定が必要なためです。チーム所属と役職はセットで管理します。設定方法はチーム所属の属性を参照してください。
ユーザーのステータス
kickflowのユーザーには、次の4つのステータスがあります。
| ステータス | 状態 |
|---|---|
invited | 招待済み。まだ利用者がアクセスしていない |
activated | 有効。利用者がアクセスした状態 |
suspended | 停止中 |
deactivated | 無効化済み（論理削除） |
YESODがアカウントとして取り込むのは、activatedとinvitedのユーザーだけです。
事前に必要なもの
- kickflowの管理画面で発行したAPIトークン
- APIトークンを発行するユーザーの管理者ロールに付与された、次の3つの管理権限
| kickflowの管理権限 | 必要な操作 |
|---|---|
| ユーザーの管理権限 | ユーザー・役職の参照・作成・更新・停止・再開・削除 |
| チームの管理権限 | 組織図・チーム・所属の参照・作成・更新・削除 |
| 管理者ロールの管理権限 | 管理者ロール・ロールメンバーシップの参照・作成・更新・削除 |
接続に使う情報
| 入力項目 | 必須 | 入力する内容 |
|---|---|---|
| 「APIトークン」 | 必須 | kickflowの管理画面で発行したAPIトークン |
kickflowのAPIのベースURLはhttps://api.kickflow.com/v1で固定です。接続画面で入力する項目はありません。
APIトークンは第三者へ共有せず、安全な場所で管理してください。
接続する
「業務アセット」画面から「SaaS接続」画面を開くまでの手順は、業務アセットを追加するを参照してください。
-
「SaaS接続」画面で「kickflow」を選択します。 「kickflow 接続」画面が表示されます。
-
「APIトークン」を入力します。
-
「名寄せに使用する項目」を確認します。 名寄せの考え方はアカウントとメンバーの名寄せを参照してください。
-
「接続」ボタンをクリックします。 同期が完了すると、業務アセットが作成されます。
接続画面には「管理者権限を持ったアカウントで［接続］してください。」と表示されます。事前に必要な管理権限を持つユーザーで発行したAPIトークンを使ってください。
アカウントの作成
アカウント作成のタスクを実行すると、YESODはメールアドレスを一意の識別子としてkickflowへ渡します。同じメールアドレスのユーザーがkickflowにあるかどうかで、動作が変わります。
| kickflowの状態 | 動作 |
|---|---|
| 同一メールアドレスのユーザーがkickflowに存在しない | ユーザーを新規作成します |
同一メールアドレスの有効なユーザーが存在する（activated／invited） | そのユーザーの情報を更新します |
同一メールアドレスの停止中のユーザーが存在する（suspended） | 再有効化（reactivate）してから情報を更新します |
同一メールアドレスの削除済みのユーザーが存在する（deactivated） | 再招待（reinvite）してから情報を更新します |
ユーザーコード
kickflowはユーザーの作成時にユーザーコード（user.code）を必須にしており、ほかのサービスと違って自動採番しません。YESODは既定で、社員番号（user.employeeNumber）の先頭の値を使います。
パスワードの扱い
kickflowは、APIと管理者のどちらにもパスワードを操作する手段を提供していません。そのため、パスワードの管理には対応していません。パスワードリセットも利用できません。
招待メール
アカウントの作成時には、既定で招待メールが送信されます。同期する項目のuser.sendEmailにfalseを指定すると、送信を抑制できます。この項目はアカウントの作成時だけ有効です。
アカウントの削除
kickflowにはユーザーの停止と削除があります。業務アセット経由のアカウント削除では、kickflow上の**削除（deactivate）**が使われます。停止は使いません。
| 操作 | kickflowのAPI | 動作 |
|---|---|---|
停止（suspend） | POST /users/{id}/suspend | ステータスがsuspendedになります。再開（reactivate）でき、チーム所属とロール所属は保持されます |
削除（deactivate） | DELETE /users/{id} | 論理削除です。ステータスがdeactivatedに変わり、deactivatedAtにタイムスタンプが設定されます。削除後もAPIから取得できます |
invitedのユーザーは停止できません。停止できるのはactivatedのユーザーだけです。invitedのユーザーを無効にするには、削除を使ってください。削除はinvited・activated・suspendedのどのステータスからでも実行できます。
削除するユーザーを上長とするユーザーがkickflowに残っていると、kickflowがエラーを返します。このときYESODには次のメッセージが表示されます。
上長が最低一人は必要です。kickflow 側で上長の付け替えを行ってから、再度実行してください。
ステータスの遷移
割当種別
| 割当種別名 | タイプ | 割当項目の例 | 備考 |
|---|---|---|---|
| 管理者ロール | 複数のグループに所属させる | スーパー管理者、ユーザー管理者など | kickflowの管理者ロールです。複数のロールを同時に付与できます |
スーパー管理者は、テナントの作成時から存在する特殊なロールで、すべての管理権限を持ちます。管理者ロールはkickflow側でカスタム作成でき、複数の権限を組み合わせて定義します。詳しくはkickflowヘルプセンターを参照してください。
同期する項目
業務アセットの「アカウント設定」にある「同期する項目」で、YESODの項目をkickflowの項目へ対応づけます。
基本属性
| 必須 | 項目 | 属性キー | 既定値 | 型 | 備考 |
|---|---|---|---|---|---|
| ✅ | メールアドレス | user.email | user.email | string | kickflowのユーザーとの紐付けに使う項目です |
| ✅ | 姓 | user.lastName | user.familyNameLocalPreferred | string | — |
| ✅ | 名 | user.firstName | user.givenNameLocalPreferred | string | — |
| ✅ | ユーザーコード | user.code | user.employeeNumber.size > 0 ? user.employeeNumber[0] : null | string | 一意の値です。自動採番されないため、既定では社員番号の先頭の値を使います |
| — | 社員番号 | user.employeeId | — | string / null | 任意の項目です |
| — | 招待メール送信 | user.sendEmail | true | boolean | アカウントの作成時だけ有効です。falseで招待メールを抑制できます |
チーム所属の属性
kickflowのチーム所属は、チームID × 役職IDリスト × 上長フラグの3つの要素で1つのエントリを構成します。1人のユーザーは複数のチームに所属できます。そのため、属性キーにはインデックス付きの動的なキーを使います。user.teamMembership[0].*、user.teamMembership[1].*のように、Nの部分で所属を区別します。
| 必須 | 項目 | 属性キー | 型 | 備考 |
|---|---|---|---|---|
| エントリを追加するときは必須 | チーム識別子 | user.teamMembership[N].teamId | string | kickflow上のチームのUUID、またはチームのコードを指定します |
| エントリを追加するときは必須 | 役職IDリスト | user.teamMembership[N].gradeIds | list<string> | kickflow上の役職IDのリストです。kickflow APIの仕様上、1件以上必要です |
| 任意 | 上長フラグ | user.teamMembership[N].leader | boolean | チームの上長として所属するかどうかを指定します。省略するとfalseです |
Nは0から始まる連番です。所属の数だけ並べます。
チーム識別子と役職IDを調べる
チーム識別子には、次のどちらかを指定できます。kickflow APIがどちらも受け付けます。
-
UUID: kickflowの管理画面の各チームのページのURLの末尾から取得します。 URLの形式は次のとおりです。
https://<テナント>.kickflow.com/admin/organizations/<組織図UUID>/teams/<チームUUID> -
コード: チームの編集画面の「コード」欄で任意に設定する文字列です。未設定のときはkickflowが自動採番します。 人が読める識別子として運用したい場合に使います。
役職IDはkickflowの管理画面から確認できません。APIトークンを使って、APIから取得します。
curl -H "Authorization: Bearer <APIトークン>" https://api.kickflow.com/v1/grades
レスポンスは役職の配列です。各要素のidが役職IDです。
[
{
"id": "00000000-0000-0000-0000-00000000000A",
"name": "部長",
"code": "MANAGER",
"level": 10
}
]
nameやcodeで対象の役職を絞り込み、そのidをuser.teamMembership[N].gradeIdsに指定してください。詳しくは役職（listGrades） - kickflow Developerを参照してください。
属性式の書き方
属性式はSpEL（Spring Expression Language）で評価されます。リテラルはSpELの構文に従って書いてください。
| 種類 | 書き方 |
|---|---|
| 文字列リテラル | シングルクォート'...'またはダブルクォート"..."で囲む |
| リストリテラル | 波括弧{...}で囲む |
| 真偽値 | true / false（クォートは不要） |
リストリテラルに角括弧[...]は使えません。SpELでは[...]はプロパティのインデックスアクセス（Indexer）として解釈されます。リストのつもりで書くと、UUIDの文字列がキーとして解釈され、エラーになります。リストには必ず波括弧{...}を使ってください。
設定例
営業チームに部長として上長で所属し、あわせて開発チームにメンバーとして所属する場合の設定例です。
次の例のUUIDは説明用のプレースホルダーです。実際にはkickflowから取得した値に置き換えてください。チームIDは管理画面のURLの末尾、役職IDはGET /v1/gradesのレスポンスから取得します。
| プレースホルダー | 説明 |
|---|---|
00000000-0000-0000-0000-000000000001 | 営業チームのID |
00000000-0000-0000-0000-000000000002 | 開発チームのID |
00000000-0000-0000-0000-00000000000A | 部長の役職のID |
00000000-0000-0000-0000-00000000000B | メンバーの役職のID |
| 属性キー | 属性式 |
|---|---|
user.teamMembership[0].teamId | '00000000-0000-0000-0000-000000000001' |
user.teamMembership[0].gradeIds | {'00000000-0000-0000-0000-00000000000A'} |
user.teamMembership[0].leader | true |
user.teamMembership[1].teamId | '00000000-0000-0000-0000-000000000002' |
user.teamMembership[1].gradeIds | {'00000000-0000-0000-0000-00000000000B'} |
チーム所属の同期の挙動
- アカウントの新規作成時: 設定したチーム所属がすべて反映されます。
- アカウントの更新時と属性の同期時: YESODの設定と現状の差分（追加・更新・削除）だけが適用されます。
- 同一のチームIDのマージ: 同じチームIDを複数のインデックスで指定した場合、
gradeIdsは和集合にマージされます。leaderは、1つでもtrueがあればtrueになります。
チーム所属の同期はオプトインです。user.teamMembershipで始まるマッピングが1つも無い場合、チーム所属の同期自体をスキップし、kickflow側の現状の所属に変更を加えません。
一方、マッピングはあるものの有効なエントリが1つも無い場合は、現在のチーム所属をすべて解除する動作になります。
入力チェック
チーム所属の属性には、次の入力チェックがあります。設定を誤ると、タスクの実行時にエラーが発生します。
teamIdが未設定で、gradeIdsまたはleaderに値があるとエラーになります。teamIdを指定してgradeIdsが空または未設定のときも、エラーになります。kickflow APIの仕様上、役職IDが1件以上必要なためです。teamIdに指定した値が、現在の組織図にあるチームのUUIDまたはコードに一致しないとエラーになります。
補足
- kickflowのユーザーを取得するAPIには、チームとロールの情報が含まれません。
GET /users/{id}/teamsとGET /users/{id}/rolesで別途取得します。 - 一覧のエンドポイント（
GET /users）と詳細のエンドポイント（GET /users/{id}）ではフィールドが違います。詳細にだけuserLineWorksAccount（LINE WORKS連携）とinvitation（招待情報）が含まれます。 - 同期の対象は、kickflow上の
current = trueの組織図の配下にあるチームだけです。next・pastの組織図には同期しません。
グループプッシュ
対応していません。