Uniform Resource Identifier (URI) specification for `dvx:`

About

There are numerous supported commands available that interact with DVX. All of them will open up the application if it is not yet started. They can either be typed into a command box or through your browser's address bar (you can normally create links to them as you would create web page links).

Introduction to scheme

According to the RFC7595 "Guidelines and Registration Procedures for URI Schemes" (June 2015) and in particular RFC7595 Section 7.4 "URI Scheme Registration Template" this specification introduces the 'dvx' scheme.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC2119.

Scheme syntax (RFC7595 Section 3.2.)

dvx:<command>[?<key2>=<value1>[&<key2>=<value2>][...]]

Syntax	Mandatory	Description	Example
`dvx:`	Yes	URI scheme name followed by colon
`command`	Yes	The `command` defines the action which is going to be executed by the uri handler. (see also Available `command`'s and requirements)	`dvx:open`
`(?\|&)keyN=valueN`	No	Additional data can be passed using a `key=value` format, also known as query. For some `command`'s it can be necessary to pass specific data. For more information see the description of possible command values. The start of this query is indicated by the first question mark (`?`) character and terminated by the end of the URI. It consists on one more more `key=value` pairs which are separated by ampersand (`&`).	`dvx:open?app=DVXB3010&addressId=100&tenant=002`

Scheme semantics (RFC7595 Section 3.3., RFC7595 Section 3.4.)

The command determines the operation and context. The scheme MUST NOT define a resource locator, but depending on the command the mandatory key=value pairs MAY uniquely identify a resource (f.e. a contact, a specific workflow or a document). A locally installed scheme handler allows the transition between different subparts of the software solution as well as a browser to desktop application transition.

Encoding considerations (RFC7595 Section 3.3., RFC7595 Section 3.6.)

Encoding for `command`

Allowed characters for command's are [a-z0-9.+-] (lowercase alphabet a-z, numbers 0-9, special chars .,+,-). Apart from that, the command has some more obligations and recommendations:

MUST start with a letter (a-z)
MUST end with a letter (a-z) or a number (0-9)
MUST have a minimum length of 3 characters and a maximum length of 200 characters
SHOULD HAVE at least 3 alphanumeric characters between two special characters (.,+,-)

Encoding for `key=value` pairs

All key=value pairs MUST use the UTF-8 (RFC3629) character set. key and value MUST be separated by an equal sign (=).

Naming of key has following obligations:

MUST start with a letter (a-z)
MUST have a minimum length of 1 character and a maximum length of 200 characters
MUST consist of alphanumeric characters (a-zA-Z0-9) (lowercase alphabet a-z, uppercase alphabet A-Z, numbers 0-9)
SHOULD be written in camelCase annotation

Data within value has following obligations:

value MUST consist of unreserved and pct-encoded characters defined in RFC3986 (see the RFC3986 Appendix A. for the collected ABNF)
The unreserved characters MAY be pct-encoded, but SHOULD NOT be encoded
The reserved characters MUST be encoded using pct-encoding
value MAY be empty, but it's not recommended

Interoperability considerations (RFC7595 Section 3.9.)

Currently the only one known context of use is within the software application stack and it's ecosystem provided by ORGAPLAN business solutions. Uses outside of context should be handled with care.

Security considerations (RFC7595 Section 3.7.)

A full security analysis and considerations are not yet available since the application which this scheme is part of is still under development. At the current state the scheme inherits the general security considerations of RFC 3986 Section 7.. We highly recommend:

Sensitive data SHOULD NOT be used in key=value pairs in forms accessible to observers
Implementations of this scheme SHOULD NOT trust a dvx-URI from an untrusted source

Security considerations will be updated as soon as the threat model becomes clearer.

Available `command`'s and requirements

The following subchapters describe available command's and related key=value pairs.

Command `dvx:open`

Open (or start if not yet started) a local instance of the defined application. Depending on the application key=value pairs are passed as startup arguments.

Key	Mandatory	Description	Default	Example
app	No	Internal name/identifier of the application within the DVX application stack. When no value is given it will start the DVX Explorer		`?app=DVXB3010`

`dvx:open?app=DVXB6601`

Key	Type	Mandatory	Description	Example
app	`String`	Yes	Must be set to `DVXB6601`	`?app=DVXB6601`
pid	`Integer`	Yes	Unique identifier for the personnel account which is requested to open (PersonnelId)	`?app=DVXB6601&pid=100`
datef	`String` (`Date(yyyy-mm-dd)`	No	Pass a date to open a specific day and show all time records for this date	`?app=DVXB6601&pid=100&datef=2021-02-15`

`dvx:open?app=DVXB0313`

Key	Type	Mandatory	Description	Default	Example
app	`String`	Yes	Must be set to `DVXB0313`		`?app=DVXB0313`
jid	`String`	Yes	Unique identifier for a specific journal entry which should be opened		`?app=DVXB0313&jid=14014-22`

Uniform Resource Identifier (URI) specification for dvx: