General
Interpretation instructions
Response messages

General

Web Service Interface enables retrieving material from and importing material to Netvisor. The Web Service Interface resources are divided into upper level categories.
Common for all transactions:

  • Dates are in ANSI format
  • Country codes are always in ISO 3166 format
  • Attachments are always Base64 encoded in XML message
  • Empty elements don't need to be given in the XML message. For example, in edit request the empty element is interpreted as an order to update the value to blank
  • Compulsory elements should not be given empty
  • Elements have to be in the same order as in the DTD

To be able to import Scandinavian characters (Ä, ä, Ö, ö or Å, å) the message has to be encoded in ISO/IEC 8859-15 but xml declaration does not need to be given. Netvisor's server side performs the necessary preprocessing for the content, so the message should always start with <root>. 

Make large retrieves and imports outside office hours if there is no special need to do these during that time. The frequency for transfers varies from resource and use case. In many cases transfers once a day or month is sufficient. You can speed up the transfers with appropriate limitations using resource parameters.

Interpretation instructions

Enclosed is a description of different entries and their meaning and interpretation in Netvisor's Web Service Interface.
The XML structure of different messages is described in tables for the part it is possible and logical. Due to the XML structure, the resource descriptions have references to different parts of the instructions to be able to keep the entity as clear as possible.

The basic structure of resource description is the following:
Query:

  • Basic data
    • The used resource
    • GET - generally retrieving data from Netvisor
    • POST - generally posting data to Netvisor
  • Parameters
    • Usually defined in the QueryString, separated from the actual resource with ?- and after the parameter there is &-
    • Not all resources have them
  • XML structure when importing data (POST)
    • Described is the XML structure and e.g. the amount of different elements and their compulsion

Note that when using self-closing tags in POST-messages, Netvisor ignores these completely, including possible attributes. For example, when importing customer details, the element <email/> is ignored, while <email></email> updates that particular value in Netvisor to blank. 


Response:
Every query is answered with an XML response. The structure of the response matches the query for the most part and the general structure can be seen in the chapter below. The response to GET type queries includes resource-specific data structure that is described in each resource description. Depending on the POST type query, Netvisor Web Service Interface returns Replies element that can include e.g. InsertedDataIdentifier element with added item's ID value.

Response messages

Every request is responded with a standard response message. In GET type request the response includes the requested data (<resource specific element>) and in POST type request the response might include a case-specific response (Replies).
The general structure of a response message:
Element: Root (occurs: 1)
Element: Root/ResponseStatus (occurs: 1)

ElementTypeDescriptionExampleDetails
StatusStringIndicates if there was an error in handling the requestOKFAILED
StatusStringError type and description This element only occurs if the status is FAILED. Check Controlling errors
TimeStampDate Time stamp of the response01.01.2018 12:00:00 

 
The response type is related to the direction of the data transfer:

1. When retrieving data from Netvisor
The retrieved data is in its own element in the response message:
Element: Root/ResponseStatus/<resource specific element>
2. When importing data to Netvisor
The response includes Replies element and in that element there is data in some occasions:
Element: Root/ResponseStatus/Replies (occurs 0-1)

ElementTypeDescriptionExampleDetails
InsertedDataIdentifierString   
OR
ReplyString   

The enclosed elements occur times 0-n.



This article has been translated using an AI-based translation tool.

Did you find it helpful? Yes No

Send feedback
Sorry we couldn't be helpful. Help us improve this article with your feedback.