Merge pull request #701 from mistryvinay/master

681 Update Intent Naming Conventions

CHANGELOG.md

@@ -7,6 +7,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
 ## [Unreleased]
 
 ### Added
+* Updated for Intent Naming conventions.  Added hyperlinks for existing Intent spec definitions. Changes based on ([#701](https://github.com/finos/FDC3/pull/701))
 * Definition of the `icons` property of `AppMetadata`, based on PWA icon spec ([#319](https://github.com/finos/FDC3/pull/319))
 * Added support for raiseIntent without a context via the addition of the `fdc3.nothing` context type ([#375](https://github.com/finos/FDC3/pull/375))
 * Added [**FDC3 Workbench**](https://fdc3.finos.org/toolbox/fdc3-workbench/), an FDC3 API developer application ([#457](https://github.com/finos/FDC3/pull/457))

docs/intents/overview.md

@@ -59,8 +59,8 @@ const intentsAndApps = await fdc3.findIntentsByContext({
 
 ## Using Intents without a context
 As the [Desktop Agent API](api/ref/DesktopAgent) and [App Directory](app-directory/overview) both
-require a context to specified whereever intents are used, using an intent without a context is
-achieved through the use of an explcit `null` context type `fdc3.nothing`. By using an explicit type
+require a context to be specified wherever intents are used, using an intent without a context is
+achieved through the use of an explicit `null` context type `fdc3.nothing`. By using an explicit type
 to represent a lack of context we allow applications to declare their support for a lack of 
 context.
 

docs/intents/spec.md

@@ -8,14 +8,17 @@ title: Intents Specification (next)
 
 FDC3 [Intents](intents-intro) define a standard set of verbs that, in conjunction with context data acting as nouns, can be used to put together common cross-application workflows on the financial desktop.
 
-### Naming Syntax
+### Naming Conventions
+Naming of Intents SHOULD follow the below guidelines:
 * Intent names should be free of non-alphanumeric characters.
 * ‘.’ will be used to namespace the intent (see below).
 * Intent names should be in UpperCamelCase.
 
+> **Note:** The naming guidelines should be adhered to when creating future Intents.  This is to ensure they meet the criteria for addition to the FDC3 standard and to provide a consistent user experience.
+
 ### Characteristics
 
-Intents shoulde be:
+When creating Intents they should be:
 * Recognizable
     * Generally self-evident what the thing is
 * Repeatable
@@ -29,31 +32,44 @@ Intents shoulde be:
 
 ### Namespaces ###
 All standard intent names are reserved. Applications may use their own intents ad hoc.
-However, there is a need for applications to ensure that their intents avoid collision. The recommended approach here is to use the app name as the noun. For example, the ‘myChart’ App may expose the ‘ViewChart’ intent and the ‘myChart.Foo’ proprietary intent.
+However, there is occasionally a need for applications to ensure that their intents avoid collision, for example, where a workflow is highly specific to or internal to an application. The recommended approach is to namespace the intent with the application name. For example, the ‘myChart’ App may expose the ‘ViewChart’ intent and the ‘myChart.Foo’ proprietary intent.
 
-## Initial Set of Standard Intents ##
+### Intent Name Prefixes
+Early versions of the FDC3 standard included 8 intents, which used one of two different prefixes.  The two initial prefixes were `View___` and `Start___`.  These are used to help define the behavior of the expected app when resolving the intent. 
+
+### `View___`
+  * Expected behaviour: Content should be displayed to the user.
+
+### `Start___`
+  * Expected behaviour: An interaction, such as a chat room or email thread, should be initiated.
+
+As more use cases were identified it was clear further Intents were required.  FDC3 2.0 expanded this set to include the following:
+
+### `Create___`
+  * Expected behaviour: A new record or entity should be created. The operation should fail if it already exists.
 
-### StartCall
-  * Expected context: Contact
-  * Expected behavior: initiate call with contact(s)
-### StartChat
-  * Expected context: Contact
-  * Expected behavior: initiate chat with contact(s)
-### ViewChart
-  * Expected context: Instrument
-  * Expected behavior: display a chart for the context
-### ViewContact
-  * Expected context: Contact
-  * Expected behavior: display details of a contact
-### ViewQuote
-  * Expected context: Instrument
-  * Expected behavior: display pricing for an instrument
-### ViewNews
-  * Expected context: Instrument, Contact, Organization, etc.
-  * Expected behavior: display news for a given context
-### ViewInstrument
-  * Expected context: Instrument
-  * Expected behavior: display relevant information for a given instrument
-### ViewAnalysis
-  * Expected context: Instrument, Organization, etc.
-  * Expected behavior: Send context to receiving application for displaying analysis
+### `Update___`
+  * Expected behaviour: An existing record or entity should be updated. The operation should fail if it does not exist.
+
+### `CreateOrUpdate___`
+  * Expected behaviour: A new record or entity should be created, or an existing one updated if it exists.
+
+### `Delete___`
+  * Expected behaviour: An existing record or entity should be deleted. The operation should fail if it does not exist.
+
+### `Get___`
+  * Expected behaviour: A record or entity should be retrieved and returned as an intent result. The operation should fail if the record does not exist.
+
+### `Share___`
+  * Expected behaviour: A record or entity should shared. The operation should fail if it does not exist
+
+## Initial Set of Standard Intents ##
+A list of standardized intents are defined in the following pages:
+* [`StartCall`](ref/StartCall)
+* [`StartChat`](ref/StartChat)
+* [`ViewChart`](ref/ViewChart)
+* [`ViewContact`](ref/ViewContact)
+* [`ViewQuote`](ref/ViewQuote)
+* [`ViewNews`](ref/ViewNews)
+* [`ViewInstrument`](ref/ViewInstrument)
+* [`ViewAnalysis`](ref/ViewAnalysis)