Sansan for kintone

2019年10月以降は本プラグインはご利用頂けません。

 Sansan API アップデートに伴う改修について

本記事で紹介しているプラグインは Sansan API ver1.1 を利用しています。
Sansan API ver1.x は2019年9月30日に廃止予定です。
cybozu developer network では、今回の廃止において ver2.x への改修はしません。

そのため、2019年10月以降は本プラグインはご利用頂けません。
ご不便、ご迷惑をおかけし大変申し訳ございませんが、ご理解のほどよろしくお願いいたします。

また、TiS 様よりSansan API ver2.x の対応をしている kintone 連携プラグインが無償公開されていますので、そちらも合わせてご確認ください。

Sansan名刺連携プラグイン

• 人物編
  https://www.tis2010.jp/sansanperson/
• 会社編
  https://www.tis2010.jp/sansancompany/
• 所有者編
  https://www.tis2010.jp/sansanowner/

Index

• 概要
• フォームを設定する
• アプリにプラグインを追加する
• プラグインを設定する
• ルックアップ機能[レコード追加/編集画面]
• レコード一括登録機能[レコード一覧画面]
• レコード一括登録時のUpsert機能[レコード一覧画面]
• サンプルプラグイン
• 制限事項
• 注意事項

概要

Sansan, Inc.の提供する名刺管理サービス「Sansan」を利用している方向けのプラグインです。Sansanの詳細はこちら

アプリに Sansan for kintone プラグインを追加すれば、 Sansan で管理している顧客情報を参照し、コピーすることができます。
アプリの指定したフィールドの値をキーワードに検索を行い、検索条件に一致したデータがルックアップにより表示されます。
※本プラグインは、アプリストアの「顧客リスト」に適用することを想定しています。

検索対象には、Sansan の次の情報を指定できます。

• 会社名
• 氏名
• メールアドレス
• 電話番号
• 携帯番号

▼主要なアップデート情報
2016/07/19： 複数の名刺データを一括登録できるようになりました。
2016/08/18： レコード一覧画面で Sansan に検索する対象をドロップダウンで選択する機能が追加されました。
2016/09/16：「名刺交換日」、「郵便番号」、「Fax」をコピー先フィールドとして指定できるようになりました。
2017/03/13：レコード一括登録時のUpsert機能[レコード一覧画面]が追加されました。その他追加機能は「更新履歴」を参照ください。

Sansan for kintone を利用する

STEP1:フォームを設定する

アプリのフォームを設定します。次のフィールド、スペースを配置します。

• 検索キーワードにするフィールド
  Sansan の検索キーワードとして使用するフィールドを配置します。次の種類のフィールドを使用できます。
• 文字列（1行）フィールド
• リンクフィールド
• コピー先フィールド
  Sansan より取得した戻り値をコピーするフィールドを配置します。次の種類のフィールドを使用できます。
• 文字列（1行）フィールド
• リンクフィールド
• 検索ボタンを配置するフィールド（※ルックアップ機能を利用する場合）
  検索ボタンを表示する場所に、「スペース」フィールドを配置します。
  また、配置したフィールドには、任意の「要素ID」を指定する必要があります。

フィールド配置例

ほかのフィールドの配置は任意です。

「検索キーワードにする」フィールドの右側に「スペース」フィールドを横長に配置することで、標準機能のルックアップのように使用できます。

STEP2:アプリにプラグインを追加する

アプリにSansan for kintoneプラグインを追加します。プラグインの追加方法は、kintone ヘルプを参照してください。
プラグインを追加する

STEP3:プラグインを設定する

