55828_zh-TW

liliconcom

SAS Macro API文檔 - 草稿

 

SAS研究所

JMP獵戶座集成（JOI） 文檔

2018年4月3日

版本2.0

 

 

 

 

d-Wise Technologies，Inc 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 獵戶座場的默認值

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的根文件夾。通過將文件夾分配給名為的宏變量來指定設置根 ，如下例所示：

％let root = C：\ Users \ dhopkins \ Documents \ Projects \ SAS_Institute \ JOI \ 2.0;

3配置文件

JOI配置設置保存在名為的單獨SAS程序中 joi_config_settings.sas 。該程序必須與主JOI程序位於同一文件夾中。它由主程序通過％include語句執行。

配置設置允許在不更改核心程序的情況下修改JOI行為的許多方面。配置設置包括以下區域：

• 記錄
• 與Salesforce的連接
• 與獵戶座的連接
• 允許的產品
• 從Salesforce獲取的字段
• 獵戶座場的默認值
• 映射規則
• 處理過濾器

3.1記錄

執行JOI時，它會將處理信息記錄到日誌文件中。日誌文件被旋轉，即JOI在每天執行時創建一個新的日誌文件，並刪除超過指定天數的日誌文件。以下宏變量包含與日誌記錄相關的配置設置：

宏變量	描述
logFolder	將存儲日誌文件的文件夾
logFilePrefix	用於構造日誌文件名稱的前綴。通過在前綴中添加日期來命名日誌文件，如下例所示，其中“JOI”是前綴： JOI - 2018年2月8日。日誌
logDuration	刪除日誌文件之前保留日誌文件的天數

3.2與Salesforce的連接

JOI通過向Salesforce REST服務發送請求來與Salesforce交換數據。下面列出的宏變量包含用於查找和驗證服務的配置設置。請注意，配置文件包含這些設置的兩個版本：一個用於訪問測試數據，另一個用於訪問生產數據。應該註釋掉一個版本的設置，具體取決於程序是執行測試還是生產使用。

宏變量	描述
salesforceBaseUrl	用於構造REST端點的基本URL
salesforceConsumerKey	消費者密鑰
salesforceConsumerSecret	消費者秘密
salesforceUsername	用戶名
salesforcePassword	密碼
salesforceSecurityToken	安全令牌
salesforcePayloadFolder	用於存儲包含Salesforce請求的有效負載的文件的文件夾

3.3與獵戶座的連接

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（整數）。下面是一個向列表添加三個產品的示例：

 

%allowOffering(JMP, 1099);
%allowOffering(JMP Genomics, 1371);  
%allowOffering(JMP Clinical, 2131);    

 

 

3.5從Salesforce獲取的字段

要為Orion的請求構造有效負載，JOI必須從五個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所需的一些字段設置為默認值，而不是從Salesforce獲取的數據。對於發佈到Orion的每個商機，這些字段具有相同的值。配置程序通過將它們分配給以下宏變量來指定將用於這些字段的值：

宏變量	獵戶座場
defaultStrategicInitiativeId
缺省的類型	/根/機會/類型
defaultInputSourceType	/根/機遇/ inputSourceType
defaultMultinationalDeal
defaultComitCreate
defaultRoleId
defaultCustBusObjId	/根/機遇/ customerBusinessObjectiveId
defaultCustBusObjGroupCode	/根/機遇/ customerBusinessObjectiveGroupCode
defaultLikelihoodToCloseId	/根/機遇/ likelihoodToCloseId
defaultMarkedPrivate	/根/機遇/ markedPrivate

3.7映射規則

配置程序包括一組映射規則，用於定義將用於Orion有效負載的JSON結構，以及將用於填充JSON結構的數據。在創建映射規則時使用了三個宏， 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結構中的元素以及用於填充每個元素的數據。

可以使用映射規則定義三種類型的元素，它們對應於用於創建規則的三個宏：

元素類型	宏名稱	調用語法
容器對象	mapJsonObject	％mapJsonObject（ parent = <父元素>， key = <元素鍵> ）;
排列	mapJsonArray	％mapJsonArray（ parent = <父元素>， key = <元素鍵>， arraySource = ）;
屬性	mapJsonProperty	語法1： ％mapJsonProperty（ parent = <父元素>， key = <元素鍵>， 值= <值> ）;   語法2： ％mapJsonProperty（ parent = <父元素>， key = <元素鍵>， valueSource = <值源> ）;

4.1映射容器對象

JSON中的容器由包含所包含元素的花括號指定。所有JSON結構都包含至少一個容器，即頂級容器（稱為“/ root”）。其他容器可以嵌套在根容器內或其他嵌套容器中。根容器在JOI中不需要映射規則，但所有嵌套容器都需要。請考慮以下JSON示例，其中包含三個嵌套容器（粗體文本）。

 

{
  "opportunity": {
   "accountId": 5110985,
    "amount": 530000,
  },
  "salesGroup": "JP",
  "comit": {
   "firstPeriodTerm": null,
    "dealLength": null,
    "form": {
      "mlaNeeded": null,
      "supplementNeeded": false,
    },
  }
}

 

此示例的映射規則將包括對該調用的三次調用 mapJsonObject 宏。每個調用都將使用以下語法指定容器元素的鍵和嵌套它的父元素：

 

%mapJsonObject(
parent=<parent element>,
key=<element key>
);

 

 

使用類似於linux文件夾路徑的語法指定父參數，其中正斜杠用於分隔路徑元素。因此，上面示例中的嵌套容器可以使用以下三個宏調用進行映射：

 

%mapJsonObject (parent=/root,       key=opportunity);
%mapJsonObject (parent=/root,       key=comit);
%mapJsonObject (parent=/root/comit, key=form);    

                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              

 

4.2映射數組

JSON中的數組由包含數組元素的方括號指定。JOI通過首先創建一個SAS數據集來構建一個數組，該數據集包含填充數組所需的記錄，字段和值，然後使用數據集作為 arraySource 映射規則中的參數。

下面的JSON示例包含一個包含兩個對象的數組（粗體文本），每個對象包含三個元素。請注意，數組的結構類似於包含兩個記錄和三個字段的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	角色ID	的TerritoryID
123	123_role	123_territory
234	234_role	234_territory

請注意，數組中的元素在JOI中不需要單獨的映射規則。陣列內容完全由SAS數據集中的數據定義。對於上面的JSON示例，不需要為其指定映射規則員工ID ，角色ID ，要么的TerritoryID 。

4.3映射屬性

要創建的最簡單的JSON元素稱為屬性。每個屬性都是鍵值對。  JOI需要映射規則，以用於未包含在數組中的所有屬性。以下JSON示例包含八個需要映射規則的屬性（綠色文本）：

{
 "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,
    },
 }
}

 

此示例的映射規則將包括對該調用的八次調用 mapJsonProperty 宏。如下所示，有兩種方法可以調用此宏，具體取決於如何為鍵值對獲取值：

語法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宏獲取所分配的值時，將使用第二種語法，如以下示例所示：

%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/comit, key=dealLength,         valueSource=macro:assignDealLength);

 

上面示例中需要映射規則的屬性可以使用以下八個宏調用進行映射：

 

%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);