Istituto SAS
|
JMP Orion Integration (JOI)
Documentazione
|
3 aprile 2018
|
Versione 2.0
|
d-Wise Technologies, Inc
www.d-wise.com
1500 Dr. Perimeter Park
Morrisville, NC 27650
lifesciences@d-wise.com
+1.919.600.6230
|
|
Contenuto
1 Esecuzione
2 Impostazioni dell'ambiente
3 File di configurazione
3.1 Registrazione
3.2 Connessione a Salesforce
3.3 Connessione a Orion
3.4 Offerte consentite
3.5 Campi recuperati da Salesforce
3.6 Valori predefiniti per i campi di Orion
3.7 Regole di mappatura
3.8 Elaborazione del filtro per i test
4 Regole di mappatura
4.1 Mappatura degli oggetti contenitore
4.2 Mapping Array
4.3 Proprietà di mappatura
1 Esecuzione
JOI viene avviato eseguendo un file batch denominato joi.bat . Il file batch naviga nella cartella del programma JOI ed esegue il programma JOI principale. Di seguito è riportato un esempio dei contenuti del file batch:
Per l'uso produttivo di JOI, il programma deve essere eseguito ripetutamente a intervalli specificati, ad esempio ogni 5 minuti. Questo può essere ottenuto utilizzando un programma di pianificazione (come l'Utilità di pianificazione di Windows) per impostare un'attività ricorrente che esegue il file batch.
2 Impostazioni dell'ambiente
Le impostazioni dell'ambiente JOI vengono mantenute in un programma SAS separato denominato joi_environment_settings.sas . Questo programma deve trovarsi nella stessa cartella del programma JOI principale. Viene eseguito dal programma principale tramite un'istruzione% include.
L'unica impostazione dell'ambiente necessaria per JOI è identificare la cartella radice in cui è installato JOI. L'impostazione viene specificata assegnando la cartella a una variabile macro denominata radice , come nell'esempio seguente:
% lascia root = C: \ Users \ dhopkins \ Documents \ Projects \ SAS_Institute \ JOI \ 2.0;
3 file di configurazione
Le impostazioni di configurazione JOI vengono mantenute in un programma SAS separato denominato joi_config_settings.sas . Questo programma deve trovarsi nella stessa cartella del programma JOI principale. Viene eseguito dal programma principale tramite un'istruzione% include.
Le impostazioni di configurazione consentono di modificare molti aspetti del comportamento di JOI senza modifiche ai programmi principali. Le impostazioni di configurazione includono queste aree:
- Registrazione
- Connessione a Salesforce
- Connessione a Orion
- Offerte consentite
- Campi recuperati da Salesforce
- Valori predefiniti per i campi di Orion
- Regole di mappatura
- Filtro di elaborazione
3.1 Registrazione
Quando viene eseguito JOI, registra le informazioni di elaborazione in un file di registro. I file di registro vengono ruotati, ovvero JOI crea un nuovo file di registro ogni giorno in cui viene eseguito ed elimina i file di registro più vecchi di un numero specificato di giorni. Le seguenti variabili macro contengono le impostazioni di configurazione relative alla registrazione:
Macro Variabile
|
Descrizione
|
LogFolder
|
Cartella in cui verranno archiviati i file di registro
|
logFilePrefix
|
Prefisso da utilizzare nella costruzione dei nomi dei file di registro. I file di registro sono nominati aggiungendo una data al prefisso, come nel seguente esempio in cui "JOI" è il prefisso:
JOI-2018/02/08.ceppo
|
logDuration
|
Numero di giorni per conservare i file di registro prima di eliminarli
|
3.2 Connessione a Salesforce
JOI scambia dati con Salesforce inviando richieste al servizio REST di Salesforce. Le variabili macro elencate di seguito contengono le impostazioni di configurazione utilizzate per individuare e autenticare il servizio. Si noti che il file di configurazione contiene due versioni di queste impostazioni: una per accedere ai dati di test e una per accedere ai dati di produzione. Una versione delle impostazioni dovrebbe essere commentata, a seconda se il programma è in esecuzione per il test o per l'uso di produzione.
Macro Variabile
|
Descrizione
|
salesforceBaseUrl
|
URL di base utilizzato nella costruzione degli endpoint REST
|
salesforceConsumerKey
|
Chiave del consumatore
|
salesforceConsumerSecret
|
Segreto dei consumatori
|
salesforceUsername
|
Nome utente
|
salesforcePassword
|
Parola d'ordine
|
salesforceSecurityToken
|
Token di sicurezza
|
salesforcePayloadFolder
|
Cartella in cui archiviare i file contenenti payload per le richieste a Salesforce
|
3.3 Connessione a Orion
JOI scambia dati con Orion inviando richieste al servizio Orion REST. Le variabili macro elencate di seguito contengono le impostazioni di configurazione utilizzate per individuare e autenticare il servizio.
Macro Variabile
|
Descrizione
|
orionBaseUrl
|
URL di base utilizzato nella costruzione degli endpoint REST
|
orionPrincipalUser
|
Utente principale
|
orionAccessKey
|
Chiave di accesso
|
orionSecretKey
|
Chiave segreta
|
orionPayloadFolder
|
Cartella in cui archiviare i file contenenti payload per le richieste a Orion
|
orionApiVersion
|
Versione dell'API Orion da utilizzare quando si effettuano richieste
|
3.4 Offerte consentite
Quando si pubblica una nuova opportunità per Orion, JOI deve includere l'ID Orion per l'offerta dell'opportunità. Per facilitare questo, il programma di configurazione imposta un elenco di offerte consentite e gli ID Orion che corrispondono a loro. Le offerte consentite vengono aggiunte all'elenco richiamando una macro chiamata allowOffering . La macro accetta due parametri, il nome dell'offerta (testo) e l'ID dell'offerta (intero). Di seguito è riportato un esempio che aggiunge tre offerte all'elenco:
%allowOffering(JMP, 1099);
%allowOffering(JMP Genomics, 1371);
%allowOffering(JMP Clinical, 2131);
3.5 Campi recuperati da Salesforce
Per costruire il carico utile per una richiesta a Orion, JOI deve recuperare campi specifici da cinque tabelle Salesforce:
- Opportunità
- account
- Utente
- Contatto
- Offerta
Il programma di configurazione specifica i campi che verranno recuperati da ciascuna di queste tabelle. Lo fa creando un dataset vuoto corrispondente a ciascuna tabella, che include i campi necessari da quella tabella. Di seguito è riportato un esempio che specifica i campi necessari dalla tabella Account:
data sfAccountVars;
length
Id $255
Orion_Account_ID__c $255
ref4__c $255
Salesgroup__c $255
;
call missing (of _all_);
run;
Campi aggiuntivi possono essere recuperati dalla tabella Account (se necessario) aggiungendoli al lunghezza dichiarazione nell'esempio sopra. Si noti che le variabili nell'istruzione della lunghezza devono avere esattamente gli stessi nomi dei campi nella tabella Salesforce.
3.6 Valori predefiniti per i campi di Orion
Alcuni dei campi necessari per pubblicare un'opportunità su Orion sono impostati su valori predefiniti, anziché su dati ottenuti da Salesforce. Questi campi hanno lo stesso valore per ogni opportunità pubblicata su Orion. Il programma di configurazione specifica i valori che verranno utilizzati per questi campi, assegnandoli alle seguenti variabili macro:
|
Macro Variabile
|
Orion Field
|
|
defaultStrategicInitiativeId
|
|
|
DefaultType
|
/ Root / opportunità / tipo
|
|
defaultInputSourceType
|
/ Root / opportunità / inputSourceType
|
|
defaultMultinationalDeal
|
|
|
defaultComitCreate
|
|
|
defaultRoleId
|
|
|
defaultCustBusObjId
|
/ Root / opportunità / customerBusinessObjectiveId
|
|
defaultCustBusObjGroupCode
|
/ Root / opportunità / customerBusinessObjectiveGroupCode
|
|
defaultLikelihoodToCloseId
|
/ Root / opportunità / likelihoodToCloseId
|
|
defaultMarkedPrivate
|
/ Root / opportunità / markedPrivate
|
3.7 Regole di mappatura
Il programma di configurazione include una serie di regole di mapping che definiscono la struttura JSON che verrà utilizzata per il payload Orion e i dati che verranno utilizzati per popolare la struttura JSON. Tre macro sono utilizzate nella creazione di regole di mappatura, mapJsonObject , mapJsonArray , e mapJsonProperty . Il set completo di regole è impostato da una sequenza di chiamate a queste macro. I dettagli su come utilizzare le macro delle regole di mappatura sono riportati nella sezione 4.
3.8 Filtro di elaborazione per i test
Il programma di configurazione fornisce un filtro di elaborazione che può essere utilizzato durante il test per limitare l'elaborazione a un sottoinsieme di opportunità specificato. Il filtro è abilitato assegnando una clausola di condizione al opportunityListFilter variabile macro. Il seguente esempio di filtro limita l'elaborazione all'opportunità con ID = '00629000002SiZnAAK':
%let opportunityListFilter=id%str(=)%str(%')00629000002SiZnAAK%str(%');
Nota che i caratteri speciali dovrebbero essere mascherati con il % str funzione, come mostrato sopra.
Il filtro di elaborazione deve essere impostato su bianco durante l'uso di produzione di JOI, come nell'esempio seguente:
%let opportunityListFilter=;
4 regole di mappatura
Le regole di mappatura vengono utilizzate per definire la struttura JSON necessaria per il payload Orion (ovvero i dati inviati a Orion per pubblicare una nuova opportunità). Le regole di mappatura definiscono gli elementi nella struttura JSON e i dati utilizzati per popolare ciascun elemento.
Esistono tre tipi di elementi che possono essere definiti con una regola di mappatura e corrispondono ai tre macro utilizzati per creare le regole:
|
Tipo di elemento
|
Nome macro
|
Chiama sintassi
|
|
Oggetto contenitore
|
mapJsonObject
|
% MapJsonObject (
genitore = ,
chiave =
);
|
|
schieramento
|
mapJsonArray
|
% MapJsonArray (
genitore = ,
chiave = ,
arraySource =
);
|
|
Proprietà
|
mapJsonProperty
|
Sintassi 1:
% MapJsonProperty (
genitore = ,
chiave = ,
value =
);
Sintassi 2:
% MapJsonProperty (
genitore = ,
chiave = ,
valueSource =
);
|
4.1 Mappatura degli oggetti contenitore
I contenitori in JSON sono designati da parentesi graffe che racchiudono gli elementi contenuti. Tutte le strutture JSON includono almeno un contenitore, cioè il contenitore di livello superiore (chiamato "/ root"). Altri contenitori possono essere nidificati all'interno del contenitore radice o all'interno di altri contenitori nidificati. Il contenitore radice non richiede una regola di mappatura in JOI, ma tutti i contenitori nidificati lo fanno. Considera il seguente esempio JSON, che include tre contenitori annidati (testo in grassetto).
{
"opportunity": {
"accountId": 5110985,
"amount": 530000,
},
"salesGroup": "JP",
"comit": {
"firstPeriodTerm": null,
"dealLength": null,
"form": {
"mlaNeeded": null,
"supplementNeeded": false,
},
}
}
Le regole di mappatura per questo esempio includeranno tre chiamate al mapJsonObject macro. Ogni chiamata dovrebbe specificare la chiave di un elemento contenitore e il genitore in base al quale è nidificata, usando la seguente sintassi:
%mapJsonObject(
parent=<parent element>,
key=<element key>
);
L'argomento principale viene specificato utilizzando una sintassi simile a un percorso di cartella linux, in cui vengono utilizzate le barre di avanzamento per separare gli elementi del percorso. Quindi i contenitori nidificati nell'esempio precedente potrebbero essere mappati con le seguenti tre macro chiamate:
%mapJsonObject (parent=/root, key=opportunity);
%mapJsonObject (parent=/root, key=comit);
%mapJsonObject (parent=/root/comit, key=form);
4.2 Mapping Array
Le matrici in JSON sono indicate da parentesi quadre che racchiudono gli elementi dell'array. JOI crea un array creando innanzitutto un set di dati SAS contenente i record, i campi e i valori necessari per popolare l'array, quindi utilizzando il set di dati come arraySource argomento in una regola di mappatura.
L'esempio JSON qui sotto include un array (testo in grassetto) che contiene due oggetti, ognuno dei quali contiene tre elementi. Si noti che la struttura dell'array è simile a un set di dati SAS contenente due record e tre campi:
{
"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,
}
Le regole di mappatura per questo esempio includeranno una chiamata al mapJsonArray macro. Usando la sintassi mostrata di seguito, la chiamata specificherà la chiave dell'elemento array, il genitore sotto il quale è nidificata e un set di dati che conterrà i dati utilizzati per popolare l'array:
%mapJsonArray(
parent=<parent element>,
key=<element key>,
key=<dataset identifier>
);
La matrice nell'esempio sopra potrebbe essere mappata con la seguente macro chiamata:
%mapJsonArray (parent=/root, key=ips, arraySource=opportunityIpsJson);
Affinché questa regola di mappatura funzioni, JOI dovrebbe creare il set di dati indicato prima di costruire il payload Orion. (Si noti che la creazione di serie di dati dell'array è gestita dal createJsonComponentDatasets macro). Per l'esempio JSON mostrato sopra, JOI avrebbe bisogno di creare un set di dati che contenga i seguenti record, campi, e valori:
|
Numero Identità dell'impiegato
|
ID ruolo
|
TerritoryID
|
|
123
|
123_role
|
123_territory
|
|
234
|
234_role
|
234_territory
|
Si noti che gli elementi all'interno di un array non richiedono regole di mappatura separate in JOI. Il contenuto dell'array è completamente definito dai dati nel set di dati SAS. Per l'esempio JSON sopra, non ci sarebbe alcuna necessità di specificare le regole di mappatura per Numero Identità dell'impiegato , ID ruolo , o TerritoryID .
4.3 Proprietà di mappatura
Gli elementi JSON più semplici da creare sono chiamati proprietà. Ogni proprietà è una coppia chiave-valore. JOI richiede regole di mappatura per tutte le proprietà che non sono contenute negli array. Il seguente esempio JSON include otto proprietà che richiedono regole di mappatura (testo 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,
},
}
}
Le regole di mappatura per questo esempio includeranno otto chiamate al mapJsonProperty macro. Come mostrato sotto, ci sono due modi per chiamare questa macro, a seconda di come si ottiene il valore per la coppia chiave-valore:
Sintassi 1:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
value=<value>
);
Sintassi 2:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
valueSource=<value source>
);
La prima sintassi viene utilizzata quando il valore assegnato è un valore letterale o un valore contenuto in una variabile macro, come nei seguenti esempi:
%mapJsonProperty (parent=/root/opportunity, key=accountId, value="5110985");
%mapJsonProperty (parent=/root/opportunity, key=comitCreate, value=&defaultcomitCreate);
La seconda sintassi viene utilizzata quando il valore assegnato viene ottenuto da una variabile Salesforce o eseguendo una macro SAS, come nei seguenti esempi:
%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/comit, key=dealLength, valueSource=macro:assignDealLength);
Le proprietà che richiedono le regole di mappatura nell'esempio precedente potrebbero essere mappate con le seguenti otto macro chiamate:
%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);
