導入ガイド
契約管理アプリのダウンロードから、最初のジョブが動くまでの手順です。すべてお客様自身の操作で完結し、弊社への申し込みや連絡は必要ありません。
事前に用意するもの
| 用意するもの | 内容 |
|---|---|
| kintone 環境 | スタンダードコース以上(JavaScript カスタマイズとプラグインを使うため)。 |
| アプリを作成できる権限 | 手順 1 で、テンプレートファイルからアプリを作成するために必要です。手順 1〜3 に、kintone システム管理者の権限は必要ありません。 |
| kintone システム管理者の権限と、対象アプリの管理権限 | 手順 4 で必要です。自動実行したいアプリを追加するときに、プラグインを kintone に読み込み、そのアプリに追加するためです。 |
| 自動実行ユーザー | 本サービスが kintone へのログインに使う専用のユーザーです。下の条件を満たすユーザーを 1 人作成してください。 |
自動実行ユーザーの条件
- 人と兼用しない専用のユーザーにする。 自分自身の操作を見分けて無限ループを防ぐために必要です。
- ログイン名とパスワードでログインできる。 2 要素認証を有効にしたユーザーと、SAML 認証でしかログインできないユーザーは使えません。
- 必要なアクセス権を持つ。 自動実行したいアプリで、カスタマイズ JavaScript が行う操作(レコードの閲覧・編集など)ができること。
- kintone の利用ユーザーとして登録されている。 kintone のライセンスを 1 ユーザー分使います。
ユーザーは cybozu.com 共通管理の「ユーザー管理」で作成します。作成後、一度そのユーザーで kintone にログインできることを確かめておくと確実です。
- IP アドレス制限: 契約管理アプリに表示される弊社の送信元 IP アドレス(固定)を、cybozu.com 共通管理で許可してください。
- セキュアアクセス: 自動実行ユーザーのクライアント証明書(.pfx)と、そのパスワードを用意してください。
- Basic 認証: Basic 認証のユーザー名とパスワードを用意してください。
手順 1: 契約管理アプリを作成する
次のリンクから、契約管理アプリのテンプレートファイル(zip)を保存します。zip は展開せず、そのまま使います。
- kintone のポータルで「アプリを作成」(アプリの「+」)を押します。
- 「テンプレートファイルを読み込んで作成」を選びます。
- ダウンロードした zip ファイルを選び、アプリを作成します。
契約管理アプリは、お試しの開始から、共通設定、ジョブを作るアプリの追加、契約、同時実行数の変更、請求書の取得、解約まで、本サービスに関する操作をまとめて行うための kintone アプリです。このアプリ自体にプラグインは必要ありません。
手順 2: 規約に同意して、お試しを開始する
- 作成した契約管理アプリを開きます。レコードの一覧や標準のツールバーは表示されず、契約の画面だけが表示されます。
- 利用規約とプライバシーポリシーを確認し、同意のチェックを入れます。
- 「お試しを開始」を押します。
無料お試しが、その場で始まります。この時点では、認証情報も支払情報も入力しません。
14 日間、同時実行数 1 件、ジョブ 5 件まで、実行 420 回まで。kintone のドメインごとに 1 回利用できます。お試し中は、1 回の実行は 5 分まで、失敗時のやり直しは行われず、ブラウザの接続先は kintone(cybozu.com)と主要なライブラリ配信元に限られます。実行が始まるまでの時間は、有料契約と変わりません。
お試しの 14 日間は、手順 3 で自動実行ユーザーの登録ができた時点から数え直します。その kintone を実際に運用しているお客様であることを、この登録で確認できるためです。
手順 3: 自動実行ユーザーを登録する
同じ契約の画面の「共通設定」で行います。共通設定は契約全体に共通で、すべてのアプリのジョブに使われます。
- 「共通設定」の「自動実行ユーザー」に、用意したユーザーのログイン名とパスワードを入力します。
- Basic 認証やセキュアアクセス(クライアント証明書)をお使いの場合は、切り替えを開いて、その情報も入力します。
- 登録します。
登録のときに、弊社のサービスが、入力されたユーザーでお客様の kintone に実際に接続できるかを確認します。自動実行ユーザーを登録するまで、ジョブは実行されません。お試しの 14 日間は、この登録ができた時点から数えます。
登録したパスワードは弊社のサービスに送られ、暗号化して保管されます。kintone には保存しません(契約管理アプリの中に保存されるのは、接続用のキーだけです)。登録後に画面へ再表示されることはありません。
自動実行ユーザーのパスワードは、お客様のカスタマイズ JavaScript を動かす実行環境には渡しません。ログインは、お客様の JavaScript を動かさない別の環境で行い、実行環境にはログイン済みの状態だけを渡します。実行結果の kintone への記録も、その別の環境で行います。Basic 認証の情報とクライアント証明書は、ブラウザが kintone に接続するために必要なので、実行環境に渡されます。
実行の結果と録画は、契約管理アプリのレコードとして保存されます。保存のために別のアプリを作成したり、設定したりする必要はありません。自動実行ユーザーは、契約管理アプリにレコードを追加できる必要があります。kintone の標準のアクセス権のままであれば、追加できます(実行の記録と失敗時の通知)。
手順 4: 自動実行したいアプリを追加する
同じ契約の画面の「ジョブ」で行います。この手順には、kintone システム管理者の権限(プラグインの読み込みに必要)と、追加するアプリの管理権限が必要です。
- カスタマイズ JavaScript を自動実行したいアプリの、アプリ ID を確かめます。アプリ ID は、そのアプリの URL の
/k/の後にある数字です。 - 「ジョブ」にアプリ ID を入力し、「追加してジョブを作成」を押します。
この操作で、次のことが自動で行われます。プラグインのファイルを別に入手して読み込む必要はありません。
- 「カスタマイズ自動実行」プラグインを kintone に読み込みます(すでにある場合は更新します)。
- 指定したアプリにプラグインを追加し、本サービスに接続します。
- そのアプリのプラグイン設定画面を開きます。ジョブはこの画面で作成します。
アプリへの反映も自動で行われます。「アプリを更新」を押す必要はありません。
複数のアプリで使う場合は、アプリごとにこの手順を行います。すでにあるジョブは契約の画面の「ジョブ」に一覧表示され、「ジョブを編集」からそのアプリのプラグイン設定画面を開けます。
自動実行ユーザーは、契約管理アプリの「共通設定」でだけ登録・変更できます。
契約管理アプリを通さずにプラグイン設定画面を直接開いた場合に、接続を求められることがあります。そのときは、登録済みの自動実行ユーザーのログイン名とパスワードを入力して「接続」を押してください。
手順 5: ジョブを作成する
「いつ」「どの画面を開くか」「何をもって完了とするか」を決めたものをジョブと呼びます。手順 4 で開いたプラグイン設定画面の「ジョブを追加」を押して作成します。
トリガー: いつ実行するか
| 種類 | 実行されるタイミング |
|---|---|
| スケジュール | 毎時・毎日・毎週・毎月の決まった時刻(日本時間)。例: 毎週 月〜金の 7:00。 |
| レコード操作(Webhook) | レコードの追加・編集・削除、ステータスの更新、コメントの書き込み。kintone 側で Webhook の登録が必要です。 |
| 手動実行のみ | 設定画面の「今すぐ実行」を押したときだけ。 |
カスタマイズ JavaScript がレコードを更新すると、その更新がまた「レコード編集」のトリガーになり、同じジョブが延々と繰り返されます。「自己起因を無視」にチェックが入っていれば、自動実行ユーザー自身の操作はトリガーになりません。
開く画面: どの画面でカスタマイズ JavaScript を動かすか
| 画面 | 使いどころ |
|---|---|
| レコード一覧 | 一覧画面のイベントで動く JavaScript。一覧(ビュー)ID を指定できます。 |
| レコード詳細 | 詳細画面のイベントで動く JavaScript。 |
| レコード編集・レコード追加 | 編集・追加画面のイベントで動く JavaScript。「表示後に保存する」にチェックすると、保存ボタンまで押します。 |
| 指定した URL | そのアプリの配下にある、上記以外の画面。 |
レコード詳細・レコード編集では、開くレコードを次のように決めます。
- レコード操作(Webhook)の場合: 操作されたレコードが自動で対象になります。指定は不要です。
- スケジュール・手動の場合: 「レコード番号」で 1 件を指定するか、「絞り込みクエリ」で条件に合うレコードを順に開きます。一度に処理する件数の上限も設定できます。
画面を開いた後の操作(必要な場合のみ)
カスタマイズ JavaScript が画面に追加したボタンを押さないと処理が始まらない場合に使います。「操作を追加」で、入力・クリック・待つ、を上から順に並べます。操作する要素は CSS セレクタで指定します。
例: 入力欄に「2026-11」と入れてから、集計ボタンを押す。
完了の条件と、失敗時の扱い
| 項目 | 内容 |
|---|---|
| 完了の判定方法 | 「JS から done() を呼ぶ(推奨)」「通信が止まったら完了」「指定した要素が現れたら完了」から選びます。 |
| タイムアウト(秒) | この時間内に完了しなければ、失敗(タイムアウト)として記録します。処理に時間がかかる場合は長めにしてください。設定できるのは 10 分までです。無料お試し中は、1 回の実行は 5 分までです。 |
| 確認ダイアログ | JavaScript が確認ダイアログを出したときに、OK とキャンセルのどちらを押すか。 |
| 失敗時のやり直し | 失敗したときに自動でやり直す回数。途中まで進んだ処理をやり直すと二重に処理されることがあるため、問題のない処理でだけ使ってください。やり直しを含めた 1 件あたりの合計は、およそ 11 分までです。タイムアウト ×(やり直しの回数 + 1)がこれを超えるジョブは、収まる回数までしかやり直しません。無料お試し中は、やり直しは行われません。 |
| 録画 | 常に保存、失敗時のみ保存、保存しない、から選びます。 |
「保存」を押すと、ジョブが一覧に追加されます。スケジュールのジョブは、保存した時点から有効です。
カスタマイズ JavaScript に完了の合図を入れる
本サービスは、JavaScript の処理が終わったことを確かめてからブラウザを閉じます。処理の最後で done() を呼ぶ 1 行を足す方法が、もっとも確実です。
kintone.events.on('app.record.detail.show', async (event) => {
// 自動実行のときだけ存在するオブジェクト。人が開いたときは undefined
const auto = window.__AUTO_EXECUTOR__;
try {
await recalculate(event.record); // いつもの処理
auto?.done(); // 処理が終わったら呼ぶ
} catch (e) {
auto?.fail(e.message); // 失敗を知らせる(履歴にこの文言が残ります)
}
return event;
});
| 使えるもの | 内容 |
|---|---|
auto.done() | 処理が正常に終わったことを知らせます。 |
auto.fail("理由") | 処理が失敗したことを知らせます。理由は履歴と通知に残ります。 |
auto.trigger | トリガーの種類です(schedule、manual、ADD_RECORD など)。 |
auto.recordId | Webhook で通知されたレコード番号です(ある場合)。 |
auto.executionId | その実行の ID です。 |
window.__AUTO_EXECUTOR__は自動実行のときにしか存在しません。if (!auto) return event;と書けば、「自動実行のときだけ動かす処理」にできます。- JavaScript を書き換えられない場合は、完了の判定方法に「通信が止まったら完了」または「指定した要素が現れたら完了」を選んでください。
Webhook を登録する(レコード操作をトリガーにする場合)
トリガーを「レコード操作(Webhook)」にしたジョブは、kintone 側にも設定が必要です。スケジュールと手動のジョブでは、この手順は不要です。
- ジョブを保存すると Webhook URL が表示されます。「URL をコピー」を押して控えます。
- 同じアプリの「アプリの設定」→「設定」タブ→「カスタマイズ/サービス連携」の「Webhook」を開き、「追加する」を押します。
- 「Webhook URL」に控えた URL を貼り付け(先頭の
https://は除きます)、「通知を送信する条件」でジョブと同じ操作にチェックを入れて、「保存」を押します。 - アプリの設定画面に戻り、「アプリを更新」を押します。これを押すまで、Webhook は有効になりません。
控え忘れた場合は、ジョブの「編集」を開いて「Webhook URL を再発行」を押してください。再発行すると、古い URL は使えなくなります。
動作を確認する
- 設定画面のジョブ一覧で、確認したいジョブの「今すぐ実行」を押します。スケジュールや Webhook のジョブも、ここから手動で試せます。
- 少し待ってから「履歴」を押します。結果が「成功」になっていれば完了です。「待機中」「実行中」の場合は、少し待ってからもう一度「履歴」を押してください。
- 「録画」の「開く」を押すと、契約管理アプリにある、その実行のレコードが開きます。録画、開いた画面の URL、JavaScript のコンソールログを確認できます。
実行は、通常は数秒で始まります。長く実行がなかった後の最初の実行や、弊社がサービスを更新した直後は、数十秒かかることがあります。
実行の記録と失敗時の通知
実行の結果は、契約管理アプリのレコードとして、実行ごとに 1 件ずつ記録されます。記録のために別のアプリを作成したり、設定したりする必要はありません。テンプレートからアプリを作成した時点で使えます。
- 記録される内容: 結果(成功・失敗)、録画、開いた画面の URL、コンソールログ、失敗時のスクリーンショット、エラーの内容。
- 契約の画面の「実行ログ」に、直近 50 件の実行が表示されます。各行の「録画とログ」を押すと、その実行のレコードが開きます。
- 表の下の「すべての実行履歴を見る」を押すと、契約管理アプリの「実行履歴」の一覧が開き、すべての実行を確認できます。「← 契約管理に戻る」を押すと、契約の画面に戻ります。
- 自動実行ユーザーが、契約管理アプリにレコードを追加できる必要があります。kintone の標準のアクセス権のままであれば、追加できます。アプリのアクセス権を絞る場合は、自動実行ユーザーのレコード追加の権限を残してください。
- 実行履歴を見る人には、契約管理アプリを開ける権限が必要です。契約や設定を変更するボタンを使えるのは、契約管理アプリの管理権限があるユーザーだけです(契約を操作できる人を管理する)。
- 録画ファイルは kintone のディスク容量を使います。容量が気になる場合は、ジョブの録画の設定を「失敗時のみ保存」にしてください。
失敗したときに通知を受け取るには
「お試しを開始」を押すと、実行が失敗またはタイムアウトしたときに、押した人へ kintone の通知が届くように、契約管理アプリが自動で設定されます。通知先は、契約管理アプリの「レコードの条件通知」で変更できます。
kintone は、操作した本人には通知を送りません。契約管理アプリにレコードを追加するのは自動実行ユーザーのため、通知先が自動実行ユーザー自身になっていると通知が届きません。
契約管理アプリでできること
本サービスに関する確認と手続きは、すべて契約管理アプリの契約の画面で行います。契約の画面には、「ご契約」「利用分析」「実行ログ」「ジョブ」「共通設定」のタブがあります。
| できること | 内容 |
|---|---|
| 契約状況の確認 | お試し中か有料契約中か、期間、同時実行数。 |
| ジョブの一覧 | すべてのアプリのジョブを一覧表示。「ジョブを編集」から、そのアプリのプラグイン設定画面を開けます。アプリ ID を入力して「追加してジョブを作成」を押すと、新しいアプリを追加できます。 |
| 共通設定 | 自動実行ユーザーの登録・変更。弊社の固定の送信元 IP アドレスの確認。 |
| 利用分析の確認 | 「利用分析」タブで、いま実行中の件数、待ち時間(平均・95 パーセンタイル・最大)、時間帯ごとの稼働率(曜日 × 時)、順番待ちの最大件数、「同時実行数を変えた場合の待ち時間」の試算と、アドバイス(「同時実行数の追加をおすすめします」「現在の同時実行数で足りています」「同時実行数に余裕があります」のいずれか)。 |
| 実行ログの確認 | 直近 50 件の実行について、待ち時間、所要時間、「録画とログ」(その実行のレコードを開くリンク)。「すべての実行履歴を見る」から、すべての実行の一覧を開けます。 |
| 有料契約の手続き | クレジットカード払い、または請求書払い(銀行振込)。有料契約の申込には、自動実行ユーザーが登録されている必要があります。未登録の場合は、契約管理アプリが「共通設定」での登録を求めます。申込のときに、利用規約と特定商取引法に基づく表記への同意のチェックを入れます。 |
| 同時実行数の変更 | 同時実行数を増やす・減らす(最大 20 件)。ご契約後いつでも変更できます。変更はすぐに反映され、料金の差額は日割りで次回の請求に含まれます。 |
| 請求書の取得 | 「請求書」で、適格請求書(PDF)のダウンロードと、請求書払いの振込先口座の確認。 |
| 解約 | 解約の手続きと、その取り消し。請求期間の末日まで利用でき、その日より前なら取り消せます。解約後も設定とジョブは残り、いつでも契約し直せます。 |
契約を操作できる人を管理する
共通設定の変更、契約、同時実行数の変更、解約など、契約の画面で契約や設定を変更するボタンを使えるのは、契約管理アプリの管理権限(アプリ管理権限)があるユーザーだけです。それ以外のユーザーは、内容の確認だけができます。これは誤操作を防ぐための画面上の制限です。契約管理アプリを開けるユーザーは、アプリの中に保存されている接続用のキーを読めるため、変更を確実に防ぎたい場合は、契約の画面の「権限管理」から契約管理アプリのアクセス権の設定を開き、アプリを開けるユーザーを絞ってください。
契約管理アプリの中には、弊社のサービスに接続するためのキーが保存されています。アプリを開ける人が退職や異動で権限を失ったときは、アクセス権を外したうえで、「接続情報」の「キーを作り直す」を押してください。それ以前に控えられていたキーは使えなくなります。
弊社のサービスの API は、kintone(cybozu.com)が中継した要求だけを受け付けます。kintone の外から直接呼び出すことはできません。
料金の詳細は料金のページをご覧ください。
うまくいかないとき
導入のとき
| 起きていること | 考えられる原因と対処 |
|---|---|
| 「テンプレートファイルを読み込んで作成」ができない | 操作しているユーザーに、kintone でアプリを作成する権限があるか確認してください。 |
| 「お試しを開始」を押すと、自動実行ユーザーのログイン名とパスワードを求められる | その kintone では、すでに自動実行ユーザーが登録されています(契約管理アプリを削除して作り直した場合など)。登録済みの自動実行ユーザーのログイン名とパスワードを入力すると、これまでの契約につなぎ直せます。 |
| 自動実行ユーザーの登録で、確認に失敗する | ログイン名とパスワードが正しいか、そのユーザーが 2 要素認証や SAML 認証専用になっていないか、IP アドレス制限で弊社の送信元 IP アドレスが許可されているかを確認してください。Basic 認証やセキュアアクセスをお使いの場合は、その情報の入力も確認してください。 |
| 「追加してジョブを作成」が失敗する | 操作しているユーザーに、kintone システム管理者の権限と、追加するアプリの管理権限があるか確認してください。アプリ ID(アプリの URL の /k/ の後の数字)が正しいかも確認してください。 |
| プラグイン設定画面で接続を求められる | 契約管理アプリを通さずに直接開いた場合です。登録済みの自動実行ユーザーのログイン名とパスワードを入力して「接続」を押してください。 |
| ジョブを作ったのに実行されない | 自動実行ユーザーを登録するまで、ジョブは実行されません。契約管理アプリの「共通設定」を確認してください。 |
| 有料契約の申込に進めない | 有料契約の申込には、自動実行ユーザーが登録されている必要があります。未登録の場合は、契約管理アプリが「共通設定」での登録を求めます。 |
| お試しを開始できない(すでに利用済み) | 無料お試しは kintone のドメインごとに 1 回です。続けて使う場合は、契約管理アプリから有料契約の手続きをしてください。 |
実行が失敗するとき
契約管理アプリの「実行ログ」の「録画とログ」からその実行のレコードを開き、「エラー」の内容と録画を確認してください。
| エラーの内容 | 考えられる原因と対処 |
|---|---|
| 完了しなかった(タイムアウト) | done() が呼ばれていない、または処理が時間内に終わっていません。録画で画面の様子を確かめ、JavaScript の修正か、タイムアウトの延長を行ってください。無料お試し中は、1 回の実行は 5 分までです。 |
| 無料お試し中に、外部への通信が失敗する | 無料お試し中は、ブラウザの接続先が kintone(cybozu.com)と主要なライブラリ配信元に限られます。カスタマイズ JavaScript がそれ以外の接続先と通信する場合、お試し中はその通信ができません。 |
| ログインできなかった | 自動実行ユーザーのパスワードが変わった、ユーザーが停止された、IP アドレス制限で弊社の IP アドレスが許可されていない、などです。契約管理アプリの「共通設定」で、自動実行ユーザーを登録し直してください。 |
| JavaScript が失敗を知らせた | fail("理由") で渡した理由が表示されます。コンソールログもあわせて確認してください。 |
| 操作に失敗した | 「画面を開いた後の操作」で指定した要素が見つかりません。CSS セレクタと、開いている一覧(ビュー)を確認してください。 |
| 上限に達した・期間が終了した | 無料お試しの実行回数(420 回)や期間(14 日間)を過ぎています。この場合、実行は行われず、画面を開かずに失敗として記録されます。料金が自動で請求されることはありません。続けて使う場合は、契約管理アプリから有料契約の手続きをしてください。 |
そのほか
| 起きていること | 考えられる原因と対処 |
|---|---|
| 実行がなかなか始まらない | 長く実行がなかった後の最初の実行や、弊社がサービスを更新した直後は、開始まで数十秒かかることがあります。待ちが続く場合は、ご契約の同時実行数がほかの実行で埋まっています。契約管理アプリの「利用分析」を確認してください。 |
| 有料契約中なのに実行されなくなった | 支払期日を過ぎた未払いの請求書がある場合、またはクレジットカードの決済ができず契約が未払い・解約の状態になった場合、実行は停止します。契約管理アプリで契約状況と「請求書」を確認してください。設定とジョブは残っており、支払いまたは再契約の後に再開されます。 |
| レコードを操作してもジョブが動かない | kintone 側の Webhook の登録と「アプリを更新」が済んでいるか、通知を送信する条件がジョブと合っているかを確認してください。ファイルからの読み込みなど、Webhook が送られない操作もあります(ご利用上の注意)。自動実行ユーザー自身の操作は、「自己起因を無視」によりトリガーになりません。 |
| 失敗の通知が届かない | 通知先が自動実行ユーザー自身になっていないか、契約管理アプリの「レコードの条件通知」を確認してください。 |
| 同じジョブが繰り返し実行される | 「自己起因を無視」のチェックが外れていないか、自動実行ユーザーを人と兼用していないかを確認してください。 |
ご利用上の注意
| 項目 | 内容 |
|---|---|
| Webhook が届かない操作 | kintone の仕様により、ファイルからの読み込み、一括削除、REST API での複数レコードの一括追加・削除では通知が送られず、ジョブは動きません。 |
| 実行の順序 | 同じジョブの実行は、依頼された順に 1 件ずつ行います。処理が長いジョブに依頼が集中すると、後の実行は待たされます。 |
| 使えないユーザー | 2 要素認証を有効にしたユーザー、SAML 認証でしかログインできないユーザーは、自動実行ユーザーにできません。 |
| kintone の画面変更 | kintone のアップデートでログイン画面や保存ボタンの作りが変わると、一時的に実行できなくなることがあります。その場合は弊社側で対応します。 |
| 記録の保存期間 | 弊社側では録画を 30 日間、実行履歴を 90 日間保存します。長く残したい記録は、契約管理アプリに保存された実行のレコードをご利用ください。お客様の kintone のレコードは、お客様が削除するまで残ります。 |
| カスタマイズ JavaScript の内容 | 自動実行されるカスタマイズ JavaScript の内容と、その実行結果は、お客様の責任で管理してください(利用規約)。 |
そのほかの疑問はよくある質問をご覧ください。