本レシピはStandardプラン以上の有償プランでご利用いただけます。ご利用をご希望の場合は下記よりお問い合わせください。

お問い合わせ | ActRecipe

SmartHRから指定期間内に削除された家族情報を取得してCSVファイルに出力する方法を解説します。
レシピを使用するには事前にSmartHRの利用契約が必要になります。

【ご説明動画】

レシピのご利用の流れをまとめておりますのでご覧ください。

0.事前準備

1. 「SmartHR - CSVファイル出力 (家族差分 - 削除)」レシピを使用するには、事前にSmartHR Plusでのアプリの登録が必要となります。
2. 以下のSmartHR Plusにアクセスし、画面右上の「ログイン」ボタンよりSmartHRへログインします
   https://www.smarthr.plus/apps/actrecipe
3. 続いて「連携をはじめる」ボタン(青色)をクリックします
4. アプリのインストール確認画面にて「連携をはじめる」ボタンをクリックします
5. アプリの連携が完了しますと上記「2」のボタンが「アプリを開く」に変わりますので、同ボタンをクリックします
6. 以下の確認画面が表示されますので「連携を許可」をクリックします(※)

連携するユーザはSmartHRの「管理者」権限を保持している必要があります。

※ 
ActRecipeのアカウントを保持しておりActRecipeにログインしていない場合にはログインをしてください。
ActRecipeのアカウントが未作成の場合は「無料ではじめる」ボタンよりアカウントを作成し、通知メールに従ってください。

1.マイレシピへの登録

メニューの「シェアレシピ」から、「SmartHR - CSVファイル出力 (家族差分 - 削除)」にチェックを入れ、画面下にある登録ボタンを押下します。シェアレシピの画面に「SmartHR - CSVファイル出力 (家族差分 - 削除)」が表示されない場合はSmartHR Plusの画面からやり直してください。
続いて「マイレシピ」から、操作メニューより「編集」を選択します。
参考：シェアレシピ・マイレシピとはなんですか？

ヘッダーでは、レシピ名とレシピ説明を変更することができます。
参考：レシピヘッダーでは何を設定すれば良いですか？

2.SmartHRの認証情報設定

「SmartHR 家族情報（差分取得 - 削除）」を押下し、設定を展開します。
本タスクでは、以下の項目を設定します。

• ヘッダーの種類：取得するヘッダーの種類を選択します。
  • 物理名：SmartHRのシステム上設定されている項目名が取得されます。例えば、社員番号は「emp_code」と出力されます。物理名を指定した場合もカスタム従業員項目は論理名が出力されます。
  • 論理名：SmartHRの画面上で表示される項目名が取得されます。例えば、社員番号は「社員番号」と出力されます。後述しますマッピング出力をされる場合には必ず論理名をご指定ください。
• 取得データの種類：
  • 物理名：システム上設定されている項目名が取得されます。例えば、性別項目の値は「male」「female」となります。物理名を指定した場合もカスタム従業員項目は論理名が出力されます。
  • 論理名：画面に表示される項目名が取得されます。例えば、性別項目の値は「男性」「女性」となります。
• 対象期間（本日から50日以内）：SmartHRから差分データを取得する期間を指定します。
  運用形態（手動実行または自動実行）に合わせて、「期間を指定」 または 「日数を指定」 のいずれかのラジオボタンを選択します。
  【API仕様上の重要制限】
  SmartHRの差分APIの制約により、指定できる日時は「実行時点から過去50日以内」となります。50日より前の日付を指定した場合はエラーとなりますのでご注意ください。
  • 期間を指定
    特定の日付範囲をカレンダーから指定して差分を取得します。
    • 開始日【必須】
      差分抽出の開始日を YYYY-MM-DD 形式（または右側のカレンダーアイコン）で指定します。
    • 終了日【任意】
      差分抽出の終了日を YYYY-MM-DD 形式で指定します。
      ※未指定の場合： レシピ実行時点の日時までが自動的に対象となります。
  • 日数を指定
    実行日を基準として、過去何日前からの差分を取得するかを数値（日数）で指定します。
    推奨例（週次定期連携の場合）：
    7（日間）と指定することで、毎週1回の実行時に「直近1週間で変更のあったデータ」を自動的に抽出します。
