Network Working Group D. Conmy Internet-Draft HCL Software Intended status: Informational 4 March 2022 Expires: 5 September 2022 The 'notes' URI Scheme for viewing HCL Notes/Domino resources draft-dconmy-notes-uri-scheme-01 Abstract This document describes the 'notes' URI scheme. Specifically, it lays out the syntactic components and how those components are used by URI resolution to locate and view or edit a Notes resource, typically an application and/or document. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 5 September 2022. Copyright Notice Copyright (c) 2022 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Conmy Expires 5 September 2022 [Page 1] Internet-Draft notes URI Scheme March 2022 Table of Contents 1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Applications and/or Protocols which use this URI Scheme Name . . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Syntax Rules . . . . . . . . . . . . . . . . . . . . . . . . 3 4.1. General Syntax . . . . . . . . . . . . . . . . . . . . . 3 4.2. ABNF Grammar . . . . . . . . . . . . . . . . . . . . . . 3 4.3. Special Cases and Default Values . . . . . . . . . . . . 4 4.3.1. If a Server is not specified and an application or document is to be located . . . . . . . . . . . . . . 4 4.3.2. If a Server is specified but not available . . . . . 5 4.3.3. If a view or folder is not supplied . . . . . . . . . 5 4.3.4. If a view or form name is supplied . . . . . . . . . 5 4.3.5. If a viewUNID or folderUNID of 0 is supplied . . . . 5 4.3.6. If OpenForm is specified . . . . . . . . . . . . . . 5 4.4. Encoding Rules . . . . . . . . . . . . . . . . . . . . . 5 4.4.1. Case sensitivity of URI components . . . . . . . . . 5 5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 5 5.1. Application Examples . . . . . . . . . . . . . . . . . . 5 5.2. Document Examples . . . . . . . . . . . . . . . . . . . . 6 5.3. Application User Interface Examples . . . . . . . . . . . 7 6. Security Considerations . . . . . . . . . . . . . . . . . . . 8 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 8. Appendix A: Registration Template . . . . . . . . . . . . . . 8 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 9.1. Normative References . . . . . . . . . . . . . . . . . . 8 9.2. Informative References . . . . . . . . . . . . . . . . . 9 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Goals The primary goal of the 'notes' URI is to view or edit a resource. Typically, a 'notes' URI would be encountered in MIME Email which contains links to other applications and/or documents residing on Domino server(s). A 'notes' URI can also be used with operating system clipboard operations to share a link with a native application or a browser application. When a 'notes' URI is clicked, a local installation of an application that supports the protocol will be launched and the resource will be located and shown. Conmy Expires 5 September 2022 [Page 2] Internet-Draft notes URI Scheme March 2022 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Applications and/or Protocols which use this URI Scheme Name All HCL Notes, HCL Nomad, HCL Client Application Access, IBM Client Application Access, IBM Notes and Lotus Notes clients since 1999 have supported the 'notes' URI scheme. [HCLDomino] 4. Syntax Rules 4.1. General Syntax The 'notes' URI comes in several forms described below. 4.2. ABNF Grammar The full ABNF (certain values are included by reference from [RFC2396]): Conmy Expires 5 September 2022 [Page 3] Internet-Draft notes URI Scheme March 2022 notes-uri = "notes:" (formDoc | formDocNew | formApp1 | formApp2 | formApp3 | formUI) formDoc = "//" [server] "/" application "/" (viewUNID | folderUNID) "/" docUNID ["?" queryDoc] formDocNew = "//" [server] "/" application "/" name "?OpenForm" formApp1 = "//" [server] "/" application formApp2 = "//" [server] "/" application "/" (viewUNID | folderUNID ) formApp3 = "//" [server] "/" application "/" name "?" queryElement ["&" parameter] formUI = "///ClientBookmark?" uiElement server = hostname hostname = // as specified in {{RFC2396}} application = (appReplicaID | appFileAndPath) appReplicaID = 16*HEXDIG appFileAndPath = 1*(unreserved | escaped)(".nsf" | ".ntf") viewUNID = (32*HEXDIG | "0") folderUNID = (32*HEXDIG | "0") docUNID = 32*HEXDIG name = 1*(unreserved | escaped) queryDoc = ("EditDocument" | "OpenDocument") queryElement = ("OpenFrameset" | "OpenView") uiElement = ("OpenDatabases" | "OpenReplication" | "OpenWorkspace") parameter = ("view=" viewUNID) unreserved = alphanum | allowedmark alphanum = // as specified in {{RFC2396}} allowedmark = "-" | "_" | "~" | "(" | ")" escaped = "%" hex hex hex = "0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "A" | "B" | "C" | "D" | "E" | "F" 4.3. Special Cases and Default Values 4.3.1. If a Server is not specified and an application or document is to be located In the case where the 'notes' URI does not contain a named server and the appReplicaID is specified, the client application SHOULD locate the specified application. In the case where the 'notes' URI does not contain a named server and an appFileAndPath is specified, the client applicaiton SHOULD locate a local copy of the application. Conmy Expires 5 September 2022 [Page 4] Internet-Draft notes URI Scheme March 2022 4.3.2. If a Server is specified but not available In the case where the 'notes' URI does contain a named server and the named server is currently unreachable, the client application MAY locate the resource on an alternate server as if the server were not specified. See Section 4.3.1 4.3.3. If a view or folder is not supplied In the case where the 'notes' URI does not contain a viewUNID, folderUNID or name, and the application initially shows a view or folder, the client application WILL choose a default. 4.3.4. If a view or form name is supplied Where available, a view or form alias should be used instead of the name shown in the user interface. [HCLDominoNamingAView] 4.3.5. If a viewUNID or folderUNID of 0 is supplied In this case, the document is still opened. 4.3.6. If OpenForm is specified A 'notes' URI of type formDocNew will create a new document in the user interface using the specified form. 4.4. Encoding Rules The server, appFileAndPath and name must be encoded using the UTF-8 encoding scheme, and any octet that is not one of the permitted characters per the above grammar MUST instead be represented by a "%" followed by two characters from the character set above. The two characters give the hexadecimal representation of that octet. The maximum length of a view or form name is 64 bytes after decoding. 4.4.1. Case sensitivity of URI components The values of server, appFileAndPath and name are case insensitive. For clarity, the actual case of the underlying resource SHOULD be used but is not REQUIRED. 5. Examples 5.1. Application Examples Conmy Expires 5 September 2022 [Page 5] Internet-Draft notes URI Scheme March 2022 notes:///1234567890ABCDEF This example would locate and view an application appReplicaID=1234567890ABCDEF notes://server1.example.com/1234567890ABCDEF This example would view an application appReplicaID=1234567890ABCDEF on server server1.example.com notes://server1.example.com/1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF This example would open a view with viewUNID=1234567890ABCDEF1234567890ABCDEF in appReplicaID=1234567890ABCDEF on server server1.example.com and navigate to notes://server1.example.com/By%20Author?OpenView This example would open a view with name "By Author" in appReplicaID=1234567890ABCDEF on server server1.example.com and notes://server1.example.com/1234567890ABCDEF/MainFrameset?OpenFrameset&view=1234567890ABCDEF1234567890ABCDEF This example would open a frameset with name "MainFrameset" and viewUNID=1234567890ABCDEF1234567890ABCDEF in appReplicaID=1234567890ABCDEF on server server1.example.com and 5.2. Document Examples Conmy Expires 5 September 2022 [Page 6] Internet-Draft notes URI Scheme March 2022 notes://server1.example.com/1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA This example would view a document with docUNID=1234567890ABCDEF1234567890FEDCBA from viewUNID=1234567890ABCDEF1234567890ABCDEF in appReplicaID=1234567890ABCDEF on server server1.example.com notes:///1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA This example would view a document with docUNID=1234567890ABCDEF1234567890FEDCBA from viewUNID=1234567890ABCDEF1234567890ABCDEF after locating appReplicaID=1234567890ABCDEF notes://server1.example.com/teamroom%2Fourteamroom.nsf/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA This example would view a document with docUNID=1234567890ABCDEF1234567890FEDCBA from viewUNID=1234567890ABCDEF1234567890ABCDEF in appPathAndFile=teamroom/ourteamroom.nsf on server server1.example.com notes://server1.example.com/1234567890ABCDEF/1234567890ABCDEF1234567890ABCDEF/1234567890ABCDEF1234567890FEDCBA?EditDocument This example would edit a document with docUNID=1234567890ABCDEF1234567890FEDCBA from viewUNID=1234567890ABCDEF1234567890ABCDEF in appReplicaID=1234567890ABCDEF on server server1.example.com notes://server1.example.com/1234567890ABCDEF/MainTopic?OpenForm This example would create a new document with form name "MainTopic" in appReplicaID=1234567890ABCDEF on server server1.example.com 5.3. Application User Interface Examples notes:///ClientBookmark?OpenWorkspace This example would launch/focus the client application and navigate to the user interface element "Workspace" notes:///ClientBookmark?OpenReplication This example would launch/focus the client application and navigate to the user interface element "Replicator Page" notes:///ClientBookmark?OpenDatabases This example would launch/focus the client application and navigate to the user interface element "Open Application" Conmy Expires 5 September 2022 [Page 7] Internet-Draft notes URI Scheme March 2022 6. Security Considerations All operations initiated as a result of locating and viewing a 'notes' URI are done so under the access rights of the user logged into the client application. All access restrictions including application access control list [HCLDominoACL], readers fields [HCLDominoReadersField] and execution control lists [HCLDominoECL] are in effect when locating the application and/or document referred to by a 'notes' URI. 7. IANA Considerations The IANA is asked to register the URL registration template found in Section 8 in accordance with [RFC7595] 8. Appendix A: Registration Template URL scheme name: notes Status: provisional URL scheme syntax: Section 4 Character encoding considerations: Section 4.4 Intended usage: Section 1 Applications and/or protocols which use this scheme: Section 3 Interoperability considerations: None not specified Security considerations: Section 6 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifiers (URI): Generic Syntax", RFC 2396, DOI 10.17487/RFC2396, August 1998, . Conmy Expires 5 September 2022 [Page 8] Internet-Draft notes URI Scheme March 2022 [RFC3978] Bradner, S., Ed., "IETF Rights in Contributions", RFC 3978, DOI 10.17487/RFC3978, March 2005, . [RFC7595] Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, DOI 10.17487/RFC7595, June 2015, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . 9.2. Informative References [HCLDomino] "HCL Domino", n.d., . [HCLDominoACL] HCL, "The database access control list", December 2021, . [HCLDominoECL] HCL, "The execution control list", December 2021, . [HCLDominoNamingAView] HCL, "Naming a view or folder", December 2021, . [HCLDominoReadersField] HCL, "Using a Readers field to restrict access to specific documents", December 2021, . Author's Address Doug Conmy HCL Software 300 Apollo Drive Chelmsford, MA 01824 United States of America Conmy Expires 5 September 2022 [Page 9] Internet-Draft notes URI Scheme March 2022 Email: dconmy@pnp-hcl.com Conmy Expires 5 September 2022 [Page 10]