従業員管理システムを Shifts と同期するカスタム統合を作成する

概要

Microsoft Teamsのスケジュール管理アプリである Shifts と、従業員管理 (WFM) システムを統合します。 この統合により、現場の従業員はシフト内でスケジュールを直接表示および管理できます。

この記事では、この統合を容易にするために Microsoft Graph APIを使用してコネクタを作成する方法について説明します。

一方向データ同期または双方向データ同期の統合を設定できます。

• 一方向同期 (WFM システムから Shifts へ): このセットアップでは、WFM システムのデータを Shifts に同期するようにスケジュールします。 コネクタは、WFM システム内のデータを読み取り、Shifts に書き込みます。 ただし、ユーザーによる Shifts での変更は、WFM システムには反映されません。

• 双方向同期 (システムとシフトWFM): この設定により、双方向同期が可能になります。WFM システムのスケジュール データは Shifts に同期され、ユーザーによる Shifts で行われた変更はすべて、WFM システムに同期されます。 コネクタは、変更が Shifts に書き込まれる前に、WFM システムによって適用されるビジネス ルールに従って、Shifts でユーザーが行った変更を検証して承認します。

この記事で使用される用語

はじめに

前提条件

• ビジネス ニーズに応じて同期するデータを決定します。
• Microsoft ID プラットフォームの認証と承認の概念について説明します。 「認証と承認の基本」を参照してください。
• 管理ロールが必要です。
  • 少なくともクラウド アプリケーション管理者がアプリをMicrosoft Entra 管理センターに登録する
  • 従業員統合を登録するグローバル管理者

統合プロセスについて理解する

統合手順の概要を次に示します。 この情報を確認して、各手順を実行するユーザーなど、プロセス全体について理解します。

手順 1: コネクタを作成する

コネクタを作成するには、次の手順を実行します。

• 手順 1a: Shifts で行った変更を WFM システムに同期する
• 手順 1b: WFM システムのデータを Shifts に同期する

手順 1a: Shifts で行った変更を WFM システムに同期する

Shifts から要求を受信して処理するようにコネクタを設定するには、次のエンドポイントを実装する必要があります。

• /connect (必須)
• /update (必須)
• /read (省略可能)

ベース URL とエンドポイント URL を決定する

ベース URL (webhook) は{url}/v{apiVersion}。ここで、url と apiVersion は、ワークフォース統合を登録するときに workforceIntegration オブジェクトで設定したプロパティです。

エンドポイント URL の相対パスは次のとおりです。

• /繋ぐ： /connect
• /更新： /teams/{teamid}/update
• /読む： /teams/{teamid}/read

たとえば、 url が https://contosoconnector.com/wfi され、 apiVersion が 1されている場合は、次のようになります。

• ベース URL が https://contosoconnector/com/wfi/v1。
• /connect エンドポイントが https://contosoconnector/wfi/v1/connect。
• /update エンドポイントが https://contosoconnector/wfi/v1/teams/{teamid}/update。
• /read エンドポイントが https://contosoconnector/wfi/v1/teams/{teamid}/read。

暗号化

すべての要求は、AES-256-CBC-HMAC-SHA256 を使用して暗号化されます。 従業員統合を登録するときに、共有秘密キーを指定します。 Shifts に返される応答は暗号化しないでください。

エンドポイント

POST /connect

Shifts はこのエンドポイントを呼び出して、 従業員統合を登録するときに接続をテストします。 成功応答は、このエンドポイントが HTTP 200 OK 応答を返す場合にのみ返されます。

例

要求
ConnectRequest

{
   "tenantId": "a1s2s355-a2s3-j7h6-f4d3-k2h9j4mqpz",
   "userId": "4fbc12d7-1234-56ef-8a90-bc123d45678f"
}

Response
HTTP を返す 200 OK

POST /teams/{teamid}/update

Shifts はこのエンドポイントを呼び出して、従業員の統合が有効になっているスケジュールで Shifts エンティティに変更が加えられた場合に承認を取得します。 このエンドポイントが要求を承認した場合、変更は Shifts に保存されます。

WFM システムはレコードのシステムであるため、コネクタがこのエンドポイントに対する要求を受け取ると、最初にWFM システムで変更を試みる必要があります。 変更が成功した場合は、成功を返します。 それ以外の場合は、エラーを返します。

