> For the complete documentation index, see [llms.txt](https://community-test.logicnets.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://community-test.logicnets.com/release-9/platform-documentation/advanced-topics/webservice-api/web-service-apis.md).
# Web Service APIs
It is possible to run an assessment protocol using an web service interface. The client of this web service can post a XML document with a set of input data. This data is processed by the selected assessment protocol and the result is sent back in the web service response.
### Implementing a Web Service
The web service implementation must start a specific assessment protocol, which is based on the following:
1. The name of the protocol provided in the input XML document.
2. If no protocol name is provided the system queries all install protocols. During this query, LogicNets executes a trigger logicnet, which must be located in the protocol's *triggers* folder. When this trigger logicnet returns the protocol is selected. The triggers logicnet gets as input the input XML document. When there are more then one protocols are selected the system returns an error to the web service client.
The web service can be accessed using the following URL:
*https\://|host|/|company|/logicnets.lns?verb=start\&code=applicationrunnerwebservice\&action=postdata*
or **https\://|host|/|company|/applicationrunnerwebservice/postdata**
The following example documents are attached to this topic:
* Input document: SamplePOSTMessageApplicationRunner.xml
* Result document: SampleRESPONSEMessageApplicationRunner.xml
* XSD: ExternalStorageV1.xsd
### Testing the Web Service
You can test the web service using any web service client. The following example uses Postman.
* 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).
* Click *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 four URLs: one for starting 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 is what you can open in the browser. Remember to unescape the XML characters; for example, & should become &. Example: https\://*|host|/|company|*/logicnets.lns?verb=start\&code=ExternalStarter\&sessionkey=42344DCC%2D825E%2D2D83%2D0205%2DFB1FA7418FED
You can also pass a redirect\_uri as an additional parameter. This URI is called in the browser when the form is saved, submitted, or cancelled or when an error is occurs while opening 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 system opens the assessment 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 you can use the getdata-url 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 occurs while opening 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 occurs, the redirect URL or the Web API response body returns the error code and message.
| 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 () 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 () | Invalid session transition |
| postdata | 105 | XML XSD validation failed: and | Provided document is not valid |
| postdata | 106 | Specified package () is not available | Provided package is not installed or active |
| postdata | 110 | More than 1 triggered package found () | |
| start interactive form | 111 | Invalid URL | An invalid URL has been provided to startup the interactive form |
### Other Scenarios
When they system detects a timeout it calls the redirect URI with the 'expiredsession' result.
When the user closes the browser or powers 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 by using the same session key to launch another instance of the same session. The system expires the previously running session.
### State Diagram
## Attachments
* [SamplePOSTMessageApplicationRunner (1).xml.zip](https://github.com/logicnets/community-portal/tree/release-9/docs/.gitbook/assets/x1lkfr-SamplePOSTMessageApplicationRunner-1.xml.zip)
* [ExternalStorageV1.xsd.zip](https://github.com/logicnets/community-portal/tree/release-9/docs/.gitbook/assets/m2lkf2-ExternalStorageV1.xsd.zip)
* [SampleRESPONSEMessageApplicationRunner.xml.zip](https://github.com/logicnets/community-portal/tree/release-9/docs/.gitbook/assets/63lkfb-SampleRESPONSEMessageApplicationRunner.xml.zip)
* [SamplePOSTMessageApplicationRunner.xml.zip](https://github.com/logicnets/community-portal/tree/release-9/docs/.gitbook/assets/h4lkfd-SamplePOSTMessageApplicationRunner.xml.zip)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://community-test.logicnets.com/release-9/platform-documentation/advanced-topics/webservice-api/web-service-apis.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.