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 | Default | 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|OneOf | Unique identifier for a specific journal entry which should be opened | ?app=DVXB0313&jid=14014-22 |
|
aid | Integer |
Yes|OneOf | Unique identifier to open a specific contact using it's address id | ?app=DVXB0313&aid=29182 |
|
cid | Integer |
Yes|OneOf | Unique identifier to open a specific contact using it's id. Note: If available, the usage of aid is preferred over cid |
?app=DVXB0313&cid=14014 |
dvx:open?app=DVXB7730
Key | Type | Mandatory | Description | Default | Example |
---|---|---|---|---|---|
app | String |
Yes | Must be set to DVXB7730 |
?app=DVXB7730 |
|
did | String |
Yes | Unique identifier to open a specific document using it's id (which consists of the document type and the document id) | ?app=DVXB7730&did=30-591837 |