• 家族情報ファイル（オプション）
  本項目は、タスク「SmartHR 家族情報（差分取得 - 削除）」において、削除された家族データを他の連携先フォーマットへ出力する際、必要に応じて補助データ（家族マスタ情報）を紐付けるためのオプション設定です。

  • SmartHRの仕様上、本来取得できる項目一覧
    ・家族ID（id） 
    ・社員番号（crew.emp_code）および従業員ID（crew.id） 
    ・続柄情報（relation.name 続柄名称、続柄ID、子フラグ等） 
    ・家族氏名（last_name 姓、first_name 名） 
    ・家族の生年月日（birth_at） ・家族コード（code） 
    ・作成日時 / 更新日時（created_at / updated_at） 
    ・削除日時（deleted_at）

  • SmartHRの仕様制約と本設定が必要な理由 
    SmartHRの削除APIでは、上記以外の情報（「家族氏名カナ（フリガナ）」、「住所」、「同居・別居区分」、「所得・扶養関連の情報」など）はシステム仕様上、一切返却されません。
    そのため、連携先システムの受入仕様として、フリガナ等の上記API仕様に含まれない項目がインポート必須となっている場合、削除API単体では連携データを作成することができません。 このような場合に、あらかじめSmartHRからダウンロードした最新の「家族情報ファイル」を本項目に設定しておくことで、家族ID(id)をキーにして不足している詳細項目を照合・補完し、連携先指定のCSVフォーマットを生成します。

  • 設定方法・操作手順

    • すでにActRecipe内にファイルを保存している場合 
      プルダウンをクリックし、登録済みの家族情報ファイルを選択してください。

    • 新しくファイルを登録する場合
      1. 枠の右側にある「アップロード」ボタンをクリックします。
      2. SmartHRから事前にダウンロード・出力した最新の家族情報CSVファイル（全件データ等）を選択してアップロードします。
      3. アップロード完了後、プルダウンに対象ファイルが選択されていることを確認し、画面右下の「保存」をクリックします。

  • ファイル有無による挙動の違い

    • ファイルを指定した場合：SmartHRの削除APIから取得した家族IDをキーにして、指定された家族情報ファイル内の一致するレコードを検索します。削除APIの仕様上欠落している「フリガナ」や「各種属性情報」をファイルから補完した上で、最終的な連携用CSVファイルを出力します。

    • 未設定（空欄）のまま実行した場合：ファイルによる情報補完は行われません。SmartHRの仕様通り、削除APIから直接取得できる標準項目（社員番号、続柄、漢字氏名、生年月日など）のみを使用してCSVファイルを出力します。 
      ※連携先システム側がこれらの基本項目のみで削除インポートを受け付ける仕様であれば、本ファイルを設定（アップロード）する必要はありません。

      【運用上の注意点】
      ・照合のキーとなる列について：アップロードするCSVには、削除データと確実に突合できるよう「家族ID」（または社員番号と家族コード・氏名）が含まれている必要があります。 
      ・定期的なファイルの最新化：削除される前の情報と突合する必要があるため、アップロードする家族情報ファイルは定期的に最新の全件データをエクスポートして差し替えておく運用を推奨します。

SmartHRとのOAuth接続を切断する場合は「テナントの変更・解除」をクリックし、続いて「接続解除」をクリックします。

3.SmartHRとCSVファイルのマッピング出力設定

「SmartHR - Convert crews data」タスクでは、SmartHRの項目のうちどの項目をCSVファイルへ出力するかを設定することができます。

はじめに以下の手順で設定ファイルを適用します。

• 以下のファイルをローカルPC環境等に保存します。
  SmartHR - 家族差分 削除用JSONファイル(物理名)v1.0
  SmartHR - 家族差分 削除用JSONファイル(論理名)v1.0
   
• レシピの編集画面より、アップロードアイコンから上記のJSONファイルをアップロードします。JSONファイルが未設定の場合にはSmartHRから取得した全ての項目がCSVファイルに保存されます。

デフォルト（全てのオプションチェックがOFFの状態）の出力項目は以下の通りです。
「ヘッダーの種類」が物理名の場合：

id,crew_id,emp_code,relation.id,relation.name,relation.preset_type,relation.is_child,relation.position,is_spouse,last_name,first_name,last_name_yomi,first_name_yomi,birth_at,moved_at,gender,job,basic_pension_number,live_together_type,address.zip_code,address.pref,address.city,address.street,address.building,address.literal_yomi,address.country_number,tel_number,handicapped_type,handicapped_note_type,handicapped_note_delivery_at,remittance_to_relative,international_student,social_insurance_support_type,income,monthly_income,soc_ins_qualified_at,soc_ins_qualified_reason,soc_ins_disqualified_at,disqualified_reason_type,disqualified_reason,tax_law_support_type,tax_deduction_income,tax_deduction_qualified_at,tax_deduction_qualified_reason,tax_deduction_disqualified_at,tax_deduction_disqualified_reason_type,tax_deduction_disqualified_reason

