GASでハーモス勤怠から社員の勤怠状況をチェックする

弊社では、社員の約8割が子育て中の方で、テレワーク環境下で様々な働き方をしています。
社員が法令通りに働くように日々チェックをしていますが、今回はそれを自動化するためのプログラムを作りました。
例えば、6時間を超えて働いた場合は、45分以上の休憩が必要ですし、8時間を超えて働いた場合は、60分以上の休憩が必要です。所定労働時間が6時間の方は、ついつい6時間ジャストであれば、休憩しなくても良いことから、休憩せずに働く方もいます。しかし、6時間から1分でも超えた場合は休憩が必要となるため、注意が必要なのです。

ハーモスAPIを利用する

弊社では、勤怠の打刻には、ハーモス勤怠(旧称:IEYASU勤怠)というクラウドサービスを利用しています。
前回、ハーモスAPIを使って、打刻情報を取得するプログラムを紹介しましたが、今回のプログラムも前回と一部重複する部分もあります。

ハーモス勤怠APIの情報は下記のサイトに掲載されています。
https://ieyasu.co/docs/api.html

GAS(Google Apps Script)を使って、ハーモスから勤怠情報を取得します。
まずは冒頭で定義する変数です。

const api_key = "xxxxx";//期限: 2022/09/11 15:42:34
const api_url = 'https://ieyasu.co/api/';
const company_name = 'xxxxx';
//Google chat Webhook URL
const googlechat_webhook = 'https://chat.googleapis.com/v1/spaces/xxxxxx';
const today = new Date();
const yesterday = new Date(today.getFullYear(), today.getMonth(), today.getDate() - 1);
const admin_user_id = getExecuteUserAddress('xxxxxxxxxxx'); //管理者通知用GoogleユーザーID

xxxxの部分は、ご自身の環境に合わせて取得して頂く必要があります。
1行目は、ハーモスAPIのAPI KEY、2行目は固定、3行目はハーモスAPIの会社ID、5行目はGoogleチャットボットのWebhook URLです。
取得方法は前回の記事を参照ください。
https://www.shanaidx.com/gas_hrmosapi/#api_keyAPI

6行目、7行目は、今日の日付と昨日の日付のオブジェクトを取得しています。
今回のプログラムでは、毎日前日の勤怠情報をチェックするようにします。

8行目は、管理者へのメンション用にUSER IDを取得します。
メンションというのは、チャットの宛先を指定することです。
今回のプログラムでは、下の図のようにGoogleチャットで、管理者である市川宛にメッセージを通知するようにします。

Googleチャットの画面

上記のように「@名前」を指定すると、相手にチャットが通知されます。

メンションを行うためには、USER IDを指定する必要がありますが、それを取得する関数を後で紹介します。8行目のxxxxxxのところには、Googleアカウントのメールアドレスを記入してください。

メインの処理

今回はメインの処理から開設します。

function myFunction() {
  let token_object = HrmosApiGetToken();
   
  //ハーモスAPI ユーザー指定の打刻情報取得
  let kintai_data = HrmosApiGetKintai(token_object.token);
  if(kintai_data.length){
    let message = '';
    for(let i = 0; i < kintai_data.length; i++ ){
      let working_hours = ChangeTime(kintai_data[i].actual_working_hours);
      let break_time = ChangeTime(kintai_data[i].total_break_time);
      let over_time = ChangeTime(kintai_data[i].total_over_work_time);
      let night_time = ChangeTime(kintai_data[i].late_night_overtime_working_hours);

      if(working_hours >= 8.5){
        message += kintai_data[i].full_name+'さんは、'+(Math.floor(working_hours * 10)) / 10+'時間勤務をしています。';
      }
      if((working_hours > 6) && (break_time < 0.75)){
        if(message){
          message += '\n';
        }
        message += kintai_data[i].full_name+'さんは、'+(Math.floor(working_hours * 10)) / 10+'時間勤務していますが、休憩時間は'+(Math.floor(break_time * 10)) / 10+'時間です。';
      }else if((working_hours > 8) && (break_time < 1)){
        if(message){
          message += '\n';
        }
        message += kintai_data[i].full_name+'さんは、'+(Math.floor(working_hours * 10)) / 10+'時間勤務していますが、休憩時間は'+(Math.floor(break_time * 10)) / 10+'時間です。';
      }
      if(over_time > 1){
        if(message){
          message += '\n';
        }
        message += kintai_data[i].full_name+'さんは、1時間以上残業をしています🥲';
      }
      if(night_time > 0){
        if(message){
          message += '\n';
        }
        message += '⚠️'+kintai_data[i].full_name+'さんは、深夜労働しています。';
      } 
    }
    if(message){
     message = '<users/'+admin_user_id+'>【勤怠チェックプログラム🚔】\n'+message;
     SendGoogleChatMessage(message);
    }
  }
}

