Administrationshandbuch (C11CQ_DNB)

Installation und Konfiguration D&B

Webservice-Version / WSDL / Herstellerdokumentationen

Authentifizierung

• Zur Authentifizierung am der REST-API sind consumer key und consumer secret notwendig. Diese werden durch D&B bereitgestellt.

• Zur Hinterlegung der Authentifizierungsinformationen in CURSOR-CRM stehen globale Variablen bereit

  • C11CQDNBConsumerKey

  • C11CQDNBConsumerSecret

Kennwortablauf, erzwungene Änderung und/oder Sperrregeln sind nicht als Teil dieser API implementiert. Kunden, die das mit einem bestimmten API-Benutzernamen verknüpfte Passwort ändern möchten, sollten sich an den D&B-Kundendienst wenden.

• Token-Management:

  • Die Webservice-Kommunikation basiert auf Authentifizierungstokens. Im Allgemeinen kann nach Erhalt eines Authentifizierungstokens dasselbe Token für alle nachfolgenden Anforderungen für die nächsten 24 Stunden verwendet werden, danach sollte ein neues Token mit dem Authentifizierungsdienst generiert werden.

  • Ein Token wird per REST-Service unter Angabe von ConsumerKey und ConsumerSecret abgefragt und verwendet. 

  • Das Token wird bei Erstabruf generiert und verwendet. Ist es abgelaufen, wird ein entsprechender http-Fehler 401 mit Errorcode zurück übermittelt. In den relevanten Fällen wird versucht, ein neues Token abzufragen und erneut ein Aufruf ausgelöst. Erst wenn der Fehler dann erneut auftritt, wird der User in den Prozess mit entsprechender Hinweismeldung involviert. 

  • Das abgefragte Token wird mittels requestCredentialWithClientCredentialsFlow in der Credentials Tabelle gespeichert und für weitere Webservcieabfragen über createRequest (OAuthUtils) verwendet werden.

 Konfiguration D&B über globale Variablen

Variablenname	Default-Wert	Beschreibung
C11CQDNBConsumerKey		Von Dun and Bradstreet bereitgestellter Consumer Key für die Dun and Bradstreet-Webservices.
C11CQDNBConsumerSecret		Von Dun and Bradstreet bereitgestellter Consumer Secret für die Dun and Bradstreet-Webservices.
C11CQDNBBaseUrl	https://plus.dnb.com	Die Basis-URL von Dun and Bradstreet
C11CQDNBBlockIDs	companyinfo_L2_v1	Liste der Datenblöcke, die über den Dun and Bradstreet Service abgefragt werden sollen. Auf Basis der Kundenanforderung zur Umsetzung der D&B-Integration werden in der ersten Ausbaustufe zunächst definierte Inhalte des Blocks Company Information Level 2 abgefragt und verarbeitet. Diese beinhaltet im Wesentlichen Basisinformationen zu einem Geschäftspartner wie Name, Adresse, Kommunikation etc. Der Abruf weiterer Datenblöcke ist unter Angabe der Datenblock ID in der Variable C11CQDNBBlockIDs möglich und vorgesehen. Allerdings findet keine strukturierte Verarbeitung in das CURSOR-CRM auf die Tabelle Dun & Bradstreet statt.  Lediglich der Payload der Response wird gespeichert. Sofern weitere Datenblöcke abgerufen und strukturiert verarbeitet werden sollen, sprechen Sie bitte Ihre CURSOR-Projektleiterin oder Projektleiter zur weiteren Vorgehensweise an.
C11CQDNBCandidatesMatchedQuantity	20	Maximale Anzahl an Einträgen, die über Dun and Bradstreet geladen und in der Trefferliste zur Auswahl angeboten werden sollen. Der Defaultwert für candidatesMatchedQuantity seitens D&B liegt bei 10. Die fachlichen Tests haben aber gezeigt, dass ein höherer Wert einen besseren Prozessfluss bringt.
C11CQDNBReference		Reference-ID für die Registration um Monitoringabfragen bei Dun and Bradstreet zu ermöglichen
C11CQDNBAddToMonitoringOnNew	false	true: Bei der Neuanlage wird versucht das Monitoring für den angefragten Datensatz zu aktivieren. false: Das Monitoring muss, wenn gewünscht und bei D&B beauftragt, manuell aktiviert werden.