Shifts は、すべての変更 (コネクタ/WFM システムから開始された変更を含む) に対してこのエンドポイントを呼び出します。 コネクタが Graph API を使用して Shifts に更新を送信し、X-MS-WFMPassthrough: workforceIntegratonId ヘッダーを追加した場合、このエンドポイントに送信される要求は同じヘッダーを持ち、これらの要求を適切に識別して処理できます。 たとえば、WFM システムで同じ変更を加えずに成功を返すと、コネクタが無限ループでスタックする可能性があります。

次の図は、データのフローを示しています。

応答コードを返す
統合からの応答 (エラーを含む) には、HTTP 応答コード 200 OKが必要です。 応答本文には、適切なサブ呼び出しエラー状態を反映する状態とエラー メッセージが必要です。 200 OK 以外の統合からの応答はエラーとして扱われ、呼び出し元 (クライアントまたは Microsoft Graph) に返されます。

一方向同期を設定する場合は、Shifts を読み取り専用にします

一方向同期の場合は、Shifts を読み取り専用にして、ユーザーが Shifts を変更できないようにする必要があります。 Shifts を読み取り専用にするには、Shifts からのすべての要求に対してエラー応答を返します。

たとえば、ユーザーがスケジュール内のシフトに変更を加えるのをブロックするには、このエンドポイントは、 shift エンティティに関する要求を受信するたびにエラー応答を返す必要があります。

例

要求
WfiRequestContainer

次の例は、ID が SHFT_12345678-1234-1234-1234-1234-1234567890ab でプロパティが一覧表示され、 本文にプロパティが表示されているシフトを Shifts に保存できるかどうかを確認する Shifts からの要求を示しています。 この要求は、ユーザーが Shifts でシフトを作成するときにトリガーされました。

{
  "requests": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "method": "POST",
      "url": "/shifts/SHFT_12345678-1234-1234-1234-1234567890ab",
      "headers": {
        "X-MS-Transaction-ID": "1",
        "X-MS-Expires": "2024-10-11T21:27:59.0134605Z"
      },
      "body": {
        "draftShift": {
          "activities": [],
          "isActive": true,
          "startDateTime": "2024-10-12T15:00:00.000Z",
          "endDateTime": "2024-10-12T17:00:00.000Z",
          "theme": "Blue"
        },
        "isStagedForDeletion": false,
        "schedulingGroupId": "TAG_a3e0b3f1-4a5c-4c2e-8eeb-5b8c3d1e3f8b",
        "userId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "createdDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedDateTime": "2024-10-11T21:27:28.762Z",
        "lastModifiedBy": {
          "user": {
            "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
            "displayName": "Adele Vance"
          }
        },
        "id": "SHFT_12345678-1234-1234-1234-1234567890ab"
      }
    }
  ]
}

Response
WfiResponse

成功: HTTP を返す 200 OK

この例では、エンドポイントが要求を承認した場合に返される応答を示します。 このシナリオでは、シフトが Shifts に保存され、ユーザーはスケジュールのシフトを確認できます。

{
  "responses": [
    {
      "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
      "status": 200,
      "body": {
        "eTag": "3f4e5d6c-7a8b-9c0d-1e2f-3g4h5i6j7k8l",
        "error": null,
        "data": null
      }
    }
  ]
}

失敗: HTTP を返す 200 OK

この例では、エンドポイントが要求を拒否した場合に返される応答を示します。 このシナリオでは、ユーザーは Shifts で "シフトを追加できませんでした" というエラー メッセージを受け取ります。

{
    "responses": [
        {
            "id": "SHFT_12345678-1234-1234-1234-1234567890ab",
            "status": 500,
            "body": {
                "error": {
                    "code": "500",
                    "message": “Could not add the shift”
                },
                "data": null
            }
        }
    ]
}

POST /teams/{teamid}/read

このエンドポイントは、Shifts からの要求を処理して、ユーザーのスワップ要求に対して適格な休暇の理由または適格なシフトをフェッチします。

次の図は、データのフローを示しています。

応答コードを返す
統合からの応答 (エラーを含む) には、HTTP 応答コード 200 OKが必要です。 応答本文には、適切なサブ呼び出しエラー状態を反映する状態とエラー メッセージが含まれている必要があります。 200 OK 以外の統合からの応答はエラーとして扱われ、呼び出し元 (クライアントまたは Microsoft Graph) に返されます。

