The 'notes' URI Scheme for viewing HCL Notes/Domino resources
draft-dconmy-notes-uri-scheme-01

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 <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 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,
              <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 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,
              <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 5 September 2022                [Page 9]
Internet-Draft              notes URI Scheme                  March 2022

   Email: dconmy@pnp-hcl.com

Conmy                   Expires 5 September 2022               [Page 10]