SAS Institute
|
JMP Orion Integration (JOI)
Dokumentation
|
3. April 2018
|
Version 2.0
|
d-Wise Technologies, Inc
www.d-wise.com
1500 Perimeter Park Dr.
Morrisville, NC 27650
lifesciences@d-wise.com
+1.919.600.6230
|
|
Inhalt
1 Ausführung
2 Umgebungseinstellungen
3 Konfigurationsdatei
3.1 Protokollierung
3.2 Verbindung zu Salesforce
3.3 Verbindung zum Orion
3.4 Zulässige Angebote
3.5 Von Salesforce abgerufene Felder
3.6 Standardwerte für Orion-Felder
3.7 Zuordnungsregeln
3.8 Verarbeitungsfilter zum Testen
4 Zuordnungsregeln
4.1 Containerobjekte zuordnen
4.2 Arrays zuordnen
4.3 Zuordnungseigenschaften
1 Ausführung
JOI wird durch Ausführen einer Batchdatei mit dem Namen gestartet joi.bat . Die Batch-Datei navigiert zum JOI-Programmordner und führt das Haupt-JOI-Programm aus. Unten finden Sie ein Beispiel für den Inhalt der Batchdatei:
Für die Produktionsanwendung von JOI muss das Programm in festgelegten Intervallen, z. B. alle 5 Minuten, wiederholt ausgeführt werden. Dies kann erreicht werden, indem ein Zeitplanungsprogramm (z. B. der Windows-Taskplaner) zum Einrichten einer sich wiederholenden Task verwendet wird, mit der die Batchdatei ausgeführt wird.
2 Umgebungseinstellungen
Die JOI-Umgebungseinstellungen werden in einem separaten SAS-Programm mit dem Namen gespeichert joi_environment_settings.sas . Dieses Programm muss sich im selben Ordner wie das Hauptprogramm von JOI befinden. Es wird vom Hauptprogramm über eine% include-Anweisung ausgeführt.
Die einzige Umgebungseinstellung, die für JOI erforderlich ist, besteht darin, den Stammordner zu identifizieren, in dem JOI installiert ist. Die Einstellung wird festgelegt, indem der Ordner einer Makrovariablen mit dem Namen zugewiesen wird Wurzel wie im folgenden Beispiel:
% let root = C: \ Benutzer \ dhopkins \ Dokumente \ Projekte \ SAS_Institute \ JOI \ 2.0;
3 Konfigurationsdatei
Die JOI-Konfigurationseinstellungen werden in einem separaten SAS-Programm mit dem Namen gespeichert joi_config_settings.sas . Dieses Programm muss sich im selben Ordner wie das Hauptprogramm von JOI befinden. Es wird vom Hauptprogramm über eine% include-Anweisung ausgeführt.
Mit den Konfigurationseinstellungen können viele Aspekte des JOI-Verhaltens geändert werden, ohne dass Änderungen an den Kernprogrammen vorgenommen werden müssen. Die Konfigurationseinstellungen umfassen folgende Bereiche:
- Protokollierung
- Verbindung zu Salesforce
- Verbindung zum Orion
- Zulässige Angebote
- Von Salesforce abgerufene Felder
- Standardwerte für Orion-Felder
- Zuordnungsregeln
- Verarbeitungsfilter
3.1 Protokollierung
Wenn JOI ausgeführt wird, werden die Verarbeitungsinformationen in einer Protokolldatei protokolliert. Die Protokolldateien werden gedreht, dh JOI erstellt an jedem Tag, an dem es ausgeführt wird, eine neue Protokolldatei und löscht Protokolldateien, die älter als eine festgelegte Anzahl von Tagen sind. Die folgenden Makrovariablen enthalten Konfigurationseinstellungen für die Protokollierung:
Makrovariable
|
Beschreibung
|
logFolder
|
Ordner, in dem die Protokolldateien gespeichert werden
|
logFilePrefix
|
Präfix für die Erstellung der Namen von Protokolldateien. Protokolldateien werden benannt, indem dem Präfix ein Datum hinzugefügt wird, wie im folgenden Beispiel, in dem „JOI“ das Präfix ist:
JOI-2018-02-08.Log
|
logDuration
|
Anzahl der Tage, die Protokolldateien aufbewahrt werden sollen, bevor sie gelöscht werden
|
3.2 Verbindung zu Salesforce
JOI tauscht Daten mit Salesforce aus, indem Anforderungen an den Salesforce-REST-Service gesendet werden. Die unten aufgeführten Makrovariablen enthalten Konfigurationseinstellungen, mit denen der Dienst gesucht und authentifiziert wird. Beachten Sie, dass die Konfigurationsdatei zwei Versionen dieser Einstellungen enthält: eine für den Zugriff auf Testdaten und eine für den Zugriff auf Produktionsdaten. Eine Version der Einstellungen sollte auskommentiert werden, je nachdem, ob das Programm zum Testen oder zur Verwendung in der Produktion ausgeführt wird.
Makrovariable
|
Beschreibung
|
salesforceBaseUrl
|
Basis-URL, die beim Erstellen von REST-Endpunkten verwendet wird
|
salesforceConsumerKey
|
Verbraucherschlüssel
|
salesforceConsumerSecret
|
Verbrauchergeheimnis
|
salesforceUsername
|
Nutzername
|
salesforcePassword
|
Passwort
|
salesforceSecurityToken
|
Sicherheitstoken
|
salesforcePayloadFolder
|
Ordner, in dem Dateien mit Nutzdaten für Anforderungen an Salesforce gespeichert werden
|
3.3 Verbindung zum Orion
JOI tauscht Daten mit Orion aus, indem Anforderungen an den Orion REST-Service gesendet werden. Die unten aufgeführten Makrovariablen enthalten Konfigurationseinstellungen, mit denen der Dienst gesucht und authentifiziert wird.
Makrovariable
|
Beschreibung
|
orionBaseUrl
|
Basis-URL, die beim Erstellen von REST-Endpunkten verwendet wird
|
orionPrincipalUser
|
Hauptbenutzer
|
orionAccessKey
|
Zugangsschlüssel
|
orionSecretKey
|
Geheimer Schlüssel
|
orionPayloadFolder
|
Ordner, in dem Dateien mit Nutzdaten für Anfragen an Orion gespeichert werden
|
orionApiVersion
|
Version der Orion-API, die für Anfragen verwendet werden soll
|
3.4 Zulässige Angebote
Wenn Sie eine neue Opportunity an Orion senden, muss JOI die Orion-ID für das Angebot der Opportunity angeben. Um dies zu vereinfachen, erstellt das Konfigurationsprogramm eine Liste der zulässigen Angebote und der dazugehörigen Orion-IDs. Zulässige Angebote werden der Liste durch Aufrufen eines aufgerufenen Makros hinzugefügt allowOffering . Das Makro akzeptiert zwei Parameter, den Namen des Angebots (Text) und die ID des Angebots (Ganzzahl). Das folgende Beispiel fügt der Liste drei Angebote hinzu:
%allowOffering(JMP, 1099);
%allowOffering(JMP Genomics, 1371);
%allowOffering(JMP Clinical, 2131);
3.5 Von Salesforce abgerufene Felder
Um die Nutzdaten für eine Anfrage an Orion zu erstellen, muss JOI bestimmte Felder aus fünf Salesforce-Tabellen abrufen:
- Gelegenheit
- Konto
- Nutzer
- Kontakt
- Angebot
Das Konfigurationsprogramm gibt die Felder an, die aus jeder dieser Tabellen abgerufen werden. Dazu wird ein leerer Datensatz für jede Tabelle erstellt, der die von dieser Tabelle benötigten Felder enthält. Im Folgenden finden Sie ein Beispiel, in dem die aus der Kontotabelle benötigten Felder angegeben sind:
data sfAccountVars;
length
Id $255
Orion_Account_ID__c $255
ref4__c $255
Salesgroup__c $255
;
call missing (of _all_);
run;
Zusätzliche Felder können aus der Account-Tabelle abgerufen werden (falls dies erforderlich sein sollte), indem Sie sie der Tabelle hinzufügen Länge Anweisung im obigen Beispiel. Beachten Sie, dass die Variablen in der Längenangabe exakt dieselben Namen haben müssen wie die Felder in der Salesforce-Tabelle.
3.6 Standardwerte für Orion-Felder
Einige der Felder, die zum Senden einer Opportunity an Orion erforderlich sind, sind auf Standardwerte festgelegt und nicht auf Daten, die von Salesforce abgerufen wurden. Diese Felder haben für jede auf Orion veröffentlichte Opportunity den gleichen Wert. Das Konfigurationsprogramm gibt die Werte an, die für diese Felder verwendet werden, indem sie den folgenden Makrovariablen zugewiesen werden:
|
Makrovariable
|
Orion Field
|
|
defaultStrategicInitiativeId
|
|
|
defaultType
|
/ root / chance / typ
|
|
defaultInputSourceType
|
/ root / chance / inputSourceType
|
|
defaultMultinationalDeal
|
|
|
defaultComitCreate
|
|
|
defaultRoleId
|
|
|
defaultCustBusObjId
|
/ root / chance / customerBusinessObjectiveId
|
|
defaultCustBusObjGroupCode
|
/ root / chance / customerBusinessObjectiveGroupCode
|
|
defaultLikelihoodToCloseId
|
/ root / chance / likelihoodToCloseId
|
|
defaultMarkedPrivate
|
/ root / chance / markedPrivate
|
3.7 Zuordnungsregeln
Das Konfigurationsprogramm enthält eine Reihe von Zuordnungsregeln, die die JSON-Struktur definieren, die für die Orion-Payload verwendet wird, sowie die Daten, die zum Auffüllen der JSON-Struktur verwendet werden. Bei der Erstellung von Zuordnungsregeln werden drei Makros verwendet. mapJsonObject , mapJsonArray , und mapJsonProperty . Der vollständige Regelsatz wird durch eine Abfolge von Aufrufen dieser Makros erstellt. Einzelheiten zur Verwendung der Zuordnungsregelmakros finden Sie in Abschnitt 4.
3.8 Filter zum Testen verarbeiten
Das Konfigurationsprogramm bietet einen Verarbeitungsfilter, der während des Tests verwendet werden kann, um die Verarbeitung auf eine bestimmte Teilmenge von Opportunities zu beschränken. Der Filter wird durch Zuweisen einer Bedingungsklausel zu aktiviert OpportunityListFilter Makrovariable. Das folgende Filterbeispiel beschränkt die Verarbeitung auf die Opportunity mit der ID '00629000002SiZnAAK':
%let opportunityListFilter=id%str(=)%str(%')00629000002SiZnAAK%str(%');
Beachten Sie, dass Sonderzeichen mit dem maskiert werden sollten % str Funktion, wie oben gezeigt.
Der Verarbeitungsfilter sollte während der produktiven Verwendung von JOI leer sein, wie im folgenden Beispiel dargestellt:
%let opportunityListFilter=;
4 Zuordnungsregeln
Mapping-Regeln werden verwendet, um die JSON-Struktur zu definieren, die für die Orion-Payload erforderlich ist (dh die Daten, die an Orion gesendet werden, um eine neue Opportunity zu veröffentlichen). Die Zuordnungsregeln definieren die Elemente in der JSON-Struktur und die Daten, die zum Auffüllen der einzelnen Elemente verwendet werden.
Es gibt drei Arten von Elementen, die mit einer Zuordnungsregel definiert werden können. Sie entsprechen den drei Makros, die zum Erstellen von Regeln verwendet werden:
|
Elementtyp
|
Makroname
|
Syntax aufrufen
|
|
Containerobjekt
|
mapJsonObject
|
% mapJsonObject (
parent = <übergeordnetes Element>,
key =
);
|
|
Array
|
mapJsonArray
|
% mapJsonArray (
parent = <übergeordnetes Element>,
key = ,
arraySource =
);
|
|
Eigentum
|
mapJsonProperty
|
Syntax 1:
% mapJsonProperty (
parent = <übergeordnetes Element>,
key = ,
Wert =
);
Syntax 2:
% mapJsonProperty (
parent = <übergeordnetes Element>,
key = ,
valueSource =
);
|
4.1 Containerobjekte zuordnen
Container in JSON sind durch geschweifte Klammern gekennzeichnet, die die enthaltenen Elemente einschließen. Alle JSON-Strukturen enthalten mindestens einen Container, dh den Container der obersten Ebene (mit dem Namen "/ root"). Andere Container können im Stammcontainer oder in anderen verschachtelten Containern verschachtelt sein. Für den Stammcontainer ist in JOI keine Zuordnungsregel erforderlich, für alle verschachtelten Container jedoch. Betrachten Sie das folgende JSON-Beispiel, das drei verschachtelte Container enthält (fettgedruckter Text).
{
"opportunity": {
"accountId": 5110985,
"amount": 530000,
},
"salesGroup": "JP",
"comit": {
"firstPeriodTerm": null,
"dealLength": null,
"form": {
"mlaNeeded": null,
"supplementNeeded": false,
},
}
}
Die Zuordnungsregeln für dieses Beispiel umfassen drei Aufrufe von mapJsonObject Makro. Bei jedem Aufruf werden der Schlüssel eines Containerelements und das übergeordnete Element, unter dem es verschachtelt ist, mithilfe der folgenden Syntax angegeben:
%mapJsonObject(
parent=<parent element>,
key=<element key>
);
Das übergeordnete Argument wird in einer Syntax angegeben, die einem Linux-Ordnerpfad ähnelt. Dabei werden Pfadelemente durch Schrägstriche voneinander getrennt. Daher können die verschachtelten Container im obigen Beispiel mit den folgenden drei Makroaufrufen zugeordnet werden:
%mapJsonObject (parent=/root, key=opportunity);
%mapJsonObject (parent=/root, key=comit);
%mapJsonObject (parent=/root/comit, key=form);
4.2 Zuordnen von Arrays
Arrays in JSON sind durch eckige Klammern gekennzeichnet, die die Array-Elemente einschließen. JOI erstellt ein Array, indem zunächst ein SAS-Dataset erstellt wird, das die Datensätze, Felder und Werte enthält, die zum Auffüllen des Arrays erforderlich sind. Anschließend wird das Dataset als verwendet arraySource Argument in einer Zuordnungsregel.
Das folgende JSON-Beispiel enthält ein Array (Fettdruck), das zwei Objekte enthält, von denen jedes drei Elemente enthält. Beachten Sie, dass die Struktur des Arrays einer SAS-Datenmenge ähnelt, die zwei Datensätze und drei Felder enthält:
{
"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,
}
Die Zuordnungsregeln für dieses Beispiel würden einen Aufruf von enthalten mapJsonArray Makro. Unter Verwendung der unten gezeigten Syntax würde der Aufruf den Schlüssel des Array-Elements, das übergeordnete Element, unter dem es verschachtelt ist, und eine Datenmenge angeben, die die zum Auffüllen des Arrays verwendeten Daten enthält:
%mapJsonArray(
parent=<parent element>,
key=<element key>,
key=<dataset identifier>
);
Das Array im obigen Beispiel könnte mit dem folgenden Makroaufruf zugeordnet werden:
%mapJsonArray (parent=/root, key=ips, arraySource=opportunityIpsJson);
Damit diese Zuordnungsregel funktioniert, muss JOI den angegebenen Datensatz vor dem Erstellen der Orion-Nutzdaten erstellen. (Beachten Sie, dass die Erstellung von Array - Datasets vom createJsonComponentDatasets Makro). Für das oben gezeigte JSON-Beispiel müsste JOI ein Dataset erstellen, das die folgenden Datensätze, Felder, und Werte:
|
Mitarbeiter-ID
|
roleId
|
territoriumId
|
|
123
|
123_Rolle
|
123_territory
|
|
234
|
234_rolle
|
234_territory
|
Beachten Sie, dass die Elemente in einem Array in JOI keine separaten Zuordnungsregeln erfordern. Der Array-Inhalt wird vollständig durch die Daten im SAS-Dataset definiert. Für das obige JSON-Beispiel müssen keine Zuordnungsregeln für angegeben werden Mitarbeiter-ID , roleID , oder territoriumId .
4.3 Abbildungseigenschaften
Die am einfachsten zu erstellenden JSON-Elemente werden Eigenschaften genannt. Jede Eigenschaft ist ein Schlüssel-Wert-Paar. Für JOI sind Zuordnungsregeln für alle Eigenschaften erforderlich, die nicht in Arrays enthalten sind. Das folgende JSON-Beispiel enthält acht Eigenschaften, für die Zuordnungsregeln erforderlich sind (grüner Text):
{
"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,
},
}
}
Die Zuordnungsregeln für dieses Beispiel würden acht Aufrufe von enthalten mapJsonProperty Makro. Wie unten gezeigt, gibt es zwei Möglichkeiten, dieses Makro aufzurufen, abhängig davon, wie der Wert für das Schlüssel-Wert-Paar erhalten wird:
Syntax 1:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
value=<value>
);
Syntax 2:
%mapJsonProperty(
parent=<parent element>,
key=<element key>,
valueSource=<value source>
);
Die erste Syntax wird verwendet, wenn der zugewiesene Wert entweder ein Literalwert oder ein in einer Makrovariable enthaltener Wert ist, wie in den folgenden Beispielen gezeigt:
%mapJsonProperty (parent=/root/opportunity, key=accountId, value="5110985");
%mapJsonProperty (parent=/root/opportunity, key=comitCreate, value=&defaultcomitCreate);
Die zweite Syntax wird verwendet, wenn der zugewiesene Wert aus einer Salesforce-Variablen oder durch Ausführen eines SAS-Makros abgerufen wird, wie in den folgenden Beispielen dargestellt:
%mapJsonProperty (parent=/root/opportunity, key=amount, valueSource=salesforce:opportunity.amount__c);
%mapJsonProperty (parent=/root/comit, key=dealLength, valueSource=macro:assignDealLength);
Die Eigenschaften, für die im obigen Beispiel Zuordnungsregeln erforderlich sind, können mit den folgenden acht Makroaufrufen zugeordnet werden:
%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);
