Add term UI.UserInteraction

examples/UI.UserInteraction-sample.json

@@ -0,0 +1,67 @@
+{
+  "$Version": "4.0",
+  "$Reference": {
+    "https://sap.github.io/odata-vocabularies/vocabularies/UI.json": {
+      "$Include": [{ "$Namespace": "com.sap.vocabularies.UI.v1", "$Alias": "UI" }]
+    }
+  },
+  "userinteraction.sample": {
+    "$Alias": "self",
+    "AlternativeProduct": {
+      "$Kind": "EntityType",
+      "Product": {},
+      "UpsellNote": {},
+      "@UI.LineItem": [
+        {
+          "@odata.type": "https://sap.github.io/odata-vocabularies/vocabularies/UI.xml#UI.DataField",
+          "Label": "Alternative Product",
+          "Value": { "$Path": "Product" }
+        },
+        {
+          "@odata.type": "https://sap.github.io/odata-vocabularies/vocabularies/UI.xml#UI.DataField",
+          "Label": "Why it's better to buy this",
+          "Value": { "$Path": "UpsellNote" }
+        }
+      ]
+    },
+    "SalesOrderItem": {
+      "$Kind": "EntityType",
+      "_AlternativeProducts": {
+        "$Kind": "NavigationProperty",
+        "$Collection": true,
+        "$Type": "self.AlternativeProduct",
+        "@[email protected]": "Please choose a product",
+        "@UI.UserInteraction": {
+          "@odata.type": "https://sap.github.io/odata-vocabularies/vocabularies/UI.xml#UI.UserInteractionChooseSingle",
+          "Parameters": [{ "ValueListProperty": "Product", "LocalDataProperty": "self.ExchangeProduct/NewProduct" }]
+        }
+      },
+      "_UpgradeProduct": {
+        "$Kind": "NavigationProperty",
+        "$Type": "self.AlternativeProduct",
+        "$Nullable": true,
+        "@[email protected]": "Do you want to upgrade the product?",
+        "@UI.UserInteraction": {
+          "@odata.type": "https://sap.github.io/odata-vocabularies/vocabularies/UI.xml#UI.UserInteractionConfirm",
+          "Parameters": [{ "ValueListProperty": "Product", "LocalDataProperty": "self.ExchangeProduct/NewProduct" }]
+        }
+      }
+    },
+    "ExchangeProduct": [
+      {
+        "$Kind": "Action",
+        "$IsBound": true,
+        "$Parameter": [
+          { "$Name": "item", "$Type": "self.SalesOrderItem" },
+          { "$Name": "NewProduct", "$Nullable": true }
+        ],
+        "$ReturnType": { "$Type": "self.SalesOrderItem", "$Nullable": true }
+      }
+    ],
+    "SalesOrderService": {
+      "$Kind": "EntityContainer",
+      "SalesOrderItems": { "$Collection": true, "$Type": "self.SalesOrder" }
+    }
+  },
+  "$EntityContainer": "userinteraction.sample.SalesOrderService"
+}

examples/UI.UserInteraction-sample.md