例: TimeOffReason

要求

次の例は、ユーザー (ユーザー ID aa162a04-bec6-4b81-ba99-96caa7b2b24d) が対象となる休暇の理由を尋ねる Shifts からの要求を示しています。 この要求は、ユーザーが Shifts で休暇を要求したときにトリガーされました。

 { 
  "requests": [ 
    { 
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
      "method": "GET", 
      "url": "/users/aa162a04-bec6-4b81-ba99-96caa7b2b24d/timeOffReasons?requestType=TimeOffReason"
    } 
  ] 
}

Response
成功: HTTP を返す 200 OK

次の応答は、ユーザーの適格な休暇理由 ID が "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc" と "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d" であることを示しています。 このシナリオでは、Shifts で選択する対応する休暇の理由がユーザーに表示されます。

{
    "responses": [ 
      { 
        "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d", 
        "status": 200, 
        "body": { 
          "data": [ 
            "TOR_29f4a110-ae53-458b-83d6-00c910fe2fbc", 
            "TOR_8c0e8d07-ac1a-48dc-b3af-7bc71a62ff7d" 
          ], 
          "error": null 
          } 
        }
    ]
}

失敗: HTTP を返す 200 OK

この例では、コネクタがユーザーの休暇の理由を取得するためにWFM システムに到達できなかったため、エラー応答が返されます。

 {
  "responses": [
    {
      "id": "aa162a04-bec6-4b81-ba99-96caa7b2b24d",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "Could not reach WFM"
        }
      }
    }
  ]
}

例: SwapRequest

要求

次の例は、ID が SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029 であるシフトとのスワップの対象となるシフトを 2024 年から 2024 年の間に確認するシフトからの要求を示しています。 10-01T04:00:00.0000000Z と 2024-11-01T03:59:59.9990000Z。

{
  "requests": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "method": "GET",
      "url": "/shifts/SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029/requestableShifts?requestType=SwapRequest&startTime=2024-10-01T04:00:00.0000000Z&endTime=2024-11-01T03:59:59.9990000Z"
    }
  ]
}

Response
成功: HTTP を返す 200 OK

次の応答は、シフトをシフトと入れ替えることができることを示しています。その ID は SHFT_98e96e23-966b-43be-b90d-4697037b67af です。

{ 
  "responses": [ 
    { 
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029", 
      "status": 200, 
      "body": { 
        "data": ["SHFT_98e96e23-966b-43be-b90d-4697037b67af"],
        "error": null, 
      } 
    }
  ]
}

失敗: HTTP を返す 200 OK

この例では、コネクタがユーザーのスワップ要求の適格なシフトを取得するためにWFM システムに到達できなかったため、エラー応答が返されます。

{
  "responses": [
    {
      "id": "SHFT_5e2b51ac-dc47-4a66-83ea-1bbbf81ac029",
      "status": 503,
      "body": {
        "data": null,
        "error": {
          "code": "503",
          "message": "could not reach WFM"
        }
      }
    }
  ]
}

手順 1b: WFM システムのデータを Shifts に同期する

Microsoft Graph の Shifts API を使用して、WFM システムからスケジュール データを読み取り、そのデータを Shifts に書き込みます。

たとえば、Shifts にシフトを追加するには、シフトの 作成 API を使用します。

Shifts API については、Microsoft Graph API v1.0 リファレンスを参照してください。これは Shift 管理の下に一覧表示されています。

次の図は、データのフローを示しています。

初期同期

最初の同期では、コネクタはWFM システムのデータを読み取り、データを Shifts に書き込む必要があります。 2 週間の将来のデータを同期することをお勧めします。

初期同期後

最初の同期後は、次のオプションを選択できます。

• WFM システムの変更を使用して Shifts を同期的に更新する: WFM システムで行われたすべての変更に対して Shifts に更新を送信します。

