Add page for common errors and add info to KI page

docs/docs/faq.md

@@ -57,21 +57,6 @@ SELECT ?sensor WHERE {
 
 	This tells the Knowledge Engine that you cannot send it an email address and receive the username.
 
-*Question*: Can you explain how to register the argument pattern and the result graph pattern? In the KE API I saw only one graph pattern in the register of a Knowledge interaction, and no parameter to indicate if it is an argument pattern or a result graph pattern.
-- *Answer*: In the Java Developer API the constructors of the [PostKnowledgeInteraction](https://github.com/TNO/knowledge-engine/blob/master/smart-connector-api/src/main/java/eu/knowledge/engine/smartconnector/api/PostKnowledgeInteraction.java) and [ReactKnowledgeInteraction](https://github.com/TNO/knowledge-engine/blob/master/smart-connector-api/src/main/java/eu/knowledge/engine/smartconnector/api/ReactKnowledgeInteraction.java) objects require both an argument and a result graph pattern.
-
-	In the JSON body of the [REST Developer API ](https://github.com/TNO/knowledge-engine/blob/master/smart-connector-rest-server/src/main/resources/openapi-sc.yaml) `POST /sc/ki` operation, you specific the type of the Knowledge Interaction. If you choose the PostKnowledgeInteraction or ReactKnowledgeInteraction `knowledgeInteractionType`, the argument and result graph patterns are also expected (see also the schema of the request body):
-
-	```json
-	{
-	"knowledgeInteractionType": "PostKnowledgeInteraction",
-	"argumentGraphPattern": "?s ?p ?o",
-	"resultGraphPattern": "?x ?y ?z"
-	}
-	```
-
-	Note that the result graph pattern is optional.
-
 *Question*: In the context of graph pattern matching, can you explain the subset/superset condition: "when the Graph Pattern" of the sender is a superset of the Graph Pattern of the receiver' ? Is it at definition level or at data level? I found (at ontology level) the following explanation: "Ontology O1 is a subset of ontology O2 if all definitions in O1 are contained in O2 (O2 is the superset of O1)".
 1) More concrete: is 'a b c .' graph pattern a subset or a superset of 'a b c . d e f.' ?
 2) In case of Post/React knowledge interactions, both argument graph patterns must match and also both result graph patterns must match?
@@ -84,18 +69,6 @@ SELECT ?sensor WHERE {
 	3) Yes, the PostKnowledgeInteraction sends the argument and the ReactKnowledgeInteraction sends the (optional) result.
 	4) Currently, this will not work, because we are using a graph pattern *matcher* instead of a *reasoner*. I expect the reasoner to indeed allow them to interact if the POST side result pattern is a subset of the REACT side result pattern. In that case the result binding set at the POST side should also be a subset (in fields) of the binding set given from the REACT side. So, the results are always given to a Knowledge Base in its own terminology, this already happens by translating the variable names, but should also happen in the way you describe once the reasoner is active.
 
