HCL Domino Proton

This package provides an easy to use interface to HCL Domino using the HCL Proton and the Domino AppDev Pack's node.js interface.

• developed for HCL Domino v12 and AppDev Pack v1.0.15.

Pre-requisites

• This packages is based on the Domino AppDev Pack kit, an extension to the HCL Domino Server. The package must be installed separately. See link 'Installation AppDev Pack'.
• the domino-db archive file (domino-domino-db-??.??.tgz) must be installed in the Node-RED environment. See link 'domino-db quick Start'.
  • for Domino on Docker it must become part of the image file.
• The HCL Proton task must be configured on the HCL Domino server.

Nodes

Domino database

This is a configuration node to access a specific HCL Domino database.

create documents

Creates multiple new documents from an array of documents.

read documents

Reads and returns multiple documents, selected either by DQL or by UNIDs.

update documents

Updates fields in multiple documents, selected either by DQL or by UNIDs.

remove items

Removes fields from multiple documents, selected either by DQL or by UNIDs.

delete documents

Deletes entire documents, selected either by DQL or by UNIDs.

read attachments

Reads file attachments from a single document.

write attachments

Attach files to a single document.

run agent

Runs an agent on the Domino server. Agent parameter can be passed using an optional context document.

create log

Creates a single agent log (NotesLog) entry.

explain query

This is a helper node to perform a DQL explain. It is not intended to be used in productive flows.

Security

• Access to the Domino database can occur as anonymous user.
• Secure access it provided using TLS certificates linked to persons or functional IDs. This is easiest done using the Proton --setupclient command. See link 'Set-up person or functional ID for Proton'.

Known Limitations

• IAM is currently not supported.
• field encryption/decryption is currently not supported, because IAM is currently not supported.
• rich text support is currently not build in. However, it can be useful to manipulate rich text fields by an agent.
• attaching files are handled as V2 attachments, i.e. they are not linked to rich text fields. Instead new files are placed at "the end" of a document. This is linked to current restrictions of the Domino AppDev Pack.

Issues and Problems

To report issues or bugs, please send a note to [email protected].

Input Validation

Data and documents passed to the nodes are formally validated using 'Ajv JSON schema validator'. This avoids unneccessary network traffic to the Domino server.

Error Handling

Potential errors should be captured the "Node-RED way" by using catch nodes. The returned object contains detailed error information.

Formats

DQL Query

The Domino Query Language (DQL) follows a kind of SQL syntax. However some severe differences must be taken into account. Please follow the instructions in link 'Domino Query Language'. In short:

• DQL does not allow double quotes for strings.
• only a subset of @functions are supported, e.g. @All, @ModifiedInThisFile, @DocumentUniqueID.
• datetime values must be defined by @dt('')
• lists must be in round brackets, e.g. ('value 1', 'value 2', 'value 3')

Document Object

Represents a single Domino document containing a JSON representation of the fields. Each field may be defined either in

• short format

  • a field-value pair. The value must be text, number or an array of those: "fieldname": "value"

• canonical format with explicit type, value, and further item attribues:

  • type must be either text, number, datetime, or reference,
  • data contains the value,
  • additional attributes like readers, authors, summary, etc.

• date fields are canonical format always.

• for more information see link 'Document Schema'.

The document field structure must be "flat". It must not contain complex JSON structures like nested objects or complex arrays. This is, because there is no representation in Domino to handle such structures. Arrays are supported as long as they consists of primitives which represents multi-value fields in Domino.
Any complex object structures must be flatten before use.
Summarized: a document object in JSON follows the basic structure of a Domino document.

Field names @created and @modified must not be part of any update operation as these fields are maintained by Domino automatically.

Example Document:

{
    Form: 'Contact',                                    -- text
    FirstName: 'Paul',
    LastName: 'McCartney',
    Spouse: 'Linda'
    Children: ['Heather', 'Mary', 'Stella', 'James'],   -- simple array (multi-value)
    Birth: {                                            -- a date field
        type: 'datetime',
        data: '1942-06-18'                              -- must be ISO date yyyy-mm-dd[Thh:nn:ss.sssZ]
    },
    AuthorNames: {                                      -- an authors field
        type: 'text',
        data: '[Editor]',
        authors: true
    }
}

Sending Notes E·Mails

E·mails can easily be sent by an agent. Just create a LotusScript® agent and call it using the run agent node passing the e·mail details in a context document.

Reading attachments from documents

Get the list of document(s) using the read documents node and pass the attachmentSummary parameter. This returns a list of attachment names available. Next use the read attachments node to retrieve the attachment buffer(s) needed.

References

• Domino AppDev Pack - start
• Installation AppDev Pack
• domino-db Quick Start
• Set-up Person or Functional ID for Proton
• Domino Query Language
• Query Arguments
• Document Schema
• DQL Explain

License

Apache-2.0 License.