目次


SugarCRM コネクターを使ってデータを外の世界に接続する

Google AJAX Search API を使って Google ニュース・コネクターを作成する

コネクターとは何か

どのようなアプリケーションであれ (それが Web アプリケーションであれ、デスクトップ・アプリケーションであれ)、ほとんどの人はそのアプリケーションを既存のアプリケーションと接続する方法を知りたいと考えます。それに応え、通常のアプリケーションでは何らかの API を提供することで、アプリケーションの機能やデータを一定のプログラム・インターフェースの形で公開します。開発者はこのインターフェースを利用すれば、そのアプリケーションに接続することができます。このソリューションによって、そのアプリケーションへの接続という問題は解決されますが、残りの半分、つまりそのアプリケーションから他のアプリケーションへの接続、という問題は解決されません。SugarCRM では、この問題をコネクター・フレームワークによって解決します。

コネクター・フレームワークは、REST または SOAP による Web サービスを介して SugarCRM のレコードを別のアプリケーションのデータに接続するための標準的な手段です。その一例が SugarCRM の LinkedIn コネクターです。この LinkedIn コネクターを利用することで、SugarCRM の詳細レコードの中にあるアカウントや連絡先を LinkedIn から参照することができます。LinkedIn コネクターは SugarCRM にデフォルトで付属しています。図 1 は、このアプリケーション内での LinkedIn コネクターの対話型インターフェースがどのようなものかを示しています。

図 1. SugarCRM 内部にある LinkedIn コネクター
SugarCRM 内部にある LinkedIn コネクターのスクリーン・キャプチャー (3 つのコネクションと、さらに他の項目へのリンクが表示されています)。
SugarCRM 内部にある LinkedIn コネクターのスクリーン・キャプチャー (3 つのコネクションと、さらに他の項目へのリンクが表示されています)。

図 1 では Accounts モジュールに LinkedIn コネクターが統合されています。アカウントの隣にある LinkedIn アイコンの上をマウスでホバリングするとコネクターがトリガーされます。すると即座に LinkedIn に対する検索が行われ、指定された会社にコネクションがいくつあるかがウィジェットとして表示されます。また、このウィジェットにはそれらのコネクションのプロファイル・ページへのリンクも表示されます。

ここまでで、コネクターの有用性を説明したので、今度は皆さんのニーズに合ったカスタム・コネクターを作成する方法を説明することにしましょう。

Google ニュース用のコネクターを作成する

この記事では Google ニュース・サービスに対するコネクターを作成します。Google ニュースはニュース集約サービスとして、全世界の多種多様な報道機関やオンライン・サイトから抽出したニュースを、1 つのサイトにまとめて表示します。このため容易に検索をすることができます。このサービスに対するコネクターは SugarCRM にとって非常に有用なアドオンとなるため、SugarCRM アプリケーションのユーザーはこのコネクターを利用することで、そのユーザーが現在閲覧しているアカウントのレコードから最新のニュース項目を即座に表示できるようになります。

この Google ニュース・コネクターでは、Google AJAX Search API を使用して Google ニュースに接続します。Google AJAX Search API は非常に軽量で使いやすい、至って便利な API です。ここでは JavaScript の部分を簡単にするために、iframe を使って統合します、この方法では、十分見やすくなるようにスタイル設定された HTML ウィジェットが iframe に入れられてクライアントに返されます。こうすることで、SugarCRM に追加して想定どおり動作させるために必要なコード部分に集中することができます。

まず、これから作成するコネクターに構成ファイルとマッピング・ファイルをいくつか追加し、またコネクターのデータをユーザーに表示するための表示テンプレートも追加します。図 2 に、この新しいファイルを追加した Google ニュース・コネクターのディレクトリー構造を示します。

図 2. Google ニュース・コネクターのディレクトリー構造
この図は Google ニュース・コネクターのディレクトリー構造を示しています。
この図は Google ニュース・コネクターのディレクトリー構造を示しています。
Google ニュース・コネクターのディレクトリー構造をテキストで表現したもの (図 2)
v custom
  V modules
    v Connectors
      v connectors
        v formatters
          v ext
            v rest
              v googlenews
                  googlenews.php
                v tpls
                    default.tpl
                    googlenews.gif
        v sources
          v ext
            v rest
              v googlenews
                  config.php
                  googlenews.php
                v language
                     en_us.lang.php
                   mapping.php
                   vardefs.php

