Institut SAS
|
Intégration JMP Orion (JOI)
Documentation
|
3 avril 2018
|
Version 2.0
|
d-Wise Technologies, Inc
www.d-wise.com
1500 Perimeter Park Dr.
Morrisville, Caroline du Nord 27650
lifesciences@d-wise.com
+1.919.600.6230
|
|
Contenu
1 Exécution
2 Paramètres de l'environnement
3 Fichier de configuration
3.1 Enregistrement
3.2 Connexion à Salesforce
3.3 Connexion à Orion
3.4 Offres permises
3,5 Champs extraits de Salesforce
3.6 Valeurs par défaut pour les champs Orion
3.7 Règles de cartographie
3.8 Filtre de traitement pour test
4 Règles de cartographie
4.1 Mappage d'objets de conteneur
4.2 Tableaux de cartographie
4.3 Propriétés de la cartographie
1 exécution
JOI est lancé en exécutant un fichier de commandes nommé joi.bat . Le fichier de commandes accède au dossier du programme JOI et exécute le programme principal JOI. Vous trouverez ci-dessous un exemple du contenu du fichier de commandes:
Pour une utilisation en production de JOI, le programme doit être exécuté de manière répétée à des intervalles spécifiés, par exemple toutes les 5 minutes. Pour ce faire, utilisez un programme de planification (tel que le Planificateur de tâches Windows) pour configurer une tâche répétitive qui exécute le fichier de traitement par lots.
2 paramètres d'environnement
Les paramètres d’environnement JOI sont conservés dans un programme SAS distinct nommé joi_environment_settings.sas . Ce programme doit se trouver dans le même dossier que le programme principal JOI. Il est exécuté par le programme principal via une instruction% include.
Le seul paramètre d’environnement requis pour JOI consiste à identifier le dossier racine dans lequel est installé JOI. Le paramètre est spécifié en affectant le dossier à une variable macro nommée racine , comme dans l'exemple suivant:
% let root = C: \ Utilisateurs \ Dhopkins \ Documents \ Projets \ SAS_Institute \ JOI \ 2.0;
3 fichier de configuration
Les paramètres de configuration JOI sont conservés dans un programme SAS distinct nommé joi_config_settings.sas . Ce programme doit se trouver dans le même dossier que le programme principal JOI. Il est exécuté par le programme principal via une instruction% include.
Les paramètres de configuration permettent de modifier de nombreux aspects du comportement de JOI sans modifier les programmes principaux. Les paramètres de configuration incluent les domaines suivants:
- Enregistrement
- Connexion à Salesforce
- Connexion à Orion
- Offres permises
- Champs extraits de Salesforce
- Valeurs par défaut pour les champs Orion
- Règles de cartographie
- Filtre de traitement
3.1 Enregistrement
Lorsque JOI est exécuté, il enregistre les informations de traitement dans un fichier journal. Les fichiers journaux sont soumis à une rotation, c’est-à-dire que JOI crée un nouveau fichier journal chaque jour de son exécution et supprime les fichiers journaux plus anciens que le nombre de jours spécifié. Les variables de macro suivantes contiennent des paramètres de configuration liés à la journalisation:
Macro variable
|
La description
|
logFolder
|
Dossier dans lequel les fichiers journaux seront stockés
|
logFilePrefix
|
Préfixe à utiliser pour construire les noms des fichiers journaux. Les fichiers journaux sont nommés en ajoutant une date au préfixe, comme dans l'exemple suivant où «JOI» est le préfixe:
JOI-2018-02-08.bûche
|
logDuration
|
Nombre de jours de conservation des fichiers journaux avant de les supprimer
|
3.2 Connexion à Salesforce
JOI échange des données avec Salesforce en envoyant des demandes au service Salesforce REST. Les variables de macro répertoriées ci-dessous contiennent les paramètres de configuration permettant de localiser et d’authentifier le service. Notez que le fichier de configuration contient deux versions de ces paramètres: une pour accéder aux données de test et une pour accéder aux données de production. Une version des paramètres doit être commentée, selon que le programme est exécuté pour des tests ou pour une utilisation en production.
Macro variable
|
La description
|
salesforceBaseUrl
|
URL de base utilisée dans la construction de points de terminaison REST
|
salesforceConsumerKey
|
La clé du consommateur
|
salesforceConsumerSecret
|
Secret du consommateur
|
salesforceUsername
|
Nom d'utilisateur
|
mot de passe salesforce
|
Mot de passe
|
salesforceSecurityToken
|
Jeton de sécurité
|
salesforcePayloadFolder
|
Dossier dans lequel stocker les fichiers contenant les données utiles pour les demandes adressées à Salesforce
|
3.3 Connexion à Orion
JOI échange des données avec Orion en envoyant des demandes au service REST d'Orion. Les variables de macro répertoriées ci-dessous contiennent les paramètres de configuration permettant de localiser et d’authentifier le service.
Macro variable
|
La description
|
orionBaseUrl
|
URL de base utilisée dans la construction de points de terminaison REST
|
orionPrincipalUser
|
Utilisateur principal
|
orionAccessKey
|
Clé d'accès
|
orionSecretKey
|
Clef secrète
|
orionPayloadFolder
|
Dossier dans lequel stocker les fichiers contenant les données utiles pour les demandes adressées à Orion
|
orionApiVersion
|
Version de l'API Orion à utiliser lors des requêtes
|
3.4 Offres autorisées
Lors de la publication d'une nouvelle opportunité sur Orion, JOI doit inclure l'identifiant Orion pour l'offre de l'opportunité. Pour faciliter cela, le programme de configuration établit une liste des offres autorisées et les ID Orion qui leur correspondent. Les offres autorisées sont ajoutées à la liste en appelant une macro appelée permettreOffering . La macro prend deux paramètres, le nom de l'offre (texte) et l'ID de l'offre (entier). Voici un exemple qui ajoute trois offres à la liste:
%allowOffering(JMP, 1099);
%allowOffering(JMP Genomics, 1371);
%allowOffering(JMP Clinical, 2131);
3.5 Champs extraits de Salesforce
Pour construire la charge utile d'une demande adressée à Orion, JOI doit extraire des champs spécifiques de cinq tables Salesforce:
- Opportunité
- Compte
- Utilisateur
- Contact
- Offre
Le programme de configuration spécifie les champs qui seront extraits de chacune de ces tables. Pour ce faire, il crée un ensemble de données vide correspondant à chaque table, qui inclut les champs nécessaires à partir de cette table. Voici un exemple qui spécifie les champs nécessaires à partir de la table Account:
data sfAccountVars;
length
Id $255
Orion_Account_ID__c $255
ref4__c $255
Salesgroup__c $255
;
call missing (of _all_);
run;
Des champs supplémentaires peuvent être extraits de la table Account (si cela est nécessaire) en les ajoutant à la liste. longueur déclaration dans l'exemple ci-dessus. Notez que les variables de l'instruction de longueur doivent porter exactement le même nom que les champs de la table Salesforce.
3.6 Valeurs par défaut pour les champs Orion
Certains des champs nécessaires pour publier une opportunité sur Orion sont définis sur les valeurs par défaut plutôt que sur les données obtenues à partir de Salesforce. Ces champs ont la même valeur pour chaque opportunité postée sur Orion. Le programme de configuration spécifie les valeurs qui seront utilisées pour ces champs en les affectant aux variables de macro suivantes:
|
Macro variable
|
Champ d'Orion
|
|
defaultStrategicInitiativeId
|
|
|
defaultType
|
/ root / opportunité / type
|
|
defaultInputSourceType
|
/ root / opportunite / inputSourceType
|
|
defaultMultinationalDeal
|
|
|
defaultComitCreate
|
|
|
defaultRoleId
|
|
|
defaultCustBusObjId
|
/ root / opportunité / customerBusinessObjectiveId
|
|
defaultCustBusObjGroupCode
|
/ root / opportunite / customerBusinessObjectiveGroupCode
|
|
defaultLikelihoodToCloseId
|
/ root / opportunité / vraisemblanceToCloseId
|
|
defaultMarkedPrivate
|
/ root / opportunité / marquéPrivé
|
3.7 Règles de mappage
Le programme de configuration comprend un ensemble de règles de mappage qui définissent la structure JSON qui sera utilisée pour la charge utile Orion, ainsi que les données qui seront utilisées pour renseigner la structure JSON. Trois macros sont utilisées dans la création de règles de mappage, mapJsonObject , mapJsonArray , et mapJsonProperty . L'ensemble complet de règles est défini par une séquence d'appels à ces macros. Des détails sur l’utilisation des macros de règles de mappage figurent à la section 4.
3.8 Filtre de traitement pour les tests
Le programme de configuration fournit un filtre de traitement pouvant être utilisé lors des tests pour limiter le traitement à un sous-ensemble spécifié d'opportunités. Le filtre est activé en attribuant une clause de condition à la opportunisteListeFiltre variable macro. L'exemple de filtre suivant limite le traitement à l'opportunité avec l'ID = '00629000002SiZnAAK':
%let opportunityListFilter=id%str(=)%str(%')00629000002SiZnAAK%str(%');
Notez que les caractères spéciaux doivent être masqués avec le % str fonction, comme indiqué ci-dessus.
Le filtre de traitement doit être défini sur vide lors de l'utilisation en production de JOI, comme dans l'exemple suivant:
%let opportunityListFilter=;
4 règles de cartographie
Les règles de mappage permettent de définir la structure JSON nécessaire à la charge utile Orion (c'est-à-dire les données envoyées à Orion pour publier une nouvelle opportunité). Les règles de mappage définissent les éléments de la structure JSON et les données utilisées pour renseigner chaque élément.
Il existe trois types d'éléments qui peuvent être définis avec une règle de mappage et ils correspondent aux trois macros utilisées pour créer des règles:
|
Type d'élément
|
Nom de la macro
|
Syntaxe d'appel
|
|
Objet conteneur
|
mapJsonObject
|
% mapJsonObject (
parent = <élément parent>,
clé =
)
|
|
Tableau
|
mapJsonArray
|
% mapJsonArray (
parent = <élément parent>,
clé = ,
arraySource =
)
|
|
Propriété
|
mapJsonProperty
|
Syntaxe 1:
% mapJsonProperty (
parent = <élément parent>,
clé = ,
valeur =
)
Syntaxe 2:
% mapJsonProperty (
parent = <élément parent>,
clé = ,
valueSource = |
)
4.1 Mappage d'objets de conteneur
Les conteneurs en JSON sont désignés par des accolades entourant les éléments contenus. Toutes les structures JSON incluent au moins un conteneur, c'est-à-dire le conteneur de niveau supérieur (appelé «/ root»). D'autres conteneurs peuvent être imbriqués dans le conteneur racine ou dans d'autres conteneurs imbriqués. Le conteneur racine ne nécessite pas de règle de mappage dans JOI, mais tous les conteneurs imbriqués en ont besoin. Considérez l'exemple JSON suivant, qui inclut trois conteneurs imbriqués (texte en gras).
{
"opportunity": {
"accountId": 5110985,
"amount": 530000,
},
"salesGroup": "JP",
"comit": {
"firstPeriodTerm": null,
"dealLength": null,
"form": {
"mlaNeeded": null,
"supplementNeeded": false,
},
}
}
Les règles de mappage pour cet exemple incluraient trois appels à la mapJsonObject macro. Chaque appel spécifierait la clé d'un élément conteneur et le parent sous lequel il est imbriqué, en utilisant la syntaxe suivante:
%mapJsonObject(
parent=<parent element>,
key=<element key>
);
L'argument parent est spécifié à l'aide d'une syntaxe similaire à celle d'un chemin de dossier Linux, où les barres obliques sont utilisées pour séparer les éléments de chemin. Ainsi, les conteneurs imbriqués dans l'exemple ci-dessus pourraient être mappés avec les trois appels de macro suivants:
%mapJsonObject (parent=/root, key=opportunity);
%mapJsonObject (parent=/root, key=comit);
%mapJsonObject (parent=/root/comit, key=form);
4.2 Tableaux de mappage
Les tableaux en JSON sont désignés par des crochets entourant les éléments du tableau. JOI construit un tableau en créant d’abord un jeu de données SAS contenant les enregistrements, les champs et les valeurs nécessaires pour remplir le tableau, puis en utilisant le jeu de données en tant que tableauSource argument dans une règle de mappage.
L'exemple JSON ci-dessous comprend un tableau (texte en gras) contenant deux objets, chacun contenant trois éléments. Notez que la structure du tableau est similaire à un ensemble de données SAS contenant deux enregistrements et trois champs:
{
"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,
}
Les règles de mappage pour cet exemple incluraient un appel à la mapJsonArray macro. En utilisant la syntaxe indiquée ci-dessous, l'appel spécifierait la clé de l'élément de tableau, le parent sous lequel il est imbriqué et un ensemble de données qui contiendra les données utilisées pour remplir le tableau:
%mapJsonArray(
parent=<parent element>,
key=<element key>,
key=<dataset identifier>
);
Le tableau de l'exemple ci-dessus peut être mappé avec l'appel de macro suivant:
%mapJsonArray (parent=/root, key=ips, arraySource=opportunityIpsJson);
Pour que cette règle de mappage fonctionne, JOI devrait créer le jeu de données indiqué avant de construire la charge utile Orion. (Notez que la création de jeux de données de tableau est gérée par le createJsonComponentDatasets macro). Pour l'exemple JSON présenté ci-dessus, JOI aurait besoin de créer un ensemble de données contenant les enregistrements, champs, et valeurs:
|
employéId
|
roleId
|
territoireId
|
|
123
|
123_role
|
123_territory
|
|
234
|
234_role
|
234_territory
|
Notez que les éléments d'un tableau ne nécessitent pas de règles de mappage distinctes dans JOI. Le contenu du tableau est entièrement défini par les données de l'ensemble de données SAS. Pour l'exemple JSON ci-dessus, il ne serait pas nécessaire de spécifier des règles de mappage pour employéId , roleID , ou territoireId .
4.3 Propriétés de mappage
Les éléments JSON les plus simples à créer sont appelés propriétés. Chaque propriété est une paire clé-valeur. JOI requiert des règles de mappage pour toutes les propriétés non contenues dans des tableaux. L'exemple JSON suivant inclut huit propriétés nécessitant des règles de mappage (texte en vert):
{
"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,
},
}
}
Les règles de mappage pour cet exemple incluraient huit appels à la mapJsonProperty macro. Comme indiqué ci-dessous, il existe deux façons d'appeler cette macro, en fonction de l'obtention de la valeur pour la paire clé-valeur:
Syntaxe 1:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
value=<value>
);
Syntaxe 2:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
valueSource=<value source>
);
La première syntaxe est utilisée lorsque la valeur affectée est une valeur littérale ou une valeur contenue dans une variable macro, comme dans les exemples suivants:
%mapJsonProperty (parent=/root/opportunity, key=accountId, value="5110985");
%mapJsonProperty (parent=/root/opportunity, key=comitCreate, value=&defaultcomitCreate);
La deuxième syntaxe est utilisée lorsque la valeur attribuée est obtenue à partir d'une variable salesforce ou en exécutant une macro SAS, comme dans les exemples suivants:
%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/comit, key=dealLength, valueSource=macro:assignDealLength);
Les propriétés nécessitant des règles de mappage dans l'exemple ci-dessus peuvent être mappées avec les huit appels de macro suivants:
%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);
