API を使用した連携方法

以下の API を使用して、生体認証アプリケーションから Zoho People アプリケーションに直接勤怠データを送信できます。この設定は、お客様側（生体認証デバイスのベンダー、またはお客様の IT チーム）の責任で行ってください。この方法が利用可能かどうか、生体認証デバイスのベンダーにご確認ください。

API リンク: https://www.zoho.com/people/api/attendance-bulkimport.html

この API には、1 分あたり 10 リクエストの上限と、5 分間のロック時間が設定されています。

プラグインを使用した連携方法

用語集

連携作業を進めるにあたっては、IT 担当者またはバイオメトリクス機器のベンダーに同席してもらうことが重要です。

クエリ要件

1. テーブル内に downloadDate 列が存在しない場合、SQL DB から Zoho People へすべてのデータが確実に送信されることを保証できず、データ欠損が発生する可能性があります。
2. 従業員に複数のシフトがある場合は、そのすべてを Zoho People 上でシフトとして設定しておく必要があります。
3. バイオメトリクス ID が Zoho People の従業員 ID と異なる場合は、Zoho People の [運用] > [勤怠] > [バイオメトリクス ID マッピング] でバイオメトリクス ID をマッピングする必要があります。
4. この連携は、バイオメトリクスデータが保存されているサーバーシステムに完全に依存します。システムの不適切なシャットダウンなどによりサーバーがクラッシュまたは再起動した場合、設定ページが破損する可能性があります。そのような場合は、連携設定を再構成する必要があります。
   

必要なソフトウェア

1. Apache Tomcat 9 - https://tomcat.apache.org/download-90.cgi（Windows サービスインストーラー）
2. Java - https://www.openlogic.com/openjdk-downloads（最新バージョン、OS に応じたもの）
   

連携作業時には、必ずバイオメトリクス機器のベンダーまたは IT チームに同席してもらってください。

手順

Java と Tomcat アプリケーションがダウンロードおよびインストールされていることを確認します。ローカルディスク C > Program Files または Program Files (x86) > に JAVA/Tomcat がインストールされているか確認し、インストールされていない場合は両方のソフトウェアをインストールします。

Tomcat 設定

1. サービス名: Tomcat8ZohoPeople
2. Shutdown Port: 8989
3. コネクタポート / Tomcat サーバーポート: 8584（このポートが他のサービスで使用されていないことを確認してください）
4. OpenLogic Java のファイルパスを選択します: C ドライブ > Program Files / Program Files (x86) / OpenLogic / jdk <バージョン>
5. スタートアップの種類: [スタート] > [サービス] を検索 > Tomcat8Zoho（右クリック）> [プロパティ] > [スタートアップの種類] > [自動] に設定
   

War ファイルのインストール

1. 以下のリンクをクリックして war ファイルをダウンロードします。
   https://www.zoho.com/people/downloads/ZAttendance.war
2. ローカルディスク C > Program Files > Apache Software Foundation > Tomcat8 > webapps に移動し、war ファイルを貼り付けて更新すると、ファイルが展開されます。
3. プラグインページへのルーティング: URL http://localhost:8584/ZAttendance でプラグインページが表示できるか確認します。

1. プラグインページ右上の [設定] ボタンをクリックして設定ページを開き、データベースの種類を選択します。
   
   
2. 項目の下に表示されている接続 URL の例をコピー＆ペーストし、データベース名を更新します。
   
   
   データベースインスタンスのポート番号を適宜変更します。
   MS SQL の場合: Program Files C > Windows > SysWOW64 > sql_server_manager > SQL Server Network
   Configuration > Protocol SQLExpress > TCP/IP > IP アドレス > TCP ポート: 1433 > [適用] > [OK]。
   
   （または）
   
   [スタート] > 検索 > [コンピューターの管理] > [SQL Server ネットワークの管理] または
   [構成]（左側 2 番目のオプション）> [TCP/IP] > [IP アドレス] > TCP ポート: 1433 > [適用] > [OK]。
   
   
   MySQL の場合 - 既定のポート番号は 3306 です。
   
   
   MS Access の場合 - データベースパスを追加し、スラッシュをバックスラッシュに変更します。
   
   