コネクターがアップグレードの影響を受けないようにするには (つまりメインの SugarCRM アプリケーションをアップグレードしてもカスタム・コードの変更部分には影響しないようにするには)、すべてのコネクター・ファイルを custom/ ディレクトリーの中に配置する必要があります。また、SugarCRM アプリケーションの中で既に LinkedIn コネクターを有効にしてある場合には、custom/modules/Connectors/ ディレクトリーの中に metadata/ ディレクトリーがあるかもしれません。metadata/ ディレクトリーには、見つかったコネクターのレジストリーが含まれています。新たに追加されたカスタム・コネクターをアプリケーションが見つけられるようにするには、このフォルダーを削除する必要があります。

ソース

コネクターは 2 つの部分に分けることができます。そのうちの 1 つであるソースの部分は、コネクターの構成の管理、Web サービスからのデータの取得、そして既存の SugarCRM モジュールのフィールドからリモート Web サービスで使用されるフィールドへのマッピングを行います。コネクターの第 2 の部分はフォーマッターです。フォーマッターについては次のセクションで説明します。ソースの部分には、いくつかのファイルが含まれています。まず config.php ファイルを見てみましょう (リスト 1)。

リスト 1. custom/modules/Connectors/sources/ext/rest/googlenews/config.php
<?php 
$config = array ( 
  'name' => 'Google News', 
  'properties' => array(), 
);

このファイルは、コネクターの名前と、コネクターに必要となるプロパティーを定義しています。多くの場合、これらの Web サービスが必要とする何らかの API キーは、リクエストに含める形で Web サービスに提供する必要があります。そのため、これらのキーをこの config.php ファイルの中で定義します。しかしここで使用する Google AJAX Search API では、他に特別な構成は必要ありません。そのため、単純にコネクターの名前と空のプロパティー配列を指定すればよいだけです。

次にリスト 2 の vardefs.php を見てください。このファイルはコネクターから提供されるフィールドを定義しています。

リスト 2. custom/modules/Connectors/sources/ext/rest/googlenews/vardefs.php
<?php 
$dictionary['ext_rest_googlenews'] = array( 
  'comment' => 'vardefs for google news connector', 
  'fields' => array ( 
    'id' => 
 array ( 
   'name' => 'id', 
   'vname' => 'LBL_ID', 
   'type' => 'id', 
   'comment' => 'Unique identifier', 
  'hidden' => true, 
), 
    'name'=> array( 
   'name' => 'name', 
   'vname' => 'LBL_NAME', 
   'type' => 'varchar', 
'hover' => true, 
   'comment' => 'The name of the company', 
    ), 
  ) 
);

Google ニュース・コネクターは Accounts レコードの name フィールドを基にクエリーを実行します。そこで、Accounts レコードの name フィールドと id フィールドを指定して Web サービスの呼び出しを行うことで、そのアカウントに関する Google ニュースの検索結果を取得します (注: SugarCRM を使用したことがある人は、このファイル・フォーマットに見覚えがあるはずです。SugarCRM で使われているフォーマットは vardefs.php ファイルのデータベース・フィールドのフォーマットと同じです。)

あるアカウントをコネクターに関連付けるマジックは mappings.php ファイルの中で行われます (リスト 3)。

リスト 3. custom/modules/Connectors/sources/ext/rest/googlenews/mapping.php
<?php 
$mapping = array ( 
  'beans' =>  
  array ( 
    'Accounts' =>  
    array ( 
      'name' => 'name', 
      'id' => 'id', 
    ), 
  ), 
);

リスト 3 はコネクターのフィールドを対象のモジュールにマッピングする方法を示しています。この例ではコネクターの name フィールドを要求しています。このフィールドの値は Accounts モジュールの name フィールドの値と同じです。同様に、コネクターの id フィールドは Accounts モジュールの id フィールドにマッピングされます。

次に、コネクターが完全に機能するように、rest ソース・クラスのインスタンスを追加します。この追加したインスタンスが、このコネクターでどのように扱われているかをリスト 4 で調べてください。ここでは完全に JavaScript とブラウザーをベースにした Google AJAX Search API を使用するため、ソース・クラス内に組み込まれている機能を使うことはありません。そのため、必要な呼び出しに対応する部分はスタブ化しています。