-*Question*: I successfully created smart connector (https://cybergrid.com/kb1) and the knowledge Interaction. When I wanted to execute the ask command with the following body:
-```json
-[
-  {
-   "deviceName": "device1" 
-  }
-]
-```
-I received the following expectation from the knowladge-engine: ```400 Bad Request: ['device1' is not an unprefixed URI or literal.]```
-- *Answer*: The reason your request fails is because variable bindings need to be either RDF Literals or IRIs. See also our [documentation](java_developer_api.md#bindings).
-	If you change your example value from `device1` to something like `<http://www.example.org/device1>`, this particular error should be resolved.
-
 *Question*: Do we need a long polling connection for every Knowledge Interaction? Doesn't that get very complicated?
 - *Answer*: No, per Smart Connector (or Knowledge Base) you need a single long polling connection to receive all interactions from the Knowledge Engine. Do remember that this long polling connection is returned with status code 202 every 29 seconds and also needs to be reestablished after you receive data via it.
 

docs/docs/get-started/knowledge-interactions.md

@@ -11,22 +11,67 @@ import TabItem from '@theme/TabItem';
 
 ```java
 // ASK:
-AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(graphPattern);
+AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(communicativeAct, graphPattern);
 smartConnector.register(askInteraction);
 
 // ANSWER:
-AnswerKnowledgeInteraction answerInteraction = new AnswerKnowledgeInteraction(graphPattern);
+AnswerKnowledgeInteraction answerInteraction = new AnswerKnowledgeInteraction(communicativeAct, graphPattern);
 smartConnector.register(answerInteraction);
 
 // POST:
-PostKnowledgeInteraction postInteraction = new PostKnowledgeInteraction(graphPattern);
+PostKnowledgeInteraction postInteraction = new PostKnowledgeInteraction(communicativeAct, argumentGraphPattern, resultGraphPattern);
 smartConnector.register(postInteraction);
 
 // REACT:
-ReactKnowledgeInteraction reactInteraction = new ReactKnowledgeInteraction(graphPattern);
+ReactKnowledgeInteraction reactInteraction = new ReactKnowledgeInteraction(communicativeAct, argumentGraphPattern, resultGraphPattern);
 smartConnector.register(reactInteraction);
 ```
 
+You can also provide a name for your interaction, for example:
+```java
+AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(communicativeAct, graphPattern, name); 
+```
+
+If you want to use prefixes in your graph pattern, these can be defined in the `graphPattern`:
+```java
+GraphPattern graphPattern = new GraphPattern(prefixes, pattern);
+```
+
+</TabItem>
+<TabItem value="JSON" label="Rest API">
+To instantiate a Knowledge Interaction, you need to send a POST to `/sc/ki` with a body that contains the type of knowledge interaction that you want to make, and any required graph patterns.
+ASK and ANSWER require one graph pattern, like so:
+
+```json
+{
+  "knowledgeInteractionType": "AskKnowledgeInteraction",
+  "graphPattern": "?s ?p ?o"
+}
+```
+
+POST and REACT require an `argumentGraphPattern`, and optionally use a `resultGraphPattern`. For example:
+
+```json
+{
+  "knowledgeInteractionType": "PostKnowledgeInteraction",
+  "argumentGraphPattern": "?s ?p ?o",
+  "resultGraphPattern": "?x ?y ?z"
+}
+```
+
+You can also provide a name for your interaction and define prefixes for your graph patterns:
+
+```json
+{
+  "knowledgeInteractionType": "AskKnowledgeInteraction",
+  "knowledgeInteractionName": "my-ask",
+  "graphPattern": "?a rdf:type ex:Book",
+  "prefixes": {
+    "rdf": "https://www.w3.org/1999/02/22-rdf-syntax-ns/"
+  }
+}
+```
+
 </TabItem>
 </Tabs>
 
@@ -50,6 +95,30 @@ AskKnowledgeInteraction askInteraction = new AskKnowledgeInteraction(graphPatter
 AskResult interactionResult = sc.ask(askInteraction, queryBindings).get();
 ```
 
+</TabItem>
+<TabItem value="JSON" label="Rest API">
+Send a POST to `/sc/ask` to execute an Ask Knowledge Interaction.
+To execute a Post Knowledge Interaction, send a POST to `/sc/post`.
+
+Triggering an interaction requires you to provide two parameters:
+* `Knowledge-Base-Id`: specifies the Knowledge Base Id for which to execute the ask
+* `Knowledge-Interaction-Id`: specifies the Ask Knowledge Interaction that should be executed
+
+In the body you can also specify a binding set, or a recipient selector *and* binding set.
+The recipient selector can be used to select a single Knowledge Base Id which should be contacted.
+The binding set specifies values that you are interested in. These must correspond to the variables in the graph pattern of the knowledge interaction.
+```json
+{
+  "recipientSelector": {
+    "knowledgeBases": []
+  },
+  "bindingSet": [
+    {}
+  ]
+}
+```
+If you leave the array for `knowledgeBases` empty, then it will simply ask all relevant KBs.
+
 </TabItem>
 </Tabs>
 

docs/docs/tke-errors.md

@@ -0,0 +1,13 @@
+---
+  sidebar_position: 9
+---
+# Common Error Messages
+
+On this page you can find a list of common error messages and what they mean.
+
+### `x` is not an unprefixed URI or literal
+Whenever you are specifying variable bindings, for example in a binding set when executing an ask, you may encounter this error.
+It occurs because all variable bindings need to be either RDF Literals or IRIs.
+If you want to identify a specific object or device, you can use something like `<http://www.example.org/x>`.
+Note that if the variable binding is for a subject in a triple (?subject ?predicate ?object), then an IRI is always rquired.
+For more information on bindings and binding sets, see: [Bindings](https://docs.knowledge-engine.eu/java_developer_api#bindings).