Instituto SAS
|
JMP Orion Integration (JOI)
Documentación
|
3 de abril de 2018
|
Versión 2.0
|
d-Wise Technologies, Inc
www.d-wise.com
1500 perímetro parque Dr.
Morrisville, NC 27650
lifesciences@d-wise.com
+1.919.600.6230
|
|
Contenido
1 Ejecución
2 Ajustes de entorno
3 Archivo de configuración
3.1 Explotación florestal
3.2 Conexión a Salesforce
3.3 Conexión a Orión
3.4 Ofrendas permitidas
3.5 Campos traídos de Salesforce
3.6 Valores predeterminados para los campos de Orion
3.7 Reglas de mapeo
3.8 Filtro de Procesamiento para Pruebas
4 Reglas de mapeo
4.1 Mapeo de objetos contenedores
4.2 Mapeo de matrices
4.3 Mapeo de propiedades
1 ejecución
JOI se inicia ejecutando un archivo por lotes llamado joi.bat . El archivo por lotes navega a la carpeta del programa JOI y ejecuta el programa principal de JOI. A continuación se muestra un ejemplo del contenido del archivo por lotes:
Para el uso de producción de JOI, el programa debe ejecutarse repetidamente a intervalos específicos, como cada 5 minutos. Esto se puede lograr usando un programa de programación (como el Programador de tareas de Windows) para configurar una tarea repetitiva que ejecute el archivo por lotes.
2 Ajustes de entorno
La configuración del entorno JOI se mantiene en un programa SAS separado denominado joi_environment_settings.sas . Este programa debe estar en la misma carpeta que el programa principal de JOI. Es ejecutado por el programa principal a través de una instrucción% include.
La única configuración de entorno necesaria para JOI es identificar la carpeta raíz donde está instalado JOI. La configuración se especifica asignando la carpeta a una variable de macro llamada raíz , como en el siguiente ejemplo:
% let root = C: \ Users \ dhopkins \ Documents \ Projects \ SAS_Institute \ JOI \ 2.0;
3 Archivo de configuración
Los ajustes de configuración de JOI se guardan en un programa SAS separado llamado joi_config_settings.sas . Este programa debe estar en la misma carpeta que el programa principal de JOI. Es ejecutado por el programa principal a través de una instrucción% include.
Los ajustes de configuración permiten modificar muchos aspectos del comportamiento de JOI sin cambios en los programas centrales. Los ajustes de configuración incluyen estas áreas:
- Explotación florestal
- Conexión a Salesforce
- Conexión a Orión
- Ofrendas permitidas
- Campos traídos de Salesforce
- Valores predeterminados para los campos de Orion
- Reglas de mapeo
- Filtro de procesamiento
3.1 Registro
Cuando se ejecuta JOI, registra información de procesamiento en un archivo de registro. Los archivos de registro se rotan, es decir, JOI crea un nuevo archivo de registro cada día que se ejecuta y elimina los archivos de registro que son más antiguos que un número específico de días. Las siguientes variables de macro contienen ajustes de configuración relacionados con el registro:
Variable Macro
|
Descripción
|
logFolder
|
Carpeta en la que se almacenarán los archivos de registro.
|
logFilePrefix
|
Prefijo que se utilizará en la construcción de nombres de archivos de registro. Los archivos de registro se nombran agregando una fecha al prefijo, como en el siguiente ejemplo donde "JOI" es el prefijo:
JOI-2018-02-08.Iniciar sesión
|
logDuration
|
Número de días para conservar los archivos de registro antes de eliminarlos
|
3.2 Conexión a Salesforce
JOI intercambia datos con Salesforce al enviar solicitudes al servicio REST de Salesforce. Las variables de macro enumeradas a continuación contienen los ajustes de configuración utilizados para localizar y autenticar el servicio. Tenga en cuenta que el archivo de configuración contiene dos versiones de estas configuraciones: una para acceder a los datos de prueba y otra para acceder a los datos de producción. Una versión de la configuración debe ser comentada, dependiendo de si el programa se está ejecutando para pruebas o para uso de producción.
Variable Macro
|
Descripción
|
salesforceBaseUrl
|
URL base utilizada en la construcción de puntos finales REST
|
salesforceConsumerKey
|
Clave del consumidor
|
salesforceConsumerSecret
|
Secreto del consumidor
|
nombre de usuario de salesforce
|
Nombre de usuario
|
salesforcePassword
|
Contraseña
|
salesforceSecurityToken
|
Token de seguridad
|
salesforcePayloadFolder
|
Carpeta en la que se almacenan los archivos que contienen cargas útiles para solicitudes a Salesforce
|
3.3 Conexión a Orión
JOI intercambia datos con Orion enviando solicitudes al servicio REST de Orion. Las variables de macro enumeradas a continuación contienen los ajustes de configuración utilizados para localizar y autenticar el servicio.
Variable Macro
|
Descripción
|
orionBaseUrl
|
URL base utilizada en la construcción de puntos finales REST
|
orionPrincipalUser
|
Usuario principal
|
orionAccessKey
|
Llave de acceso
|
orionSecretKey
|
Llave secreta
|
orionPayazoFolder
|
Carpeta en la que se almacenan los archivos que contienen cargas útiles para solicitudes a Orion
|
orionApiVersion
|
Versión de la API de Orion para usar al realizar solicitudes
|
3.4 Ofrendas permitidas
Al publicar una nueva oportunidad en Orion, JOI debe incluir la ID de Orion para la oferta de la oportunidad. Para facilitar esto, el programa de configuración configura una lista de ofertas que están permitidas y las ID de Orion que se corresponden con ellas. Las ofertas permitidas se agregan a la lista invocando una macro llamada allowOffering . La macro toma dos parámetros, el nombre de la oferta (texto) y el ID de la oferta (entero). A continuación se muestra un ejemplo que agrega tres ofertas a la lista:
%allowOffering(JMP, 1099);
%allowOffering(JMP Genomics, 1371);
%allowOffering(JMP Clinical, 2131);
3.5 Campos traídos de Salesforce
Para construir la carga útil para una solicitud a Orion, JOI debe obtener campos específicos de cinco tablas de Salesforce:
- Oportunidad
- Cuenta
- Usuario
- Contacto
- Ofrecimiento
El programa de configuración especifica los campos que se buscarán en cada una de estas tablas. Lo hace creando un conjunto de datos vacío correspondiente a cada tabla, que incluye los campos necesarios de esa tabla. A continuación se muestra un ejemplo que especifica los campos necesarios de la tabla de cuentas:
data sfAccountVars;
length
Id $255
Orion_Account_ID__c $255
ref4__c $255
Salesgroup__c $255
;
call missing (of _all_);
run;
Se pueden obtener campos adicionales de la tabla de la Cuenta (si esto fuera necesario) agregándolos a la longitud declaración en el ejemplo anterior. Tenga en cuenta que las variables en la declaración de longitud deben tener los mismos nombres exactos que los campos en la tabla de Salesforce.
3.6 Valores predeterminados para los campos de Orion
Algunos de los campos necesarios para publicar una oportunidad en Orion están configurados en valores predeterminados, en lugar de datos obtenidos de Salesforce. Estos campos tienen el mismo valor para cada oportunidad publicada en Orion. El programa de configuración especifica los valores que se utilizarán para estos campos, asignándolos a las siguientes variables de macro:
|
Variable Macro
|
Campo de orion
|
|
defaultStrategiaEdiativaEdiativa
|
|
|
defaultType
|
/ raíz / oportunidad / tipo
|
|
defaultInputSourceType
|
/ root / opportunity / inputSourceType
|
|
defaultMultinationalDeal
|
|
|
defaultComitCreate
|
|
|
defaultRoleId
|
|
|
defaultCustBusObjId
|
/ root / opportunity / customerBusinessObjectiveId
|
|
defaultCustBusObjGroupCode
|
/ root / opportunity / customerBusinessObjectiveGroupCode
|
|
defaultLikelihoodToCloseId
|
/ root / opportunity / likelihoodToCloseId
|
|
defaultMarkedPrivate
|
/ raíz / oportunidad / marcadoPrivado
|
3.7 Reglas de mapeo
El programa de configuración incluye un conjunto de reglas de asignación que definen la estructura JSON que se utilizará para la carga útil de Orion y los datos que se utilizarán para completar la estructura JSON. Se utilizan tres macros en la creación de reglas de mapeo, mapJsonObject , mapJsonArray y mapJsonProperty . El conjunto completo de reglas se configura mediante una secuencia de llamadas a estas macros. Los detalles sobre cómo usar las macros de reglas de mapeo se encuentran en la sección 4.
3.8 Filtro de Procesamiento para Pruebas
El programa de configuración proporciona un filtro de procesamiento que se puede usar durante las pruebas para limitar el procesamiento a un subconjunto específico de oportunidades. El filtro se habilita asignando una cláusula de condición a la OportunidadListFilter variable macro El siguiente ejemplo de filtro limita el procesamiento a la oportunidad con ID = '00629000002SiZnAAK':
%let opportunityListFilter=id%str(=)%str(%')00629000002SiZnAAK%str(%');
Tenga en cuenta que los caracteres especiales deben enmascararse con la % str función, como se muestra arriba.
El filtro de procesamiento se debe establecer en blanco durante el uso de producción de JOI, como en el siguiente ejemplo:
%let opportunityListFilter=;
4 reglas de mapeo
Las reglas de asignación se utilizan para definir la estructura JSON que se necesita para la carga útil de Orion (es decir, los datos enviados a Orion para publicar una nueva oportunidad). Las reglas de asignación definen los elementos en la estructura JSON y los datos utilizados para rellenar cada elemento.
Hay tres tipos de elementos que pueden definirse con una regla de mapeo, y corresponden a las tres macros utilizadas para crear reglas:
|
Tipo de elemento
|
Nombre de macro
|
Sintaxis de llamadas
|
|
Objeto contenedor
|
mapJsonObject
|
% mapJsonObject (
padre = ,
clave =
);
|
|
Formación
|
mapJsonArray
|
% mapJsonArray (
padre = ,
clave = ,
arraySource =
);
|
|
Propiedad
|
mapJsonProperty
|
Sintaxis 1:
% mapJsonProperty (
padre = ,
clave = ,
valor =
);
Sintaxis 2:
% mapJsonProperty (
padre = ,
clave = ,
valueSource =
);
|
4.1 Mapeo de objetos contenedores
Los contenedores en JSON se designan mediante llaves que encierran los elementos contenidos. Todas las estructuras JSON incluyen al menos un contenedor, es decir, el contenedor de nivel superior (llamado "/ root"). Otros contenedores pueden estar anidados dentro del contenedor raíz o dentro de otros contenedores anidados. El contenedor raíz no requiere una regla de asignación en JOI, pero todos los contenedores anidados sí lo requieren. Considere el siguiente ejemplo de JSON, que incluye tres contenedores anidados (texto en negrita).
{
"opportunity": {
"accountId": 5110985,
"amount": 530000,
},
"salesGroup": "JP",
"comit": {
"firstPeriodTerm": null,
"dealLength": null,
"form": {
"mlaNeeded": null,
"supplementNeeded": false,
},
}
}
Las reglas de mapeo para este ejemplo incluirían tres llamadas al mapJsonObject macro. Cada llamada especificaría la clave de un elemento contenedor y el padre bajo el cual está anidado, usando la siguiente sintaxis:
%mapJsonObject(
parent=<parent element>,
key=<element key>
);
El argumento principal se especifica mediante una sintaxis similar a una ruta de carpeta de Linux, donde las barras diagonales se utilizan para separar los elementos de ruta. Por lo tanto, los contenedores anidados en el ejemplo anterior podrían asignarse con las siguientes tres llamadas de macro:
%mapJsonObject (parent=/root, key=opportunity);
%mapJsonObject (parent=/root, key=comit);
%mapJsonObject (parent=/root/comit, key=form);
4.2 Mapeo de matrices
Las matrices en JSON están designadas por corchetes que encierran los elementos de la matriz. JOI crea una matriz al crear primero un conjunto de datos SAS que contiene los registros, campos y valores necesarios para completar la matriz, luego usar el conjunto de datos como arraySource argumento en una regla de mapeo.
El siguiente ejemplo de JSON incluye una matriz (texto en negrita) que contiene dos objetos, cada uno de los cuales contiene tres elementos. Tenga en cuenta que la estructura de la matriz es similar a un conjunto de datos SAS que contiene dos registros y tres campos:
{
"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,
}
Las reglas de mapeo para este ejemplo incluirían una llamada al mapJsonArray macro. Usando la sintaxis que se muestra a continuación, la llamada especificaría la clave del elemento de la matriz, el elemento primario bajo el cual está anidado y un conjunto de datos que contendrá los datos utilizados para completar la matriz:
%mapJsonArray(
parent=<parent element>,
key=<element key>,
key=<dataset identifier>
);
La matriz en el ejemplo anterior podría asignarse con la siguiente llamada de macro:
%mapJsonArray (parent=/root, key=ips, arraySource=opportunityIpsJson);
Para que esta regla de mapeo funcione, JOI tendría que crear el conjunto de datos indicado antes de construir la carga útil de Orion. (Tenga en cuenta que la creación de conjuntos de datos de matriz es manejada por el createJsonComponentDatasets macro). Para el ejemplo JSON que se muestra arriba, JOI necesitaría crear un conjunto de datos que contenga los siguientes registros, campos, y valores:
|
ID de empleado
|
Identificación del rol
|
ID de territorio
|
|
123
|
123_role
|
123_territorio
|
|
234
|
234_role
|
234_territorio
|
Tenga en cuenta que los elementos dentro de una matriz no requieren reglas de mapeo separadas en JOI. El contenido de la matriz está completamente definido por los datos en el conjunto de datos SAS. Para el ejemplo JSON anterior, no habría necesidad de especificar reglas de mapeo para ID de empleado , Identificación del rol o ID de territorio .
4.3 Mapeo de propiedades
Los elementos JSON más simples para crear se llaman propiedades. Cada propiedad es un par clave-valor. JOI requiere reglas de mapeo para todas las propiedades que no están contenidas en arreglos. El siguiente ejemplo de JSON incluye ocho propiedades que necesitan reglas de mapeo (texto verde):
{
"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,
},
}
}
Las reglas de mapeo para este ejemplo incluirían ocho llamadas al mapJsonProperty macro. Como se muestra a continuación, hay dos formas de llamar a esta macro, dependiendo de cómo se obtiene el valor para el par clave-valor:
Sintaxis 1:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
value=<value>
);
Sintaxis 2:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
valueSource=<value source>
);
La primera sintaxis se usa cuando el valor que se asigna es un valor literal o un valor contenido en una variable de macro, como en los siguientes ejemplos:
%mapJsonProperty (parent=/root/opportunity, key=accountId, value="5110985");
%mapJsonProperty (parent=/root/opportunity, key=comitCreate, value=&defaultcomitCreate);
La segunda sintaxis se usa cuando el valor que se asigna se obtiene de una variable de Salesforce o ejecutando una macro SAS, como en los siguientes ejemplos:
%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/comit, key=dealLength, valueSource=macro:assignDealLength);
Las propiedades que necesitan reglas de mapeo en el ejemplo anterior se podrían mapear con las siguientes ocho llamadas de macro:
%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);