Testbetrieb

Der Testbetrieb ist mit Ihrem D&B-Ansprechpartner abzustimmen.

Der Testbetrieb kann gegen den produktiven D&B Datenbestand erfolgen. In einem Testvertrag wird die Anzahl möglicher Testabrufe und der Abruf definierter DataBlocks definiert. Alle unter dem Record Under Management (RUM) Lizenzmodell laufenden Produkte erzeugen bei mehrfachem Produktabruf keine Mehrkosten, da hierbei Unique DUNS gezählt werden. Das Vorgehen anders definierter Lizenzmodelle ist mit D&B abzustimmen.

Timer für Dunkelverarbeitung

Um den Prozess Dunkelverarbeitung automatisiert starten zu können, muss ein Timer wie folgt konfiguriert werden.

• Name: C11CQDNBAutomaticProcessingStart

• Typ: PROCESS

• Ausführen als: User der CLEARINGSTELLE

• Parameter: <Search Plain Key>
  Über den Parameter kann gesteuert werden, welche Datenmenge zur Dunkelverarbeitung herangezogen werden soll. In der Methode SC11CQUtils.readAutomaticProcessingDatasearch() werden entsprechende Suchen mit ausgeliefert. In diese Liste können weitere Suchen aufgenommen werden (übersteuern in C2). Es ist der PlainKey der Suche zu hinterlegen.

Ausgeliefert werden die Suchen mit den Plainkeys

• Dun and Bradstreet

  • C11CQDNBQualifyNew

  • C11CQDNBQualifyExisting

Zeitplan: kann projektindividuell gewählt werden.

Monitoring

Das Monitoring bietet die Möglichkeit, Benachrichtigungen zu erhalten, wenn Änderungen an Inhalten auftreten, die in bestimmten Datenprodukten und D-U-N-S-Nummern enthalten sind.

Zur Abfrage der Benachrichtigungen (Notifications) wird das Verfahren "Abruf von Notifications via Pull new Notifications und REST-API Abfrage" verwendet. Der Vorteil dieser Variante ist, dass auf eine Bereitstellung und Verarbeitung von Datendateien über ein Fileshare verzichtet werden kann und online erfolgt. Die beschriebene Einschränkung "die Pull-API-Methode sollte nur für Registrierungen bis zu 300.000 D-U-N-S verwendet werden" wurde als gering eingestuft, da derartige Datenmenge im Monitoring Stand heute bei CURSOR-Kunden nicht vorliegt und deutlich geringer sein werden.
Voraussetzung ist, dass die Abfrage von Notifications Minimum alle 4 Tage erfolgen muss, da die Aufbewahrung der Notifications bei D&B max. 4 Tage ist.

Registrierung

Um Nachrichten (Notifications) über das Monitoring zu erhalten, ist eine Registrierung erforderlich. Die D&B Direct+-Überwachungsregistrierung stellt eine Anfrage dar, eine Reihe von D-U-N-S-Nummern mit einem der D&B Direct+-Datenprodukte zu überwachen. Es enthält Einzelheiten darüber, wie Benachrichtigungen zuzustellen sind, bspw. in welchem Zyklus (Daily, weekly) und in welchem Umfang die Notifications übermittelt werden (UPDATE, FULL_PRODUCT). Die zu monitorenden DUNS-Nummern können als ListOfDuns (LOD) direkt bei der Registrierung übermittelt oder nachträglich über die API einer Registrierung zugeführt werden. Bei der Registrierung muss allerdings mindestens eine D-U-N-S-Nr. eingefügt werden.

Bei der Registrierung handelt es sich um keinen automatisierten Prozess oder eine Integration. Die Registrierung muss zwischen dem Endkunden und D&B direkt erfolgen.

Um eine Registrierung zu erstellen, müssen diverse Informationen bereitgestellt werden. Details siehe https://directplus.documentation.dnb.com/html/guides/Monitor/CreateMonitoringRegistration.html
Nachstehend werden einige Rahmenparameter definiert und abgegrenzt, die für den späteren Prozess vom Bedeutung sind.

• Es könnten mehrere Registrationen mit unterschiedlichen Konfigurationen des Monitorings bei D&B abgeschlossen werden.
  In der ersten Ausbaustufe wird genau eine Registrierung im Monitoring aus CURSOR-CRM behandelt. Dies betrifft die Abfrage und Verarbeitung der Daten sowie das An- und Abmelden einer DUNS in der Registrierung.

