Merge remote-tracking branch 'origin/main' into UI.UserInteraction

SAP · Jul 29, 2024 · 8c34ac5 · 8c34ac5
2 parents eadfe5e + 082489e
commit 8c34ac5
Show file tree

Hide file tree

Showing 46 changed files with 2,891 additions and 1,266 deletions.
diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
@@ -0,0 +1,54 @@
+# Sample workflow for building and deploying a Jekyll site to GitHub Pages
+name: Build GitHub Pages using pandoc
+
+on:
+  # Runs on pushes targeting the default branch
+  push:
+    branches: ["main"]
+
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued.
+# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete.
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  # Build job
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+      - name: Setup pandoc
+        uses: nikeee/setup-pandoc@v1
+        with:
+          pandoc-version: 3.1.12.2
+      - name: Build with pandoc
+        run: |
+          npm ci
+          npm run pages
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+
+  # Deployment job
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/.github/workflows/nodejs.yml b/.github/workflows/nodejs.yml
@@ -1,6 +1,6 @@
-name: Node CI
+name: Rebuild JSON and MarkDown files
 
-on: push
+on: [push, workflow_dispatch]
 
 jobs:
   build:
@@ -11,13 +11,17 @@ jobs:
         node-version: [20.x]
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           ref: ${{ github.head_ref }}
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: ${{ matrix.node-version }}
+      - name: Setup pandoc
+        uses: nikeee/setup-pandoc@v1
+        with:
+          pandoc-version: 3.1.12.2
       - name: npm install, build, and test
         run: |
           npm ci

