Loading

Direct 2.0
Collapse

Getting Started with Monitoring

IMPORTANT: Please see the new Online Services Security Enhancement Release, effective December 14, 2018.

For a given D&B Direct data layer, this feature allows the pre-configuration of D-U-N-S number, data field and change condition/value combinations, along with a method of communicating triggered events. Here are some of the terms used as part of the configuration process:

Monitoring Profiles

A Monitoring Profile establishes the specific data fields within a given data layer that should be monitored, and the conditions under which a change event should be triggered.

There are no fees involved with establishing Monitoring Profiles, and customers may create as many profiles as needed.

User Preferences

A User Preference captures the technical details required to deliver information through various protocols, including Email and HTTP Callback.

User Preferences are created/maintained through the User Service.

Notification Profiles

A Notification Profile establishes the protocol by which change events should be delivered to customers, and references user preferences setup in the User Service. This is the PUSH component of the Data Field Monitoring feature.

There are no fees involved with establishing Notification Profiles, and customers may create as many profiles as needed.

Monitoring Registrations

The Monitoring Registration combines Monitoring and Notification Profiles with a specific D-U-N-S Number and initiates the Data Field Monitoring process. There are two levels of monitoring: change events only, or events with data layer included.

Fees are incurred only when a Monitoring Registration is created and/or upon contract renewal (if the auto-renew option is active).

Change Notices

A Change Notice is triggered whenever a data field for the D-U-N-S Number specified in a Monitoring Registration exceeds the thresholds set in the Monitoring Profile. Copies of Change Notices are delivered based on the Notification Profile and may also be retrieved with the ListChangeNotice operation.

Field Monitoring Setup ('What to Monitor')

Monitoring Profiles may be established for entitled D&B Direct data layers that support the process (as noted in the "Available Products" section), and require a valid product code. These profiles can be assigned a user-generated name and description for reference purposes; however, a unique profile ID will be provided for use in creating Monitoring Registrations and for updating the profile.

In addition to the product code, a level ("Level1" or "Level2") must be selected. Level2 provides change event notices along with a copy of the data layer; while Level1 only provides the notices.

As an option, specific data fields within the data layer can be designated as trigger criteria. If data fields are not specified, any change within the data layer will trigger an event and a Change Notice will be generated. Some data fields may only be monitored by the associated aggregate or attribute XPATH.

When specifying a data field, a change condition and value must also be specified. The possible conditions include: AnyChange, ValueIncreaseByPercentage, ValueDecreaseByPercentage, ValueChangeByPercentage, ValueIncreaseBy, ValueDecreaseBy, ValueChangeBy, ValueGoesBeyond, ValueGoesBelow, ValueEquals, DateChangeBy or DateEquals. Each data field specified as a trigger criteria must have a condition defined, along with a value (unless AnyChange is selected).

NOTE: This is a separate service from the monitoring component of the D&B Compliance √ (check) available via D&B Direct. Business elements delivered by the Compliance API may NOT be included Data Layer/Field Monitoring profiles.

The Monitoring process triggers events based on the old and new data field values WHEN A CHANGE OCCURS, and is not based on the data layer values when the Monitoring Registration was created. To capture cumulative but gradual changes, using the "ValueGoesBeyond" or "ValueGoesBelow" conditions is recommended.

In addition to the Create and Update, a List Monitoring Profiles operation exists.

Monitoring Profiles can be removed by setting the status to "Cancelled"; however, if the profile is referenced in a Monitoring Registration it will not be removed.

Notification Setup ('How Often')

The D&B Direct Monitoring process currently supports notification by Email, HTTP CallBack, IBM WebSphere MQ or Amazon SQS. The actual destination for a given deliver mode is specified in a User Preference (default or named), which is configured using the User Service. Notification Profiles can be assigned a user-generated name and description for reference purposes; however, a unique profile ID will be provided for use in creating Monitoring Registrations and for updating the profile.

A delivery frequency must also be specified for the profile. Available options include: Immediate (when an event is detected), Hourly, Daily, or Weekly.

The delivery of Change Notices can be paused/resumed by updating an indicator on the profile. While a Notification Profile (Push) is required to establish a Monitoring Registration, this pause/resume indicator can be used to disable delivery of all notices, if a customer prefers to obtain notices using the ListChangeNotice operation (Pull).

In addition to the Create and Update, a List Notification Profiles operation exists.

Notification Profiles can be removed by setting the status to "Cancelled"; however, if the profile is referenced in a Monitoring Registration it will not be removed.

User Preferences ('How to Notify')

