kintone x Sansan連携事始め～カスタマイズまで

> kintone x Sansan
連携事始め～カスタマイズまで
2016.05.27
名刺管理サービスSansanのプラグインを使って
顧客管理業務を劇的改善

Copyright © 2015 Sansan, Inc. All rights reserved.
> 本日のアジェンダ
1
1. 自己紹介・会社紹介
2. Sansan の概要説明
3. 製品連携とSansan APIの紹介
4. 本日のハンズオン内容

> １．自己紹介・会社紹介

> 自己紹介 (1/2)
3
Sansan株式会社
Sansan事業部開発部
外部サービスとの連携担当
清水裕紀シミズユウキ
キャリアサマリ：SIerでCRMパッケージの導入部隊 → Sansan
得意な技術分野：C#
趣味：ビール,日本酒 , バンド活動

> 自己紹介 (2/2)
4
Sansan株式会社
Sansan事業部開発部
Sansanスマートフォン版担当
伊藤勝城イトウカツキ
キャリアサマリ：独立系SIer → Sansan
得意な技術分野：.NET
趣味：飲酒と運動

> 会社紹介
5
社名 Sansan株式会社
所在地渋谷区青学の前（最寄り駅は表参道）
設立年 2007年6月
従業員数 260人ぐらい
主な事業名刺管理クラウドサービスの企
画・開発・販売

> ２．Sansan の概要説明

Sansanの２つのサービス
法人向け
個人向け
名刺を企業の資産に変える
7

> Sansanの仕組み
8
①名刺をスキャン ③OCR処理＆オペレーター入力
OCRとオペレーターによる多重入力
④データベース化
• テキストデータ
• 画像データ
⑤アプリケーションで活用
名刺の検索・閲覧・編集
②データ送信
インターネット
お客様
入力
サービス
クラウド
サービス
Database

> 最も選ばれる名刺管理サービス
76%
キヤノンエスキース
システム株式会社
11%
その他
13%
（シード・プランニング調査）

> ３．Sansan API の紹介

> 名刺のこれまでとこれから
11
？
名刺が紙だけで
管理される世界
名刺が
データ化される世界
名刺データを自由に
活用できる世界
誰も
想像できていない
管理が煩雑で
その後情報が
活用されない
検索・共有等
が可能になり
便利さを体感
現在
API公開へ

> シナジーのあるサービス
12
Sansan上にある名刺を元にした人脈データをAPI経由で
「必要な時に」「必要な粒度で」取り出すことができます。
GPS
サービスIP電話
配送
サービス
CRM
SFA
BIMA

> 連携事例①
13
名刺管理 X オンディマンド印刷・配送サービス

> 連携事例②
14
名刺管理 X WEBデータベース
SFAパック日報営業活動セミナー名簿見積書案件管理
顧客リスト顧客リストを起点にさまざまな
アプリにデータを活用できます
名刺から取り込み

> ver1.0で提供されているAPI
15
①名刺Set取得API（期間指定）
Sansanに存在する名刺のSetを期間指定で取得する
②名刺Set取得API（条件指定）
Sansanに存在する名刺のSetを条件指定で取得する
③人物取得API
特定の人物の最新情報を取得する
④タグSet取得API
Sansanに存在するタグのSetを取得する

> レスポンスオブジェクト
16
名刺ID
人物ID
名刺交換日
名刺登録日
[ 所有者オブジェクト ]
会社名
郵便番号
都道府県
市区町村
番地
ビル名
TEL
FAX
URL
姓
名
姓カナ
名カナ
部署
役職
email
mobile
[ 名刺オブジェクト ]
＜名刺プロパティ＞＜人物情報＞＜会社情報＞

> Sansan API における認証
17
Sansan APIの認証は、Sansan上で個別のユーザーが発行したAPI Keyを
HTTPヘッダーに付与してアクセスする、いわゆる API Key認証です。
Sansanの画面上で
各々のユーザが発行
プラグイン設定画面にAPI Keyを
入力することで、HTTPヘッダーに
同情報が付与される

> ４．本日のハンズオン内容

> ハンズオンのステップ
4-1. 前準備：アプリとプラグインの用意
4-2. その１：既存プラグインのUIカスタマイズ
4-3. その２：別のSansan APIを使ったカスタマイズ
※まずは「その１」まで。余裕のある方は「その２」もやってみよう

> ハンズオンで使用するソース
4-1. 前準備：アプリとプラグインの用意
4-2. その１：既存プラグインのUIカスタマイズ
https://github.com/ikatsuki/plugin-sdk/pull/4
4-3. その２：別のSansan APIを使ったカスタマイズ

