共通変数：拡張機能
変数
Zoho People拡張機能の変数を使うと、コンポーネント、スクリプト、ワークフロー、テンプレートなど、プラットフォームのさまざまな項目で利用できるキーと値のペアを作成できます。作成したペアが保持するデータは再利用できるため、情報を一度保存すると、システム内で必要に応じていつでも利用できるようになります。詳細については、「共通変数」および「共通変数の利用方法」のヘルプ記事をご参照ください。
Zoho People拡張機能の変数の詳細
プラットフォームの変数は、Zoho Peopleの変数とは異なり、より高度なカスタマイズや機能連携、開発者の管理性が必要となる場合にメリットがあります。変数の値を変えることで、カスタマイズされたロジックを自動的に実行できます（例：通知、関連する設定の調整、他のタブでの値の呼び出し）。
権限のカテゴリー
エンドユーザーによる変数の使用に関する権限は、拡張機能プラットフォームから設定できます。
権限のカテゴリーは、以下の4種類です。
- 表示／編集：ユーザーの組織で変数を表示するための権限です。ユーザーは値の確認と変更が可能です。ただし、開発者向けコンソールで値を変更した場合、アップグレードの際に変更内容が送信されることはありません。また、ユーザーの組織に反映されることもありません。このような変更は、新規のサインアップに対してのみ適用されます。今後、拡張機能がアップグレードされる際に、変数の情報を変更できます（値を除く）。
- 表示のみ：［表示のみ］の変数は、ユーザーの組織で閲覧は可能ですが、変更はできません。また、アップグレード時に開発者向けコンソールから値を変更することもできません。ただし、他の変数の値を除き、拡張機能の次のバージョンに対するアップグレード時に、データを変更することは可能です。
- 非表示：［非表示］の変数は、開発者が開発者向けコンソールで管理することはできますが、ユーザーの組織内のエンドユーザーには表示されません。開発者向けコンソールで変数の値を変更しても、ユーザーアカウントに対して更新は反映されません。ただし、新規サインアップ時には変更が反映されます。また、変数の値以外のデータは、拡張機能の次のバージョンに対するアップグレード時に変更できます。
- システム：［システム］の変数は、開発者が開発者向けコンソールで管理することはできますが、ユーザーの組織内のエンドユーザーには表示されません。この権限では、ユーザーの組織における変数の値を変更することはできません。開発者向けコンソールで変数の値を変更した場合、アップグレードの際にユーザーアカウントに反映されます。
権限の種類 | 表示設定 （開発者の組織） | 表示設定 （顧客の組織） | 拡張機能のアップグレード時における値の変更 |
表示／編集 | 〇 | 〇 | ✕ |
| 表示のみ | 〇 | 〇 | ✕ |
| 非表示 | 〇 | ✕ | ✕ |
| システム | 〇 | ✕ | 〇 |
- ユーザーの組織では、［システム］権限の変数を除くすべてのカテゴリーで、APIによる変数の値の変更が可能です。
- ［非表示］および［システム］権限の変数は、他のコンポーネントで差し込み項目として使用することはできません。
- すべての権限の変数（［システム］権限の変数を除く）は、onChangeスクリプト関数に対応しています。
以下の場合に変数を使用可能
- 独自の関数：コードのロジックや計算の際に、値に動的にアクセスします。
- メールテンプレート：定義済みの変数の値でメッセージをカスタマイズします。
- データのテンプレート：データの作成／表示の際に、データを動的に挿入します。
- 差し込み文書テンプレート：文書の作成時に変数を使用することで、データをかんたんに入力できます。
- API連携：外部のシステムやサービス連携向けに、APIを使用して変数の値にアクセスします。
- onChangeスクリプト関数：独自の関数に個別に対応します。各変数はonChangeスクリプト関数に対応しています。この機能は、変数の値が更新された際に実行されます。
変数のプロパティのパッケージ化
開発者向けコンソールでは、変数をパッケージ化でき、サインアップやアップグレードの際にユーザーの組織に展開できます。以下の表では、このような変数の挙動を説明しています。
プロパティ | アップグレードの種類 | 修正 |
変数名 | アップグレード可能 | 開発者のみ可能 |
API名 | アップグレード不可 | 編集不可 |
説明 | アップグレード可能 | 開発者のみ可能 |
変数の種類 | アップグレード不可 | 編集不可 |
権限 | アップグレード可能 | 開発者のみ可能 |
分類グループ | アップグレード不可 | 編集不可 |
onChangeスクリプト関数
Zoho People拡張機能の開発者向けコンソールでは、変更スクリプトを定義することで、ユーザーの組織で共通変数の値が変更された場合に実行されるロジックを操作できます。
機能の概要
変数が変更されると、システムにより関連する変更スクリプトが実行され、過去および変更後の値がそのスクリプトに渡されます。これにより、変更後の挙動を正確に把握できます。これに対応するため、「variableMap」という定義済みの入力オブジェクトがスクリプトに渡されます。このオブジェクトには、変数の新旧の値が含まれています。
スクリプトの設定
変更スクリプトを追加するには：
- 変数の設定画面で、［項目の値］→［onChange］タブに移動します。
- ［スクリプトを作成する］をクリックします。
- 編集画面でvariableMapオブジェクトを使用して、過去および現在の値を確認します。
構文の例
- oldValue：変更前の変数の値です。
- newValue：変更後の変数の値です。
これらの値を使って、独自のロジックを作成できます。
例：
if (oldVal != newVal)
{
// Run custom logic here
info "Variable updated from " + oldVal + " to " + newVal;
}
利用例：
変更スクリプトの利用例は以下のとおりです。
- 設定済みの変数が変更された場合に、該当の項目を再計算する。
- 重要な設定に変更があった場合に、ユーザー／管理者に通知する。
- しきい値が変更された場合に、値やワークフローをリセットする。
- グローバル設定が依存するAPI呼び出しや機能連携を変更する。
インストール時の設定
- ユーザーがインストールした拡張機能に変数が含まれる場合、インストール画面に［変数を認証する］タブが表示されます。
- このタブに表示されるのは、［表示／編集］および［表示のみ］の権限を持つ変数です。［表示のみ］の変数は編集できませんが、［表示／編集］の変数は、インストール画面で直接設定が可能です。
- インストール時にこの手順を実行しない場合、拡張機能の設定スライダーや、［開発者向け情報］の［変数］タブから変数の値を別途編集できます。
変更による影響
Zoho People拡張機能で共通変数を追加／変更し、ユーザーの組織に対するアップグレードパッケージの一部として送信した場合、このような変更が既存の設定にどのように影響するかを把握しておくことが重要です。
変数に対してどのような変更を行うかにより、以下のような影響が生じます。
新しい変数の追加
- アップグレード時に新たに共通変数を追加しても、ユーザーの組織における既存の設定には影響しません。
- 新しいワークフロー、スクリプト、項目設定で変数を使えるようになります。
- 既存の機能やユーザーが定義したプロセスは、導入前と変わらず機能します。
- 現在の設定には干渉せず、遡及的な影響を及ぼすこともありません。
既存の変数の変更
既存の変数を変更すると、変更した内容に応じて、さまざまな階層で影響が生じることがあります。
他への影響が生じない変更：
- 説明や変数名を変更しても、既存の参照関係や機能に影響はありません。
- これらは形式上のみの変更です。
影響が生じる変更：
権限の変更：権限のレベルを変更（［表示／編集］→［表示のみ］、［表示／編集］→［非表示］など）すると、ユーザーの組織における変数の挙動が即時変化します。
- ［非表示］／［システム］権限の変数が設定のUIに表示されなくなる場合があります。
- エンドユーザーが値を編集できなくなる場合があります。
値の変更（初期設定時の変数の値をパッケージ内で変更した場合）：
- 従来の値に依存するスクリプト、ワークフロー、プロセスの挙動が変化する場合があります。
- 開発者は変更スクリプトを使って、このような移行をプログラムとして処理できます。
- ただし、エンドユーザーが新しい値に適合するには、カスタムロジックを手作業で更新する必要があります。
値をわずかに変更するだけでも、従来の設定に依存するしきい値、条件、計算に影響が生じることがあります。
変数の削除
変数を削除すると、大きな影響が生じます。ユーザーのデータや設定に、長期的な影響が及ぶこともあります。変数を削除する前にどのような影響があるか慎重に検討し、どうしても必要な場合にのみ削除します。
共通変数を削除すると重大な影響が生じ、かつ操作を取り消すことはできません。このため、十分に注意して処理する必要があります。
- 削除された変数を参照するプロセス、項目、スクリプト、ワークフローが機能しなくなります。
- 拡張機能全体で、ランタイムのエラー、値の欠落、ロジックの不具合が生じることがあります。
- 明示的にコーディングしない限り、自動的なフォールバックや置換が行われることはありません。
変数を削除すると、使用中のユーザー環境が使用できなくなることがあります。削除しようとする変数が使用されていないこと、下流のプロセスに依存関係がないことを確認します。また、できる限りリリースノートが提供される主要なバージョンアップグレード時に削除します。
利用例：IDfyとZoho People拡張機能との連携
Zoho People拡張機能とIDfyの機能連携を行う場合、従業員の認証をバックグラウンドで実行するかどうかを検討します。従業員用のフォームで、従業員の情報（マイナンバー、納税者番号、氏名、生年月日）が取得されます。フォームを送信すると、拡張機能により、APIを経由してIDfyへのバックグラウンド認証のリクエストが実行されます。認証結果（合格／不合格、ステータス、詳細）が従業員のデータに保存されます。拡張機能はカスタムUIウィジェットやWebタブに対応しており、人事担当者が認証ステータスを確認したり、確認を行ったり、機能連携を設定したりできます。
変数の設定
拡張機能で顧客向けに変数のパッケージを作成し、機密情報の設定や保護を行うことができます。
| 変数名 | 説明 | 権限 |
| idfy_api_key | IDfyのシークレットAPIキー | 表示／編集 |
| idfy_client_id | IDfyが発行するクライアントID | 表示／編集 |
| idfy_access_token | テスト環境／本番環境 | 非表示 |
| idfy_refresh_token | IDfyラベル | 非表示 |
| Dev_Contact | 開発者が使用するシステム変数 | システム |
拡張機能のフロー
- インストールと初期設定
- ユーザーの組織に拡張機能をインストールします。
- インストール画面で以下を入力します。
・idfy_client_id（表示／編集）
・idfy_client_secret（表示／編集） - idfy_client_secretを入力して保存すると、この変数に関連付けられたonChangeスクリプトが実行されます。
- idfy_client_secret向けonChangeスクリプト
- このスクリプトを使用すると、変数のAPIを通じて、idfy_client_secretの権限が［表示／編集］から［非表示］に変更されます。これによりクライアントシークレットがロックされ、表示や修正が行えなくなります。
- 次にスクリプトはOAuthのトークン生成フローを実行して、クライアントのIDとシークレットを使い、IDfyのアクセストークンとリフレッシュトークンをリクエストします。
- 受け取ったaccess_tokenとrefresh_tokenは新しい非表示の変数（idfy_access_token、idfy_refresh_token）として保存され、変数のAPIにより動的に作成／更新されます。
- 従業員の認証フロー（WebタブUIが実行する場合）
- ユーザーの組織の従業員が、IDfy認証のためにWebタブUIから従業員情報（マイナンバーなど）を入力します。
- 入力した情報を送信すると、以下のスタンドアロンの機能が実行されます。
・表示されていないOAuthトークン（idfy_access_token、idfy_refresh_token）の変数の読み取り
・アクセストークンによるIDfy認証APIの呼び出し
・認証への回答の処理、従業員データの更新 - アクセストークンが失効している場合、リフレッシュトークンにより新しいアクセストークンを取得し、非表示の変数を更新できます。