Bulk Add Monitoring Registration
Product | D&B Direct 2.0 |
Batch Process ID(s) | TR_BTCH_MNTR_REG |
Options(s) | None |
Monitoring Available | No |
Interface | REST |
Method(s) | POST |
Format(s) | XML |
Service | TransactionalMiniBatch |
{version} | 2.0 |
Initial Release | October 3, 2013 |
This feature allows multiple monitoring registration requests to be issued from a single API call, using the Transactional Mini-Batch Service to support small-sized batches (fewer than 100 companies).
Update History
No modifications have been made to this data layer since the initial release.
Quick Start for Small Batches
The process for small batches requires the following steps:
- List Preparation - this feature uses the same request format as the single add registration (in XML) concatenated into a single submission.
- List Uploads - when you're ready to initiate a batch, submit the list (i.e. ProcessBatch) for processing.
- Get Ready for the Results - like the initial list, the results will be in same layout/format as the single add registration (in XML) concatenated into a single result.
- Downloading Results - since this feature is synchronous, the response from the ProcessBatch request will contain the registration results.
Feature Request
IMPORTANT: Please see the new Online Services Security Enhancement Release, effective November 09, 2020.
Overview
The list of product request details is packaged in a base 64 encoded and embedded in a typical D&B Direct API call.
To prepare the product request list using XML, concatenate multiple copies of the Add Monitoring Registration request detail package and place within AddMonitoringRegistrationRequest tags before encoding.
The maximum number of product requests for this operation is 100.
The InputObjectDetail LayoutVersion value should match the latest version of the Monitoring service as stated on the Add Monitoring Registration page.
Data Layer Entitlement
For customers in U.S. and Canadian markets, the API is provisioned for specific collections of products, reports, and/or features (collectively referred to as data layers) for production and trial usage. Entitlement is not required for testing in the sandbox environment.
- This feature does not require entitlement for production and trial usage. While this component does not require entitlement, customers will only be permitted to monitor data layers to which they have been entitled.
For customers in the UK, Ireland, Belgium, Netherlands and Luxembourg markets, the API is provisioned as a specific set of data layers for production, trial, and sandbox usage.
- This particular data layer is NOT included in the D&B Direct Onboard suite.
Specification
Exception: Requests to this operation must be submitted in XML format via a POST command regardless of the ObjectFormatTypeText value.
POST https://direct.dnb.com/V2/TransactionalMiniBatch HTTP/1.1 Accept-Encoding: gzip,deflate Content-Type: multipart/form-data; boundary="----=_Part_1_3248653.1468334682993" MIME-Version: 1.0 Authorization: <My Auth Token> Content-Length: 5316 Host: 10.162.228.116:80 Connection: Keep-Alive User-Agent: Apache-HttpClient/4.1.1 (java 1.5) ------=_Part_1_3248653.1468334682993 Content-Type: multipart/form-data Content-Transfer-Encoding: 8bit <tmb:ProcessBatchRequest xmlns:tmb="http://services.dnb.com/TransactionalMiniBatchV1.0"> <BatchDetail> <ApplicationBatchID>ServiceGovernanceSamples</ApplicationBatchID> <MessageTimeStamp>2001-12-17T09:30:47-05:00</MessageTimeStamp> </BatchDetail> <BatchSpecification> <BatchProcessID>TR_BTCH_MNTR_REG</BatchProcessID> <BatchPriorityValue>5</BatchPriorityValue> <LanguagePreferenceCode>39</LanguagePreferenceCode> <CharacterSetPreferenceCode>23423</CharacterSetPreferenceCode> </BatchSpecification> <InputDetail> <InputObjectDetail> <ContentObject> <xop:Include href="3ce36328:13ba8e236c9:-7dd2" xmlns:xop="http://www.w3.org/2004/08/xop/include"/> </ContentObject> <ObjectFormatTypeText>XML</ObjectFormatTypeText> <LayoutName>AddRegistration</LayoutName> <LayoutVersion>2.0</LayoutVersion> </InputObjectDetail> </InputDetail> <OutputSpecification> <OutputMethodValue>Online</OutputMethodValue> <ObjectFormatTypeText>XML</ObjectFormatTypeText> </OutputSpecification> </tmb:ProcessBatchRequest> ------=_Part_1_3248653.1468334682993 Content-Type: application/octet-stream; name=attachment-attach-clnstxt1419439046092640363.dat Content-Transfer-Encoding: binary Content-Disposition: form-data; name="attachment-attach-clnstxt1419439046092640363.dat"; filename="attachment-attach-clnstxt1419439046092640363.dat" <BatchAddMonitoringRegistrationRequest xmlns:mon="http://services.dnb.com/MonitoringServiceV2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <mon:AddMonitoringRegistrationRequest xmlns:tmb="http://services.dnb.com/TransactionalMiniBatchV1.0"> <TransactionDetail> <ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID> <TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp> <SubmittingOfficeID>345</SubmittingOfficeID> </TransactionDetail> <AddMonitoringRegistrationRequestDetail> <InquiryDetail> <DUNSNumber>804735132</DUNSNumber> <CountryISOAlpha2Code>US</CountryISOAlpha2Code> </InquiryDetail> <MonitoringRegistrationSpecification> <MonitoringProfileID>12498</MonitoringProfileID> <NotificationProfileID>4674</NotificationProfileID> <TradeUpIndicator>0</TradeUpIndicator> <AutoRenewalIndicator>0</AutoRenewalIndicator> <SubjectCategoryText>high</SubjectCategoryText> <RegistrationReasonCode>1</RegistrationReasonCode> </MonitoringRegistrationSpecification> <InquiryReferenceDetail> <CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText> <CustomerReferenceText/> <CustomerReferenceText/> <CustomerReferenceText/> <CustomerReferenceText/> <CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText> </InquiryReferenceDetail> </AddMonitoringRegistrationRequestDetail> </mon:AddMonitoringRegistrationRequest> <mon:AddMonitoringRegistrationRequest xmlns:tmb="http://services.dnb.com/TransactionalMiniBatchV1.0"> <TransactionDetail> <ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID> <TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp> <SubmittingOfficeID>345</SubmittingOfficeID> </TransactionDetail> <AddMonitoringRegistrationRequestDetail> <InquiryDetail> <DUNSNumber>214567885</DUNSNumber> <CountryISOAlpha2Code>GB</CountryISOAlpha2Code> </InquiryDetail> <MonitoringRegistrationSpecification> <MonitoringProfileID>12498</MonitoringProfileID> <NotificationProfileID>4674</NotificationProfileID> <TradeUpIndicator>0</TradeUpIndicator> <AutoRenewalIndicator>0</AutoRenewalIndicator> <SubjectCategoryText>high</SubjectCategoryText> <RegistrationReasonCode>1</RegistrationReasonCode> </MonitoringRegistrationSpecification> <InquiryReferenceDetail> <CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText> <CustomerReferenceText/> <CustomerReferenceText/> <CustomerReferenceText/> <CustomerReferenceText/> <CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText> </InquiryReferenceDetail> </AddMonitoringRegistrationRequestDetail> </mon:AddMonitoringRegistrationRequest> </BatchAddMonitoringRegistrationRequest> ------=_Part_1_3248653.1468334682993--
Name | Characteristics |
---|---|
ProcessBatchRequest | Aggregate |
ProcessBatchRequest@ServiceVersionNumber | Attribute |
ProcessBatchRequest. BatchDetail | Aggregate, Required Records information necessary to process a particular request. |
ProcessBatchRequest. BatchDetail. ApplicationBatchID | string up to 64 chars., Required A number assigned by consuming application (e.g., GIH) which is used to uniquely identify a batch request. |
ProcessBatchRequest. BatchDetail. MessageTimeStamp | dateTime, Required The date and time when this message was created. When the message is from an intermediary, such as a workflow manager or service bus, this is the date and time when the message was sent to or from the D&B function, |
END: ProcessBatchRequest. BatchDetail | /Aggregate |
ProcessBatchRequest. BatchSpecification | Aggregate, Required Records specific information that are required for processing a Batch Request. |
ProcessBatchRequest. BatchSpecification. BatchProcessID | string up to 32 chars., Required Code used to uniquely identify the business function to be performed (e.g., Match, Cleanse, Match and Cleanse). |
ProcessBatchRequest. InputDetail | Aggregate, Required Records information about the input into the Batch process. |
ProcessBatchRequest. InputDetail. InputObjectDetail | Aggregate, Optional (Array) |
ProcessBatchRequest. InputDetail. InputObjectDetail. ContentObject | base64Binary, Required Records or holds the actual file (e.g. data, picture, blob) stored within the attachment. |
ProcessBatchRequest. InputDetail. InputObjectDetail. ObjectFormatTypeText | string up to 5 chars., Required Format of the Content Object (eg: XML, CSV etc) |
ProcessBatchRequest. InputDetail. InputObjectDetail. LayoutName | string up to 32 chars., Required The name of the layout for this collection of the data records. For example the layout names 'GBI' denotes the Global Batch Input layout. |
ProcessBatchRequest. InputDetail. InputObjectDetail. LayoutVersion | string up to 10 chars., Required The version of the service for the underlying request. |
END: ProcessBatchRequest. InputDetail. InputObjectDetail | /Aggregate |
END: ProcessBatchRequest. InputDetail | /Aggregate |
ProcessBatchRequest. OutputSpecification | Aggregate, Required Records information about the output specification. |
ProcessBatchRequest. OutputSpecification. OutputMethodValue | string, Required Call Back, FTP, JMS Queue, Web Service Possible value(s): Online |
ProcessBatchRequest. OutputSpecification. ObjectFormatTypeText | string, Required XML,CSV,JSON Possible value(s): XML |
END: ProcessBatchRequest. OutputSpecification | /Aggregate |
ProcessBatchRequest. BatchReferenceDetail | Aggregate, Optional Records data that allows the customer to specify information to be linked to the request in order to support subsequent process. |
ProcessBatchRequest. BatchReferenceDetail. BatchReferenceText | string up to 240 chars., Optional(Up to 5x) A freeform reference string provided by the customer to be linked to the product in order to support subsequent process. |
END: ProcessBatchRequest. BatchReferenceDetail | /Aggregate |
END: ProcessBatchRequest | /Aggregate |
Endpoint
Use the following endpoint for requesting this feature. The {version} is dependent on the underlying service delivering the response.
Endpoint (TransactionalMiniBatch) |
---|
POST https://direct.dnb.com/V{version}/TransactionalMiniBatch/Batches |
Testing
This operation will return a static set of results in the D&B Direct test environment (sandbox), regardless of the request parameters.
Feature Response
Specification
The following is a list of the possible data fields returned by this operation in the XML response. Samples are provided for testing successful and failed retrieval, and to demonstrate the basic layout of a response. The data returned in samples may not represent actual values that this feature will deliver.
The MTOM attachment specified in the ContentObject is a base64 encoded field that, when decoded, will be in the format specified by ObjectFormatTypeText.
NOTE: This operation will send back a response in XML, regardless of the ObjectFormatTypeText value submitted on the request.
HTTP/1.1 200 OK Via: 1.1 dbslsigwbv03 (), 1.1 dbslsegwbv03 () Connection: Keep-Alive X-CorrelationID: Id-69be905720fe03004bbc06009e042776 0; Id-6abe9057a99a00006b6c02007c105c61 0 Date: Thu, 21 Jul 2016 12:22:02 GMT X-Powered-By: Servlet/2.5 JSP/2.1 Content-Type: multipart/related; boundary=MIME_Boundary; start=8259981961911062378-56316fa7.1560d4d01aa.-61da; type="application/xop+xml"; start-info="text/xml" Vary: Accept-Encoding Content-Encoding: gzip Content-Length: 1114 --MIME_Boundary Content-ID: 8259981961911062378-56316fa7.1560d4d01aa.-61da Content-Type: application/xop+xml; charset="utf-8"; type="text/xml" <?xml version="1.0" encoding="utf-8"?> <tran:ProcessBatchResponse ServiceVersionNumber="2" xmlns:tran="http://services.dnb.com/TransactionalMiniBatchV1.0"> <BatchDetail> <ApplicationBatchID>ServiceGovernanceSamples</ApplicationBatchID> <ServiceBatchID>Id-a04d9057f2960100569906005b0e8a7b-1</ServiceBatchID> <MessageTimeStamp>2001-12-17T09:30:47-05:00</MessageTimeStamp> </BatchDetail> <BatchResult> <SeverityText>Information</SeverityText> <ResultID>CM000</ResultID> <ResultText>Success</ResultText> </BatchResult> <OutputDetail> <OutputObjectDetail> <ObjectFormatTypeText>XML</ObjectFormatTypeText> <LayoutName>AddRegistration</LayoutName> <ContentObject> <inc:Include href="cid:-5673d010:1560b36a40f:-196b" xmlns:inc="http://www.w3.org/2004/08/xop/include"/> </ContentObject> </OutputObjectDetail> </OutputDetail> <BatchProcessSummary> <ExectuionTimeSummary> <BatchRequestCreatedTimeStamp>2001-12-17T09:30:47-05:00</BatchRequestCreatedTimeStamp> <BatchReceivedTimeStamp>2001-12-17T09:30:47-05:00</BatchReceivedTimeStamp> <ActualProcessCompletionTimestamp>2016-07-21T08:22:11</ActualProcessCompletionTimestamp> </ExectuionTimeSummary> <RecordSummary> <TotalInputRecordCount>2</TotalInputRecordCount> <TotalOutputRecordCount>2</TotalOutputRecordCount> <TotalPassedRecordCount>2</TotalPassedRecordCount> <TotalFailedRecordCount>0</TotalFailedRecordCount> </RecordSummary> </BatchProcessSummary> </tran:ProcessBatchResponse> --MIME_Boundary Content-ID: <56316fa7:1560d4d01aa:-61ad> Content-Type: application/octet-stream <BatchOrderProductResponse xmlns:soap-env="http://schemas.xmlsoap.org/soap/envelope/"> <ns2:AddMonitoringRegistrationResponse ServiceVersionNumber="?" xmlns:ns2="http://services.dnb.com/MonitoringServiceV2.0" xmlns:ns3="http://services.dnb.com/TransactionFaultV2.0" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <TransactionDetail> <ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID> <ServiceTransactionID>Id-68bb9057d47a0200526309002836a65b-2</ServiceTransactionID> <TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp> </TransactionDetail> <TransactionResult> <SeverityText>Information</SeverityText> <ResultID>CM026</ResultID> <ResultText> Request accepted.Processing pending.</ResultText> </TransactionResult> <AddMonitoringRegistrationResponseDetail> <InquiryDetail> <DUNSNumber>804735132</DUNSNumber> <CountryISOAlpha2Code>US</CountryISOAlpha2Code> </InquiryDetail> <MonitoringRegistrationDetail> <DUNSNumber>804735132</DUNSNumber> <MonitoringProfileID>12498</MonitoringProfileID> <NotificationProfileID>4674</NotificationProfileID> <StartDate>2016-07-21</StartDate> <EndDate>2017-09-12</EndDate> </MonitoringRegistrationDetail> <InquiryReferenceDetail> <CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText> <CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText> </InquiryReferenceDetail> </AddMonitoringRegistrationResponseDetail> </ns2:AddMonitoringRegistrationResponse> <ns2:AddMonitoringRegistrationResponse ServiceVersionNumber="?" xmlns:ns2="http://services.dnb.com/MonitoringServiceV2.0" xmlns:ns3="http://services.dnb.com/TransactionFaultV2.0" xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"> <TransactionDetail> <ApplicationTransactionID>ServiceGovernanceSamples</ApplicationTransactionID> <ServiceTransactionID>Id-68bb9057d37a020052630900cc6f3df8-2</ServiceTransactionID> <TransactionTimestamp>2013-06-03T09:30:47Z</TransactionTimestamp> </TransactionDetail> <TransactionResult> <SeverityText>Information</SeverityText> <ResultID>CM026</ResultID> <ResultText> Request accepted.Processing pending.</ResultText> </TransactionResult> <AddMonitoringRegistrationResponseDetail> <InquiryDetail> <DUNSNumber>214567885</DUNSNumber> <CountryISOAlpha2Code>GB</CountryISOAlpha2Code> </InquiryDetail> <MonitoringRegistrationDetail> <DUNSNumber>214567885</DUNSNumber> <MonitoringProfileID>12498</MonitoringProfileID> <NotificationProfileID>4674</NotificationProfileID> <StartDate>2016-07-21</StartDate> <EndDate>2017-09-12</EndDate> </MonitoringRegistrationDetail> <InquiryReferenceDetail> <CustomerReferenceText>ServiceGovernanceSamples-MiniBatch</CustomerReferenceText> <CustomerBillingEndorsementText>ServiceGovernanceSamples-MiniBatch</CustomerBillingEndorsementText> </InquiryReferenceDetail> </AddMonitoringRegistrationResponseDetail> </ns2:AddMonitoringRegistrationResponse> </BatchOrderProductResponse> --MIME_Boundary--
Name | Characteristics |
---|---|
ProcessBatchResponse | Aggregate |
ProcessBatchResponse @ServiceVersionNumber | Attribute |
ProcessBatchResponse { BatchDetail | Aggregate, Required Records information necessary to return a particular response. |
ProcessBatchResponse { BatchDetail { ApplicationBatchID | string, up to 64 chars, Required A number assigned by consuming application (e.g., GIH) which is used to uniquely identify a batch request. |
ProcessBatchResponse { BatchDetail { ServiceBatchID | string, up to 64 chars, Required A number assigned by the composite service (e.g., MatchCleanseService, GHM) which is used to uniquely identify a batch request. |
ProcessBatchResponse { BatchDetail { MessageTimeStamp | Element |
END: ProcessBatchResponse } BatchDetail | /Aggregate |
ProcessBatchResponse { BatchResult | Aggregate, Optional Records information about the result of the process. |
ProcessBatchResponse { BatchResult { SeverityText | string, Required Text that records the criticality of the outcome, e.g., Information, Warning, Error, Fatal. |
ProcessBatchResponse { BatchResult { ResultID | string, up to 32 chars, Required An alphanumeric string that uniquely identifies the outcome of the batch. |
ProcessBatchResponse { BatchResult { ResultText | string, up to 512 chars, Optional Text that explains the outcome of the batch. |
ProcessBatchResponse { BatchResult { ResultMessage | Aggregate, Optional (Array) An aggregate that can repeat multiple times to record textual data that expands on the ResultID and ResultText to provide additional information to the user regarding the status of the batch. If the status implies that there is a problem this may also provide guidance to the user on how to address it. |
ProcessBatchResponse { BatchResult { ResultMessage { ResultDescription | string, up to 512 chars, Required Text that describes the additional information regarding the outcome of the batch. |
END: ProcessBatchResponse } BatchResult } ResultMessage | /Aggregate |
END: ProcessBatchResponse } BatchResult | /Aggregate |
ProcessBatchResponse { OutputDetail | Aggregate, Optional Records information about the output of the Batch process. |
ProcessBatchResponse { OutputDetail { OutputObjectDetail | Aggregate, Optional (Array) |
ProcessBatchResponse { OutputDetail { OutputObjectDetail { ObjectFormatTypeText | string, up to 5 chars, Required Describes the format of the attached file, e.g., txt, pdf, html. Possible values: JSON; XML |
ProcessBatchResponse { OutputDetail { OutputObjectDetail { LayoutName | string, up to 32 chars, Required The name of the layout for this collection of the data records. For example the layout names 'GBI' denotes the Global Batch Input layout. |
ProcessBatchResponse { OutputDetail { OutputObjectDetail { ContentObject | base64Binary, Required Records or holds the actual file (e.g. data, picture, blob) stored within the attachment. |
END: ProcessBatchResponse } OutputDetail } OutputObjectDetail | /Aggregate |
END: ProcessBatchResponse } OutputDetail | /Aggregate |
ProcessBatchResponse { BatchProcessSummary | Aggregate, Optional Records information about the process time and the number of records processed. |
ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary | Aggregate, Optional Records information about the process time and completion time. |
ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary { BatchRequestCreatedTimeStamp | dateTime, Required The date and time when the batch request was created by the submitting application. |
ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary { BatchReceivedTimeStamp | dateTime, Optional The date and time when the batch request was received by the service. |
ProcessBatchResponse { BatchProcessSummary { ExecutionTimeSummary { ActualProcessCompletionTimestamp | dateTime, Optional The date and time when the requested process (i.e., match, cleanse, cleansematch) was actually completed by the service. |
END: ProcessBatchResponse } BatchProcessSummary } ExecutionTimeSummary | /Aggregate |
ProcessBatchResponse { BatchProcessSummary { RecordSummary | Aggregate, Optional Records information about the number of input and output records, and the count of the number of records which have passed and failed the requested process. |
ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalInputRecordCount | integer, Optional A numeric value denoting the total number of records contained in the input file. |
ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalOutputRecordCount | integer, Optional A numeric value denoting the total number of records contained in the output file. |
ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalPassedRecordCount | string, Optional A numeric value denoting the total number of records which have passed the requested process. |
ProcessBatchResponse { BatchProcessSummary { RecordSummary { TotalFailedRecordCount | string, Optional A numeric value denoting the total number of records which have failed the requested process. |
END: ProcessBatchResponse } BatchProcessSummary } RecordSummary | /Aggregate |
END: ProcessBatchResponse } BatchProcessSummary | /Aggregate |
END: ProcessBatchResponse | /Aggregate |
Response Codes & Error Handling
Successful service requests will return a CM000 response code in the BatchResult ResultID field. Otherwise, one of the D&B Direct standard response codes will be returned.
This operation may return the following response codes: CM002, CM004, and SC001-SC008.
NOTE: Each individual request will return a response code in the AddMonitoringRegistrationResponse TransactionResult ResultID field. Refer to Data Layer/Field Monitoring for a list of valid response codes.
D&B Direct 2.0 API requests are provided on a metered basis; and may require entitlement prior to use in the production environment. In addition, a concurrency limit (QPS) is monitored to ensure that it is not exceeded. An error code will be returned in the event that a transaction is throttled.
Qualified usage (e.g., a successful response) is tracked and billed according to the terms & conditions of the customer's contract. The response codes CM000, CM010, PD002 and PD015 are considered successful. A built-in feature exists to prevent duplicate billing when multiple successful requests with the same criteria are submitted on the same calendar day (which is based on Eastern Standard Time [GMT-5]).
The usage details for a Small batch request are recorded as a series of individual requests of the underlying request type. Therefore, customer online usage (OLUS) reports will display multiple entries for each batch submitted.
Feature Notes
The results from this feature will be a base 64 encoded concatenated block of separate Add Monitoring Registration responses (based on the format specified on the request).
Response codes will be returned for the overall result, as well as, for each individual product request.