「ヘッダーの種類」が論理名の場合：

家族ID,紐づく従業員のID,紐づく従業員の社員番号,続柄ID,続柄名,プリセット続柄,子であるかどうか,ポジション,配偶者かどうか,姓,名,姓（カタカナ）,名（カタカナ）,生年月日,住所変更年月日,性別,職業,基礎年金番号,同居・別居の別,郵便番号,都道府県,市区町村,丁目・番地,建物名・部屋番号,ヨミガナ,国コード,電話番号,障害者区分,障害者手帳の種類,障害者手帳の交付年月日,海外居住時の送金額,留学生,社会保険の扶養状況,社会保険の年間収入,社会保険の月間収入,社会保険の被扶養者になった日,社会保険の被扶養者になった理由,社会保険の被扶養者でなくなった日,社会保険の扶養から削除された理由,社会保険の扶養から削除された理由（その他の場合）,税法上の扶養状況,税法上の年間所得見積額,税法上の被扶養者になった日,税法上の被扶養者になった理由,税法上の被扶養者でなくなった日,税法上の扶養から削除された理由,税法上の扶養から削除された理由（その他の場合）

※家族情報ファイル（オプション）を設定していない場合、出力される値は、以下のみとなります。
・家族ID（id） 
・社員番号（crew.emp_code）および従業員ID（crew.id） 
・続柄情報（relation.name 続柄名称、続柄ID、子フラグ等） 
・家族氏名（last_name 姓、first_name 名） 
・家族の生年月日（birth_at） ・家族コード（code） 
・作成日時 / 更新日時（created_at / updated_at） 
・削除日時（deleted_at）

JSONファイルはSmartHRとCSVファイルのマッピング設定をまとめたものとなりますので、検証等で設定変更を繰り返したい場合にはダウンロードアイコンから設定ファイルをバックアップしてください。

続いて、「SmartHR - Convert crews data」タスクの画面について説明します。
【入力設定】

• 文字コード：入力ファイル(変換元ファイル)の文字コードを選択します。
• ヘッダーあり/なし：入力ファイルにヘッダーが含まれる場合は「ヘッダーあり」、ヘッダーが含まれない場合は「ヘッダーなし」にします。
  ※本レシピにおいては、変更不要です。
• 区切り文字：入力ファイルの区切り文字を入力します。デフォルトはカンマ(,)です。

【入力フィルター】
入力フィルタでは、SmartHRから取得する家族情報を任意の条件に基づいて絞り込むことが可能になります。フィルタ項目の増減は下部の「(+)」アイコン、または、右側の「(-)」アイコンより行っていただけます。

• 入力項目： SmartHR上の項目名を入力します。SmartHRの項目名とその説明は以下の資料をご確認ください。
  SmartHR家族情報連携項目
• 条件：以下の条件の内いずれかを指定します。
  • 次に等しい：入力項目で指定した項目が、以下の”値”にて指定した値と等しい場合に出力します。
  • 次に等しくない：入力項目で指定した項目が、以下の”値”にて指定した値と等しくない場合に出力します。
  • が空：入力項目で指定した項目が、空欄である場合に出力します。
  • が空ではない：入力項目で指定した項目が、空欄ではない場合に出力します。
• 値：絞り込みたい条件に基づき値を入力します。
  「XXXX, YYYY」のようにカンマ区切りで入力することで、複数の値を一括で指定することも可能です。
• AND・OR：複数の条件を「かつ(AND)」「または(OR)」で組み合わせることができます。
  条件行の左右に「( 」および「 ) 」のプルダウンから条件のグルーピングもでき、「(A かつ B) または (C かつ D)」といった、特定の条件をグループ化して優先させる複雑な絞り込みも可能です。
  ※対応可能なネストは1階層（括弧は一重）までです。
  ( ) によるグルーピングは可能ですが、(( )) のように括弧を二重に設定することには対応しておりませんのでご注意ください。
  

【出力設定】