リスト 4. custom/modules/Connectors/sources/ext/rest/googlenews/googlenews.php
<?php 
require_once('include/connectors/sources/ext/rest/rest.php'); 
class ext_rest_googlenews extends ext_rest  
{ 
public function __construct() 
{ 
parent::__construct(); 
$this->_enable_in_wizard = false; 
$this->_enable_in_hover = true; 
} 
/* 
* getItem 
*  
* As the google news connector does not have a true API call, you simply 
* override this abstract method 
*/ 
public function getItem($args=array(), $module=null) {} 
/* 
* getList 
*  
* As the google news connector does not have a true API call, you simply 
* override this abstract method 
*/ 
public function getList($args=array(), $module=null) {} 
}

最後に、このコネクターで使われる (ある言語での) 文字列を定義する、言語定義ファイル (リスト 5) を追加します。このファイルによって、リスト 2 の vardefs.php ファイルで使われている name フィールドのフィールド名を指定します。(en_us.lang.php ファイルの完全なディレクトリー・パスは custom/modules/Connectors/connectors/sources/ext/rest/googlenews/language/en_us.lang.php です。)

リスト 5. .../Connectors/connectors/sources/ext/rest/googlenews/language/en_us.lang.php
<?php 
$connector_strings = array ( 
    'LBL_NAME' => 'Company Name', 
);

以上で、このコネクターに対するソースのマッピングと構成を作成できました。今度はフォーマッターを使用して、Web サービスから取得したデータを表示します。

フォーマッター

コネクターのもう一方の部分はフォーマッターと呼ばれ、フォーマッターはコネクター・データをユーザーに表示します。まず、定義ファイルを作成します。この定義ファイルでは default_formatter クラスを継承した上で、詳細ビューにコネクター・データを表示するために必要な部分を追加する必要があります。このファイルにはコネクターの名前が付けられており (googlenews.php)、リスト 6 にはその中身が示してあります。