> ４-1．ハンズオン前準備
～アプリとプラグインの用意～

> Sansan for kintone プラグイン
- cybozu.com developer network からサンプルプラグイン（zip）を
ダウンロード可能
- Github にサンプルプラグインのソースがある
https://cybozudev.zendesk.com/hc/ja/articles/207420183-Sansan-for-kintone
https://github.com/kintone/plugin-sdk

> プラグインのカスタマイズ
1. Cloud９で Github からプラグインのソースをダウンロードする
2. ソースを変更する
3. パッケージングし、ダウンロードする
4. kintone にプラグインを読み込む
5. kintone アプリでプラグインを使用できるように設定する
6. 動作確認

> Cloud9 に新規プロジェクトを作成する

> プラグインをダウンロードする
- GitHub からプラグインのソースを取得するため、コンソールで以下
のコマンドを実行する
$ git clone https://github.com/kintone/plugin-sdk.git
- plugin-sdk がダウンロードされていることを確認する
plugin-sdk/examples/sansan がプラグインのソース

> パッケージング
- ダウンロードしたソースをプラグインとして使用するためには、パッ
ケージングする必要がある
- パッケージング
$ sh plugin-sdk/package.sh plugin-sdk/examples/sansan/
※ workspace 直下で行う場合
生成されたプラグインの ID（PluginID）が出力される
- プラグインダウンロード
plugin-sdk/plugins/{PluginId}/plugin.zip がプラグインファイル

> kintoneシステム管理

> プラグインの設定画面を開く

> プラグインを読み込む

※まず、kintone アプリを用意する
6. 動作確認

> kintoneに「顧客リスト」アプリを追加

> アプリストアから「顧客リスト」アプリを探す

> 「営業・セールス」を選択

> 「顧客リスト」アプリを選択

> 「顧客リスト」アプリの設定を開く

> フォームの編集

> Sansan プラグイン用のスペースを用意する

> 要素IDを「Sansan」にする

> 「詳細設定」＞「プラグイン」をクリック

> 先ほど読み込んだプラグインを追加する

> プラグインの設定を行う

> 各項目を設定する
- API Key
- 6f1354d392c34c87b72eb4920effa8a8
-検索ボタン配置スペース
- Sansan
- 検索キーフィールド
- 会社名
- コピー元のSansanフィールド
- 会社名
- コピー先フィールド
- 会社名 → 会社名
- 氏名 → 担当者名
- 部署名 → 部署名
- 住所 → 住所
- Email → メールアドレス
- Tel → TEL（数字のみ）

> Sansan のデータが取得できることを確認する

> ４-2．ハンズオンその１
～既存プラグインのUIカスタマイズ～

> その１：改修後のUI
Sansanでの検索結果を
複数選択→アプリ登録
できるようにしよう

※カスタマイズ用のソースを用意する
6. 動作確認

> カスタマイズ用のソースを準備する
- workspace 直下にソースをコピーする
$ cp -r plugin-sdk/examples/sansan sansan-customize
- sansan-customize 内のファイルを編集し、プラグインをカスタマイ
ズする

> 複数レコードを選択できるようにする (1/4)
desktop.js - createLookupListView 関数
選択ボタンからチェックボックスへ変更する
//1列目：選択ボタン
'<td class="lookup-cell-kintone">' +
'<span><button class="button-simple-custom sansan-lookup-select" type="button">' +
'選択</button></span>' + '</td>' +
//1列目：チェックボックス
'<span><input class="button-simple-custom sansan-lookup-select" type="checkbox" />' +
'</span></td>' +

desktop.js - C_COPYFIELD 変数
フィールド名が格納されている配列の定義を変更する（処理しやすくするため）
var C_COPYFIELD = [
CONFIG['copy_owner'],//名刺所有者名 → owner
CONFIG['copy_companyname'],//会社名 → companyName
CONFIG['copy_username'],//氏名 → lastName + firstName
CONFIG['copy_departmentname'],//部署名 → departmentName
CONFIG['copy_title'],//役職 → title
CONFIG['copy_address'],//住所 → prefecture + city + street + building
CONFIG['copy_email'],//E-mail → email
CONFIG['copy_tel'],//Tel → tel
CONFIG['copy_mobile']//携帯 → mobile
];
var C_COPYFIELD = {
owner: CONFIG['copy_owner'],//名刺所有者名 → owner
companyname: CONFIG['copy_companyname'],//会社名 → companyName
username: CONFIG['copy_username'],//氏名 → lastName + firstName
departmentname: CONFIG['copy_departmentname'],//部署名 → departmentName
title: CONFIG['copy_title'],//役職 → title
address: CONFIG['copy_address'],//住所 → prefecture + city + street + building
email: CONFIG['copy_email'],//E-mail → email
tel: CONFIG['copy_tel'],//Tel → tel
mobile: CONFIG['copy_mobile']//携帯 → mobile
};

