0

Webservice API

It is possible to run an assessment protocol via an webservice interface. The client of this webservice can post a XML document with a set of input data. This data is processed by the selected assement protocol and the result is sent back in the webservice responds.

The webservice implement must start a specific assessment protocol. The assessment protocol is selected based on:
1) The name of the protocol provided in the input XML document
2) If no protocol name is provided all the install protocols are queried. During this quering a trigger-net is executed which must be located in the triggers-folder of the protocol. When this trigger net return 1 the protocol is selected. The triggers-nets gets as input the input XML document. When there are more then one protocols selected an error is returned to the webservice client.

 

The webservice can be access via the following URL

https://|host|/|company|/logicnets.lns?verb=start&code=applicationrunnerwebservice&action=postdata

or 
https://|host|/|company|/applicationrunnerwebservice/postdata

Example documents are attached:

  • Input document: SamplePOSTMessageApplicationRunner.xml
  • Result document: SampleRESPONSEMessageApplicationRunner.xml
  • XSD: ExternalStorageV1.xsd


Testing the webservice

The Webservice can be tested using any webservice client. In the following example Postman is used.

Steps

  • Start postman
  • Change GET to POST (1)
  • Paste the URL  https://|host|/|company|/logicnets.lns?verb=start&code=applicationrunnerwebservice (2)
  • Change the body-type to raw (3)
  • Paste the content of the SamplePOSTMessageApplicationRunner.xml (4)
  • Press send (5)
  • Check the body of the response.

 
An XML message is returned when the URL and the posted data is correct.

The XML message contains 4 urls one for start the interactive session; one for getting the data (after the interactive session); one for getting the state and one for closing the session. It also contains a sessionkey. This sessionkey is important since this will be used in all further communication between the external client and LogicNets.

 


The "start" URL you can open in the browser (do not forget to unescape the XML characters: e.g. & should become &).
for example: https://|host|/|company|/logicnets.lns?verb=start&code=ExternalStarter&sessionkey=42344DCC%2D825E%2D2D83%2D0205%2DFB1FA7418FED

You can also pass a redirect_uri as additional parameter. This URI is called (in the browser) when the form is saved, submitted or cancelled or when an error is occured during the opening of the form
For example
https://|host|/|company|/logicnets.lns?verb=start&code=ExternalStarter&sessionkey=42344DCC%2D825E%2D2D83%2D0205%2DFB1FA7418FED&redirect_uri=https%3A%2F%2Fmyclient%2Fform_ready

The assessment will be opened in the browser and you can fill in the forms. When you are ready you can save, submit or cancel the form.

After the form is closed the getdata-url can be used to retrieve the data.

Redirect URL
The redirect url is called (in the browser) when the form is saved, submitted or cancelled or when an error is occured during the opening of the form. The following query-parameters are added to the URL to report back the status

Parameter Description Example
sessionkey Key of the session of which the form is closed
9CD0075B-5F0C-580F-4E6E-D76E602FAA1A
result Result of the session error | save | submit | cancel | expiredsession
errorcode Error code (see below) 101
message Error message

No sessionkey provided


Error codes
In case an error is occured the error code and message are returned via the redirect URL or via the Web API response body.

Action Error-code Message Description
- 100

No action specified

Missing action-parameter in url

getdata
getstate
close
start interactive form
101

No sessionkey provided

Missing sessionkey-parameters in url

getdata
close
102

Provided session (<sessionkey>) not found

Session not found (e.g. invalid session key provided, session has been cleaned after reinstall)

getdata
close
start interactive form
103

Session state is incorrect (<error>)

Invalid session transition

postdata 105

XML XSD validation failed: <errors> and <warnings>

Provided document is not valid

postdata 106

Specified package (<package name>) is not available

Provided package is not installed or active

postdata 110

More than 1 triggered package found (<package names>)

 
start interactive form 111 Invalid URL

An invalid URL has been provided to startup the interactive form

Misc. scenarios
When time-out is detected, the redirect URI is called with the 'expiredsession'-result.

When the user closes the browser or power down his/her machine: The session remains in the same state; the same start-url can be used to restart the interactive form.

Re-open the start-URL that is already opened (i.e. use the same session key to launch another instance of the same session): Other running session will be expired.

State diagram
 

Reply Oldest first
  • Oldest first
  • Newest first
  • Active threads
  • Popular
Like Follow
  • 7 mths agoLast active
  • 14Views
  • 2 Following

Home