As a requisite to creating a Notification Profile, a minimum of one default user preference needs to be established. User preferences can have user-generated names, or be designated as the default (i.e. no name), and capture the specific destination for a given delivery protocol. For example, if the preferred notification method is Email, the user preference will contain the actual Email address(es) to be used.

User Preferences can be removed by setting the status to "Cancelled"; however, if the profile is referenced in a Notification Profile it will not be removed.

D-U-N-S Number Registration ('Who to Monitor')

Combines "Who" + "What" + "How to Notify" + "How Often"

The Monitoring process is initiated by the creation of a Monitoring Registration, and requires a minimum of one Monitoring Profile, one Notification Profile (which requires a user preference) and a valid D-U-N-S Number. Monitoring and Notification Profiles can be used in multiple Monitoring Registrations, and in any combination.

When adding a Monitoring Registration, a valid D-U-N-S Number for a company, its country code, and the unique ID's for a Monitoring and Notification profile will be required. A trade up option exists to monitor data for the headquarters when the requested organization is a branch.

NOTE: For Contact products: a valid Principal identification number (Principal ID) is required

When ordering information for organizations located in Germany, you will be required to provide an order reason code.

The volume of resulting change notices is dependent on the product/data field criteria (i.e. Monitoring Profile), volatility of the company being monitored, and the data update frequency (which may vary in certain countries). Change detection is currently based on the latest values as compared to previous values, and therefore is not cumulative from the date of registration.

The Product Availability Lookup feature should be utilized to determine if the D&B Direct product that will monitored is available for a given D-U-N-S Number.

A category field is available that allows user-generated values to be entered. This subject category is included on all related Change Notices.

An auto-renewal indicator is available that allows for a Monitoring Registration to be preserved when an annual contract is renewed.

In addition to the Add and Update, a List Monitoring Registrations operation exists.

Monitoring Registrations can be removed by setting the status to "Cancelled".

Eligible Products

The following is a list of products that may be included in the Monitoring process. Please refer to the Business Element listings for each product to determine which fields may be included in a Monitoring Profile.

NOTE: For Direct Onboard, Monitoring is available only for CST_PRD_3, DCP_PREM, LNK_FF, GBO, CMP_VRF_ID, and CMP_VRF_RPT.

ProductCode
Corporate LinkageLNK_FF, LNK_UPF
Detailed Company ProfileDCP_STD, DCP_PREM
Detailed Company Profile - SDMRDCP_SDMR
Detailed Company Profile - WB1784DCP_WB1784
Alternative Detailed Company ProfileDCP_ALT_STD, DCP_ALT_ENH, DCP_ALT_PREM
Diversity IndicatorsDVR_STD, DVR_ENH
Financial HighlightsFIN_HGLT
Financial StatementsFIN_ST_PLUS
Payment Information & Paydex (Rating) - DetailPIAP_STD, PIAP_ENH, PIAP_PREM
USA PATRIOT Act PlusPAC_PLUS
PeopleCNTCT, CNTCT_PLUS
Predictive Bankruptcy Risk - D&B Financial Stress Score (FSS)PBR_FSS_V7.1
Predictive Payment Risk - D&B Commercial Credit Score (CCS)PPR_CCS_V9
Predictive Bankruptcy & Payment RiskPBPR_STD, PBPR_ENH
Predictive Global Payment Risk - D&B Emerging Market Mediation Alert Score (EMMA)PGPR_EMMA
D&B Supplier Evaluation Risk RatingSER
D&B Total Loss PredictorTLP
D&B Viability RatingVIAB_RAT
Custom ProductsCST_PRD_1 to CST_PRD_6
Global Beneficial OwnershipGBO
Identity Verification & ReportCMP_VRF_ID, CMP_VRF_RPT
Global Supplier RiskSR_GLB
Know Your Vendor - Suits, Liens, and JudgmentsSR_SLJ

Special Cases

The Corporate Linkage data layer may only be monitored at the product code level (i.e. individual Business Elements may NOT be specified), and the change notice will be generated for any change in the entire linkage of the global ultimate parent.

The Financial Statements data layer may only be monitored at the aggregate level and will generate a change notice whenever any line item in a given financial statement changes. The notice does not specify which line items have changed.

Notification Retrieval (Optional)

Change Notices that have occurred within the past sixty days can be retrieved using the ListChangeNotice operation. The format of information available via this (Pull) process differs slightly from the notices that are delivered (Push) automatically. Change Notices for the same D-U-N-S Number and product code (in the Push notification) are bundled together; whereas in the Pull process they are listed separately.

When requesting a list of available Change Notices, up to ten D-U-N-S Numbers, three user-defined subject categories, a product code, level (one or two), and a date range may be included. The results for a single request are limited to the first 1,000 matching notices.

