Web Services

Introduction

In conjunction with operating over databases, files and, of course, PDAs, BrightServer may be configured to receive and respond to Web Service Calls by external sources. This is performed via HTTP over TCP/IP and SOAP protocols accordingly. The processing of the SOAP request is performed via the user defined Web Service script. BrightServer deserializes the Web Services (SOAP) message receives and places into a WebMessage object. It then passes this WebMessage object to the user defined script via the handle function. This means the user defined JavaScript must implement the function handle(message) to process the Web Services call. The script  then reads the request deserialized a 'WebMessage', performs any specific logic defined, and then returns a response. The response is sent back in a a 'WebMessage' object. The response WebMessage is serialised as a SOAP message when transmitted back to the caller.

It may be useful to note that BrightServer uses AJAX framework to serialize and de-serialize the Web Service messages received from the remote caller.

Using this tool, BrightServer may respond directly to external calls, integrating itself seamlessly with any existing system. For example, BrightServer could be configured to push out notifications to remote field users in the field in real time upon receiving a web service call with the particular recipients and details of the notification. A more concrete example would be dispatching jobs to BrightServer via web services calls, and, in turn, send them to remote users almost in real time.

Scripts

A Web Service script is created for a BrightServer configuration by right clicking its 'Scripts' node, then selecting 'New Script'. Upon doing so, the New Script Wizard will open, where the 'Web Services' template may be selected. Selecting this option and clicking the 'Finish' button will create a Web Services template for editing in BrightBuilder.

The Web Services template will contain the handle() function, which is called when the script name is queried from BrightServer's Web Service URL.

This method will take in the BrightServer parsed SOAP request in the form of a WebMessage object which may then be analysed and processed to any business requirements. The name and parameters of the SOAP message may be retrieved via the getMessageName() and getParam() methods respectively.

Once the SOAP request is processed, the script must construct and return a WebMessage through the createMessage() and addParam() methods. Open completion of the handle() function, BrightServer will then construct a SOAP response from the returned WebMessage object, and transmits it to the caller as a SOAP response.

An example Web Service Script would be as follows.

Here, given a SOAP message "HelloTest" with the "name" parameter, BrightServer will construct a WebMessage with the name "HelloTestResult", greeting the sender via the "result" return parameter.

Web Messages

The WebMessage object is used in conjunction with Web Service scripts, and is designed to simplify the process of reading and processing SOAP messages, as they may be encapsulated and/or transported via different means. As such, regardless of the script being called, WebMessage methods may be used to inspect SOAP requests without any XML or SOAP specific parsing. This also allows Web Service Callers to utilise any platforms, libraries or languages to serialise the Request messages - as long as they conform to the SOAP and HTTP protocols, BrightServer will be able to process them for script use.

The WebMessage class has a very simple interface, and is designed both to allow the inspection incoming SOAP messages, and the construction of outgoing ones.

To include the WebMessage class in scripts, please ensure the following class is imported in the Web Service script:

This line is included in the Web Service template by default.

Once added, the WebMessage methods may be utilised in the Web Service script. The method getMessageName may be used to verify the message received from the remote caller, and then the necessary named parameters may be read via getParam(). When the response is constructed, the method createMessage() must be used to specify the name of the response message, and named parameters may be added with addParam().

For more information, please refer to the Reference Manuals > Script Methods Reference > WebMessage chapter of this documentation.

Communications

In order to call a BrightServer Web Service script, the Web Service Caller must first log in to authenticate itself with BrightServer, send the SOAP request and then log out via HTTP protocol. The resulting SOAP message will be included in the HTTP response.

The HTTP context when performing these operations is as follows:

For example, "http://127.0.0.1:8080/brightserver/ws" would connect to the local BrightServer instance's Web Service. Also note that equally the secure HTTPS port can be used as well to communicate with BrightServer to execute web services scripts.

• Authentication is performed via a form or basic authentication. If the form authentication method is used, then the form data should contain the following input values

  j_username=<username>&j_password=<password>

  where the username and password is that of a valid BrightServer user.

• Once authenticated, the caller may then specify the BrightServer script to which to handle the request. The name of the script is specified by the "script" HTTP query input, i.e. the context will be as follows when a script named "TestScriptWebService" is to handle the web services call.

  /brightserver/ws?script=TestScriptWebService

• Once the transactions are complete, the caller must log out from BrightServer. This is achieved by specifying "logout=yes" as an HTTP query input, i.e. the context will be as follows :

  /brightserver/ws?logout=yes

  If a single web service call needs to be made, then "logout" parameter can be combined with the "script" parameter, as follows

  /brightserver/ws?script=TestScriptWebService&logout=yes

  This will send the request to the script "TestScriptWebService" and log out immediately.