• Jede Registrierung hat eine eindeutige reference-ID, welche bei den Monitoringabfragen angegeben werden muss. Diese ist in der globalen Variable C11CQDNBReference zu hinterlegen

• Notification Type =  FULL_PRODUCT; hierdurch wird mit jeder Notification der volle Umfang der Produktabfrage zur Verfügung gestellt. Bei der Verarbeitung der Notifications wird daraus im CRM immer ein vollständiger Datensatz C11CQ_DNB zum Geschäftspartner angelegt und mit dem Status AKTUELL markiert. Es findet kein Delta-Abgleich der vorliegenden Änderungen statt.

• Unter Data Block(s) (blockIDs) müssen in der Registrierung die identischen Datablock-IDs angegeben werden, wie in C11CQDNBBlockIDs konfiguriert.

• Die Angabe der Notification Frequency muss später mit dem CRM-Timer synchronisiert werden, damit die Daten rechtzeitig abgefragt und verarbeitet werden können. Empfehlung seitens D&B ist DAILY.
  Da die Aufbewahrung der Notifications bei D&B max. 4 Tage beträgt, ist die Voraussetzung für Pull Notification via API eine tägliche Bereitstellung und Verarbeitung.

• In der Registrierung muss für die API-Abfrage die Abfragevariante mit API_PULL angegeben werden

• In der Registrierung kann Seed File = false angegeben werden, damit auf den File-Transfer komplett verzichtet werden kann.

Registrierung um DUNS erweitern

Die initial in der Registration eingefügten DUNS-Nr. können erweitert werden. Die Erweiterung erfolgt entweder direkt bei Abruf einer Qualifizierung bei D&B und kann über einen manuellen Prozess erfolgen.

• Über die globale Variable C11CQDNBAddToMonitoringOnNew (true / false) kann konfiguriert werden, ob eine durchgeführte Qualifizierungsanfrage immer einen Datensatz der Monitoringliste zuführen soll, oder ob dies über einen manuell auszuführenden Prozess erfolgen soll.

