kom godt i gang

se client code examples

Kom godt i gang

Før du kan begynde at ringe til Bisnodes webtjenester, skal du sørge for at have følgende oplysninger:

Bisnode live server URL 

If you have the URL to the server then you can access the WSDL file to each Bisnode web service on the following URL:https://www.bisgateway.com/brg/services/<service_name>?wsdl
The URL to where the web service itself can be accessed follows the following standard:
https://www.bisgateway.com/brg/services/<service_name>/

A login account

Most of the Bisnode web services demand that you submit login information when you call the service. When requesting data for Credit Reports or Decision Support, the login account consists of four parameters:

  • Customer code

  • Customer code owner

  • User id

  • User Password

When requesting data for Nordic Business Key the login account consists of three parameters:

  • Customer code

  • User

  • Password

SOAP

All communication with the Bisgateway takes place using the Simple Object Access Protocol (SOAP) as protocol/message format. This means that all of the Bisgateway web services should be accessed with SOAP requests via HTTP. Each service’ interface is described in detail in a Web Service Definition Language (WSDL) file.

A raw SOAP request message to the gateway might look something like this.

The corresponding SOAP response message looks like this.

Please see each service’ section below for a SOAP example request to each service.
All services require that you set a SOAP action as a HTTP header. This is for the Bisgateway to be able to route the message to the correct service. In you don’t specify a SOAP action then the gateway won’t be able to handle the request.

SOAP Headers 

Several of the Bisgateway web services uses SOAP headers to communicate for example login account information. 

The SOAP headers are placed in the Header section of the message.

The SOAP response message could also contain headers, for example the timeTaken header.

SOAP headers which are not specified in the WSDL file, except in the schema part, are called optional headers. They can be sent in a request but they are not mandatory. If you generate proxy code from the WSDL file, specific code for these headers will not be included. If you want to send them, you have to specify them yourself. Please refer to the FAQ Java section for an example on how to do this in Java.

Error handling

The Bisgateway defines a number of standard errors that can occur during a call. These are all communicated to the caller in the form of SOAP faults. In the WSDL files for all services a standard brgFault is defined, which includes an errorCode and an exception that will hold detailed information about which error occurred. ErrorCode and exception will be sent under the detail-element in the SOAP fault. These elements are both within the namespace http://www.dnbnordic.com/brg/faults.

A SOAP fault example, as it will look when returned from the Bisgateway

The following table shows the specific errors that the Bisgateway can return

ErrorCode Exception Description
100 LoggableXmlMessageException General error (none of the below)
101 AuthenticationException Incorrect login
102 AuthorizationException The service requested is not allowed for specified the user
103 BackendCommunicationFailureException An error has occured in the communication with the Bisgateway and the back end system (e.g. NRG)
104 BackendFailureException An error has occured in the backend system
105 InvalidInputException Incorrect input, e.g a mandatory header, such as language, from Country or to Country is missing

The following codes are not errors per se, but they are also returned as SOAP faults

 ErrorCode  Exception  Description
 200  NoHitsException  No hits in the back end database
 201  TooManyHitsException  Too many hits in the back end database

Namespaces

The WSDL files to all services have elementFormDefault set to qualified in the schema parts. This means that when making the SOAP request all elements in both the header and body section have to be namespace qualified. If you’re writing your SOAP request manually, don’t forget to check which namespaces the elements belong to.

Here follows an overview of all namespaces used in the Bisgateway web services. The namespaces are ordinary xml namespaces, used to distinguish the xml elements in the SOAP headers and body from one another.

Each service has two separate namespaces for request and response data: 

http://www.dnbnordic.com/brg/<service_name>/request
http://www.dnbnordic.com/brg/<service_name>/response

The following namespace is general to all services. General SOAP headers belong to this namespace:

http://www.dnbnordic.com/brg

The log namespace is used for logging information:

http://www.dnbnordic.com/brg/log

The faults namespace is used for detailed fault information (see Error Handling for further details):

http://www.dnbnordic.com/brg/faults

Client Code Examples

Java

If you are writing your client code in Java, we recommend that you use the open source SOAP engine/framework called Axis to generate proxy client code for the Bisgateway web services. This recommendation is for all services except the Annual Report PDF service, which uses SOAP attachments. For this web service we have included an entire code example with client code that can be used to call this service.Please refer to http://ws.apache.org/axis/ for more information about Axis and to download the latest version.

Generating Java Client Code with Axis 
In Axis there is a tool called WSDL2Java that can be used to generate Java client stub code from a web service WSDL file. To use this tool you just run it with java from the command prompt:

java org.apache.axis.wsdl.WSDL2Java -a <WSDL URL>

Please notice that you must have java.exe in your path before running this and that all jar files used by Axis (found in the lib directory under your Axis installation directory) must be in your classpath before you can use the command above.
If successful the command above should result in a lot of new java classes being created for you. If we run this command with the NRG Consumer Search WSDL file as an input parameter then the following classes and interfaces should be generated:

  • NRGConsumerSearchLocator.java

  • NRGConsumerSearchSoapBindingStub.java

  • BRGService.java

  • NRGConsumerSearch.java

  • NRGConsumerSearchRequest.java

  • Criteria.java

  • NRGConsumerSearchResponse.java

  • Consumer.java

  • BRGFault.java

  • ToCountry.java

  • UserId.java

  • UserPassword.java

  • CustomerCode.java

  • CustomerCodeOwner.java

  • FromCountry.java

  • IncludeEmptyFields.java

  • Language.java

  • TimeTaken.java

This might seem like a lot of classes, but don’t worry too much about what they do right now. Please see Using the generated code section below for an example on how to use the generated code.
WSDL2Java have a lot of optional parameters that can be used to specify which java package you want the generated code to be placed in, which directory they should be placed under etc. Please refer to the Axis user guide at http://ws.apache.org/axis/java/user-guide.html for a complete documentation on WSDL2Java.

Using the Generated Code

After you have generated client code with Axis you probably want to use the code. Here you will find a basic example code that shows how to use the Axis generated client code to perform a consumer search (please see the NRG Consumer Search section below for further information about this web service).

Client Code to Annual Report PDF

The following example code can be used when calling the Annual Report PDF service in the Bisgateway. This code uses a javax.activation.DataHandler, which holds the PDF file. It also uses SOAP with Attachments API for Java (SAAJ) and commons-httpclient 2.0 from Apache which can be downloaded at http://jakarta.apache.org/commons/httpclient/. Note: This code will be distributed as a ready-to-use component in the download section.

.Net

Here follows an example on how to build your client using the Microsoft .Net framework. The code example is given in C# but it could easily be changed into VB.Net.

Generate a Proxy in .Net

The .Net SDK contains a tool called wsdl.exe that can be used to generate client proxy code from the WSDL-file of any web service.

To use the tool you just type:

wsdl /l:CS /protocol:SOAP <WSDL URL>

into a Visual Studio Command Prompt. If you do this on the Consumer Search service WSDL for example it should generate a source file called NRGConsumerSearch.cs.

You can also use the Add Web Reference functionality in Visual Studio which will let you add a web service reference to your project by simply pointing out a WSDL file. This action will also generate client proxy code, much like above. Please refer to the Microsoft Visual Studio documentation for more information about how to do this.

Using the Generated Code

The following example shows how to use the generated proxy code.