リスト 6. custom/modules/Connectors/formatters/ext/rest/googlenews/googlenews.php
<?php 
require_once('include/connectors/formatters/default/formatter.php'); 
class ext_rest_googlenews_formatter extends default_formatter  
{ 
    public function getDetailViewFormat()  
    {  
       $mapping = $this->getSourceMapping(); 
       $mapping_name = !empty($mapping['beans'][$this->_module]['name']) ?
 $mapping['beans'][$this->_module]['name'] : ''; 

       if(!empty($mapping_name)) { 
           $this->_ss->assign('mapping_name', $mapping_name); 
           return $this->fetchSmarty(); 
       } 

       $GLOBALS['log']->error($GLOBALS['app_strings']['ERR_MISSING_MAPPING
_ENTRY_FORM_MODULE']); 
       return ''; 
    } 

    public function getIconFilePath()  
    { 
       return 'custom/modules/Connectors/connectors/formatters/ext/rest
/googlenews/tpls/googlenews.gif'; 
    } 
}

リスト 6 で定義されている 2 つの関数は DetailView メタデータ・フレームワークによって呼び出され、実際にフォーム内にコネクターを描画します。getIconFilePath() は、DetailView フォームのフィールドの隣に表示されるアイコンの URL を返します。この関数ではコネクターによって、この URL に対する接続が作成されます。そして次に、getDetailViewFormat() が、このアイコン上をマウスでホバリングすると表示されるウィジェット・フォームの描画の処理を行います。リスト 7 はコネクター・ウィジェットの Smarty テンプレートを示しています。

リスト 7. custom/modules/Connectors/formatters/ext/rest/googlenews/tpls/default.tpl
<div style="visibility:hidden;" id="googlenews_popup_div"></div>
<script type="text/javascript" src="{sugar_getjspath 
file='include/connectors/formatters/default/company_detail.js'}"></script>
<script type="text/javascript"> 
function show_ext_rest_googlenews(event) 
{literal}  
{ 
var xCoordinate = event.clientX; 
var yCoordinate = event.clientY; 
var isIE = document.all?true:false; 

if(isIE) { 
    xCoordinate = xCoordinate + document.body.scrollLeft; 
    yCoordinate = yCoordinate + document.body.scrollTop; 
} 
{/literal} 
cd = new CompanyDetailsDialog("googlenews_popup_div",  
  '<iframe height="90px" width="728px" frameborder="0" marginheight=0 
marginwidth=0 scrolling="no" src="//www.google.com/uds/modules/elements
/newsshow/iframe.html?rsz=small&q={$fields.{{$mapping_name}}.value}
&format=728x90"></iframe>', 
  xCoordinate, yCoordinate); 
cd.setHeader("{$fields.{{$mapping_name}}.value}"); 
cd.display(); 
{literal} 
}  
{/literal} 
</script>

ここで、detailview のアイコン上をマウスでホバリングするとトリガーされる JavaScript 関数 show_ext_rest_googlenews() を定義する必要があります。この JavaScript 関数ではウィジェットの内容を含むポップアップ・ダイアログの描画処理を行うとともに、Web サービスに対する外部呼び出しを行い、その結果をポップアップ・ダイアログの中に描画します。その後、この描画コードは、ポップアップ・ウィンドウを初期化し、そのウィンドウのタイトルに現在のレコードの名前を設定し、最後に API を呼び出す iframe の作成を行います。この場合、現在閲覧中のレコードから取得して渡された企業名が使われます。これらの実際の動作を示したものが図 3 です。

図 3. Google ニュース・コネクターの実際
対象とする企業のニュース項目が Google ニュース・コネクターに表示されている様子のスクリーン・キャプチャー
対象とする企業のニュース項目が Google ニュース・コネクターに表示されている様子のスクリーン・キャプチャー

これで、完全に機能するコネクターが完成しました。アカウント名の隣に表示されているニュース・アイコンの上をマウスでホバリングすると、そのアカウントに関する Google ニュースのデータがコネクターによって取得されます。SugarCRM アプリケーションの他のモジュールにも、このコネクターを容易に追加することができます。そのためには、リスト 3 の mapping.php ファイルに対象のモジュールのエントリーを単純に追加し、そのレコードをこのコネクターにマッピングすればよいだけです。また SugarCRM には、SugarCRM アプリケーションの Admin セクションの Connector Settings オプションを利用して、この操作をグラフィカルに行う方法も用意されています。Admin 画面の Connector Settings を単純にクリックすると、どのモジュールにニュース・アイコンを表示するのかを変更するための画面が表示されます (図 4)。

図 4. Connector Settings
Connector Settings のスクリーン・キャプチャー。Google News タブで Accounts と Contacts に対してアイコンが有効になっています。
Connector Settings のスクリーン・キャプチャー。Google News タブで Accounts と Contacts に対してアイコンが有効になっています。

次に、追加したモジュールのフィールドをマッピングする必要があります。これは Connector Settings 配下の Map Connector Fields ページで行います (図 5)。

図 5. Map Connector Fields
Google News タブの Map Connector Fields のスクリーン・キャプチャー。ここで Accounts と Contacts のモジュール・フィールドを選択します。
Google News タブの Map Connector Fields のスクリーン・キャプチャー。ここで Accounts と Contacts のモジュール・フィールドを選択します。

コネクターの各フィールドに対し、そのモジュールのフィールドの中から 2 つのエンティティー間のマッピングで使用するフィールドを選択します。コネクターを使用可能なそれぞれのモジュールごとに異なるマッピング設定をすることができます。

まとめ

この記事では、アプリケーション内部から外部データ・ソースへの接続手段を提供する SugarCRM のコネクター・フレームワークについて学びました。そしてこの SugarCRM のコネクター・フレームワークを使って外部アプリケーションと統合する手法が、従来の手法とは異なることを学びました (従来の手法では、アプリケーションへの外部フックを提供し、そのフックを他のアプリケーションが使用します)。またこの記事では、SugarCRM に用意されている LinkedIn コネクターについて概説した後、Google AJAX Search API を使用して独自の Google ニュース・コネクターを作成する方法を、定義の手順を追いながら学びました。そして最後に、完全に機能する Google ニュース・コネクターを完成させました。このコネクターによって、表示しているアカウントのレコードに関するニュースを検索してその結果を表示することができます。


ダウンロード可能なリソース


関連トピック

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=60
Zone=XML, Open source
ArticleID=470257
ArticleTitle=SugarCRM コネクターを使ってデータを外の世界に接続する
publish-date=02022010