desktop.js - showLookupDialog 関数内の dialog のプロパティをセットしている部分
モーダルに登録ボタンを追加する
buttons: {
'登録': function() {
// 選択されたデータを抽出する
var records = [];
$('.sansan-lookup-select:checked').each(function(i, el){
var params = Sansanlookup.getElementParams($(el).parents(".sansan-lookup-tr"));
var record = kintone.app.record.get();
for (var key in params) {
if(C_COPYFIELD[key] !== 'null'){
record['record'][C_COPYFIELD[key]]['value'] = params[key];
}
}
records.push(record['record']);
});
// Sansan データ登録
kintone.api('/k/v1/records', 'POST', {app: kintone.app.getId(), records: records}).then(function(resp) {
alert('登録が完了しました。');
},
function(error) {
// エラーの場合はメッセージを表示する
var errmsg = 'レコード取得時にエラーが発生しました。';
// レスポンスにエラーメッセージが含まれる場合はメッセージを表示する
if (error.message !== undefined) {
errmsg += '¥n' + error.message;
}
alert(errmsg);
});
$(this).dialog('close');
},
Cancel: function() {
}
}

desktop.js – showLookupDialog関数
選択ボタンのクリックイベントを削除する
$(".sansan-lookup-select").click(function() {
Sansanlookup.copyFieldParams(Sansanlookup.getElementParams($(this).parents(".sansan-lookup-
tr")));
});

> パッケージング
- パッケージング
$ sh plugin-sdk/package.sh sansan-customize/ plugin-
sdk/keys/{前回のパッケージングで作成された秘密鍵ファイル名}
※最初にパッケージングした際に作成された秘密鍵ファイル（keysフォルダ直下に作成されてい
る）を引数に指定することにより、プラグインを読み込んだ時点でアプリに反映される
- プラグインダウンロード
plugin-sdk/plugins/{前回のPlugin ID}/plugin.zip がプラグイン
ファイル

> 完成ソース
- 完成ソース
https://github.com/ikatsuki/plugin-sdk/tree/master/sansan-
customize-1
- 差分

> ４-3．ハンズオンその２
～別のSansan APIを使ったカスタマイズ～

> Sansanにおける「タグ」とは
Sansanでは名刺
にタグを付けて
整理可能

> その２：改修後のUI
Sansanの名刺に付与され
ているタグの一覧を表示し、
当該タグの付いた名刺をま
とめて取得するように修正
しよう

> タグSet取得
66
- API概要
Sansanにあるタグ一覧を取得する
アクセスしているユーザーが参照可能なタグを返す
- HTTP リクエスト
GET https://api.sansan.com/v1/tags
- レスポンス
タグオブジェクトのSet

> タグオジェクト
67
プロパティ名データ型説明
id string タグID
name string タグ名
type string
非公開マイタグ (private)、公開マイタグ (public)、共
有タグ (shared)
owner User object 所有者を表すユーザオブジェクト

> タグ取得 API パラメータ（省略可能）
68
パラメータ名値説明
range "me" | "all" 対象とする所有者の範囲(省省略略時：me)
type "private" | "public" | "shared"
対象とするタグの種別(省省略略時：private)
複数指定可能
(…/tags?type=public&type=shared&...)
limit int (1~100) 取得する一覧の上限(省省略略時：100)
offset int 取得する一覧の開始位置(省省略略時：0)

> エラーコード一覧
69
HTTP
ステータス
コード
errorType 内容説明
400 required - 必須パラメータなし
invalid_value - リクエスト値が不不正
401 invalid_api_key -
認証エラー( API Key が不正)
invalid_app_id -
認証エラー( Application ID
が不正)
403 has_no_permission - API利利用用権限なし
404 - 指定リソースが存在しない
429 too_many_request "access_count" : number,
"retry_after" : number
リクエスト数制限超過
access̲count : 現在のアクセ
ス回数
retry̲after : 制限が解除され
るまでの期間(秒)
500 - - サーバエラー
503 - - サーバエラー
※一部のステータスコードにはエラーの詳細を表すError object の配列列が返却されます。
※下記以外のステータスコード(200や203等) はHTTP の仕様に準拠します。

> タグAPIを使用してSansanのデータを取得する (1/8)
desktop.js – Sansanlookup スコープ内
Sansan タグ取得 API でタグリストを取得する関数
getSansanTag: function(opt_offset, opt_records) {
//Sansanよりタグデータ取得
var offset = opt_offset || 0;
var alltags = opt_records || [];
var url = 'https://api.sansan.com/v1/tags?range=all';
url += '&offset=' + offset;
return kintone.plugin.app.proxy(PLUGIN_ID, url, 'GET', {}, {}).then(function(body) {
alltags = alltags.concat(JSON.parse(body[0]).data);
if (JSON.parse(body[1]) !== 200) {
var error_message = JSON.parse(body[0]).error[0].code;
if (JSON.parse(body[1]) === 429) {
error_message = 'リクエスト数が制限値を超えています。¥n5分以上時間を置いてから再度取得してください。';
}
return Promise.reject(new Error(error_message));
}
//5000件以上は処理終了
if (alltags.length >= 5000)
{
return alltags;
}
if (JSON.parse(body[0]).data.length === 100)
{
return Sansanlookup.getSansanTag(offset + 100, alltags);
}
return alltags;
}, function(error) {
return Promise.reject(new Error(error.message));
});
},

取得したタグリストをもとに処理を切り分ける関数
getLookupTagList: function() {
Sansanlookup.getSansanTag().then(function(sansan_tags) {
//Sansan取得タグ数(0~5000件)チェック
if (sansan_tags.length === 0) {
var nodata_msg = '<div id="sansan_lookup_validator_error" class="input-error-custom">' +
'<span>データがありません。</span></div>';
Sansanlookup.lookUpMessage($(nodata_msg));
Spin.hideSpinner();
return false;
} else if (sansan_tags.length >= 5000) {
//5000件以上の場合エラー
var find_msg = '<div id="sansan_lookup_validator_error" class="input-error-custom">' +
'<span>5000件以上のレコードがヒットしました<br>検索条件で絞り込んでください</span></div>';
Sansanlookup.lookUpMessage($(find_msg));
Spin.hideSpinner();
return false;
} else {
//2~4999件の場合ルックアップ画面表示
Sansanlookup.showTagDialog(Sansanlookup.createLookupTagListView(sansan_tags));
}
}).catch(function(error) {
Spin.hideSpinner();
swal('Error!', 'Sansanタグデータの取得に失敗しました。¥n' + error.message, 'error');
return false;
});
},

タグリストを作成する（モーダルの中身を組み立てる）関数
createLookupTagListView: function(sansan_tags) {
var result;
var taglist = "";
var count = 0;
//Sansan検索結果のリストを作成
for (var i = 0; sansan_tags.length > i; i++) {
var sansan_record = sansan_tags[i];
taglist += '<tr id="lookuplist_' + i + '" class="sansan-lookup-tr">' +
//1列目：選択ボタン
'<span><button class="button-simple-custom sansan-lookup-select" type="button">' +
'選択</button></span>' + '</td>' +
//2列目：タグ
'<td>' + '<div class="line-cell-kintone"><span>' +
escapeHtml(sansan_record['name']) + '</span></div>' +
//選択ボタンクリック時の取得値
'<input class="sansan_lookup_tagid" value="' +
escapeHtml(sansan_record['id']) +
'" type="hidden">' + '</td>' + '</tr>';
count++;
}
result =
'<table class="listTable-kintone lookup-table-kintone">' +
'<thead class="lookup-thead-gaia">' + '<tr>' +
//1列目見出し
'<th>' + '<div><span class="recordlist-header-label-kintone">' + count + '件' + '</span></div>' + '</th>' +
//2列目見出し
'<th>' + '<div><span class="recordlist-header-label-kintone">タグ名</span></div>' + '</th>' +
'</tr>' + '</thead>' + '<tbody>' + taglist + '</tbody>' + '</table>';
return result;
},

タグリストを画面に表示する関数
showTagDialog: function(date_list) {
//ダイアログの初期設定
var $date_dialog = $('<div>');
$date_dialog.attr('id', 'sansan-date-dialog');
$date_dialog.html(date_list);
$date_dialog.dialog({
title: 'タグ設定',
autoOpen: false,
width: 900,
maxHeight: 700,
show: 400,
hide: 400,
modal: true,
buttons: {
Cancel: function() {
$(this).remove();
}
}
});
$('#sansan-date-dialog').dialog('open');
$(".sansan-lookup-select").click(function() {
var tagId = $(this).parents(".sansan-lookup-tr").find(".sansan_lookup_tagid").val();
Sansanlookup.doSearch(null, tagId);
$('#sansan-date-dialog').dialog('close');
$('#sansan-date-dialog').remove();
});
},

Sansan データを取得する関数を変更（既存の searchSansanData 関数）
searchSansanData: function(dates, tagId, opt_offset, opt_records) {
//Sansanよりデータ取得
var record = kintone.app.record.get();
var offset = opt_offset || 0;
var value = record['record'][C_KEYFIELD]['value'] || "";
var allrecords = opt_records || [];
var url = "https://api.sansan.com/v1/bizCards";
if (dates) {
url += "?range=all" + "&registeredFrom" + "=" + encodeURIComponent(dates[0]) +
"&registeredTo" + "=" + encodeURIComponent(dates[1]);
} else if(tagId) {
url += "/search" + "?range=all&tagId=" + tagId;
} else {
url += "/search" + "?range=all";
if (value !== "") {
url += "&" + C_ORIGINALFIELD + "=" + encodeURIComponent(value);
}
}
url += "&offset=" + offset;
return kintone.plugin.app.proxy(PLUGIN_ID, url, "GET", {}, {}).then(function(body) {
allrecords = allrecords.concat(JSON.parse(body[0]).data);
if (JSON.parse(body[1]) !== 200) {
var error_message = JSON.parse(body[0]).error[0].code;
if (JSON.parse(body[1]) === 429) {
error_message = "リクエスト数が制限値を超えています。¥n5分以上時間を置いてから再度取得してください。";
}
return Promise.reject(new Error(error_message));
}
//5000件以上は処理終了
if (allrecords.length >= 5000) {
return allrecords;
}
if (JSON.parse(body[0]).data.length === 100) {
return Sansanlookup.searchSansanData(dates, tagId, offset + 100, allrecords);
}
return allrecords;
}, function(error) {
return Promise.reject(new Error(error.message));
});
},

Sansan データを取得する関数の呼び出し側も変更（getLookupList）
getLookupList: function(dates, tagId) {
Sansanlookup.searchSansanData(dates, tagId).then(function(sansan_data) {
Sansan データを取得する関数の呼び出し側も変更（doSearch）
doSearch: function(dates, tagId) {
Spin.showSpinner();
this.init();
this.getLookupList(dates, tagId);
},

画面にタグ検索を呼び出すボタンを作成（lookupHtml）
'<button id="lookup_tag_button" type="button">タグ</button>' +
'</div>'
タグリストモーダルを表示するイベントを追加する（kintone.events）
// [追加画面/編集画面]表示イベント
kintone.events.on(EVENTS, function(event) {
var $lookup = $(kintone.app.record.getSpaceElement(C_SPACEFIELD));
$lookup.append($(Sansanlookup.lookupHtml));
$("#lookup_search_button").click(function() {
Sansanlookup.doSearch();
});
$("#lookup_clear_button").click(function() {
Sansanlookup.doClear();
});
$("#lookup_setting_button").click(function() {
Sansanlookup.init();
Sansanlookup.showDateDialog(Sansanlookup.createDateListView());
});
$("#lookup_tag_button").click(function() {
Sansanlookup.getLookupTagList();
});
return event;
});

desktop.css
配置したボタンのデザインを変更する
#lookup_search_button, #lookup_clear_button, #lookup_setting_button, #lookup_tag_button {
margin-left: 5px;
height: 40px;
border-color: transparent;
border-style: solid;
border-width: 1px;
background-color: transparent;
font-size: 14px
}
#lookup_search_button:focus, #lookup_clear_button:focus, #lookup_setting_button:focus,
#lookup_tag_button:focus {
border-color: #3498db;
border-style: solid;
border-width: 1px
}

> 完成ソース
- 完成ソース
https://github.com/ikatsuki/plugin-sdk/tree/master/sansan-
customize-2
- 差分

kintone x Sansan連携事始め～カスタマイズまで

kintone x Sansan連携事始め～カスタマイズまで

Recommended

Recommended

More Related Content

What's hot

What's hot (20)

Similar to kintone x Sansan連携事始め～カスタマイズまで

Similar to kintone x Sansan連携事始め～カスタマイズまで (20)

Recently uploaded

Recently uploaded (10)