55828_zh-CN

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