For Change Notices generated by level two monitoring registrations, the related product data may be retrieved using the GetMonitoringProduct operation without incurring any additional usage charges. This operation returns a copy of the product data taken at the time of the most recent change, which will not necessarily be the data available at the date/time when a specific the Change Notice was triggered.

Understanding Change Notices

There are several types of changes that will be reported by the monitoring service: changes in data layers (or a subset thereof) and changes to corporate linkage.

Data Field Changes

Here are a couple of things to be aware of when monitoring a data layer, an aggregate within a data layer, or specific fields within a data layer:

  • The monitoring service will trigger notices whenever the values of fields (as defined by the Monitoring profile) change. This may include the first time the field has a value (NewlyAdded), when it no longer has a value (Dropped), or the value has been modified (ValueChanged).
  • The monitoring change notice may include "changes" for items that fall within the definition of the Monitoring profile, but did not change (No Change). For example, if the MailingAddess is monitored, and the street address changes, but the city and state do not, the change notice will include entries for the city and state.
  • When the condition is ValueChanged or Dropped, the change notice will also include the previous value.
  • When there are multiple occurrences of a field, the sequence will be incorporated into the XPATH (e.g. "/PrimaryAddress[1]/").
  • Multiple change events for a D-U-N-S Number may be clustered into a single change notice when delivered to customer (i.e. PUSH), whereas, they will be separate when using the ListChangeNotice function (i.e. PULL).

Example #1: CEO Change

Company XYZ announces a new CEO: John Smith is replaced by Edward Jones. The business element for the CEO name is Most Senior Principal Full Name. It is part of an aggregate XPATH, therefore all elements of the aggregate will be included in the change notice.

In the change notice, the following items should be examined:

  • SubjectHeader will equal D-U-N-S Number of company XYZ,
  • Multiple elements will be delivered in the change event.
  • The attributes on the element explain the change that has occurred.
  • The outer PCMElementXPATHText represents the aggregate.
  • The inner (attribute) PCMElementXPATHText represents the business element(s).

<ChangeEvent>

<PCMElementXPATHText>//Organization/PrincipalsAndManagement/MostSeniorPrincipal/</PCMElementXPATHText>

<Element ChangeType="ValueChanged" OldValue="John Smith" PCMElementXPATHText="//Organization/PrincipalsAndManagement/MostSeniorPrincipal/PrincipalName/FullName">Edward Jones</Element>

{ all other aggregate elements will be included here }

</ChangeEvent>

Example #2: Change of Address

Company XYZ announces it's headquarters have moved within New York City from 123 E 81st Street, Suite 400 to 200 Park Avenue. These business elements are part of an aggregate. The street address will change, and the suite portion will be dropped. The city and state will be included and reflect no change.

In the change notice, the following items should be examined:

  • SubjectHeader will equal D-U-N-S Number of company XYZ,
  • One or more elements will be delivered in the change event.
  • The attributes on the element explain the change that has occurred.
  • The outer PCMElementXPATHText represents the aggregate.
  • The inner (attribute) PCMElementXPATHText represents the business element(s).

<ChangeEvent>

<PCMElementXPATHText>//Organization/Location/PrimaryAddress</PCMElementXPATHText>

<Element ChangeType="ValueChanged" OldValue="123 E 81st Street" PCMElementXPATHText="//Organization/Location/PrimaryAddress[1]/StreetAddressLine[1]/LineText">200 Park Avenue</Element>

<Element ChangeType="Dropped" OldValue="Suite 400" PCMElementXPATHText="//Organization/Location/PrimaryAddress[1]/StreetAddressLine[2]/LineText" />

<Element ChangeType="NoChange" PCMElementXPATHText="//Organization/Location/PrimaryAddress[1]/PrimaryTownName">New York</Element>

<Element ChangeType="NoChange" PCMElementXPATHText="//Organization/Location/PrimaryAddress[1]/TerritoryAbbreviatedName">NY</Element>

</ChangeEvent>

D-U-N-S Number Retirement (a.k.a. "Deletes")

As a result of database maintenance and normal business activities (mergers, acquisitions, divestitures) it is possible that a D-U-N-S Number assigned to a company may change. To capture these events, customers should monitor the //Organization/SubjectHeader/TransferDUNSNumberRegistration/TransferredToDUNSNumber XPATH available in the Detailed Company Profile data layers.

If/when a D-U-N-S Number is retired (or "deleted") from D&B's database, a change notice will be triggered with the new "retained" D-U-N-S Number (TransferredToDUNSNumber), the date of the event (TransferReasonText), and a reason that explains the type of event (TransferDate). The new D-U-N-S Number will not be registered automatically in the monitoring engine. Customers need to manually register the transferred D-U-N-S Number in order to continue to receive Change Notices.