@@ -0,0 +1,87 @@
+# Modelling a user interaction with annotations
+
+Certain user interactions cannot be handled by one request, because they follow the pattern "user triggers, server offers, user chooses". For example, the action "exchange product in a sales order item" is triggered by the user on a sales order item, the server returns the item with an inlined collection of alternative products, from which the user must then choose, and the request is repeated with the chosen product.
+
+In the "upgrade case", the server returns only one alternative product and lets the user confirm rather than choose. Both cases (exchange and upgrade) are supported by a service with [these metadata](UI.UserInteraction-sample.xml), let's look at an example of the exchange case where the user chooses.
+
+## User triggers
+
+The "exchange product" action is triggered by the user on a sales order item without specifying a parameter.
+
+```
+POST SalesOrderItems(...)/userinteraction.sample.ExchangeProduct HTTP/1.1
+Content-Type: application/json
+
+{}
+```
+
+## Server offers
+
+The server returns the item with an inlined collection of alternative products, from which the user must then choose.
+
+```
+HTTP/1.1 409 Conflict
+Content-Type: application/json
+
+{
+  "Order": "A",
+  "Item": "010",
+  "Product": "Wheat flour",
+  "_AlternativeProducts": [
+    {"Product": "Rice", "UpsellNote": "Healthier"},
+    {"Product": "Noodles", "UpsellNote": "Tastes better"}
+  ]
+}
+```
+
+Servers that cannot send a structured payload in a 4xx response may instead return an error message with a [`Common.callback`](../vocabularies/Common.md#callback) instance annotation.
+
+```
+HTTP/1.1 400 Bad Request
+Content-Type: application/json
+
+{
+  "error": {
+    "code": "UF0",
+    "message": {
+      "lang": "en",
+      "value": "Missing parameter 'NewProduct'"
+    },
+    "@Common.callback": {
+      "Order": "A",
+      "Item": "010",
+      "Product": "Wheat flour",
+      "_AlternativeProducts": [
+        {"Product": "Rice", "UpsellNote": "Healthier"},
+        {"Product": "Noodles", "UpsellNote": "Tastes better"}
+      ]
+    }
+  }
+}
+```
+
+Upon receiving either of these payloads, the client constructs a user dialog based on (a) the `UI.UserInteraction` annotation of the `_AlternativeProducts` navigation property and (b) the UI annotations of the `AlternativeProduct` entity type. The [type](../vocabularies/UI.md#UserInteractionChooseSingle) of the `UI.UserInteraction` annotation implies that this is a choice popup, not a confirmation prompt. The superscripted headings in the popup also come from the annotations.
+
+> ### Please choose a product<sup>a</sup>
+>
+> |Alternative Product<sup>b</sup>|Why it's better to buy this<sup>b</sup>|
+> |-------------------------------|---------------------------------------|
+> |Rice                           |Healthier                              |
+> |Noodles                        |Tastes better                          |
+>
+> <kbd>OK</kbd> <kbd>Cancel</kbd>
+
+## User chooses
+
+After the user has chosen, the client repeats the request with the chosen product inserted according to the `UI.UserInteraction/Parameters`.
+
+```
+POST SalesOrderItems(...)/userinteraction.sample.ExchangeProduct HTTP/1.1
+Content-Type: application/json
+
+{"NewProduct": "Rice"}
+```
+
+The status 409 in the first response implies that the first request made no changes on the server. As a consequence
+* if the first request had been a POST on a collection, the second request would again be a POST (not a PATCH)
+* no second request is made if the user has canceled the popup (no clean-up needed).

examples/UI.UserInteraction-sample.xml

@@ -0,0 +1,66 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
+  <edmx:Reference Uri="https://sap.github.io/odata-vocabularies/vocabularies/UI.xml">
+    <edmx:Include Namespace="com.sap.vocabularies.UI.v1" Alias="UI" />
+  </edmx:Reference>
+  <edmx:DataServices>
+    <Schema Namespace="userinteraction.sample" Alias="self" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+      <EntityType Name="AlternativeProduct">
+        <Property Name="Product" Type="Edm.String" Nullable="false"/>
+        <Property Name="UpsellNote" Type="Edm.String" Nullable="false"/>
+        <Annotation Term="UI.LineItem">
+          <Collection>
+            <Record Type="UI.DataField">
+              <PropertyValue Property="Label" String="Alternative Product"/>
+              <PropertyValue Property="Value" Path="Product"/>
+            </Record>
+            <Record Type="UI.DataField">
+              <PropertyValue Property="Label" String="Why it's better to buy this"/>
+              <PropertyValue Property="Value" Path="UpsellNote"/>
+            </Record>
+          </Collection>
+        </Annotation>
+      </EntityType>
+      <EntityType Name="SalesOrderItem">
+        <NavigationProperty Name="_AlternativeProducts" Type="Collection(self.AlternativeProduct)">
+          <Annotation Term="UI.UserInteraction">
+            <Annotation Term="Core.Description" String="Please choose a product"/>
+            <Record Type="UI.UserInteractionChooseSingle">
+              <PropertyValue Property="Parameters">
+                <Collection>
+                  <Record>
+                    <PropertyValue Property="ValueListProperty" String="Product"/>
+                    <PropertyValue Property="LocalDataProperty" PropertyPath="self.ExchangeProduct/NewProduct"/>
+                  </Record>
+                </Collection>
+              </PropertyValue>
+            </Record>
+          </Annotation>
+        </NavigationProperty>
+        <NavigationProperty Name="_UpgradeProduct" Type="self.AlternativeProduct">
+          <Annotation Term="UI.UserInteraction">
+            <Annotation Term="Core.Description" String="Do you want to upgrade the product?"/>
+            <Record Type="UI.UserInteractionConfirm">
+              <PropertyValue Property="Parameters">
+                <Collection>
+                  <Record>
+                    <PropertyValue Property="ValueListProperty" String="Product"/>
+                    <PropertyValue Property="LocalDataProperty" PropertyPath="self.ExchangeProduct/NewProduct"/>
+                  </Record>
+                </Collection>
+              </PropertyValue>
+            </Record>
+          </Annotation>
+        </NavigationProperty>
+      </EntityType>
+      <Action Name="ExchangeProduct" IsBound="true">
+        <Parameter Name="item" Type="self.SalesOrderItem" Nullable="false"/>
+        <Parameter Name="NewProduct" Type="Edm.String"/>
+        <ReturnType Type="self.SalesOrderItem"/>
+      </Action>
+      <EntityContainer Name="SalesOrderService">
+        <EntitySet Name="SalesOrderItems" EntityType="self.SalesOrder"/>
+      </EntityContainer>
+    </Schema>
+  </edmx:DataServices>
+</edmx:Edmx>

vocabularies/Common.json

@@ -10,6 +10,9 @@
     "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.Aggregation.V1.json": {
       "$Include": [{ "$Namespace": "Org.OData.Aggregation.V1", "$Alias": "Aggregation" }]
     },
+    "https://oasis-tcs.github.io/odata-vocabularies/vocabularies/Org.OData.JSON.V1.json": {
+      "$Include": [{ "$Namespace": "Org.OData.JSON.V1", "$Alias": "JSON" }]
+    },
     "https://sap.github.io/odata-vocabularies/vocabularies/UI.json": {
       "$Include": [{ "$Namespace": "com.sap.vocabularies.UI.v1", "$Alias": "UI" }]
     },
@@ -1351,6 +1354,15 @@
       "@Common.Experimental": true,
       "@Core.Description": "Channel for WebSocket connections",
       "@Core.LongDescription": "Messages sent over the channel follow the [ABAP Push Channel Protocol](https://community.sap.com/t5/application-development-blog-posts/specification-of-the-push-channel-protocol-pcp/ba-p/13137541).\nTo consume a channel, the client opens a web socket connection at the [`WebSocketBaseURL`](#WebSocketBaseURL)\nfollowed by URL parameters\n- parameter name = annotation qualifier, parameter value = channel ID (see below)\n- parameter name = `relatedService`, parameter value = base URL (relative to server root) of the OData service of the app\n\n<dl>Supported qualifiers and channel IDs:\n<dt>`sideEffects` <dd>Notifications about side effects to be triggered by the client (channel ID = non-null annotation value)\n</dl>"
+    },
+    "callback": {
+      "$Kind": "Term",
+      "$Type": "JSON.JSON",
+      "$AppliesTo": ["Record"],
+      "@Common.Experimental": true,
+      "@Common.IsInstanceAnnotation": true,
+      "@Core.Description": "Data that the server has embedded within an error response to make a callback to the client",
+      "@Core.LongDescription": "This instance annotation has the format of a [message body](https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html#sec_MessageBody)\n          that could be a valid response to the given request.\n          The callback allows the client to adjust the request so that it can be successfully repeated.\n          An example for such a callback is a user interaction to resolve a conflict that was detected by the server,\n          see [`UI.UserInteraction`](UI.md#UserInteraction)."
     }
   }
 }