まず前回の記事でも紹介したように認証用のトークンをハーモスから取得します。
取得する関数はHrmosApiGetTokenという名前です。
前回の記事を参照ください。
https://www.shanaidx.com/gas_hrmosapi/#i-2

前回のプログラムではAPIを2つ使用しましたが、今回は勤怠情報を取得するAPI1つのみです。
指定した日付の勤怠情報を取得するAPIになります。
関数名はHrmosApiGetKintaiです。

ハーモスのAPIのリファレンスは下記になります。
https://ieyasu.co/docs/api.html#/paths/~1work_outputs~1daily~1{day}/get

取得する情報は、ユーザーのフルネーム、実働時間、休憩時間、残業時間、深夜労働時間の5つです。

取得した情報をもとに、以下の条件と一致したらチャットから通知します。

  • 8.5時間以上働いた人
  • 6時間を超えて働いた人で、休憩を45分以上取得していない人
  • 8時間を超えて働いた人で、休憩を60分以上取得していない人
  • 残業を1時間以上行っている人
  • 深夜労働を行っている人

勤怠情報を取得する関数

先程メインの処理で書いてあったHrmosApiGetToken関数部分です。

//ハーモスAPI 指定された日の日次勤怠データの一覧
function HrmosApiGetKintai(token)
{
  let check_d = GetDate(yesterday);
  let headers = {
    'Authorization': 'Token '+token,
    'Content-Type':'application/json'
  };
  let options = {
    'method' : 'get',
    "headers" : headers
  };
  let response = UrlFetchApp.fetch(api_url+company_name+'/v1/work_outputs/daily/'+check_d+'?limit=100', options);
  return JSON.parse(response);
}

最初に取得した認証用トークンを引数としてもらってます。
今回も100件までしか取得できませんので、社員数が100名以上いる会社の場合は、追加修正が必要です。

冒頭で取得した昨日の日付オブジェクトをGetDate関数に渡してYYYY-MM-DDというフォーマットを取得しています。

//Dateオブジェクトを日付だけ抽出 YYYY-DD-MM
function GetDate(date)
{
  return date.getFullYear()+'-'+(date.getMonth() + 1).toString().padStart(2, '0')+'-'+date.getDate().toString().padStart(2, '0');

}

GoogleユーザーIDの取得

こちらの処理は、Qiitaの下記の記事を参照させて頂きました。
Google Chat botがメンションするのに必要なUser IDを開発者コンソールに出力するスクリプト
https://qiita.com/takatama/items/9029ceef857516363c32

//GoogleのユーザーIDを取得 サービスからAdmin SDK APIを追加してください。
function getExecuteUserAddress(email) {
  let user = AdminDirectory.Users.get(email, { viewType: 'domain_public' });
  return user.id; 
}

このプログラムを動かすには、エディタのサービスから「Admin SDK API」を追加する必要があります。

サービスを追加から「Admin SDK API」を探して追加する

Googleチャットでメインションを書く場合は、下記のように記載します。xxxxxxxのところにUSER IDを入れます。

<users/xxxxxxxx>

ハーモスAPIから返された時間を変換する

ハーモスAPIから返ってきた実働時間や休憩時間は、時計と同じフォーマットです。
たとえば、8時間15分働いた場合は、8:15と返ってきます。
これだとプログラムで比較できませんので、時間に変換します。
8:15の場合は、8.25時間となります。

//8:30と表示されているものを8.5時間と時間で返す
function ChangeTime(checktime)
{
  let checktime_array = checktime.split(':');
  return Number(checktime_array[0]) + Number(checktime_array[1]/60);
}

Googleのチャットへ通知するプログラムの説明は割愛します。
以前、Slack、ChatWork、GoogleチャットへGASからメッセージを書く記事を紹介していますので、ぜひそちらを参照してみてください。

ソースコードのダウンロード

作成したソースコードを無料でダウンロードして頂けます。 ダウンロードしたテキストファイルに書かれたソースコードをGASのコード.gsにコピー&ペーストしてください。 1行目のハーモスのAPI KEY、3行目のハーモスの会社ID、5行目のGoogleチャットボットのWebhoookのURL、8行目の管理者通知用のGoogleのメールアドレスの4箇所を書き換えて頂く必要があります。

    < 利用規約 >
    ダウンロードして頂いたソースコードなど(以下、「ダウンロードファイル」と呼ぶ)は無償で利用することができます。弊社は、ダウンロードファイルを利用されて生じた一切の損害について、その賠償義務を負いません。
    < 個人情報の取扱いについて >
    ご提供いただいた個人情報につきましては、下記の目的の範囲内で取り扱います。
    その他の取扱いについては当社のプライバシーポリシーに従います。

    ・お客さまの本人確認・与信管理
    ・当社のサービスまたは製品のご案内のため(電子メールによるものを含む)
    ・当社によるアンケート、各種セミナーのご案内、市場調査のため
    ・当社のサービス品質改善に向けた利用分析及び統計データ作成のため
    ・その他重要なご連絡のため