NOTE: Change notices for D-U-N-S Numbers being retired are ONLY available by Monitoring one of these Detailed Company Profile data layers (DCP_STD, DCP_PREM, DCP_ALT_STD, DCP_ALT_ENH and DCP_ALT_PREM).

<ChangeEvent>

<PCMElementXPATHText>//Organization/SubjectHeader/TransferDUNSNumberRegistration</PCMElementXPATHText>

<Element ChangeType="NewlyAdded" PCMElementXPATHText="//Organization/SubjectHeader/TransferDUNSNumberRegistration/TransferReasonText">Duplicate Record Transferred</Element>

<Element ChangeType="NewlyAdded" PCMElementXPATHText="//Organization/SubjectHeader/TransferDUNSNumberRegistration/TransferReasonText@DNBCodeValue">420</Element>

<Element ChangeType="NewlyAdded" PCMElementXPATHText="//Organization/SubjectHeader/TransferDUNSNumberRegistration/TransferDate">2014-01-01</Element>

<Element ChangeType="NewlyAdded" PCMElementXPATHText="//Organization/SubjectHeader/TransferDUNSNumberRegistration/TransferredToDUNSNumber">123456789</Element>

</ChangeEvent>

NOTE: In the case of a "Straight Deletion" event, the TransferredToDUNSNumber field will not be present in the Change Notice.

If the AutoRenewalIndicator was set to true when the initial AddMonitoringRegistration request was made, it is recommended that the developer issue a UpdateMonitoringRegistration request for the subject D-U-N-S Number and set the MonitoringRegistrationStatusText field to "Cancelled" when notified of a retirement event.

Corporate Linkage Changes

The linkage (or family tree) monitoring feature triggers notifications when a member is added to, moves within or departs from a corporate structure. Here are some examples:

NOTE: The Change Trigger Feed from Linkage will have the deleted/departed members first followed by the new/moves within members.

Example #1: Company "F" is added to the "A" tree, directly "owned" by company "E"

A
|
B - C
|    |
D    E
     +
     F

In the change notice, the following items should be examined:

  • SubjectHeader will equal D-U-N-S Number of "A",
  • LinkageChange.DunsNumber will equal D-U-N-S Number of "F",
  • LinkageChange.ChangeType will be Add,
  • LinkageChange.GlobalUltimateOrganization.DunsNumber will equal D-U-N-S Number of "A"
  • LinkageChange.UpwardFamilyMemberOrganization.DunsNumber will equal D-U-N-S Number of "E".

Example #2: Company "F" is moves within the "A" tree, directly "owned" by company "C"

A
|
B - C
|    |
D    E
     |
     F

A
|
B - C
|    | \
D    E  F

In the change notice, the following items should be examined:

  • SubjectHeader will equal D-U-N-S Number of "A",
  • Change Event 1
    • LinkageChange.DunsNumber will equal D-U-N-S Number of "F",
    • LinkageChange.ChangeType will be Drop,
    • LinkageChange.FormerUpwardFamilyMemberOrganization.DunsNumber will equal D-U-N-S Number of "E".
  • Change Event 2
    • LinkageChange.DunsNumber will equal D-U-N-S Number of "F",
    • LinkageChange.ChangeType will be Add,
    • LinkageChange.UpwardFamilyMemberOrganization.DunsNumber will equal D-U-N-S Number of "C".

Example #3: Company "F" leaves the "A" tree, now directly "owned" by company "H"

A
|
B - C
|    |
D    E
     |
     F

A
|
B - C
|    |
D    E

G
|
H
|
F

In the change notice, the following items should be examined:

  • SubjectHeader will equal D-U-N-S Number of "A",
  • LinkageChange.DunsNumber will equal D-U-N-S Number of "F",
  • LinkageChange.ChangeType will be Drop,
  • LinkageChange.FormerGlobalUltimateOrganization.DunsNumber will equal D-U-N-S Number of "A"
  • LinkageChange.FormerUpwardFamilyMemberOrganization.DunsNumber will equal D-U-N-S Number of "C".

If the "G" tree is also being monitored, a second change notice will be triggered:

  • SubjectHeader will equal D-U-N-S Number of "G",
  • LinkageChange.DunsNumber will equal D-U-N-S Number of "F",
  • LinkageChange.ChangeType will be Add,
  • LinkageChange.GlobalUltimateOrganization.DunsNumber will equal D-U-N-S Number of "G"
  • LinkageChange.UpwardFamilyMemberOrganization.DunsNumber will equal D-U-N-S Number of "H".

FAQ

For more information, please see the Frequently Asked Questions page.