1. アプリ管理画面の「詳細設定」＞「プラグイン」を開き、Sansan for kintone プラグインの歯車マークをクリックします。
2. 各項目を設定します。（※はアップデートにより追加された項目です。 ）
   

   項目名	説明
   Sansan API Key	Sansan の管理画面で発行した、API Keyを入力するフィールド。(必須項目)
   使用する機能※	本プラグインで使用する機能のON/OFFを切り替えることができる。 ルックアップ機能[レコード追加/編集画面] レコード一括登録機能[レコード一覧画面]※ レコード一括登録時のUpsert機能[レコード一覧画面]※
   ルックアップ機能設定項目： 検索ボタン配置スペース	ここで指定した「スペース」フィールドに、「取得」「クリア」「期間」の枠なしボタンを配置する。 ※フィールドコードの設定がない「スペース」フィールドに関しては表示しない。
   ルックアップ機能設定項目： 検索キーフィールド	このフィールドに入力した文字を元に Sansan のデータを検索する。 次のフィールドタイプのフィールドを選択肢に出し設定できる。 文字列(1行) リンク(メールアドレス) リンク(電話番号)
   ルックアップ機能設定項目： コピー元のSansanフィールド	kintone側の検索フィールドの値に、このSansanフィールドが該当した場合、検索結果を返す。 次のフィールドをドロップダウンで設定できる。 会社名 氏名 メールアドレス 電話番号 携帯番号
   Upsert機能設定項目： Upsert用キーフィールド※	Upsert機能で使用するキーフィールドを選択します。重複禁止が設定された文字列一行フィールドのみ選択可。「人物ID」での利用を想定。
   コピー先フィールド※	Sansanの戻り値をコピーするフィールドを予め設定する。 以下のフィールドをドロップダウンで設定できる。太字はアップデートによる追加項目 名刺ID：文字列(1行) 会社ID：文字列(1行) 人物ID：文字列(1行) 名刺交換日：文字列(1行) or 日付 or 日時 名刺登録日時：文字列(1行) or 日付 or 日時 名刺所有者ID：文字列(1行) 名刺所有者名：文字列(1行) 氏名：文字列(1行) 氏名カナ：文字列(1行) 部署名：文字列(1行) 役職名：文字列(1行) E-mail：文字列(1行)or リンク(メールアドレス) 携帯:文字列(1行)or リンク(電話番号) 会社名：文字列(1行) 郵便番号：文字列(1行) 住所：文字列(1行) TEL：文字列(1行)or リンク(電話番号) TEL2：文字列(1行)or リンク(電話番号) Fax：文字列(1行)or リンク(電話番号) メモ：文字列(1行)or 文字列(複数行) URL：文字列(1行)or リンク(Webサイトのアドレス)

   
   プラグイン設定画面
   
3. [保存]をクリックします。
4. 「アプリの設定」画面で[設定完了]をクリックすると、プラグインの設定がアプリに反映されます。

STEP4:プラグインを利用する

ルックアップ機能[レコード追加/編集画面]

レコードの追加/編集画面でSTEP3に設定されたスペースに「取得/クリア/期間」ボタンが作成されます。

• 「取得」ボタンをクリックした場合
• 設定画面で設定した、「検索キーフィールド」「コピー元のSansanフィールド」を元に、Sansanに検索リクエストを送信します。
• 検索結果の戻り値をウィンドウに表示します。
• 各列左端に「選択」ボタンを表示されます。「選択」ボタンをクリックすると設定画面で設定した通り、Sansanから取得した結果がkintoneのレコードにコピーされます。
• 「クリア」ボタンをクリックした場合
• kintone上のコピー先にコピーしてある値をクリアします。
• 「期間」ボタンをクリックした場合
  • 「名刺登録日」か「名刺更新日」の期間でSansanに検索リクエストを送信します。※2017/03/13 アップデート追加機能
  • 開始日付と終了日付を入力するウィンドウを表示します。
  • 「OK」ボタンをクリックすると、設定された期間を元にSansanに検索リクエストを送信します。
  • 検索結果の戻り値をウィンドウに表示します。
  • 各列左端に「選択」ボタンを表示されます。「選択」ボタンをクリックすると設定画面で設定した通り、Sansanから取得した結果がkintoneのレコードにコピーされます。

レコードの追加/編集画面

「取得」ボタンクリック時の画面

「期間」ボタンクリック時の画面

レコード一括登録機能[レコード一覧画面] ※2016/07/19 アップデート追加機能

レコードの一覧画面でヘッダー部分に検索項目を選択するドロップダウン、一括登録用の検索フォーム、虫眼鏡マークのボタン、タグマークのボタンが表示されます。

