idnits 2.17.1 draft-dconmy-notes-uri-scheme-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an Introduction section. ** There are 13 instances of too long lines in the document, the longest one being 51 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (18 March 2022) is 767 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Unused Reference: 'RFC3978' is defined on line 330, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2396 (Obsoleted by RFC 3986) ** Obsolete normative reference: RFC 3978 (Obsoleted by RFC 5378) Summary: 4 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group D. Conmy 3 Internet-Draft HCL Software 4 Intended status: Informational 18 March 2022 5 Expires: 19 September 2022 7 The 'notes' URI Scheme for viewing HCL Notes/Domino resources 8 draft-dconmy-notes-uri-scheme-02 10 Abstract 12 This document describes the 'notes' URI scheme. Specifically, it 13 lays out the syntactic components and how those components are used 14 by URI resolution to locate and view or edit a Notes resource, 15 typically an application and/or document. 17 Status of This Memo 19 This Internet-Draft is submitted in full conformance with the 20 provisions of BCP 78 and BCP 79. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF). Note that other groups may also distribute 24 working documents as Internet-Drafts. The list of current Internet- 25 Drafts is at https://datatracker.ietf.org/drafts/current/. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 This Internet-Draft will expire on 19 September 2022. 34 Copyright Notice 36 Copyright (c) 2022 IETF Trust and the persons identified as the 37 document authors. All rights reserved. 39 This document is subject to BCP 78 and the IETF Trust's Legal 40 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 41 license-info) in effect on the date of publication of this document. 42 Please review these documents carefully, as they describe your rights 43 and restrictions with respect to this document. Code Components 44 extracted from this document must include Revised BSD License text as 45 described in Section 4.e of the Trust Legal Provisions and are 46 provided without warranty as described in the Revised BSD License. 48 Table of Contents 50 1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 52 3. Applications and/or Protocols which use this URI Scheme 53 Name . . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 4. Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . 3 55 4.1. General Syntax . . . . . . . . . . . . . . . . . . . . . 3 56 4.2. ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 3 57 4.3. Special Cases and Default Values . . . . . . . . . . . . 4 58 4.3.1. If a Server is not specified and an application or 59 document is to be located . . . . . . . . . . . . . . 4 60 4.3.2. If a Server is specified but not available . . . . . 5 61 4.3.3. If a view or folder is not supplied . . . . . . . . . 5 62 4.3.4. If a view or form name is supplied . . . . . . . . . 5 63 4.3.5. If a viewUNID or folderUNID of 0 is supplied . . . . 5 64 4.3.6. If OpenForm is specified . . . . . . . . . . . . . . 5 65 4.4. Encoding Rules . . . . . . . . . . . . . . . . . . . . . 5 66 4.4.1. Case sensitivity of URI components . . . . . . . . . 5 67 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 68 5.1. Application Examples . . . . . . . . . . . . . . . . . . 5 69 5.2. Document Examples . . . . . . . . . . . . . . . . . . . . 6 70 5.3. Application User Interface Examples . . . . . . . . . . . 7 71 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 72 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 73 8. Appendix A: Registration Template . . . . . . . . . . . . . . 8 74 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 75 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 76 9.2. Informative References . . . . . . . . . . . . . . . . . 9 77 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 79 1. Goals 81 The primary goal of the 'notes' URI is to view or edit a resource. 82 Typically, a 'notes' URI would be encountered in MIME Email which 83 contains links to other applications and/or documents residing on 84 Domino server(s). A 'notes' URI can also be used with operating 85 system clipboard operations to share a link with a native application 86 or a browser application. 88 When a 'notes' URI is clicked, a local installation of an application 89 that supports the protocol will be launched and the resource will be 90 located and shown. 92 2. Conventions and Definitions 94 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 95 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 96 "OPTIONAL" in this document are to be interpreted as described in BCP 97 14 [RFC2119] [RFC8174] when, and only when, they appear in all 98 capitals, as shown here. 100 3. Applications and/or Protocols which use this URI Scheme Name 102 All HCL Notes, HCL Nomad, HCL Client Application Access, IBM Client 103 Application Access, IBM Notes and Lotus Notes clients since 1999 have 104 supported the 'notes' URI scheme. [HCLDomino] 106 4. Syntax Rules 108 4.1. General Syntax 110 The 'notes' URI comes in several forms described below. 112 4.2. ABNF Grammar 114 The full ABNF (certain values are included by reference from 115 [RFC2396]): 117 notes-uri = "notes:" (formDoc | formDocNew | 118 formApp1 | formApp2 | formApp3 | 119 formUI) 120 formDoc = "//" [server] "/" application "/" (viewUNID | folderUNID) "/" docUNID ["?" queryDoc] 121 formDocNew = "//" [server] "/" application "/" name "?OpenForm" 122 formApp1 = "//" [server] "/" application 123 formApp2 = "//" [server] "/" application "/" (viewUNID | folderUNID ) 124 formApp3 = "//" [server] "/" application "/" name "?" queryElement ["&" parameter] 125 formUI = "///ClientBookmark?" uiElement 127 server = hostname 128 hostname = // as specified in {{RFC2396}} 130 application = (appReplicaID | appFileAndPath) 131 appReplicaID = 16*HEXDIG 132 appFileAndPath = 1*(unreserved | escaped)(".nsf" | ".ntf") 134 viewUNID = (32*HEXDIG | "0") 135 folderUNID = (32*HEXDIG | "0") 136 docUNID = 32*HEXDIG 138 name = 1*(unreserved | escaped) 139 queryDoc = ("EditDocument" | "OpenDocument") 140 queryElement = ("OpenFrameset" | "OpenView") 141 uiElement = ("OpenDatabases" | "OpenReplication" | "OpenWorkspace") 142 parameter = ("view=" viewUNID) 144 unreserved = alphanum | allowedmark 145 alphanum = // as specified in {{RFC2396}} 146 allowedmark = "-" | "_" | "~" | "(" | ")" 147 escaped = "%" hex hex 148 hex = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | 149 "8" | "9" | "A" | "B" | "C" | "D" | "E" | "F" 151 4.3. Special Cases and Default Values 153 4.3.1. If a Server is not specified and an application or document is 154 to be located 156 In the case where the 'notes' URI does not contain a named server and 157 the appReplicaID is specified, the client application SHOULD locate 158 the specified application. 160 In the case where the 'notes' URI does not contain a named server and 161 an appFileAndPath is specified, the client applicaiton SHOULD locate 162 a local copy of the application. 164 4.3.2. If a Server is specified but not available 166 In the case where the 'notes' URI does contain a named server and the 167 named server is currently unreachable, the client application MAY 168 locate the resource on an alternate server as if the server were not 169 specified. See Section 4.3.1 171 4.3.3. If a view or folder is not supplied 173 In the case where the 'notes' URI does not contain a viewUNID, 174 folderUNID or name, and the application initially shows a view or 175 folder, the client application WILL choose a default. 177 4.3.4. If a view or form name is supplied 179 Where available, a view or form alias should be used instead of the 180 name shown in the user interface. [HCLDominoNamingAView] 182 4.3.5. If a viewUNID or folderUNID of 0 is supplied 184 In this case, the document is still opened. 186 4.3.6. If OpenForm is specified 188 A 'notes' URI of type formDocNew will create a new document in the 189 user interface using the specified form. 191 4.4. Encoding Rules 193 The server, appFileAndPath and name must be encoded using the UTF-8 194 encoding scheme, and any octet that is not one of the permitted 195 characters per the above grammar MUST instead be represented by a "%" 196 followed by two characters from the character set above. The 197 two characters give the hexadecimal representation of that octet. 199 The maximum length of a view or form name is 64 bytes after decoding. 201 4.4.1. Case sensitivity of URI components 203 The values of server, appFileAndPath and name are case insensitive. 204 For clarity, the actual case of the underlying resource SHOULD be 205 used but is not REQUIRED. 207 5. Examples 209 5.1. Application Examples 210 notes:///1234567890ABCDEF 211 This example would locate and view an application 212 appReplicaID=1234567890ABCDEF 214 notes://server1.example.com/1234567890ABCDEF 215 This example would view an application 216 appReplicaID=1234567890ABCDEF 217 on server server1.example.com 219 notes://server1.example.com/1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF 220 This example would open a view with 221 viewUNID=1234567890ABCDEF1234567890ABCDEF 222 in appReplicaID=1234567890ABCDEF 223 on server server1.example.com and navigate to 225 notes://server1.example.com/By%20Author?OpenView 226 This example would open a view with 227 name "By Author" 228 in appReplicaID=1234567890ABCDEF 229 on server server1.example.com and 231 notes://server1.example.com/1234567890ABCDEF/MainFrameset?OpenFrameset&view=1234567890ABCDEF1234567890ABCDEF 232 This example would open a frameset with 233 name "MainFrameset" and 234 viewUNID=1234567890ABCDEF1234567890ABCDEF 235 in appReplicaID=1234567890ABCDEF 236 on server server1.example.com and 238 5.2. Document Examples 239 notes://server1.example.com/1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA 240 This example would view a document with 241 docUNID=1234567890ABCDEF1234567890FEDCBA 242 from viewUNID=1234567890ABCDEF1234567890ABCDEF 243 in appReplicaID=1234567890ABCDEF 244 on server server1.example.com 246 notes:///1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA 247 This example would view a document with 248 docUNID=1234567890ABCDEF1234567890FEDCBA 249 from viewUNID=1234567890ABCDEF1234567890ABCDEF 250 after locating appReplicaID=1234567890ABCDEF 252 notes://server1.example.com/teamroom%2Fourteamroom.nsf/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA 253 This example would view a document with 254 docUNID=1234567890ABCDEF1234567890FEDCBA 255 from viewUNID=1234567890ABCDEF1234567890ABCDEF 256 in appPathAndFile=teamroom/ourteamroom.nsf 257 on server server1.example.com 259 notes://server1.example.com/1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA?EditDocument 260 This example would edit a document with 261 docUNID=1234567890ABCDEF1234567890FEDCBA 262 from viewUNID=1234567890ABCDEF1234567890ABCDEF 263 in appReplicaID=1234567890ABCDEF 264 on server server1.example.com 266 notes://server1.example.com/1234567890ABCDEF/MainTopic?OpenForm 267 This example would create a new document with 268 form name "MainTopic" 269 in appReplicaID=1234567890ABCDEF 270 on server server1.example.com 272 5.3. Application User Interface Examples 274 notes:///ClientBookmark?OpenWorkspace 275 This example would launch/focus the client application and navigate to the user interface element "Workspace" 277 notes:///ClientBookmark?OpenReplication 278 This example would launch/focus the client application and navigate to the user interface element "Replicator Page" 280 notes:///ClientBookmark?OpenDatabases 281 This example would launch/focus the client application and navigate to the user interface element "Open Application" 283 6. Security Considerations 285 All operations initiated as a result of locating and viewing a 286 'notes' URI are done so under the access rights of the user logged 287 into the client application. All access restrictions including 288 application access control list [HCLDominoACL], readers fields 289 [HCLDominoReadersField] and execution control lists [HCLDominoECL] 290 are in effect when locating the application and/or document referred 291 to by a 'notes' URI. 293 7. IANA Considerations 295 The IANA is asked to register the URL registration template found in 296 Section 8 in accordance with [RFC7595] 298 8. Appendix A: Registration Template 300 Resource Identifier (RI) Scheme name: notes 302 Status: provisional 304 Scheme syntax: Section 4 306 Encoding considerations: Section 4.4 308 Intended usage: Section 1 310 Applications and/or protocols which use this scheme: Section 3 312 Interoperability considerations: None not specified 314 Security considerations: Section 6 316 9. References 318 9.1. Normative References 320 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 321 Requirement Levels", BCP 14, RFC 2119, 322 DOI 10.17487/RFC2119, March 1997, 323 . 325 [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 326 Resource Identifiers (URI): Generic Syntax", RFC 2396, 327 DOI 10.17487/RFC2396, August 1998, 328 . 330 [RFC3978] Bradner, S., Ed., "IETF Rights in Contributions", 331 RFC 3978, DOI 10.17487/RFC3978, March 2005, 332 . 334 [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines 335 and Registration Procedures for URI Schemes", BCP 35, 336 RFC 7595, DOI 10.17487/RFC7595, June 2015, 337 . 339 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 340 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 341 May 2017, . 343 9.2. Informative References 345 [HCLDomino] 346 "HCL Domino", n.d., 347 . 349 [HCLDominoACL] 350 HCL, "The database access control list", December 2021, 351 . 354 [HCLDominoECL] 355 HCL, "The execution control list", December 2021, 356 . 359 [HCLDominoNamingAView] 360 HCL, "Naming a view or folder", December 2021, 361 . 364 [HCLDominoReadersField] 365 HCL, "Using a Readers field to restrict access to specific 366 documents", December 2021, 367 . 371 Author's Address 373 Doug Conmy 374 HCL Software 375 300 Apollo Drive 376 Chelmsford, MA 01824 377 United States of America 378 Email: dconmy@pnp-hcl.com