3. データベースのユーザー名とパスワードを追加します。MySQL の既定のユーザー名は「root」、MS Access の既定のユーザー名は「admin」です。
   
   
4. Delay 時間と Sleep 時間を 5 分に設定します（推奨される最小時間）。
   
   
5. SQL クエリ設定

   
   

   すべての列が要件どおりに存在する場合:

   固定テーブルの場合:

   SELECT [employeeID] as employeeId, ischeckin as isCheckin, [eventTime] as eventTime, [DownloadDate] FROM [ZAttendance].[dbo].[Att-checkin] where DownloadDate>=$1 and DownloadDate<$2

   
   

   動的テーブルの場合:

   SELECT [employeeID] as employeeId, ischeckin as isCheckin, [eventTime] as eventTime, [DownloadDate] FROM #Tablename_%M_%Y# where DownloadDate>=$1 and DownloadDate<$2

   
   

   DownloadDate 列が存在しない場合（Delay 時間は 1〜2 時間に設定）:

   
   

   SELECT [Id] as employeeId, case [Checkin] when 'IN' then 1 when 'OUT' then 0 end as isCheckin, [EventTime] as eventTime FROM [ZAttendance].[dbo].[Att-checkin] where eventTime>=$1 and eventTime<$2

   
   

   テーブル内で IN/OUT の区別がされていない場合:

   
   

   各打刻を Zoho へ IN/OUT 両方として送信する:

   
   

   SELECT [empid] as employeeId, '1' as isCheckin, [EventTime] as eventTime, [downloaddate] FROM [ZAttendance].[dbo].[Att_noCheck] where DownloadDate>=$1 and DownloadDate<$2

   UNION

   SELECT [empid] as employeeId, '0' as isCheckin, [EventTime] as eventTime, [downloaddate] FROM [ZAttendance].[dbo].[Att_noCheck] where DownloadDate>=$1 and DownloadDate<$2
   
   
   (または)

   
   IN/OUT を交互の打刻として扱う場合:

   
   

   SELECT [Id] as employeeId ,[EventTime] as eventTime ,[DownloadDate] FROM

   [ZAttendance].[dbo].[Att-checkin] where DownloadDate>=$1 and DownloadDate<$2

   
   

   Tomcat > config.properties > url を bulkImport ではなく bulkImportRawEntry に変更してください。
   
   
6. 認証トークンの生成:

   api-console.zoho.in（またはご利用の DC に応じて .com / .eu）にアクセスし、Self Client タイプのクライアントを作成して、クライアント ID と クライアントシークレット をコピーし、プラグインページに貼り付けます。
   

   
   

   [Generate Code] タブでコードを生成します。

   Scope: ZohoPeople.attendance.ALL

   有効期間: 10 分

   説明: BI

   
   

   リフレッシュトークンの生成: クライアント ID / クライアントシークレット / コードを入力し、DC を選択して

   [Generate] をクリックし、生成されたリフレッシュトークンをコピーして、プラグインページのリフレッシュトークン項目に貼り付けます。

   
   

   トークンは、権限設定で Zoho の役割/Role が「admin」に設定されている管理者アカウントで作成されていることを確認してください。
   
   
7. タイムゾーンの更新: ご利用の拠点のタイムゾーンを選択します。データベース内の勤怠データのタイムゾーンと、管理者アカウントのタイムゾーンが同じであることを確認してください。

   
   
8. 手動テストと送信: テスト用に、任意の 1 名の従業員データを同期します。SQL クエリの where 句以降で、downloadDate 列名を EventTime 列名に変更し、以下のように従業員 ID のフィルターを追加します。
   

   
   

   SELECT [Id] as employeeId, [Checkin] as isCheckin, [EventTime] as eventTime , [DownloadDate] FROM [ZAttendance].[dbo].[Att-checkin] where EventTime>=$1 and EventTime<$2 and Id='1001'

   
   

   [手動同期] タブで「データ件数を取得」をクリックしてデータを取得し、「アップロード」をクリックして Zoho People にデータを送信します。
   
   
9. テストが完了したら、プラグインページで [再開] をクリックして同期を自動化します。
   
   
10. 今後の参照のために URL をブックマークし、Tomcat フォルダー外に config.xml ファイルのバックアップを取得しておいてください。

Q&A とよくある問題の対処