こちらの記事では、はじめて gusuku Customine Job Runner を使い始める方向けに、簡単なカスタマイズ作成方法をご紹介します。
まずはじめにやること
Job RunnerでkintoneのWebhookや定期実行タスクのカスタマイズを作成する前に、まず「ジョブへのスロット割り当てについて」を実施する必要があります。
これは、利用中のアプリスロットをどの程度Job Runnerで利用できるようにするか、という設定です。
詳しくは Job Runnerを利用するとき、初めにすること ： ジョブへのスロット割り当てについて をご確認ください。
カスタマイズの種類について
gusuku Customine で作成できるカスタマイズには、以下の種類があります。
この記事では、定期実行タスクを使った「年齢計算」を取り上げます。
Job Runnerのカスタマイズの全体像
Job Runnerのカスタマイズでは、下記の様な流れで処理を行っていきます。
1. 処理対象となるkintoneアプリに接続する
2. 処理対象となるレコードを取得する
3. 取得したレコードに対して処理を行う
4. 処理結果をkintoneに反映する
5. カスタマイズの実行
これを踏まえて今回のカスタマイズの流れを示すと、次のようになります。
kintoneアプリと接続設定を行い (1. に相当)
レコードを取得し (2. に相当)
取得したレコードに対して年齢計算を行う (3. および 4. に相当)
また、カスタマイズが終わったら、「直ちに実行」や「定期実行」を設定し、カスタマイズを動かします。(5. に相当)
それでは始めましょう！
kintoneアプリと動作イメージについて
カスタマイズの完成例
今回のカスタマイズでは、「従業員名簿」の全レコードに対して、「生年月日」をもとに処理を行った日時点の年齢を計算し、「年齢」フィールドにセットします。
カスタマイズに用いるkintoneアプリの準備
今回利用するkintoneアプリに必要なフィールドは、以下の2つです。
生年月日（日付）
年齢（数値）
このため、今回はkintoneアプリストアの人事労務パックの「従業員名簿」アプリを使用します。
今回用いる「従業員名簿」アプリには「年齢」欄がないので、次のように数値フィールド「年齢」を新たに追加してください。
※フィールドコードも同様に「年齢」と設定してください。
また、定期実行タスクのカスタマイズではgusukuサーバがkintoneに対しレコード取得やレコード更新をするために、APIトークンをあらかじめ設定しておく必要があります。また、設定した際に発行されたトークンはカスタマイズで設定する必要があります。
今回は、このAPIトークンを利用してレコードの取得と更新を行うので、APIトークンのアクセス権も同様に「レコード閲覧」と「レコード編集」のアクセス権を設定し、トークンを生成しておきます。また生成した後、必ず保存し「アプリを更新」するのを忘れないようにしてください。
またAPIトークンについては、次の点に注意してください。
APIトークンに付与する権限は、よく検討して必要最小限のものを付与するよう心がけてください。
生成したAPIトークンは取扱に注意し、第三者に知られないようにしてください。
定期実行タスクの作成手順
カスタマイズ一覧画面からは「新規のカスタマイズ作成」→「定期実行タスク」、カスタマイズ画面からは左上のメニューから「新しいカスタマイズ」→「定期実行タスク」で定期実行タスクの作成を開始します。
カスタマイズ一覧画面の例
作成するプロジェクトを選択し初期画面が表示されると、アクション1番と2番に初めから「やること」と「条件」が設定されています。
これらは、定期実行タスクでの定番となる設定が自動的にセットされています。
まずはこの「やること」「条件」を順に説明していきます。
1.処理対象となるkintoneアプリに接続する
最初のアクションには、やること「kintone 接続設定を行う」と条件「実行予定時刻になった時」がセットされています。
Job Runnerのカスタマイズは、kintoneアプリのカスタマイズと違い、”カスタマイズ実行時に画面に表示されているレコード”がありません。
このため値を取得したい、更新したい、コメントを投稿したいなど何か処理を行いたいレコードについては、あらかじめ取得しておく必要があります。
また、レコードの取得には前述の通りAPIトークンが必要です。処理対象としたいレコードの処理を行うためのkintoneアプリへの接続は、このAPIトークンを使って行います。
kintoneアプリへの接続は、やること「kintone 接続設定を行う」を使用します。
やること「kintone 接続設定を行う」を指定したアクションは、レコードの取得・更新を行うkintoneアプリの数だけ作成する必要があります。今回はレコードの取得・更新を行うアプリは従業員名簿アプリのみですので、アクションは１つだけ作成します。
もし、アプリがカスタマインにまだ登録されていない場合はアプリを追加する必要があります。「kintone 接続設定を行う」の「アプリ」の一覧に対象アプリが表示されていない場合は、画面に沿ってアプリを追加してください。
なお定期実行タスクのカスタマイズの起点となる「条件」は、条件「実行予定時刻になった時」です。これ以外の条件を指定することはありません。
2.処理対象となるレコードを取得する
kintone接続設定をした後は、レコードを取得したり、更新したりすることが可能となります。
今回の処理では、従業員名簿アプリの全レコードを対象に年齢の計算を行いたいので、やること「全レコードを取得する」を使用します。
今回はやること「全レコードを取得する」を使っていますが、このほかにもやること「キーを指定してレコードを取得する」「条件を組み立ててレコードを取得する」などのやることを使用してレコードを取得することもできます。
これらのやることは、キーなどの条件となる値を指定する必要がありますが、前述したとおり Job Runner には ”カスタマイズ実行時に画面に表示されているレコード” がないため、表示されているレコードのフィールド値を利用することができません。
条件となる値には固定値や、「やること」で取得できる値(例:today()など) を指定するか、または別のアクションでレコードを取得し、そのレコード内のフィールドの値を指定する必要があります。
また、今回はやること「全レコードを取得する」を使用しています。これはレコードを取得する一番簡単な「やること」ですが、アプリにあまりに多くのレコードがある場合には、非常に時間がかかったり、場合によってはジョブがタイムアウトする可能性があります。そういった場合は、前述した他の「やること」の使用も検討してみてください。
3. 取得したレコードに対して処理を行う
先ほど取得したレコードに対して、やること「年齢を計算する」で処理を行います。
ここで指定するのは、条件「レコード１行が準備できた時」です。
条件「レコード１行が準備できた時」は、取得したレコードから１レコードずつ取り出し、処理を行います。
Job Runnerでレコード取得後、次のアクションの条件について
Job Runner のカスタマイズでは、レコードを取得したのち、取得したレコードに対しての処理の起点となる一つ目のアクションの条件は原則、条件「レコード１行が準備できた時」、または条件「レコード全行が準備できた時」を使用します。
取得したレコードに対しての処理の起点となるアクションで、条件「他のアクションの実行が完了した時」を指定すると取得したレコードを正常に扱えないため、こういった条件の使用はしないように気を付けてください。
NG例：
OK例：
なお、Job Runner のカスタマイズではアクションを設定する際に、「やること」より先に「条件」を指定するのがおすすめです。Job Runnerのアクションは、条件に指定されたアクションをたどって処理対象となるレコードおよびレコードが所属しているアプリを識別する仕組みとなっています。
このため、条件が指定されていない状態ではやることのパラメーターでフィールドを使用する設定ができません。
下記は、条件を指定せずにやることのパラメーターで「フィールド選択」ボタンをクリックした際のエラーメッセージです。
条件が指定されていないため、どのアプリのフィールドを使用可能なのかを判別できず、次の様なエラーが表示されます。
「条件」設定前に「やること」を設定した場合、エラーメッセージが出ることがある
この様なエラーメッセージが表示された場合は、まず「条件」を設定した上で「やること」の設定を行ってください。
4.処理結果をkintoneに反映する
処理結果をkintoneのレコードに反映します。やること「年齢を計算する」は、パラメーター「結果をセットするフィールド」に処理結果を保存したいフィールドを指定することで、結果を反映します。
フィールドカテゴリーの「やること」は、フィールドを指定するパラメーター（「結果をセットするフィールド」や、「フィールド」）で指定したフィールドに対し、処理結果の保存や、フィールドの値を直接置換して処理結果を反映することができます。
それ以外の「やること」の結果をレコードに反映する場合は、やること「フィールドに値をセットする」や、やること「キーの値をもとにレコードを更新する」などを用いて反映します。
カスタマイズは以上です！
レコードの保存は？
年齢計算は、計算しただけでは保存されないのではないか？と思われるかもしれませんが、ご安心ください。保存は自動で実行されます。
kintoneから取得して、そのあと操作されたレコード、例えば やること「フィールドに値をセットする」などで、なにか値がセットされたレコードは、ジョブの最後にまとめて保存されるようになっており、Job Runnerでは基本的にレコードの保存を自分で考慮する必要はありません。
全体のカスタマイズ設定
設定全体はこちらになりますので、ご確認ください。この3アクションで年齢計算のカスタマイズが実現できます。
カスタマイズの実行
カスタマイズが完成したら、「ジョブ生成・設定」ボタンをクリックし、カスタマイズをもとにジョブを作成・実行します。
クリックするとジョブが生成され、「ジョブ設定」ダイアログが開きます。「ジョブ設定」ダイアログの詳しい使い方についてはこちらのページも併せてご確認ください。
作成したカスタマイズを実行する前に、下記「カスタマイズ実行時の注意点」を確認し、準備を行ってください。
カスタマイズ実行時の注意点
Job Runner のカスタマイズは複数のレコードに対する一括処理が可能なため、カスタマイズの誤りによって意図せず大量のレコードが更新される危険性があります。
そういった事故を防ぐため、カスタマイズの実行時は下記のような予防措置を取ることをおすすめします。
テスト実行機能(後述)であらかじめテストする
テスト用のアプリを作成し、テストを行う
誤って想定しないレコードが更新された場合にデータを復旧できるように、CSV への書き出しや、レコードのバックアップを行う連携サービスを使用してレコードのバックアップを取得しておく ( ※注)
更新対象とするレコードを、やること「条件を組み立ててレコードを取得する」で絞り込んでのレコード取得や、レコードを取得する「やること」のパラメータ「最大取得件数」を設定して件数を限定し、まずは少ないレコードで試してみる
※注：gusuku シリーズの 1 つである gusuku Deploit のバックアップオプションでもレコードのバックアップは可能です。
gusuku Deploit については下記の製品ページをご覧ください。
テスト実行機能について
Job Runnerにはテスト実行機能があります。この機能を使うと作成したジョブを気軽にテストする事ができ、次のような特徴があります。
実行時間を一切消費しません。何度実行しても料金はかかりません
一連のカスタマイズを実行した結果の、レコードの中身を確認することが可能です
kintoneから実際にレコードを読み込みます（APIリクエスト数を消費します）
kintoneへのレコードの追加・更新は一切行いません（APIリクエスト数を消費しません）
外部連携システムとの接続は一切行いません
詳しくは、次の記事も併せてご覧ください。
Job Runnerテスト実行の使い方
カスタマイズの実行
定期実行タスクのカスタマイズは、下記の 3 パターンで実行が可能です。
定期実行
直ちに実行
画面から呼び出して実行
今回のような、日ごとに処理を実行するカスタマイズでは「定期実行」を用いていただくのがおすすめですが、それぞれの実行方式と用途についても、ここでは併せてご説明します。
定期実行：
・毎日、毎月など決まったタイミングで繰り返し処理を実行する
定期実行のスケジュールを追加するには、「ジョブ設定」ダイアログの「設定を追加」をクリックしてください。するとスケジュールの入力欄が追加され、定期実行スケジュールの設定が行えます。
具体的な設定例ですと、例えば上記で作成頂いた年齢計算を毎日0時に実行するための、定期実行のスケジュール設定は次のようになります。
設定が終わったら、最後に右下の「設定保存」を忘れずにクリックしてください。 これで毎日、最新のその日時点の年齢が計算されることになります。
直ちに実行：
・カスタマイズ作成中のテスト(実際のレコード操作を行わないとテストできないもの)で実行する
・複数のレコードに対して行う処理を、1 回だけ Job Runner で処理を行う
例：新しく作った検索用文字列フィールドに対して、既存レコードのフィールドには Job Runner で一括で検索用文字列をセットし、その後は kintone アプリのカスタマイズでレコードが保存された際に検索用文字列の作成を行う など
画面から呼び出して実行：
・ボタンクリックなどユーザーの操作によって Job Runner の処理を呼び出す
例：ユーザーが CSV から kintone にレコードを読み込んだ後で、ボタンを押して Job Runner の処理を呼び出す など
カスタマイズの実行確認では直ちに実行を使用します。ボタンをクリックするとすぐにジョブが実行されます。
実行結果はジョブ設定画面の「実行履歴」タブに表示されます。表示されていない場合は、ジョブ設定画面左上のボタンをクリックしてください。
エラーが表示されている場合や、うまく動かないときの対処方法については、以下の記事を参考にしてください。
●エラー全般
「kintone API 呼び出しがエラーになりました。」という場合の対応方法
●kintone接続設定を中心とした観点
Job Runnerで「関連レコード一覧の条件でレコードを取得する」を使おうとしたら「関連レコード情報がありません」エラーが出るのですが、どうすればいいですか？
「ルックアップを取得しなおす」を使っているのに、ルックアップが取得できません。
●テスト実行についての観点
Jobの作成中に意図しないデータ更新を起こした場合、データを元に戻すことはできますか？
●ログ、アクショングラフについての観点
ログの見方（Job Runner）
スケジュール設定
カスタマイズが想定通り動作することを確認したら、定期実行タスクを実行したいタイミングでスケジュール設定します。
スケジュールは、下記の間隔で指定ができます。
・1 年毎
・1 ヶ月毎
・1 週間毎
・1 日毎
・1 時間毎
以上が、定期実行タスクの設定です。
定期実行タスクのカスタマイズ名は必ず指定しましょう
定期実行タスクのカスタマイズは特定の kintone アプリに紐づかないため、カスタマイズ名は既定の名称では kintone のアプリ名が含まれない「無題の定期実行タスク」になります。
もしカスタマイズ名をこのままにしておくと、ドライブ画面に表示されるカスタマイズが無題の定期実行タスクだらけになり、カスタマイズの識別ができなくなってしまいます。
このような状況を防ぐため、定期実行タスクのカスタマイズを作成したら、まずカスタマイズ名を分かりやすい名前に変更することを強くおすすめします。
カスタマイズ名をクリックすると名前の変更とコメントを記載する画面が出てきますので、こちらから変更してください。
おわりに
以上で定期実行タスクの使い方のご紹介を終わります。非常に簡単にレコードを取得して更新できることを、ご確認いただけたかと思います。
レコードの更新は簡単にできる分、思いもよらない大量のレコードを、意図しない内容で更新したりすることもできてしまうものです。実際にカスタマイズを作成される際には、テストアプリとテストデータでよくテストを行った上で、実際のアプリ・運用に適用していくことをおすすめします。
ご不明な点がございましたら、チャットでお問い合わせください。