• Wenn C11CQDNBAddToMonitoringOnNew

  • true: mit erfolgreicher Verarbeitung des C11CQDNB Datensatzes wird,

    • Über Check for Subjects in Registration zunächst geprüft, ob eine SubjectID bereits im Monitoring enthalten ist.

    • wenn nicht, wird der Webserviceaufruf AddSingleSubjectToRegistration aufgerufen.

    • Dies gilt für Neuanlage und Nachqualifizierung

    • Wurde der Prozess erfolgreich ausgeführt (in der Response wird http Status 200 und errorcode 21110 übermittelt, siehe auch https://directplus.documentation.dnb.com/errorsAndInformationMessages.html), wird der D&B Datensatz mit im Monitoring = true markiert.

  • false:

    • das hinzufügen / entfernen eines Datensatzes im Monitoring kann über einen Oberflächenprozess manuell ausgeführt werden.

• Über den Schalter "Monitoring Ändern Dun&Bradstreet" in der Aktionsbox der Entität C11CQDNB hat der Anwender die Möglichkeit, einen Datensatz im Monitoring zu ergänzen, oder den Datensatz aus dem Monitoring zu entfernen

  • Zunächst wird via Check for Subjects in Registration der Zustand der Registration abgefragt.

    • Ist die DUNS des Datensatzes bereits enthalten:

      • Es folgte eine Abfrage an den Anwender, ob das Monitoring für den Datensatz deaktiviert werden soll. 
        Ja: Aufruf Remove Single Subject from a LOD Registration

      • Der Feldwert Im Monitoring wird auf false gesetzt

    • Ist nicht enthalten:

      • es erfolgt eine Hinweismeldung an den Anwender

      • Ja: Aufruf AddSingleSubjectToRegistration

      • Der Feldwert Im Monitoring wird auf true gesetzt

Monitoring ausführen

Das Monitoring wird über einen Timer ausgeführt, der in der C2-Schicht herzustellen ist (vgl. Installation und Konfiguration der Geschäftspartnerqualifizierung | Kundenspezifisches-Customizing-(C2) .

Da die Aufbewahrung der Notifications bei D&B max. 4 Tage beträgt, sollte der Timer zur Abfrage auf 1x täglich konfiguriert sein!

Beim Auslösen der Monitoringabfrage werden zunächst nachstehende Vorprüfungen durchgeführt um die Abfrage ausführen zu können.

• Status Monitoring-Registration abfragen

  • Wenn der Status on hold, wird der Status On Hold Notifications / delete zurückgesetzt

  • Wenn der Status suppressed = true, dann wird der Status über Unsuppress Notifications zurückgesetzt

• Kann die Abfrage der Benachrichtigungen nun erfolgen wir der Service Pull new Notifications aufgerufen.

  • Innerhalb einer Abfrage können max. 375 FULL_PRODUCT Abfragen abgefragt werden. Der Prozess wird daher so oft in einer Schleife abgefragt, bis keine weiteren Benachrichtigungen zur Verfügung stehen.

  • Aus der Benachrichtigung heraus werden dann die jeweiligen DUNS-Nr extrahiert und überprüft, ob ein C11CQDNB Datensatz vorliegt.

Da in Version 21.2. noch nicht vollständig auf die Massendatenverarbeitung zurückgegriffen werden kann, können die Ergebniswerte aus der Notification-Response nicht vollständig extrahiert und verarbeitet werden. Daher werden lediglich die DUNS-Nr. extrahiert und damit die Produktabfrage ausgeführt. In zukünftigen Versionen könnte man die Verarbeitung umstellen, und aus der Notification direkt die Verarbeitung der mit übermittelten Daten anpassen. Die Notification beinhaltet aufgrund der Angabe FULL_PRODUKT die vollständige Struktur zur Verarbeitung.

Das Vorgehen ist mit Dun and Bradstreet abgestimmt. Alle unter dem Record Under Management (RUM) Lizenzmodell laufenden Produkte erzeugen bei mehrfachem Produktabruf keine Mehrkosten, da hierbei Unique DUNS gezählt werden. 

• Mittels jeder DUNS-Nr. wird im Anschluss die Produktabfrage je DUNS ausgeführt und die aktuellen DataBlock Informationen abgefragt.

• Analog der Produktabfrage wird ein neuer Datensatz Dun and Bradstreet zum Geschäftspartner erzeugt. Der neu angelegte Datensatz erhält dabei den Status AKTUELL. Bestehende Datensätze werden mit HISTORISCH gekennzeichnet.
  

  • Wenn C11CQDNBAddToMonitoringOnNew = false, und der zu aktualisierende D&B Datensatz IsMonitoring = true, dann wird der Zustand des Monitorings auf den neu angelegten Datensatz übernommen. Andernfalls wird IsMonitoring = true gesetzt.
    

• Die Strukturen der Abfrage Pull new Notifications beinhaltet in der JSON Struktur alle NotificationTypes (Delete, reviewed, under_review, transfer etc.) zur Verarbeitung. Grundsätzlich gilt, dass alle in einer Abfrage enthaltenen Benachrichtigungen unabhängig vom Typ gleich verarbeitet werden. Da Datensätze nur verarbeitet werden, wenn sie als Notification übermittelt werden, stellen die Notificationtypen delete, undelete, exit lediglich eine Momentaufnahme, bzw. den Status des Monitorings bei D&B dar. Da das Monitoring durch den Anwender im CRM jedoch übersteuert werden kann (manuelles Einfügen / Löschen von Monitoring-Einträgen) werden die Natification-Typen nicht weiter verarbeitet. Wird eine Notification übermittelt und ist die DUNS-Nr in EVI hinterlegt, wird die Notfication auch verarbeitet. Es findet kein Abgleich auf IsMonitoring in CURSOR-CRM statt.
  Beispiel: Ist ein Datensatz in CURSOR-CRM als IsMonitoring = true gekennzeichent, wird aber keine Notification geliefert, findet auch keine Verarbeitung statt. Umgekehrt, wird eine Notification geliefert, ist aber der Datensatz in CURSOR-CRM dennoch als IsMonitoring=false gekennzeichnet, wird die Notification dennoch verarbeitet.

• Lediglich bei TRANSFER ist erwähnenswert, dass zu einer bestehenden DUNS im Transfer eine weitere neue DUNS mitgeteilt wird. Hier findet dann dei Produktabfrage mittels der neuen DUNS statt.