Internet-Draft \'notes\' URI Scheme February 2022
Conmy Expires 27 August 2022 [Page]
Workgroup:
Network Working Group
Internet-Draft:
draft-dconmy-notes-uri-scheme-00
Published:
Intended Status:
Standards Track
Expires:
Author:
D. Conmy
HCL Software

The 'notes' URI Scheme for viewing HCL Notes/Domino resources

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 27 August 2022.

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.

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]):

    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.

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 

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 

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"

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

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, , <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, , <https://www.rfc-editor.org/info/rfc2396>.
[RFC3978]
Bradner, S., Ed., "IETF Rights in Contributions", RFC 3978, DOI 10.17487/RFC3978, , <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, , <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, , <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", , <https://help.hcltechsw.com/domino/12.0.0/admin/conf_thedatabaseaccesscontrollist_c.html>.
[HCLDominoECL]
HCL, "The execution control list", , <https://help.hcltechsw.com/domino/12.0.0/admin/conf_theexecutioncontrollist_t.html?hl=ecl>.
[HCLDominoNamingAView]
HCL, "Naming a view or folder", , <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", , <https://help.hcltechsw.com/dom_designer/12.0.0/basic/H_ABOUT_RESTRICTING_ACCESS_TO_SPECIFIC_DOCUMENTS_USING_A_READERS_FIELD.html>.

Author's Address

Doug Conmy
HCL Software
300 Apollo Drive
Chelmsford, MA 01824
United States of America