• 出力ファイル種別：出力ファイルの種類を「CSV」または「TEXT」から選択します。
• ヘッダー出力する/しない：出力ファイルのヘッダーの有無を選択します。
• 文字コード：出力ファイルの文字コードを「UTF-8」「SHIFT_JIS」「SHIFT_JIS (CP932)」から選択します。
• 区切り文字：出力ファイルの区切り文字を設定します。
• クォート：出力ファイルデータについて「"文字列"」のようにクォートを付与する対象を選択します。
• 桁数を超える処理：下記の「出力フォーマット」において、指定した桁数を超過した場合の処理を選択します。

【出力フォーマット】
出力フォーマットでは、入力ファイルを用いてどのようなアウトプットとするかを決定します。マッピング項目の増減は下部の「(+)」アイコン、または、右側の「(-)」アイコンより行っていただけます。
下図の「項目名」はCSVファイルのヘッダーを指しており、「出力指定」はSmartHRの項目を指しております。SmartHRの項目とその説明、ActRecipeのJSON項目名は以下の資料をご確認ください。

SmartHR家族情報連携項目

「出力指定」には上記ファイルの「SmartHR項目名 (物理名)」または「SmartHR項目名 (論理名)」の指定が可能です。設定値は「SmartHR 家族情報（差分取得 - 削除）」タスクの「ヘッダーの種類」に依存しますので、以下の組み合わせとなるようご対応ください。

• 「出力指定」に「SmartHR項目名 (物理名)」を使用する場合：「ヘッダーの種類」からは「物理名」を指定します。
• 「出力指定」に「SmartHR項目名 (論理名)」を使用する場合：「ヘッダーの種類」からは「論理名」を指定します。
  物理名を指定した場合もカスタム従業員項目はSmartHRの論理名が出力されますので、カスタム従業員項目を出力される場合は「ヘッダーの種類」を「論理名」としていただくことを推奨します。

「型」や「桁数」や「出力区分」は任意の設定を行なっていただくことができます。

「出力指定」ではExcelとほぼ同様の関数指定を行うことができます。例えば、SmartHRの「姓」と「名」を1つのフィールドに出力したい場合は、出力区分および出力指定を以下のように指定します。

出力区分：計算式
出力指定：#(姓)&#(名)

• 参照ファイル内の値を参照したい場合
  ※ 参照ファイル（下記赤枠にセットするファイル）：SmartHRから取得したい家族情報とは別に変換時に外部マスタとして参照するファイルを指します。
  ActRecipeのファイル一覧画面（https://app.actrecipe.com/v2/files）
  
  フォーマット：$([ファイル番号]:"[カラム名]")
  上記の「ファイル番号」はActRecipeのファイル一覧内のファイル番号を指します。「カラム名」はファイル一覧に保存したCSVファイルのカラム名を指します。
  ※ ファイル一覧内のCSVファイルが対象であり、マスターファイル以外のファイルも指定可能です

  【例】
  以下のファイル番号およびカラム名指定をする場合の計算式は「$(362025:"事業所名")」となります。
  ※カラム名前後のダブルクォートは必須ですので省略せずご入力ください。
  ・ファイル番号：362025
  ・指定するカラム名：事業所名

  【ユースケース】
  SmartHRから取得した事業所名を、ファイル一覧内の”変換表（マッピングCSV）”を参照して、事業所名コードに変換
  【計算式】
  IFS(
  #(事業所名) = $(362025:"事業所名"), $(362025:"事業所名コード"),
  TRUE, "該当なし"
  )

  

  

  

※ ActRecipeのコンバート処理は、設定画面の定義順（上から順番）にデータを上書き更新しながら実行されます。
予期せぬエラーやデータ不整合を防ぐため、設定の際は必ず以下の2点をご遵守ください。

■1. 項目名の重複禁止
同じ項目名を複数作ると、すべて同じ値に上書きされます。

・NG例
 以下のように全ての項目名を同一名で定義
➔ 最後の#(部署3)により上書きされ、全ての部署が同一名として出力されます。・OK例
 出力項目名をすべて「一意（ユニーク）」に定義
➔ それぞれの#(部署〇)が出力されます。■2. 項目名に「元データの項目名」を使用
連携元データのヘッダーの項目名をそのままに、値だけ変換し、以下のように#(項目名)を指定すると、連携元データの項目名の値ではなく、変換後の項目名の値を参照してしまい、後続の計算や変換で「#ERROR!」や変換不具合が発生します。
・NG例
 1. 「入社年月日」を和暦（2019年11月07日）に変換し、出力項目名も「入社年月日」にして上書きする。
    ➔ 元データ（2019-11-07）が消え、ただの「文字列」に変わる。
 2. 後続の「入社年数（DATEDIF）」で #(入社年月日) を参照する。
    ➔ 文字列を計算しようとするため計算エラー（#ERROR!）になる。