• WFM システムの変更を使用して Shifts を非同期に更新する: 特定の期間内 (たとえば 10 分) 内にWFM システムで発生したすべての変更を Shifts に書き込むことで、定期的な同期を実行します。

  コネクタによって開始された書き込み操作を含め、Shifts へのすべての書き込み操作によって、コネクタの /update エンドポイントへの呼び出しがトリガーされます。 コネクタが識別して適切に処理できるように、すべての書き込み呼び出しに X-MS-WFMPassthrough: workforceIntegratonId ヘッダーを含めてお勧めします。 たとえば、WFM システムが変更を開始した場合は、WFM システムに更新プログラムを適用せずに承認します。

  注:

  WFM システムと Shifts の間でデータの双方向同期用にコネクタを設定する場合は、定期的な同期で Shifts から開始された変更を除外します。これらの変更は既に Shifts で記述されています。

手順 2: Microsoft Entra 管理センターにアプリを登録する

次の手順に従って、Microsoft ID プラットフォームでコネクタのアプリを登録し、アプリが Microsoft Graph にアクセスするためのアクセス許可を構成し、アクセス トークンを取得します。

1. 少なくともクラウド アプリケーション管理者としてMicrosoft Entra 管理センターにサインインします。

2. アプリを登録する。 手順については、「Microsoft ID プラットフォームにアプリケーションを登録する」を参照してください。

3. アプリ専用アクセス用に Schedule.ReadWrite.Allアプリケーションのアクセス許可 をアプリに割り当て、アクセス トークンを取得します。

   詳細なガイダンスについては、「 ユーザーなしでアクセスを取得する」を参照してください。

   アクセス トークンは、Schedule.ReadWrite.All アクセス許可を使用して、アプリが独自の ID を使用して Microsoft Graph を呼び出す権限を持っていることを確認します。 要求の Authorization ヘッダーに含める必要があります。

手順 3: 同期するチームとスケジュールを作成する

同期する Teams でチームを設定します。既存のチームを使用することも、新しいチームを作成することもできます。

1. WFM システム内のチームと場所に対応するように Teams でチームを設定します。 各チームに次のユーザーを追加してください。

   • チーム所有者としての現場マネージャー。 各チームのチーム所有者として、 MS-APP-ACTS-AS ヘッダーにユーザーを追加してください。
   • チーム メンバーとしての現場担当者。

2. 各チームのシフトでスケジュールを作成します。 詳細については、「スケジュールの 作成または置換」を参照してください。

3. 各チームのスケジュールにスケジュール グループを追加します。 スケジュール グループは、チーム内の共通の特性に基づいて従業員をグループ化するために使用されます。 たとえば、スケジュール グループには、部署またはジョブの種類を指定できます。 詳細については、「 schedulingGroup リソースの種類」を参照してください。

4. 各スケジュール グループに従業員を追加します。 詳細については、「 schedulingGroup を置き換える」を参照してください。

手順 4: 従業員統合を登録して有効にする

ワークフォース統合では、Shifts とコネクタ間の通信の暗号化設定、Shifts からのコールバックの URL、同期するエンティティの種類を定義します。

従業員統合を登録して有効にするには、次の手順を実行します。

• 手順 4a: 従業員統合を登録する
• 手順 4b: チーム スケジュールの従業員統合を有効にする

手順 4a: テナントに従業員統合を登録する

この手順を実行するには、グローバル管理者である必要があります。

WorkforceIntegration API を使用して、テナントに従業員の統合を登録します。

要求の例を次に示します。

POST https://graph.microsoft.com/v1.0/teamwork/workforceIntegrations/
{ 
  "displayName": "Contoso integration", 
  "apiVersion": 1, 
  "encryption": { 
    "protocol": "sharedSecret", 
    "secret": "secret-value" 
  }, 
  "isActive": true, 
  "url": "https://contosoconnector.com/wfi", 
  "supportedEntities": "Shift,SwapRequest,UserShiftPreferences,Openshift,OpenShiftRequest,OfferShiftRequest”,
}

詳細は次の表を参照してください。 詳細については、「 workforceIntegration リソースの種類」を参照してください。

手順 4b: チーム スケジュールの従業員統合を有効にする

管理するスケジュールで従業員統合を有効にします。 これを行うには、スケジュール API の 作成または置換 を使用して、チームのスケジュールを作成または更新します。

要求の例を次に示します。

POST https://graph.microsoft.com/v1.0/teams/{teamId}/schedule
{
  enabled: true,
  timezone: “America/New_York”,
  workforceIntegrationIds: [ “workforceIntegrationId”]
}

