SmartHR × GAS カスタム従業員項目に色んな情報を更新してみよう

鬼無里餅衛門

2024年4月30日 16:59

こんばんは、しがない情シスです。

今回はSmartHRをGASでこねこねしたお話です。

へーしゃ、少し前にSmartHRを使い始めまして。
「うわあああああすごいスマートだこれーーー！！！」ってなっている状態が数ヶ月続いています。
すごいです。スマートです！！（語彙力マイナス）

SmartHRのスマートなポイントのひとつに、APIがすっごいというものがあります。

超絶充実&みやすいリファレンスと、リファレンスページからURLリクエストも発行できてその場でメソッドお試しできちゃうという充実ぶり。すごい。

すごいし、色々できそうで可能性は無限大（You can change your world…）
…でも、この有り余るすごさをどうしたものか、果たしてお仕事や運用中のツール類に絡めてどうにか活かせるのだろうか…？

ということを思いつつも、なんやかんやあってSmartHRのAPI、その一端に触れてみた記録を書き綴っていこうと思います。

ライトな内容なので、柿の種（梅しそ味・ピーナッツなし）をポリポリするくらいの感覚でお読みください。

きっかけ

SmartHRとお近づきになれそう…だったのですが、上述の通りに「どうしたらいいのだ…ﾓｼﾞﾓｼﾞ…」と尻込みしていたときに、SmartHR大師匠（心の中で一方的に勝手にそう思っている）のツイートが目に飛び込んできました。

SmartHRのAPI使って自動でesaやGitHubのIDをSmartHRのカスタム属性に格納するようにしてたり、SlackのプロフィールにSmartHRの従業員ページのURLを載せて飛べるようにしたり、従業員情報をスプレッドシートに自動で書込みしたりetcしてます。要はSmartHRのAPIはいいぞ。 https://t.co/V4Sukhy6NX
— howdy39 (@howdy39) December 20, 2023

なるほどー！カスタムの項目ー！！

任意に設定できる項目に「システム周りの情報」を載っけたら、「ユーザーの情報とシステムの情報」がリンクして扱いやすそう…！

というわけで情報を持たせてみました。
APIを叩く環境はGASを使用しています。

SmartHRのカスタム従業員項目について

概要

カスタム従業員項目の作り方・使い方は、ヘルプページを見てもらえればOKだと思います。

普通に使う分にはGUIから項目を持たせるだけでも十分便利ですね。
いろんな使い道が考えられます。
（人事の方が従業員の付帯的な情報を持たせたり～とか）

カスタム項目を扱う上での注意点は、入力タイプと閲覧・編集権限くらいでしょうか。

入力タイプは参照、更新する時のデータ型に影響が出ます。
テキストなら文字列型、数値なら数値型、という具合ですね。

閲覧・編集権限は発行されているAPIトークンに影響します。
デフォルトだとトークン発行後に追加された項目は閲覧も編集もできないので、後からポチポチ追加するか、設定を見直して新規にトークン発行されたらデフォで権限付与するようにするなどしておきましょう。

やろうとすること

SmartHRにカスタム従業員項目（SlackIDを入れるフィールド）を作る
そこに社員に対応したSlackユーザーIDを一括で更新する

というようなことをやってみます。

準備作業

SmartHRのトークンを発行する

アクセストークンの発行もヘルプページに丁寧に記載されてますね。

ヘルプページに記載のある通り、［アトリビュート（従業員出力項目）の制限］の設定は適切に行ってあげましょう。
（発行したトークンでお目当てのカスタム項目をいじれるようにします）

トークンを発行したら、GASのスクリプトプロパティなどにコピペして保存しておきます。

テンプレートIDを取得する

よーし早速情報を埋め込むぞー！

…と、その前に、埋め込む先のカスタム項目IDを取得する必要があります。
埋め込み先がわかんないと埋め込みようがないですもんね。

まずは作成したカスタム項目のIDを調べる処理を作っておきます。

/**
 * カスタムテンプレートIDを調べるための処理
 */
function getCustomTemplate(){
  //　テンプレートURL
  const url = `${url}/v1/crew_custom_field_templates?per_page=100`;
  const options = {
    'method' : 'GET',
    'headers' : { 'Authorization': `Bearer ${token}` },
  };

  const response = UrlFetchApp.fetch(url, options);
  const result = JSON.parse(response.getContentText());

  for (let i=0; i < result.length; i++) {
    Logger.log(result[i].id + ' : ' + result[i].name);
  }
}

url や token にはサブドメインやトークンが入るので、リファレンスを見ながら設定してみましょう。

リクエストURLの per_page は1ページあたりのアイテム数になります。
デフォルトでは10が設定されており、何も指定しないと1リクエストで10個しか参照できないことになります。
なのでMAXの100に設定。