• ドロップダウン ※2016/08/18 アップデート追加機能
  • Sansan のデータに検索をかける際の検索キーを選択します。
• 検索フォーム
  
  • この検索フォームに入力した文字を元に Sansan のデータを検索します。
• 虫眼鏡マークのボタンをクリックした場合
• 「ドロップダウンの値」と「検索フォームの値」を元に、Sansanに検索リクエストを送信します。
• 検索結果の戻り値をウィンドウに表示します。
• 各列左端にチェックボックスが表示されます。登録したい名刺データにチェックを入れて「登録」ボタンを押すと設定画面で設定した通り、Sansanから取得した結果がkintoneのレコードに一括登録されます。
• タグマークのボタンをクリックした場合
• Sansan より「共有タグ」のみを取得し、一覧を表示します。表示順は昇順となります。
• 「選択」ボタンをクリックすると選択したタグの名刺データの一覧を表示します。
  このとき「検索フォーム」に値が入力されていた場合、「ドロップダウンの値」を元に絞り込むことができます。
• 各列左端にチェックボックスが表示されます。登録したい名刺データにチェックを入れて「登録」ボタンを押すと設定画面で設定した通り、Sansanから取得した結果がkintoneのレコードに一括登録されます。
• カレンダーマークのボタンをクリックした場合
  • 「名刺登録日」か「名刺更新日」の期間でSansanに検索リクエストを送信します。※2017/03/13 アップデート追加機能
  • 開始日付と終了日付を入力するウィンドウを表示します。
  • 「OK」ボタンをクリックすると、設定された期間を元にSansanに検索リクエストを送信します。
  • 検索結果の戻り値をウィンドウに表示します。
  • 各列左端にチェックボックスが表示されます。登録したい名刺データにチェックを入れて「登録」ボタンを押すと設定画面で設定した通り、Sansanから取得した結果がkintoneのレコードに一括登録されます。

レコードの一覧画面

虫眼鏡マークのボタンクリック時の画面

登録ボタンクリック時の画面

タグマークのボタンクリック時の画面

「選択」ボタンクリック以降は「虫眼鏡マークのボタンクリック時の画面」と「登録ボタンクリック時の画面」と同様です。

レコード一括登録時のUpsert機能[レコード一覧画面] ※2017/03/13 アップデート追加機能

• レコード一括登録時に取得項目に「人物ID」項目がセットされており、かつ対象フィールドに重複禁止の設定がされている場合にUpsert機能を利用することができます。
• Upsert成功時に登録件数と更新件数がアラートで表示されます。

レコード一括登録前の画面

Upsert成功時の画面

サンプルプラグイン

GitHubにアクセスしてフォルダごとダウンロードしてください。そのフォルダ内の「examples/sansan」に、今回のファイル群があります。
「sansan」 配下のファイル構成及び使用ライブラリは次のとおりです。

sansan/ 
 css/
  -51-modern-default.css
  -config.css
  -desktop.css
 html/ 
  -config.html
 image/
  -icon.png
 js/
  -common.js
  -config.js
  -desktop_lookup.js
  -desktop_postRecords.js
  -kintoneUtility.min.js
manifest.json

Cybozu CDNより以下のライブラリを使用しています。

• jQuery
• jQuery UI
• Moment.js
• SweetAlert
• Spin.js
• JSRender
• Font Awesome

こちらの手順を参考にパッケージングします。

パッケージングしたサンプル

sansan_plugin_v3.0.2.zip

更新履歴

2016/02/15 v1.0 を公開しました
2016/02/22 v1.0.1 を公開しました: 名刺交換日がなしのデータが最新のデータと扱われる不具合を修正しました。
2016/07/19 v2.0 を公開しました:
以下の機能追加及び修正を行いました。

• レコード一覧画面で Sansan データの参照が可能になりました。
• レコード一覧画面でタグ検索機能が追加されました。
• レコード一覧画面で複数の名刺データの取り込み機能が追加されました。
• ルックアップ機能とレコード一括登録機能のON/OFF機能が追加されました。
• 「人物ID」と「URL」のコピー先フィールドとして指定できるようになりました。
• その他軽微な修正を行いました。

