email ext

Question 1

SMTP Connector

Answer 1

SMTP Connector

Before you can send any email you will need to setup at least one SMTP connector. The SMTP connector is a record with the following tags:

• smtpConn: marker tag for SMTP email connector record
• dis: all connectors should have display name
• host: Str host name of server
• port: optional Number or if omitted, defaults to 25
• from: Str email address to use as “from” when sending emails
• username: Str username for SMTP account
• password: must have password stored in password db for connector’s record id
• ssl: marker tag is connection should use SSL

To test a connector use the “Test” command in the Email App to send yourself an email. This command will trace the SMTP protocol exchange for debugging.

Question 2

Authentication

Answer 2

Authentication

The following are typical scenarios for authentication:

• If the server requires authentication, make sure you have a username tag configured and the password is stored in the password db
• If your server does not require authentication, you can leave the username and/or password blank or omit them entirely
• If the ssl marker tag is applied to the smtp connector rec, then the connection is opened using SSL/TLS. Otherwise the connection is opened using plaintext
• If the connection is opened in plaintext, an upgrade to TLS will be performed if the server specifies STARTTLS without any plaintext authentication options
• The following authentication options are supported: CRAM-MD5, LOGIN, PLAIN
• For trouble shooting, use the Test command which dumps the text based requests and responses; if you need help, make sure you capture the full test trace for support

Question 3

Sending Emails

Answer 3

Sending Emails

The emailSend function can be used to send emails via an SMTP connector. The first parameter to the emailSend function is the connector. In most cases you will have only one SMTP connector defined in which case you can pass null to use it as the default.

The recipients parameter supports multiple formats:

// simple "to" email address emailSend(null, "a@acme.com", "subject", "body") // list of "to" email addresses emailSend(null, ["a@acme.com", "b@acme.com"] "subject", "body") // to, cc, and bcc recipients emailSend(null, {to:"a@acme.com", cc:["b@acme.com", "c@acme.com"]}, "subject", "body")

The fifth parameter is an optional set of attachments. See emailSend for more details on the types that can be used in the attachment list.

// send single attachment emailSend(null, "a@acme.com", "subject", "body", `io/report.pdf`) // send a list of attachments. reportId: @1c3d59ff-c9f0e21d reportDict: read(report and dis=="My Report") compound: [fandoc("This is a compound report."), read(energy).hisRead(yesterday)] emailSend(null, "a@acme.com", "subject", "body", [`io/data.xml`, reportId, reportDict, compo

Question 4

Topic Subscriptions

Answer 4

Topic Subscriptions

Users can be configured to receive emails on various topics configured in the system by thetopic tag. Specific types of topics include:

• Note Topics
• Spark Topics

All topics support both immediate mode or daily digest mode by adding these tags to userrecords:

• topicsEmailImmediate: topics for immediate email notification
• topicsEmailDigest: topics for daily digest email notification

Both tags are encoded as a string of comma separated topic Refs. In order to use email notification, you must enable the email extension and configure exactly one SMTP connector. Every user subscribed for topics must have a valid email tag configured.

A topic represents a group of items such as notes or sparks which are matched using a filter via the topicOn tag. Topic filters may be any valid filter. The filter is applied to the item itself (note, spark, etc).

In addition, subscriptions are implicitly filtered by the item’s targetRef if the user has access filters configured. For example:

// user only has access to hvac equip username: "bob", equipAccessFilter: hvac // two pieces of equip id: @ahu, equip, hvac id: @meter, equip, energy

In the example above we have user named “bob” with an access filter which only lets him see equipment marked with the hvac tag. We also have two pieces of equip: an AHU marked with hvac tag and a meter which is missing the hvac tag. In normal operation Bob will see the AHU, but not the meter. Likewise email subscription to notes or sparks with a targetRef to AHU will be sent to Bob, but no notes or sparks for the meter.

Question 5

emailSend

Answer 5

• emailSend
• emailSend(conn, recipients, subject, content, attachments: null)

Send an email:

< >conn: SmtpConn id or record, or if null we use use first SmtpConn foundrecipients: one of the following:Str email address for “to”List of Str email addresses for “to”Dict with “to”, “cc”, or “bcc” of Str or Str[]subject: Str subject textcontext: Str text for body. If the content begins with “”, then it is send as “text/html”, otherwise as “text/plain”attachments: any one, or list of the following types will be included as file attachments:file io handleRef to an App report will be attached as a PDF fileDict of an App report record will be attached as a PDF fileGrid[] (list of Grids) will be treated as a compound report and attached as a PDF fileemailExt for additional example code.

<dl>
</dl>