流石に100個以上カスタム項目設定するのは使い込んでる状態だと思いますが、これすら超過しちゃったらページネーション処理も作る必要がありますね。

この関数を実行すると、ログにテンプレートIDとテンプレート名がズラーっと吐き出されます。
その中からお目当ての名前がついたものを見つけて、IDをコピーなりメモなりスクリプトプロパティに入れるなりしておきます。

テンプレートID取得のAPIメソッド：

SmartHRのIDを用意する

埋め込み先のもう一つの情報として、SmartHRのユーザーIDが必要となります。

ユーザー一人だけ狙い撃ちで更新、というのであればID参照してコピペとかでもいいと思います。
（でもそれくらいならGUIから更新した方が早そう）

今回私がやりたかったのは「全ユーザーのカスタム項目にSlackIDを埋めていく」という動作なので、事前にスプシでユーザーをリストアップしました。

従業員をリストアップするAPIメソッド：

従業員のリスト取得メソッドでガッと取れます。

埋め込みたいものの情報を用意する

埋め込む元となる情報も用意しておきましょう。

今回はSlackIDを埋め込んでみようと思ったので、SlackIDもおんなじようにスプシにリストアップしました。

ユーザーリストを取得するAPIメソッド：

Slackもリストでガッと取れます。

二つのリストのマッチングのキーとなるものはメールアドレスです。
双方ともメールアドレスとIDがリストアップできてれば最低限準備オッケーですね。

SmartHRに情報を埋め込む

準備ができたので、埋め込んでみましょう。

今回のサンプルでは、以下の情報を埋め込んでいます。

カスタム項目名：SlackID
埋め込む情報：ユーザーのSlackID

/**
 * SmartHRにSlackIDをセット
 * 引数：ユーザーアレイ（SmartHRの対象IDを渡す）
 * 戻値：true（成功）,false（失敗） 
 */
function updateSlackColumn(userData,slackData) {
  const id = userData[0]; // id
  const email = userData[2]; // email
  for (let i = 0; i < slackData.length; i++){
    //emailをキーとして情報を判定
    if (email === slackData[i][2]) {
      const slackId = slackData[i][0];
      //emailが一致するユーザーに対してSlackID埋め込み
      let shrUrl = `${url}/v1/crews/${id}`;
      let options = {
        'method' : 'PATCH',
        'headers' : {
          'Authorization' : `Bearer ${token}`, 
          'Content-Type' : 'application/json'
        },
        'payload' : JSON.stringify({
          'custom_fields' : [
            {
              'template_id': 'XXXXXXXXXXXXXXXXXXXXXXXXXXXXx', //SlackIDのテンプレートID
              'value': slackId //セットするSlackID
            }
          ]
        })
      };
      // HTTPリクエストを投げる
      let response = UrlFetchApp.fetch(shrUrl,options);
      // 正常終了true
      return true;
    };
  };
  // ループ完了しちゃったら値は入らないfalse
  return false;
};

コード全体を貼るのもアレなので、PATCHのリクエストを投げてる関数だけ貼ります。ご容赦を…。

この関数の前段の処理として、用意したスプシ二種（SmartHRとSlackのID一覧表）をgetValuesで配列として読み込んであります。
読みこんだ配列を引数として渡して、ループでぐるぐるマッチさせてます。
ユーザー情報が一致したら、PATCHのAPIを叩いて更新、以下繰り返し…という感じです。

これでSmartHRに情報を埋め込むことができました！

おわりに

ここで作った処理を明け方に定期スケジューリングして、新しい従業員が増えたらSlackIDを埋めていく、というようなことをしてます。
（即時反映しても良かったのですが、Slackアカウントが入社初日オンボーディングの一環で生成される流れになってるので、入社翌日更新でいいか～！と妥協しました）

今はSmartHRに埋め込んだ情報を参照して、色んなものに使ったりしてます。
SlackであればSlackIDから逆引きでSmartHRのユーザーがわかったり…とか、他のサービスのIDも埋め込んでユーザー参照したり…とか、参照したユーザーのSlackID宛に通知を送ったり…などなど、そんな具合に利用したりしてます。

人の情報とシステムの情報がリンクしていくのはとても良いものですね…！

まだ使い始めたばかりなので作ったものも小規模、SmartHRもこれから利用拡充、というフェーズです。
ここから活用が進むにつれて、色んな社内要望も出てきそうです。
そうなったときにこうした引き出しを持っておけば、対応の選択肢も広がって良い感じですね。

SmartHR、すっごいスマートです！

スマートこそパワー！！！

この記事が気に入ったらサポートをしてみませんか？