2016/08/18 v2.0.1 を公開しました:
以下の機能追加及び修正を行いました。

• レコード一覧画面で Sansan に検索する項目をドロップダウンで選択する機能が追加されました。
• タグ検索でスピナーが表示されない不具合を修正しました。
• その他軽微な修正を行いました。

2016/09/16 v2.0.2 を公開しました:
以下の機能追加及び修正を行いました。

• 「名刺交換日」、「郵便番号」、「Fax」をコピー先フィールドとして指定できるようになりました。
• その他軽微な修正を行いました。

2017/03/13 v3.0.0 を公開しました:
以下の機能追加及び修正を行いました。

• 人物IDをキーとしたレコード一括登録時のUpsert機能[レコード一覧画面]が追加されました。
• 「名刺ID」、「会社ID」、「名刺登録日時」、「名刺所有者のユーザID」、「氏名カナ（姓カナ＋名カナ）」、「電話番号２」、「メモ」をコピー先フィールドとして指定できるようになりました。
• レコード一覧画面で「期間指定」による検索ができるようになりました。
• ダイアログに全件チェック用のチェックボックスを追加しました。
• 「期間指定」検索ダイアログで「名刺更新日付」が選択できるようになりました。
• その他Sansan APIのアップデートに伴い軽微な修正を行いました。

2017/07/21 v3.0.1 を公開しました:
以下の機能追加及び修正を行いました。

• cssの名前を「51-current-default.css」⇒「51-modern-default.css」に修正。
• プラグインにhomepageを追加。
• その他軽微な修正。

2017/10/04 v3.0.2 を公開しました:

• プログラムで使用しているフォーム設計情報取得APIを、フィールドの一覧を取得するAPIに置き換えました。

制限事項

• Internet Explorer 8では本プラグインはご利用いただけません。
• スマートフォンでは、使用することができません。
• Sansan からのデータ取得は5000件が上限となります。
• 検索結果が重複した場合、Emailが重複したデータのみ重複が削除されます。重複削除対象は名刺交換日が古いものとなります。
• Sansan APIの仕様により、リクエスト数が100回/5分を超えるとエラーとなります。エラーが表示された場合、5分以上時間を置いてから再度取得を行ってください。
• Sansan APIの仕様により、Sansan への検索仕様は以下となります。
  • 会社名：部分一致
  • 氏名：前方一致
  • メールアドレス：完全一致
  • 電話番号：部分一致
  • 携帯番号：部分一致
• Sansanから取得可能な名刺設定は下記の名刺となります。
  名刺のステータス：データ入力が完了した名刺(completed)
  名刺の公開設定：[公開]状態の名刺
• 会社名、氏名、メールアドレス全てが空文字の名刺は取得できません。
• 取得した名刺のメールアドレスが重複した場合及びUpsert機能利用時に人物IDが重複した場合は、名刺交換日が最新の名刺のみ検索結果に表示されます。
• レコード一括登録及び一括登録時のUpsert機能により一度に登録、更新できる件数は1000件までとなります。
• タグ検索で使用できるタグは「共有タグ」のみとなります。
• 選択したタグの名刺情報がない場合はエラーが表示されます。

注意事項

• サンプルプラグインは、その動作を保証するものではありません。
• サンプルプラグインの技術的なサポート等は行っていません。
• 本プラグイン内では、一部の処理にDOM操作を含んでいます。アップデートの影響をうける可能性がある実装となっており、参考にする際はご注意ください。
• 本プラグインは新デザインを想定して作成しております。旧デザインでは動作不良を起こす可能性がありますのでご注意ください。
• 本プラグインをv2.0.2以前のプラグインからアップデートする際はプラグインの設定画面より設定を再保存する必要があります。
• 設定画面で保存する際、エラーが出る場合は[コピー先フィールド]内の項目を初期値から変更いただくことで対応いただけます。

※kintoneプラグインはスタンダードコースでのみご利用いただけます。ライトコースではご利用いただけませんのでご注意ください。