Web Service Scripts

Web Service Scripts provide a flexible solution to create and publish customized Web Services using Javascript.


You can use SOAP Web Services to interact with GpsGate Server, but previously you had to create your own adapter if you had to translate the data format to fit your legacy system. This is no longer necessary as you can configure your customized Web Services inside GpsGate Server to communicate with external systems that require a specific data format.

Installation
  1. Login to SiteAdmin
  2. Go to the Plugins tab
  3. Under Plugins tab, make sure that Patch.v4 is installed and up to date
Configuration
  1. Login to SiteAdmin
  2. Go to the Applications tab and click on the Application you want to edit
  3. Enable the privileges: _EditWebServiceScripts and _WebServiceScriptLogin
  4. Click on Save
Creating a Web Service Script

To add a Web Service Script, login to your VehicleTracker application and click on Web Service Scripts in the Admin menu. Click on the Add new Web Service Script button.
(BETA: enable the _EditScriptApp privilege, too, and in VehicleTracker go to Development > App Builder. Then create a new App and go to step “Web Service Scripts”.)

You can fill in the details for the web service as shown below:

web service script form

When you click the Edit button, the script editor window shows up with the default script template. If you have experience with other types of scripts in GpsGate platform, the editor interface will be familiar. The list of exposed objects is on the right side. The editable input fields can be used to set test data when clicking the Test Script button.

web service script editor

Example

Usually a web service script consists of three main parts:

  1. Parsing the request parameters from url or request body
  2. Interaction with GpsGate server through exposed Javascript functions
  3. Creating the response body

Here I show you how to use the Javascript framework to implement these steps. Take a look at the API section of the article for further API documentation that is not covered in the example. The current list of exposed functions is limited, it will be extended on a case by case basis.

In this example we create a Web Service to return the latest position of a vehicle. The Web Service consumer system requests the data in the format shown below. It authenticates itself using the credentials specified in login xml node. The user needs to have _WebServiceScriptLogin, _ReadUsers and _ReadData privileges to be able to access the specified vehicle.

The service consumer system expects the response in the following format:

Example script:

In the object browser fill the request body with test data, then click on the Test Script button. You will see the response in the script editor console.

Note: you need to authenticate the web service consumer system to be able to access data. It is a good practice to create a separate user for the service with the minimal necessary privilege set. The AccessFilter plugin makes it possible to control which IP addresses can access your service.
Note: XML format is used in the examples above, but it is also possible to communicate using JSON format (check JSON.stringify(obj) and JSON.parse(str) functions)
Note: API methods can throw exceptions in case of missing privilege, etc. Use try-catch to handle those errors.

Forum topic
Enable Logging at runtime
You may enable the log function for Web Service Scripts at runtime by editing the Nlog.config file in the NMEA service folder under the GpsGate Server installation folder (if you are not hosting your own server, please contact support). Under <targets>, you should add a new target entry like this: where TARGET_NAME is an unique name for the file target and FILE_NAME is the name of the log file you wish to be created with full path to the file. Under <rules>, add an entry like this: where NAME_OF_WEB_SERVICE_SCRIPT is the name of the click script which you want to log to the file, and TARGET_NAME is the unique name of the target you added above. Data logged through log method in the specified web service script will then be written to the specified file.
API
request:
  • body: string
    Request body.
  • query: string
    Request query string.
  • queryParams : NameValueCollection
    Represents a collection of query string parameters.
xml:
  • parseFromString(strXml) : XmlDocument
    Returns a document object that represents the DOM tree of the XML source.
  • createDocument() : XmlDocument
    Returns a new empty xml document object.
JSON: (added in version 4.0.0.2174)
  • stringify(object) : string
    Converts a value to JSON
  • parse(str) : object
    Parses a string as JSON.
auth:
  • login(strUsername, strPassword) : string
    Authenticates a user with password and returns session id.
  • login(strSessionId)
    Authenticates a user with session id.
customFields:
  • getValues(strNamespace, iObjectID) : array of CustomFieldValue
    Returns the Custom Fields for the specified object. Value of strNamespace can be ‘user’ or ‘poi’.
directory:
  • getUserByID(iUserID) : GateUser
    Returns a user by user id.
  • getUserByIMEI(strIMEI) : GateUser
    Returns a user by IMEI.
  • getUsers() : array of GateUser
    (added in version 4.0.0.2174)
    Returns all users in the current application
  • getLatestRecords(iUserID) : array of MessageRecord
    Returns the latest value of variables.
tags (added in version 4.0.0.2174)
  • getTags() : array of UserTag
    Get all tags in the application.
  • getTagByName(strName) : UserTag
    Returns the usertag having the specified name.
  • updateUsers(iTagID, userIDsToAdd, userIDsToRemove) : UserTag
    Adds/Removes users to/from the specified tag.
geo (added in version 4.0.0.2190)
  • reverseGeocode(lat, lng) : Location
    Resolves a geo-location into an address.

log(valueOrObject) : void
This function logs value to log file or script editor console.


Types that are not exposed explicitly as root members:


CustomFieldValue
  • name : string
    The name of the field.
  • value : string
    The value of the filed.
GateUser
  • id : int
    User id.
  • name : string
    User name.
  • username: string
    User username.
  • trackPoint: TrackPoint
    Latest valid TrackPoint for the user.
UserTag
  • id : integer
    The id of user tag.
  • name : string
    The name of user tag.
  • description : string
    The description of the user tag.
  • userIDs : array of integers
    User IDs associated to the tag.
MessageRecord
  • name: string
    Name of the field.
  • value: object
    Value of the field
  • type: string
    Type of the field
  • unit: string
    Unit of the field.
  • utc: JsDate
    Specifies when the value was recorded.
NameValueCollection:
  • get(strName) : string
    Gets the value associated with the specified key.
XmlNode:
  • nodeName : string
    The name of this node.
  • nodeValue : string
    The value of this node.
  • innerText : string
    Gets the concatenated values of the node and all its child nodes.
  • nodeType: int
    A code representing the type of the underlying object.
  • nodeTypeName : string
    A type name representing the type of the underlying object.
  • hasChildNodes : bool
    Returns whether this node has any children.
  • childNodes : XmlNodeList
    A NodeList that contains all children of this node. If there are no children, this is a NodeList containing no nodes.
    (for(var child in node.childNodes){} also works)
  • appendChild(XmlNode) : XmlNode
    Adds the specified node to the end of the list of child nodes, of this node.
  • selectNodes(strXPath) : XmlNodeList
    Selects a list of nodes matching the XPath expression.
    (for(var child in node.childNodes){} also works)
  • selectSingleNode(strXPath) : XmlNode
    Selects the first node that matches the XPath expression.
XmlNodeList:
  • length : int
    The number of nodes in the list.
  • [index] : XmlNode
    Returns the item from the specified position.
XmlDocument : XmlNode
  • createElement(strName) : XmlElement
    Creates an element with the specified name.
  • createTextNode(strText) : XmlText
    Creates a text node with the specified content.
  • outerXml: string
    Gets the markup representing this node and all its child nodes.

XmlElement: XmlNode

XmlText: XmlNode


  Discuss this blog post on the forum please



Download free GpsGate Server

Install it on your own server. The installation is free for 5 users.

Download Now