Internet DRAFT - draft-dconmy-notes-uri-scheme
draft-dconmy-notes-uri-scheme
Network Working Group D. Conmy
Internet-Draft HCL Software
Intended status: Informational 18 March 2022
Expires: 19 September 2022
The 'notes' URI Scheme for viewing HCL Notes/Domino resources
draft-dconmy-notes-uri-scheme-02
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 19 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 19 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 19 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 19 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 19 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 <hex> 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 19 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 19 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 19 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
Resource Identifier (RI) Scheme name: notes
Status: provisional
Scheme syntax: Section 4
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,
<https://www.rfc-editor.org/info/rfc2119>.
[RFC2396] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifiers (URI): Generic Syntax", RFC 2396,
DOI 10.17487/RFC2396, August 1998,
<https://www.rfc-editor.org/info/rfc2396>.
Conmy Expires 19 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,
<https://www.rfc-editor.org/info/rfc3978>.
[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,
<https://www.rfc-editor.org/info/rfc7595>.
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>.
9.2. Informative References
[HCLDomino]
"HCL Domino", n.d.,
<https://en.wikipedia.org/wiki/HCL_Domino>.
[HCLDominoACL]
HCL, "The database access control list", December 2021,
<https://help.hcltechsw.com/domino/12.0.0/admin/
conf_thedatabaseaccesscontrollist_c.html>.
[HCLDominoECL]
HCL, "The execution control list", December 2021,
<https://help.hcltechsw.com/domino/12.0.0/admin/
conf_theexecutioncontrollist_t.html?hl=ecl>.
[HCLDominoNamingAView]
HCL, "Naming a view or folder", December 2021,
<https://help.hcltechsw.com/dom_designer/12.0.0/basic/
H_ABOUT_NAMING_A_VIEW.html>.
[HCLDominoReadersField]
HCL, "Using a Readers field to restrict access to specific
documents", December 2021,
<https://help.hcltechsw.com/dom_designer/12.0.0/basic/H_AB
OUT_RESTRICTING_ACCESS_TO_SPECIFIC_DOCUMENTS_USING_A_READE
RS_FIELD.html>.
Author's Address
Doug Conmy
HCL Software
300 Apollo Drive
Chelmsford, MA 01824
United States of America
Conmy Expires 19 September 2022 [Page 9]
Internet-Draft notes URI Scheme March 2022
Email: dconmy@pnp-hcl.com
Conmy Expires 19 September 2022 [Page 10]
