Merge pull request #926 from finos/kriswest/issue312

Deprecating IntentMetadata.displayname
finos · May 30, 2023 · 7fa7c47 · 7fa7c47
2 parents 55d7775 + f705e71
commit 7fa7c47
Show file tree

Hide file tree

Showing 7 changed files with 30 additions and 30 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -20,6 +20,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 * Deprecated the `name` field in AppD records, to match deprecation of API signatures and metadata objects using `name` (see ([#722](https://github.com/finos/FDC3/pull/722))
 )) in 2.0 ([#928])(https://github.com/finos/FDC3/pull/928))
 
+* Deprecated `IntentMetadata.displayName` and the appD record's `interop.intents.listensFor[].displayName` field in favour of using intent names for display (which are required to be recognizable) as it can be set differently for each application in the appD ([#926](https://github.com/finos/FDC3/pull/926))
+
 ### Fixed
 
 * Further clarified the difference between the behavior of User channels and other channel types on joinUserChannel/addContextListener. ([#971](https://github.com/finos/FDC3/pull/971))

diff --git a/docs/api/ref/DesktopAgent.md b/docs/api/ref/DesktopAgent.md
@@ -288,7 +288,7 @@ I know 'StartChat' exists as a concept, and want to know which apps can resolve
 const appIntent = await fdc3.findIntent("StartChat");
 // returns a single AppIntent:
 // {
-//   intent: { name: "StartChat", displayName: "Chat" },
+//   intent: { name: "StartChat" },
 //   apps: [
 //    { appId: "Skype" }, 
 //    { appId: "Symphony" }, 
@@ -304,7 +304,7 @@ const appIntent = await fdc3.findIntent("StartChat");
 // returns an AppIntent, but with multiple options for resolution, 
 // which includes an existing instance of an application:
 // {
-//   intent: { name: "StartChat", displayName: "Chat" },
+//   intent: { name: "StartChat" },
 //   apps: [
 //    { appId: "Skype" }, 
 //    { appId: "Symphony" }, 
@@ -320,21 +320,21 @@ const appIntent = await fdc3.findIntent("StartChat", contact);
 
 // returns only apps that support the type of the specified input context:
 // {
-//     intent: { name: "StartChat", displayName: "Chat" },
+//     intent: { name: "StartChat" },
 //     apps: { name: "Symphony" }]
 // }
 
 const appIntent = await fdc3.findIntent("ViewContact", "fdc3.ContactList");
 // returns only apps that return the specified result type:
 // {
-//     intent: { name: "ViewContact", displayName: "View Contact Details" },
+//     intent: { name: "ViewContact" },
 //     apps: { appId: "MyCRM", resultType: "fdc3.ContactList"}]
 // }
 
 const appIntent = await fdc3.findIntent("QuoteStream", instrument, "channel<fdc3.Quote>");
 // returns only apps that return a channel which will receive the specified input and result types:
 // {
-//     intent: { name: "QuoteStream", displayName: "Quotes stream" },
+//     intent: { name: "QuoteStream" },
 //     apps: { appId: "MyOMS", resultType: "channel<fdc3.Quote>"}]
 // }
 ```
@@ -368,11 +368,11 @@ const appIntents = await fdc3.findIntentsByContext(context);
 // returns, for example:
 // [
 //   {
-//     intent: { name: "StartCall", displayName: "Call" },
+//     intent: { name: "StartCall" },
 //     apps: [{ appId: "Skype" }]
 //   },
 //   {
-//     intent: { name: "StartChat", displayName: "Chat" }, 
+//     intent: { name: "StartChat" }, 
 //     apps: [
 //       { appId: "Skype" }, 
 //       { appId: "Symphony" }, 
@@ -381,7 +381,7 @@ const appIntents = await fdc3.findIntentsByContext(context);
 //     ]
 //   },
 //   {
-//     intent: { name: "ViewContact", displayName: "View Contact" },
+//     intent: { name: "ViewContact" },
 //     apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}]
 //   }
 // ];
@@ -393,7 +393,7 @@ or I look for only intents that are resolved by apps returning a particular resu
 const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.ContactList");
 // returns for example:
 // [{
-//     intent: { name: "ViewContact", displayName: "View Contact" },
+//     intent: { name: "ViewContact" },
 //     apps: [{ appId: "Symphony" }, { appId: "MyCRM", resultType: "fdc3.ContactList"}]
 // }];
  

diff --git a/docs/api/ref/Metadata.md b/docs/api/ref/Metadata.md
@@ -302,8 +302,9 @@ interface IntentMetadata {
   /** The unique name of the intent that can be invoked by the raiseIntent call. */
   readonly name: string;
 
-  /** A friendly display name for the intent that should be used to render UI
-   *  elements.
+  /** Display name for the intent.
+   * @deprecated Use the intent name for display as display name may vary for
+   * each application as it is defined in the app's AppD record.
    */
   readonly displayName: string;
 }

diff --git a/src/api/DesktopAgent.ts b/src/api/DesktopAgent.ts
@@ -72,7 +72,7 @@ export interface DesktopAgent {
    *
    * // returns a single AppIntent:
    * // {
-   * //     intent: { name: "StartChat", displayName: "Chat" },
+   * //     intent: { name: "StartChat" },
    * //   apps: [
    * //    { appId: "Skype" },
    * //    { appId: "Symphony" },
@@ -88,7 +88,7 @@ export interface DesktopAgent {
    * // returns an AppIntent, but with multiple options for resolution,
    * // which includes an existing instance of an application:
    * // {
-   * //   intent: { name: "StartChat", displayName: "Chat" },
+   * //   intent: { name: "StartChat" },
    * //   apps: [
    * //    { appId: "Skype" },
    * //    { appId: "Symphony" },
@@ -104,23 +104,23 @@ export interface DesktopAgent {
    *
    * // returns only apps that support the type of the specified input context:
    * // {
-   * //     intent: { name: "StartChat", displayName: "Chat" },
+   * //     intent: { name: "StartChat" },
    * //     apps: [{ appId: "Symphony" }]
    * // }
    *
    * const appIntent = await fdc3.findIntent("ViewContact", contact, "fdc3.ContactList");
    *
    * // returns only apps that return the specified result Context type:
    * // {
-   * //     intent: { name: "ViewContact", displayName: "View Contact Details" },
+   * //     intent: { name: "ViewContact" },
    * //     apps: { appId: "MyCRM", resultType: "fdc3.ContactList"}]
    * // }
    *
    * const appIntent = await fdc3.findIntent("QuoteStream", instrument, "channel<fdc3.Quote>");
    *
    * // returns only apps that return a channel which will receive the specified input and result types:
    * // {
-   * //     intent: { name: "QuoteStream", displayName: "Quotes stream" },
+   * //     intent: { name: "QuoteStream" },
    * //     apps: [{ appId: "MyOMS", resultType: "channel<fdc3.Quote>"}]
    * // }
    * ```
@@ -148,11 +148,11 @@ export interface DesktopAgent {
    * // returns for example:
    * // [
    * //   {
-   * //     intent: { name: "StartCall", displayName: "Call" },
+   * //     intent: { name: "StartCall" },
    * //     apps: [{ name: "Skype" }]
    * //   },
    * //   {
-   * //     intent: { name: "StartChat", displayName: "Chat" },
+   * //     intent: { name: "StartChat" },
    * //     apps: [
    * //       { appId: "Skype" },
    * //       { appId: "Symphony" },
@@ -166,7 +166,7 @@ export interface DesktopAgent {
    * const appIntentsForType = await fdc3.findIntentsByContext(context, "fdc3.ContactList");
    * // returns for example:
    * // [{
-   * //     intent: { name: "ViewContact", displayName: "View Contacts" },
+   * //     intent: { name: "ViewContact" },
    * //     apps: [{ appId: "MyCRM", resultType: "fdc3.ContactList"}]
    * // }];
    *

diff --git a/src/api/IntentMetadata.ts b/src/api/IntentMetadata.ts
@@ -10,6 +10,9 @@ export interface IntentMetadata {
   /** The unique name of the intent that can be invoked by the raiseIntent call */
   readonly name: string;
 
-  /** A friendly display name for the intent that should be used to render UI elements */
+  /** Display name for the intent.
+   * @deprecated Use the intent name for display as display name may vary for
+   * each application as it is defined in the app's AppD record.
+   */
   readonly displayName: string;
 }
diff --git a/src/app-directory/specification/appd.yaml b/src/app-directory/specification/appd.yaml
@@ -624,7 +624,8 @@ components:
       properties:
         displayName:
           type: string
-          description: An optional display name for the intent that may be used in UI instead of the name.
+          description: Optional display name for the intent. Deprecated in favour of the intent name, which is common amongst all apps that support it, where the display name may vary as it is defined in the app's AppD record.
+          deprecated: true
         contexts:
           type: array
           items:
@@ -1043,11 +1044,9 @@ components:
           intents: 
             listensFor: 
               ViewChart: 
-                displayName: View Chart
                 contexts: 
                   - fdc3.instrument
               myApp.GetPrice: 
-                displayName: Get Price
                 contexts: 
                   - fdc3.instrument
                 resultType: myApp.quote
@@ -1157,11 +1156,9 @@ components:
               intents: 
                 listensFor: 
                   ViewChart: 
-                    displayName: View Chart
                     contexts: 
                       - fdc3.instrument
                   myApp.GetPrice: 
-                    displayName: Get Price
                     contexts: 
                       - fdc3.instrument
                     resultType: myApp.quote

diff --git a/website/static/schemas/next/app-directory.yaml b/website/static/schemas/next/app-directory.yaml
@@ -624,7 +624,8 @@ components:
       properties:
         displayName:
           type: string
-          description: An optional display name for the intent that may be used in UI instead of the name.
+          description: Optional display name for the intent. Deprecated in favour of the intent name, which is common amongst all apps that support it, where the display name may vary as it is defined in the app's AppD record.
+          deprecated: true
         contexts:
           type: array
           items:
@@ -1043,11 +1044,9 @@ components:
           intents: 
             listensFor: 
               ViewChart: 
-                displayName: View Chart
                 contexts: 
                   - fdc3.instrument
               myApp.GetPrice: 
-                displayName: Get Price
                 contexts: 
                   - fdc3.instrument
                 resultType: myApp.quote
@@ -1157,11 +1156,9 @@ components:
               intents: 
                 listensFor: 
                   ViewChart: 
-                    displayName: View Chart
                     contexts: 
                       - fdc3.instrument
                   myApp.GetPrice: 
-                    displayName: Get Price
                     contexts: 
                       - fdc3.instrument
                     resultType: myApp.quote