・OK例①
出力項目名（ヘッダー名）を変更する。
 変換後の出力項目名を「入社日」や「生年月日_変換後」などの「別名」に指定します。
 ➔ 元データが上書きされずに残るため、すべての計算や変換が正常に動作します。

 ・OK例②：コンバート設定の順番を入れ替える
 計算（DATEDIF等）を行う項目を、上書き変換（和暦変換等）を行う項目よりも「上（前）」に配置してください。


【出力フィルター】
出力フィルターでは、出力フォーマットによって出力されたファイルを任意の条件に基づいて絞り込むことが可能になります。フィルタ項目の増減は下部の「(+)」アイコン、または、右側の「(-)」アイコンより行っていただけます。

• 括弧 ( )：複数の条件をグループ化して優先順位を指定できます。各条件行の左端に開始括弧「(」、右端に終了括弧「)」を設定できます。
  ※ 対応可能なネストは1階層（括弧は一重）までです。( ) によるグルーピングは可能ですが、(( )) のように括弧を二重に設定することはできません。
• 出力項目：出力フォーマットにて、設定した項目を指定します。
• 条件：以下の条件の内いずれかを指定します。
  • 次に等しい：出力項目で指定した項目が、以下の”値”にて指定した値と等しい場合に出力します。
  • 次に等しくない：出力項目で指定した項目が、以下の”値”にて指定した値と等しくない場合に出力します。
  • が空：出力項目で指定した項目が、空欄である場合に出力します。
  • が空ではない：出力項目で指定した項目が、空欄ではない場合に出力します。
• 値：絞り込みたい条件に基づき値を入力します。
   「営業部, 開発部」のようにカンマ区切りで入力することで、複数の値を一括で指定することも可能です。

• AND・OR：複数の条件を「かつ(AND)」「または(OR)」で組み合わせることができます。
  複数の条件を設定した場合、上から順番に1つずつ評価（直列評価）されます。
  例：条件A AND 条件B OR 条件C は、(条件A かつ 条件B) または 条件C として処理されます。

  【例】

• 条件A AND ( 条件B OR 条件C )
  → 条件Aを満たし、かつ「条件Bまたは条件Cのどちらか」を満たすデータを出力します。

• ( 条件A AND 条件B ) OR ( 条件C AND 条件D )
  → 「条件AとBの両方」を満たす、または「条件CとDの両方」を満たすデータを出力します。 

  

コンバート機能の詳細や出力指定のサンプルは下記ページをご覧ください。
コンバートの設定方法を教えてください

給与ソフト等に合わせた各種テンプレートは下記ページをご覧ください。
SmartHR用インポート・エクスポートテンプレート
 

出力指定の条件指定方法のサポートは有償プランにて承っております。詳しくはお問い合わせください。

レシピを実行する (自動実行はこちら)

マイレシピの操作メニューより「実行」を選択することでレシピを実行できます。
画面イメージや履歴の確認方法は以下をご参照ください。

参考：レシピを実行するにはどうすれば良いですか？

レシピの実行に成功すると、SmartHR上の指定した項目および値がCSVファイルに出力されます。

【注意事項】SmartHR - CSVファイル出力 (家族差分 - 削除) で取得可能な従業員情報の取扱いについて

•  取得できる従業員の範囲・項目は、設定時に利用したSmartHRのアカウントの権限設定を反映します。目的と用途に応じた権限のSmartHRのアカウントを使って設定を行なってください。
  詳しくは、*従業員関連の閲覧・作成・更新・削除の権限を設定する* を参照してください。
  https://support.smarthr.jp/ja/help/articles/1500001368101/

エクスポートテンプレートについて

本レシピに適用可能なエクスポートテンプレートは下記ページをご覧ください。

• SmartHR用インポート・エクスポートテンプレート

Freeプランについて
このレシピはActRecipeのStandardプランでご利用いただけます。Freeプランの制約事項や有償プランへの移行は下記をご覧ください。
 

• Freeプランについて

このレシピで連携できるSaaSについて

• SmartHR

その他のSmartHR連携ができるレシピ

• SmartHR連携レシピ