Transactional Web Service Guide

In addition to using the Simple Reporting Service to retrieve data from Navigator, it is possible to complete a number of transactions on Navigator using web service calls.

In order to do this, you will need to contact your Navigator Account Manager to be allocated an API key - which is targeted specifically to allow the calls you wish to make.

Each Navigator transaction contains the following information :-

 API Key:        The API Key supplied by Navigator

 Session Key:        An optional Session Key used for security - this is retrieved using a login call if needed for the call in question

 Method Name:        The name of the transaction to call

In addition each call may have a specific set of parameters sent and returned.

The URL for the web service is : https://services.dmservices.co.uk/DmsNavigator.NavigatorWebService.svc/CallProgExt

The web service uses HTTP POST to accept a text/text data structure that may be XML or JSON in the following format :-

XML

<request>        

<apikey>i[api key]</apikey>

<method>[method name]</method>

<parameters>

<[parameter 1 name]>[parameter 1 data]</[parameter 1 name]>

<[parameter 2 name]>[parameter 2 data]</[parameter 2 name]>

<[parameter 3 name]>[parameter 3 data]</[parameter 3 name]>

...

<[parameter n name]>[parameter n data]</[parameter n name]>

</parameters>

</request>

JSON

{

 "request": {

  "apikey": "[api key]",

  "method": "[method name]",

  "parameters": {

    "[parameter name 1]": "[parameter 1 data]",

    "[parameter name 1]": "[parameter 2 data]",

    "[parameter name 2]": "[parameter 3 data]",

 ...

    "[parameter name n]": "[parameter n data]"

    }

  }

}

The web service call returns a result containing the following information :-

 Method : The transaction method name called

 resultcode: 1/0 to indicate success or failure 

 message: a general message indicating reason for failure or generic success message

 result: a list of returned parameters

XML

<response>

<method>WIN.TEST</method>

<resultcode>[1/0 - success or failure</resultcode>

<message>[Error Message or information]</message>

<result>

<[result 1 name]>[result 1 data]</[result 1 name]>

<[result 2 name]>[result 2 data]</[result 2 name]>

<[result 3 name]>[result 3 data]</[result 3 name]>

...

<[result n name]>[result n data]</[result n name]>

</result>

</response>

JSON

{

"response:{

"method": "[method name]",

"resultcode": "[1/0]",

"message": "[message returned]",

"result": {

"result 1 name": "[result 1 data returned",

"result 2 name": "[result 2 data returned",

"result 3 name": "[result 3 data returned",

...

"result n name": "[result n data returned"

}

}

}

Many transactional calls are available, in theory duplicating almost anything that Navigator itself can do - for example posting a nominal journal, or adding a stock record. 

A typical use of this will be in Excel.    Excel supports macros written in VBA.   For those that are familiar, sample VBA call made to make a call and parse the result is as follows -

Excel VBA Sample

Public Sub CallProg()

' call prog

Dim wsControl As Worksheet

Dim apiKey As String

Dim MethodName As String

Set wsControl = Sheets("Control")

apiKey = wsControl.Cells(3, 2) ' assumes the API key is stored in cell B3 in Control Sheet

MethodName = wsControl.Cells(4, 2) ' assumes the method name is stored in cell B4 in Control Sheet

' Set up XML for call

Dim xml As String

xml = "<request>"

xml = xml & "<apikey>" & apiKey & "</apikey>"

xml = xml & "<method>" & MethodName & "</method>"

xml = xml & "<parameters>"

' Assumes that the control sheet has a list of parameter names in columm A and the data in column B starting at column 7 onwards

Dim rowno As Integer

rowno = 7

Do

   xml = xml & "<" & wsControl.Cells(rowno, 1) & ">" & wsControl.Cells(rowno, 2) & "</" & wsControl.Cells(rowno, 1) & ">"

   rowno = rowno + 1

Loop Until wsControl.Cells(rowno, 1) = ""

xml = xml & "</parameters>"

xml = xml & "</request>"

' Make the call

Destws = wsControl.Cells(5, 2) ' Assumes the destination sheet for the call result is stored in cell B5 in Control Sheet

Sheets(Destws).Activate

With ActiveSheet.QueryTables.Add(Connection:="URL;https://services.dmservices.co.uk/DmsNavigator.NavigatorWebService.svc/CallProgExt", Destination:=Range("A2"))

   .PostText = xml

   .RefreshStyle = xlOverwriteCells

   .SaveData = True

   .BackgroundQuery = False

   .Refresh

End With

' Now parse the result

   xml = Range("A2").Text

   ActiveSheet.Cells(4, 1) = "Batch No"

   ActiveSheet.Cells(4, 2) = getXML(xml, "BatchNo") ' This example extracts a result of "BatchNo" and displays in cell B4 in the reault sheet

End Sub

Public Function getXML(xml As String, NodeName As String) As String

' Function to extract XML result information

Dim oXml As MSXML2.DOMDocument60

   Set oXml = New MSXML2.DOMDocument60

   oXml.LoadXML xml

   Dim oSeqNodes, oSeqNode As IXMLDOMNode

   Set oSeqNodes = oXml.SelectNodes("//response/result")

   getXML = oSeqNodes(0).SelectSingleNode(NodeName).Text

End Function