diff --git a/_layouts/default.html b/_layouts/default.html
diff --git a/_site/.gitignore b/_site/.gitignore
@@ -0,0 +1,2 @@
+*
+!.gitignore
diff --git a/assets/template.html b/assets/template.html
@@ -0,0 +1,92 @@
+<!DOCTYPE html>
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$lang$" xml:lang="$lang$"$if(dir)$ dir="$dir$"$endif$>
+<head>
+  <meta charset="utf-8" />
+  <meta name="generator" content="pandoc" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes" />
+$for(author-meta)$
+  <meta name="author" content="$author-meta$" />
+$endfor$
+$if(date-meta)$
+  <meta name="dcterms.date" content="$date-meta$" />
+$endif$
+$if(keywords)$
+  <meta name="keywords" content="$for(keywords)$$keywords$$sep$, $endfor$" />
+$endif$
+$if(description-meta)$
+  <meta name="description" content="$description-meta$" />
+$endif$
+  <title>$if(title-prefix)$$title-prefix$ – $endif$$pagetitle$</title>
+  <style>
+    $styles.html()$
+  </style>
+$for(css)$
+  <link rel="stylesheet" href="$css$" />
+$endfor$
+$for(header-includes)$
+  $header-includes$
+$endfor$
+$if(math)$
+$if(mathjax)$
+  <script src="https://cdnjs.cloudflare.com/polyfill/v3/polyfill.min.js?features=es6"></script>
+$endif$
+  $math$
+$endif$
+</head>
+<body>
+$for(include-before)$
+$include-before$
+$endfor$
+<div class="container-lg px-3 my-5 markdown-body">
+$if(title)$
+<header id="title-block-header">
+<h1 class="title">$title$</h1>
+$if(subtitle)$
+<p class="subtitle">$subtitle$</p>
+$endif$
+$for(author)$
+<p class="author">$author$</p>
+$endfor$
+$if(date)$
+<p class="date">$date$</p>
+$endif$
+$if(abstract)$
+<div class="abstract">
+<div class="abstract-title">$abstract-title$</div>
+$abstract$
+</div>
+$endif$
+</header>
+$endif$
+$if(toc)$
+<nav id="$idprefix$TOC" role="doc-toc">
+$if(toc-title)$
+<h2 id="$idprefix$toc-title">$toc-title$</h2>
+$endif$
+$table-of-contents$
+</nav>
+$endif$
+$body$
+</div>
+<footer>
+  <div class="container">
+    <p>
+      © Copyright 2016&ndash;2024, SAP SE and odata-vocabularies Contributors.
+      <a href="https://www.sap.com/corporate/en/legal/impressum.html">Legal Disclosure</a>.
+      <a href="https://www.sap.com/corporate/en/legal/terms-of-use.html">Terms of Use</a>.
+      <a href="$github-repo$/blob/main/$github-path$">View On <strong>GitHub</strong></a>.
+    </p>
+    <p>
+      This site is hosted by <a href="https://pages.github.com/">GitHub Pages</a>. 
+      Please see the <a href="https://docs.github.com/en/github/site-policy/github-privacy-statement">GitHub Privacy Statement</a> for any information how GitHub processes your personal data.
+    </p>
+  </div>
+</footer>
+$for(include-after)$
+$include-after$
+$endfor$
+$for(include-script)$
+$include-script$
+$endfor$
+</body>
+</html>
diff --git a/docs/recommendations.md b/docs/recommendations.md
@@ -0,0 +1,91 @@
+Entity types for which recommendations are available have an additional property carrying the recommendations and the following annotation pointing to this property:
+```xml
+<EntityType Name="...">
+  <Annotation Term="UI.Recommendations" Path="SAP__Recommendations" />
+  <Key>
+    <PropertyRef Name="ID" />
+  </Key>
+  <Property Name="ID" Type="Edm.String" Nullable="false" />
+  <Property Name="DocumentType" Type="Edm.String" />
+  ...
+  <Property Name="SAP__Recommendations" Type="self.RecommendationsType" />
+</EntityType>
+<ComplexType Name="RecommendationsType">
+  <Property Name="DocumentType" Type="Collection(UI.PropertyRecommendationType)" />
+  ...
+</ComplexType>
+```
+
+Clients request recommendations from the server at their discretion.
+
+```mermaid
+sequenceDiagram
+  actor client as Fiori client
+  actor otherclient as Other Fiori client<br>of same collaborative draft
+  box ABAP
+    participant server as OData service
+    participant task as New task
+  end
+  participant AI as BTP recommendations service
+  client ->>+ server: POST $batch
+  server ->> server: PATCH SalesOrder('A')
+  server ->> server: GET SalesOrder('A')?$expand=... for side effects
+  server -->> client: $batch response
+  par server decides whether to update recommendations
+    opt input for recommendations has changed
+      server ->>+ task: call function ... starting new task
+      deactivate server
+      task ->>+ AI: compute recommendations
+      AI -->>- task: return recommendations
+      task ->> task: update recommendations in draft
+      deactivate task
+    end
+  and
+    client ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+    server ->> server: read recommendations from draft
+    server -->>- client: return recommendations
+  and
+    otherclient ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+    server ->> server: read recommendations from draft
+    server -->>- otherclient: return recommendations
+  end
+```
+
+Alternatively, clients can be notified via web socket if recommendations have been updated.
+
+```mermaid
+sequenceDiagram
+  actor client as Fiori client
+  actor otherclient as Other Fiori client<br>of same collaborative draft
+  box ABAP
+    participant server as OData service
+    participant task as New task
+  end
+  participant AI as BTP recommendations service
+  client ->>+ server: POST $batch
+  server ->> server: PATCH SalesOrder('A')
+  server ->> server: GET SalesOrder('A')?$expand=... for side effects
+  server -->> client: $batch response
+  opt input for recommendations has changed
+    server ->>+ task: call function ... starting new task
+    deactivate server
+    task ->>+ AI: compute recommendations
+    AI -->>- task: return recommendations
+    task ->> task: update recommendations in draft
+    par
+      task ->> client: notify client of updated recommendations
+    and
+      task ->> otherclient: notify client of updated recommendations
+    end
+    deactivate task
+    par
+      client ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+      server ->> server: read recommendations from draft
+      server -->>- client: return recommendations
+    and
+      otherclient ->>+ server: GET SalesOrder('A')?$select=SAP__Recommendations&$expand=...
+      server ->> server: read recommendations from draft
+      server -->>- otherclient: return recommendations
+    end
+  end
+```
diff --git a/examples/Common.SortOrder-sample.json b/examples/Common.SortOrder-sample.json
@@ -0,0 +1,25 @@
+{
+  "$Version": "4.0",
+  "$Reference": {
+    "https://sap.github.io/odata-vocabularies/vocabularies/Common.json": {
+      "$Include": [{ "$Namespace": "com.sap.vocabularies.Common.v1", "$Alias": "Common" }]
+    }
+  },
+  "sortorder.sample": {
+    "WorkerTimeSheet": {
+      "$Kind": "EntityType",
+      "ClockInDateTime": { "$Type": "Edm.DateTimeOffset", "$Nullable": true, "$Precision": 0 },
+      "ClockOutDateTime": { "$Type": "Edm.DateTimeOffset", "$Nullable": true, "$Precision": 0 }
+    },
+    "$Annotations": {
+      "timezone.sample.WorkerTimeSheet": {
+        "@Common.SortOrder#HeroesOfLabor": [
+          {
+            "Expression": { "$Sub": [{ "$Path": "ClockOutDateTime" }, { "$Path": "ClockInDateTime" }] },
+            "Descending": true
+          }
+        ]
+      }
+    }
+  }
+}
diff --git a/examples/Common.SortOrder-sample.xml b/examples/Common.SortOrder-sample.xml
@@ -0,0 +1,29 @@
+<?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/Common.xml">
+    <edmx:Include Namespace="com.sap.vocabularies.Common.v1" Alias="Common" />
+  </edmx:Reference>
+  <edmx:DataServices>
+    <Schema Namespace="sortorder.sample" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+      <EntityType Name="WorkerTimeSheet">
+        <Property Name="ClockInDateTime" Type="Edm.DateTimeOffset" />
+        <Property Name="ClockOutDateTime" Type="Edm.DateTimeOffset" />
+      </EntityType>
+      <Annotations Target="timezone.sample.WorkerTimeSheet">
+        <Annotation Term="Common.SortOrder" Qualifier="HeroesOfLabor">
+          <Collection>
+            <Record>
+              <PropertyValue Property="Expression">
+                <Sub>
+                  <Path>ClockOutDateTime</Path>
+                  <Path>ClockInDateTime</Path>
+                </Sub>
+              </PropertyValue>
+              <PropertyValue Property="Descending" Bool="true"/>
+            </Record>
+          </Collection>
+        </Annotation>
+      </Annotations>
+    </Schema>
+  </edmx:DataServices>
+</edmx:Edmx>