Notification Service

A microservice for sending notifications part of the Restorecommerce.

Features

Sends notifications through different channels.
Implemented channels are Email and Log (via winston or classic console).
Internally the microservice uses the mailer module for sending email notifications which is a wrapper for nodemailer.

Note: Unimplemented channels as of now are: Slack, Mattermost, SMS.

Configuration

The following Mail Server configuration properties under the server:mailer configuration are available:

host: hostname of mail server.
port: port of mail server to connect to.
auth.user: user name for mail server.
auth.pass: password for mail server.
address: specifies the from address for every message.

Alternatively the credentials for the mail server auth.user and auth.pass can be added as separate resource Credential resource using resources-srv.

API

This microservice exposes the following gRPC endpoints:

`Send`

This is a generic operation which can be invoked to send any type of notifications. Requests are performed providing io.restorecommerce.notification_req.NotificationReq protobuf message as input and responses are a google.protobuf.Empty message.

io.restorecommerce.notification_req.NotificationReq

Field Type Description Label Log

Field	Type	Description	Label	Log
email	`io.restorecommerce.notification_req.Email`	email channel properties	optional	n/a
log	`io.restorecommerce.notification_req.Log`	log channel properties	n/a	optional
subject	string	URL of a hbs template	optional	n/a
body	string	URL of a hbs template	optional	required
transport	string	Directly declares the transportation channel. Possible values: `email` or `log`	optional	optional
provider	bool	Further specifies the chosen transport. Example: use `winston` when transport is set to `log`	optional	optional
attachments	[]`io.restorecommerce.notification_req.Attachment`	An array of attachment objects, see below	optional	n/a

io.restorecommerce.notification_req.Email

email channel properties

optional

n/a

log

io.restorecommerce.notification_req.Log

log channel properties

n/a

optional

subject

string

URL of a hbs template

optional

n/a

body

string

URL of a hbs template

optional

required

transport

string

Directly declares the transportation channel. Possible values: email or log

optional

provider

bool

Further specifies the chosen transport. Example: use winston when transport is set to log

optional

attachments

[]io.restorecommerce.notification_req.Attachment

An array of attachment objects, see below

optional

n/a

io.restorecommerce.notification_req.Email

Field	Type	Description	Label	Log
to	string [ ]	an array of recipients email addresses that will appear on the to: field	optional	n/a
cc	string [ ]	an array of recipients email addresses that will appear on the cc: field	optional	n/a
bcc	string [ ]	an array of recipients email addresses that will appear on the bcc: field	optional	n/a
replyto	string	If set, the outgoing mail will have this replyTo header set	optional	n/a

Field

Type

Description

Label

Log

string [ ]

an array of recipients email addresses that will appear on the to: field

optional

n/a

string [ ]

an array of recipients email addresses that will appear on the cc: field

optional

n/a

bcc

string [ ]

an array of recipients email addresses that will appear on the bcc: field

optional

n/a

replyto

string

If set, the outgoing mail will have this replyTo header set

optional

n/a

io.restorecommerce.notification_req.Log

Field Type Description Label Log

Field	Type	Description	Label	Log
level	string	Logging level ex: `info`	n/a	optional

level

string

Logging level ex: info

n/a

optional

Attachments may be used in case of email notifications. Attachment properties are based on the standard nodemailer API:

io.restorecommerce.notification_req.Attachment

Field Type Description Label Log

Field	Type	Description	Label	Log
filename	string	filename to be reported as the name of the attached file, use of unicode is allowed. If you do not want to use a filename, set this value as false, otherwise a filename is generated automatically	optional	n/a
text	string	String, Buffer or a Stream contents for the attachment	optional	n/a
buffer	bytes	binary data eg.: images	optional	n/a
path	string	path to a file or an URL (data uris are allowed as well) if you want to stream the file instead of including it (better for larger attachments)	optional	n/a
content_type	string	optional content type for the attachment, if not set will be derived from the filename property	optional	n/a
content_disposition	string	optional content disposition type for the attachment, defaults to `attachment`	optional	n/a
cid	string	optional content ID for using inline images in HTML message source	optional	n/a
encoding	string	If set and content is string, then encodes the content to a Buffer using the specified encoding. Example values: base64, hex, binary etc. Useful if you want to use binary attachments in a JSON formatted e-mail object	optional	n/a

filename

string

filename to be reported as the name of the attached file, use of unicode is allowed. If you do not want to use a filename, set this value as false, otherwise a filename is generated automatically

optional

n/a

text

string

String, Buffer or a Stream contents for the attachment

optional

n/a

buffer

bytes

binary data eg.: images

optional

n/a

path

string

path to a file or an URL (data uris are allowed as well) if you want to stream the file instead of including it (better for larger attachments)

optional

n/a

content_type

string

optional content type for the attachment, if not set will be derived from the filename property

optional

n/a

content_disposition

string

optional content disposition type for the attachment, defaults to attachment

optional

n/a

cid

string

optional content ID for using inline images in HTML message source

optional

n/a

encoding

string

If set and content is string, then encodes the content to a Buffer using the specified encoding. Example values: base64, hex, binary etc. Useful if you want to use binary attachments in a JSON formatted e-mail object

optional

n/a

Because of limitations in the protobuf protocol, there is single hatch: content should be specified as one of the attributes text (for strings) or buffer (raw bytes, like images).

Textual attachments are appended in the mail as-is, while binary attachments are converted to base64 and then included (see tests).

Events

Emitted

List of events emitted by this microservice for below topics:

Topic Name Event Name Description

Topic Name	Event Name	Description
`io.restorecommerce.command`	`healthCheckResponse`	system health check response
	`versionResponse`	system version response

io.restorecommerce.command

healthCheckResponse

system health check response

versionResponse

system version response

Consumed

This microservice consumes messages for the following events by topic:

Topic Name Event Name Description

Topic Name	Event Name	Description
`io.restorecommerce.command`	`healthCheckCommand`	to get system health check
	`versionCommand`	to get system version
`io.restorecommerce.notification_req`	`sendEmail`	to send email

io.restorecommerce.command

healthCheckCommand

to get system health check

versionCommand

to get system version

io.restorecommerce.notification_req

sendEmail

to send email

sendEmail events are based on the same protobuf message as the gRPC call for the Send endpoint.