SASインスティテュート
|
JMPオリオン統合（JOI）
ドキュメンテーション
|
2018年4月3日
|
バージョン2.0
|
株式会社ディーワイズテクノロジーズ
www.d-wise.com
1500ペリメーターパーク博士
ノースカロライナ州モリスビル 27650
lifesciences@d-wise.com
+1.919.600.6230
|
|
内容
1 実行
2 環境設定
3 設定ファイル
3.1 ロギング
3.2 Salesforceへの接続
3.3 オリオンとのつながり
3.4 許可されている製品
3.5 Salesforceから取得したフィールド
3.6 Orionフィールドのデフォルト値
3.7 マッピング規則
3.8 テスト用処理フィルタ
4 マッピング規則
4.1 コンテナオブジェクトのマッピング
4.2 マッピング配列
4.3 マッピングプロパティ
1実行
JOIは、という名前のバッチファイルを実行することによって起動されます。 joi.bat 。バッチファイルはJOIプログラムフォルダに移動し、メインJOIプログラムを実行します。以下はバッチファイルの内容の例です。
JOIを本番用に使用するには、プログラムを5分ごとなど、指定した間隔で繰り返し実行する必要があります。これは、バッチファイルを実行する繰り返しタスクを設定するために、（Windowsタスクスケジューラなどの）スケジュールプログラムを使用することによって実現できます。
2環境設定
JOI環境設定は、という別のSASプログラムに保存されています。 joi_environment_settings.sas 。このプログラムはメインのJOIプログラムと同じフォルダになければなりません。これは、％include文を介してメインプログラムによって実行されます。
JOIに必要な唯一の環境設定は、JOIがインストールされているルートフォルダーを識別することです。設定は、フォルダをという名前のマクロ変数に割り当てることによって指定されます。ルート次の例のように
％root = C：\ Users \ dhopkins \ Documents \ Projects \ SAS_Institute \ JOI \ 2.0;
3設定ファイル
JOI構成設定は、という別のSASプログラムに保存されます。 joi_config_settings.sas 。このプログラムはメインのJOIプログラムと同じフォルダになければなりません。これは、％include文を介してメインプログラムによって実行されます。
構成設定により、JOIの動作の多くの側面を、コアプログラムを変更することなく変更することができます。構成設定には、以下の領域があります。
- ロギング
- Salesforceへの接続
- オリオンとのつながり
- 許可されている製品
- Salesforceから取得したフィールド
- Orionフィールドのデフォルト値
- マッピング規則
- 処理フィルター
3.1ロギング
JOIが実行されると、処理情報をログファイルに記録します。ログファイルはローテーションされます。つまり、JOIは実行される日ごとに新しいログファイルを作成し、指定された日数より古いログファイルを削除します。次のマクロ変数には、ロギングに関連する設定が含まれています。
マクロ変数
|
説明
|
logFolder
|
ログファイルを格納するフォルダ
|
logFilePrefix
|
ログファイル名の作成に使用されるプレフィックス。次の例のように、ログファイルの名前にはプレフィックスに日付が追加されています。「JOI」はプレフィックスです。
JOI-2018-02-08。ログ
|
logDuration
|
ログファイルを削除する前に保持する日数
|
3.2 Salesforceへの接続
JOIはSalesforce RESTサービスにリクエストを送信することによってSalesforceとデータを交換します。以下にリストされているマクロ変数には、サービスを見つけて認証するために使用される構成設定が含まれています。設定ファイルには、これらの設定の2つのバージョンが含まれています。1つはテストデータにアクセスするためのもので、もう1つは本番データにアクセスするためのものです。プログラムがテスト用に実行されているのか、実運用用に実行されているのかに応じて、設定の1つのバージョンをコメントアウトする必要があります。
マクロ変数
|
説明
|
salesforceBaseUrl
|
RESTエンドポイントの構築に使用されるベースURL
|
salesforceConsumerKey
|
消費者キー
|
salesforceConsumerSecret
|
消費者の秘密
|
salesforceUsername
|
ユーザー名
|
salesforcePassword
|
パスワード
|
salesforceSecurityToken
|
セキュリティトークン
|
salesforcePayloadFolder
|
Salesforceへのリクエストのペイロードを含むファイルを格納するフォルダ
|
3.3 Orionへの接続
JOIはOrion RESTサービスにリクエストを送信することでOrionとデータを交換します。以下にリストされているマクロ変数は、サービスを見つけて認証するために使用される構成設定を含んでいます。
マクロ変数
|
説明
|
orionBaseUrl
|
RESTエンドポイントの構築に使用されるベースURL
|
orionPrincipalUser
|
主なユーザー
|
orionAccessKey
|
アクセスキー
|
orionSecretKey
|
秘密鍵
|
orionPayloadFolder
|
Orionへのリクエスト用のペイロードを含むファイルを保存するフォルダ
|
orionApiVersion
|
リクエストを行う際に使用するOrion APIのバージョン
|
3.4許可された提供
Orionに新しい機会を投稿するとき、JOIは機会の提供のためにOrion IDを含まなければなりません。これを容易にするために、設定プログラムは許可されているオファリングのリストとそれらに対応するOrion IDを設定します。許可されたオファリングは、というマクロを呼び出すことによってリストに追加されます。 allowOffering 。マクロは、オファリングの名前（テキスト）とオファリングのID（整数）の2つのパラメーターを取ります。以下は、リストに3つのオファリングを追加する例です。
%allowOffering(JMP, 1099);
%allowOffering(JMP Genomics, 1371);
%allowOffering(JMP Clinical, 2131);
3.5 Salesforceから取得したフィールド
Orionへのリクエストのペイロードを作成するには、JOIは5つのSalesforceテーブルから特定のフィールドを取得する必要があります。
構成プログラムは、これらの各テーブルから取り出されるフィールドを指定します。そのためには、各テーブルに対応する空のデータセットを作成します。これには、そのテーブルから必要なフィールドが含まれます。 以下は、Accountテーブルから必要なフィールドを指定する例です。
data sfAccountVars;
length
Id $255
Orion_Account_ID__c $255
ref4__c $255
Salesgroup__c $255
;
call missing (of _all_);
run;
追加のフィールドをAccountテーブルから取得することができます（これが必要になった場合）。長さ上記の例のステートメント lengthステートメントの変数は、Salesforceテーブルの項目とまったく同じ名前でなければなりません。
3.6 Orionフィールドのデフォルト値
機会をOrionに投稿するために必要なフィールドのいくつかは、Salesforceから取得したデータではなく、デフォルト値に設定されています。これらのフィールドは、Orionに投稿されたすべての商談に対して同じ値を持ちます。構成プログラムは、これらのフィールドに使用される値を、以下のマクロ変数に割り当てることによって指定します。
|
マクロ変数
|
オリオンフィールド
|
|
defaultStrategicInitiativeId
|
|
|
defaultType
|
/ルート/機会/タイプ
|
|
defaultInputSourceType
|
/ root / chance / inputSourceType
|
|
defaultMultinationalDeal
|
|
|
defaultComitCreate
|
|
|
defaultRoleId
|
|
|
defaultCustBusObjId
|
/ root / chance / customerBusinessObjectiveId
|
|
defaultCustBusObjGroupCode
|
/ root / chance / customerBusinessObjectiveGroupCode
|
|
defaultLikssibleToCloseId
|
/ root / chance/尤度ToCloseId
|
|
defaultMarkedPrivate
|
/ root / chance / markedPrivate
|
3.7マッピング規則
設定プログラムには、Orionペイロードに使用されるJSON構造と、JSON構造の生成に使用されるデータを定義する一連のマッピング規則が含まれています。マッピング規則の作成には3つのマクロが使用されます。 mapJsonObject 、 mapJsonArray 、そして mapJsonProperty 。一連の完全な規則は、これらのマクロへの一連の呼び出しによって設定されます。マッピング規則マクロの使い方の詳細は以下のセクション4にあります。
3.8テスト用処理フィルタ
構成プログラムは、テスト中に処理を特定の機会のサブセットに制限するために使用できる処理フィルターを提供します。フィルタは、条件句をに割り当てることで有効になります。 opportunityListFilter マクロ変数 次のフィルター例は、ID = '00629000002SiZnAAK'の商談に処理を制限します。
%let opportunityListFilter=id%str(=)%str(%')00629000002SiZnAAK%str(%');
特殊文字は次の文字でマスクする必要があります。 ％str 上記のように関数。
次の例のように、JOIの本番使用中は処理フィルタを空白に設定する必要があります。
%let opportunityListFilter=;
4マッピング規則
マッピングルールは、Orionペイロードに必要なJSON構造（つまり、新しい商談を投稿するためにOrionに送信されるデータ）を定義するために使用されます。マッピング規則は、JSON構造内の要素と各要素の設定に使用されるデータを定義します。
マッピング規則で定義できる要素は3種類あり、それらは規則の作成に使用される3つのマクロに対応します。
|
要素タイプ
|
マクロ名
|
呼び出し構文
|
|
コンテナオブジェクト
|
mapJsonObject
|
％mapJsonObject（
parent = <親要素>
key =
;
|
|
アレイ
|
mapJsonArray
|
％mapJsonArray（
parent = <親要素>
key =
arraySource = <データセット名>
;
|
|
物件
|
mapJsonProperty
|
構文1
％mapJsonProperty（
parent = <親要素>
key =
値= <値>
;
構文2：
％mapJsonProperty（
parent = <親要素>
key =
valueSource = <値ソース>
;
|
4.1コンテナオブジェクトのマッピング
JSONのコンテナーは、含まれている要素を囲む中括弧で示されます。すべてのJSON構造には、少なくとも1つのコンテナ、つまり最上位コンテナ（「/ root」と呼ばれます）が含まれています。他のコンテナは、ルートコンテナ内または他のネストされたコンテナ内にネストすることができます。ルートコンテナはJOIでマッピングルールを必要としませんが、ネストされたコンテナはすべて必要です。次のJSONの例を検討してください。これには、3つの入れ子になったコンテナ（太字のテキスト）が含まれています。
{
"opportunity": {
"accountId": 5110985,
"amount": 530000,
},
"salesGroup": "JP",
"comit": {
"firstPeriodTerm": null,
"dealLength": null,
"form": {
"mlaNeeded": null,
"supplementNeeded": false,
},
}
}
この例のマッピング規則には、3つの呼び出しが含まれます。 mapJsonObject マクロ。各呼び出しは、次の構文を使用して、コンテナ要素のキーとそれがネストされている親を指定します。
%mapJsonObject(
parent=<parent element>,
key=<element key>
);
親引数は、パス要素を区切るためにフォワードスラッシュが使用されるlinuxフォルダパスに似た構文を使用して指定されます。したがって、上記の例の入れ子になったコンテナは、次の3つのマクロ呼び出しでマッピングできます。
%mapJsonObject (parent=/root, key=opportunity);
%mapJsonObject (parent=/root, key=comit);
%mapJsonObject (parent=/root/comit, key=form);
4.2マッピング配列
JSONの配列は、配列要素を囲む角括弧で示されます。JOIは、最初に配列を作成するのに必要なレコード、フィールド、および値を含むSASデータセットを作成し、次にデータセットを arraySource マッピング規則の引数。
以下のJSONの例には、それぞれが3つの要素を含む2つのオブジェクトを含む1つの配列（太字のテキスト）が含まれています。配列の構造は、2つのレコードと3つのフィールドを含むSASデータセットに似ています。
{
"cdhubId": 999,
"accountNameId": 999,
"inputSourceType": "foo",
"ips": [
{
"employeeId": 123,
"roleId": "123_role",
"territoryId": "123_territory",
},
{
"employeeId": 234,
"roleId": "234_role",
"territoryId": "234_territory",
}
],
"comitCreate": true,
}
この例のマッピング規則には、 mapJsonArray マクロ。以下に示す構文を使用して、呼び出しは配列要素のキー、それがネストされている親、および配列の生成に使用されるデータを含むデータセットを指定します。
%mapJsonArray(
parent=<parent element>,
key=<element key>,
key=<dataset identifier>
);
上記の例の配列は、次のマクロ呼び出しでマッピングできます。
%mapJsonArray (parent=/root, key=ips, arraySource=opportunityIpsJson);
このマッピング規則が機能するためには、JOIはOrionペイロードを構築する前に指示されたデータセットを作成する必要があります。（配列データセットの作成は、 createJsonComponentDatasets マクロ）。上記のJSONの例では、JOIは以下のレコード、フィールドを含むデータセットを作成する必要があります。と値：
|
従業員ID
|
roleId
|
territoryId
|
|
123
|
123_ロール
|
123テリトリー
|
|
234
|
234_ロール
|
234_テリトリー
|
配列内の要素は、JOIでは別々のマッピング規則を必要としません。配列の内容は、SASデータセットのデータによって完全に定義されています。上記のJSONの例では、マッピング規則を指定する必要はありません。従業員ID 、 roleID または territoryId 。
4.3マッピングプロパティ
作成する最も単純なJSON要素はプロパティと呼ばれます。各プロパティはキーと値のペアです。 JOIでは、配列に含まれていないすべてのプロパティに対してマッピング規則が必要です。次のJSONの例には、マッピング規則を必要とする8つのプロパティ（緑色のテキスト）が含まれています。
{
"opportunity": {
"accountId": 5110985,
"amount": 530000,
"ips": [
{
"employeeId": 123,
"roleId": "123_role",
"territoryId": "123_territory",
}
],
"comitCreate": true,
},
"salesGroup": "JP",
"comit": {
"firstPeriodTerm": null,
"dealLength": null,
"form": {
"mlaNeeded": null,
"supplementNeeded": false,
},
}
}
この例のマッピング規則には、8つの呼び出しが含まれます。 mapJsonProperty マクロ。以下に示すように、キーと値のペアに対する値の取得方法に応じて、このマクロを呼び出す方法は2つあります。
構文1
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
value=<value>
);
構文2：
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
valueSource=<value source>
);
最初の構文は、次の例のように、割り当てられている値がリテラル値またはマクロ変数に含まれる値のいずれかである場合に使用されます。
%mapJsonProperty (parent=/root/opportunity, key=accountId, value="5110985");
%mapJsonProperty (parent=/root/opportunity, key=comitCreate, value=&defaultcomitCreate);
次の例のように、割り当てられている値がsalesforce変数から取得されるか、SASマクロを実行することによって取得される場合、2番目の構文が使用されます。
%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/comit, key=dealLength, valueSource=macro:assignDealLength);
上記の例でマッピング規則を必要とするプロパティは、次の8つのマクロ呼び出しでマッピングできます。
%mapJsonProperty (parent=/root/opportunity, key=accountId, value="5110985");
%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/opportunity, key=comitCreate, value=&defaultcomitCreate);
%mapJsonProperty (parent=/root, key=salesGroup, valueSource=salesforce:account.Salesgroup__c);
%mapJsonProperty (parent=/root/comit, key=firstPeriodTerm, valueSource=macro:assignFirstPeriodTerm);
%mapJsonProperty (parent=/root/comit, key=dealLength, valueSource=macro:assignDealLength);
%mapJsonProperty (parent=/root/comit/form, key=mlaNeeded, valueSource=salesforce:opportunity.mla__c);
%mapJsonProperty (parent=/root/comit/form, key=supplementNeeded, valueSource=salesforce:opportunity.supplement__c);