• 従業員統合を登録したときに生成された workforceIntegrationId を指定します。
• 1 つのスケジュールで最大 1 つの従業員統合を有効にすることができます。 要求に複数の workforceIntegrationId を含める場合、最初の workforceIntegrationId が使用されます。

トラブルシューティング

Connector

コネクタが Shifts からの要求に応答すると、200 以外の応答コードが返された場合はどうなりますか? 応答本文で 200 以外の状態を返すと違いがありますか?

これら 2 つのシナリオには違いがあります。

• コネクタが 200 以外の応答コードを返す場合、Shifts は /read エンドポイントと /update エンドポイントを複数回再試行しようとします。 最終的に、Shifts に "問題が発生しました。 チームの従業員統合セットアップが無効なデータで応答しました。" というエラー メッセージが表示されます。
• コネクタが応答本文で 200 以外の状態を返すと、Shifts に "問題が発生しました。 申し訳ございません。変更を完了できませんでした」というエラー メッセージが表示され、エンドポイントの再試行が停止します。

コネクタから応答本文で無効なデータが返された場合はどうなりますか?

Shifts では、/read エンドポイントと /update エンドポイントの再試行が複数回試行されます。 最終的に、Shifts に "問題が発生しました。 チームに設定された従業員統合が無効なデータで応答しました。" というエラー メッセージが表示されます。

操作方法、無限ループを防ぐために、最初に Shifts または WFM システムで要求が行われたかどうかを特定します。

X-MS-WFMPassthrough: workforceIntegratonId ヘッダーをすべての書き込み呼び出しと更新呼び出しに追加して、コネクタによってトリガーされた変更を識別または無視します。 このヘッダーは、コネクタが WFM システムのデータを Shifts に同期するためにGraph APIする前の呼び出しのために要求が行われたことを示すために使用されます。

従業員統合登録

私は従業員統合を登録し、"SwapRequest、OfferShiftRequest、TimeOffReason" を含む "eligibilityFilteringEnabledEntities" を指定しましたが、応答本文には "eligibilityFilteringEnabledEntities" リストは表示されません。

現在、適格性フィルター処理は、https://graph.microsoft.com/v1 エンドポイントではなく、https://graph.microsoft.com/beta エンドポイントを介してサポートされています。

従業員の統合を登録し、"supportedEntities" を追加しましたが、400 の無効な要求応答と "無効なペイロード: 要求された値 'shift, ...' を受け取ります。 が見つかりませんでした」というメッセージが表示されます。

supportedEntitiesリスト要求本文のすべての Shifts エンティティが大文字で始まることを確認します。 たとえば、「 "supportedEntities":"Shift,SwapRequest,OpenShift" 」のように入力します。

従業員統合を登録し、/connect、/update、/read エンドポイントを実装しましたが、Webhook は機能していません。

チーム スケジュールに対して従業員の統合が有効になっていることを確認します。 さらに、url プロパティと apiVersion プロパティが正しいことをチェックします。

エンドポイントリファレンス

要求

ConnectRequest

{
  "tenantId": "string",
  "userId": "string"
}

WfiRequestContainer

{
  "requests": [
    {
      "id": "string",
      "method": "string",
      "url": "string",
      "headers": {
        "X-MS-Transaction-ID": "string",
        "X-MS-Expires": "string (DateTime)"
      },
      "body": "ShiftsEntity"
    }
  ]
}

要求内の要素の数:

• ほとんどの場合、要求には 1 つの要素があります。
• スワップ シフト要求の承認など、一部の要求には、1 つの PUT スワップ要求、2 つの DELETE シフト (既存のシフト)、2 つの POST シフト (新しいシフト) の 5 つの要素があります。

WfiRequest

POST /teams/{teamId}/update の場合

POST /teams/{teamsId}/read の場合

WfiRequestHeader

X-MS-WFMPassthrough: workforceIntegratonId WfiRequestHeader には含まれません。 HttpRequest から抽出する必要があります。

応答

WfiResponseContainer

{
  "responses": [
    {
      "id": "string",
      "status": "string",
      "body": {
        "eTag": "string",
        "error": {
          "code": "string",
          "message": "string"
        },
        "data": ["string1", "string2"]
      }
    }
  ]
}

WfiResponse

WfiResponseBody

WfiResponseError

関連記事

• 現場organizationのシフト
• シフト コネクタ