fabric8-services/fabric8-notification

Fabric8 Notification service

This service takes care of sending email notification for different Notification Type.

Table of Contents

• 1. Contributes
  • 1.1. Project Structure
    • 1.1.1. Introducing New / Ehnancing Existing - Notification Type
      • Register
      • Resolver
      • Template
  • 1.2. Notification API
  • 1.3. Build Project
    • 1.3.1. Prerequisites
    • 1.3.2. make commands for local development
      • make all - build everything
      • make preview - test email generation against template
      • make test-unit-no-coverage - execute unit tests
      • make clean
    • 1.3.3. Updating WIT/Auth API dependency

1. Contributes

1.1. Project Structure

This project is build around Notification Type in center.

To register new notification type and to see list of exisitng notification type check in main.go

1.1.1. Introducing New / Ehnancing Existing - Notification Type

For each kind of Notification, there is one Notification Type is defined. This section will give details on what are the components of Notification Type which helps to introduce new Notification Type or Enhance existing one.

Register

New Notification Type can be registered as below,

resolvers.Register("analytics.notify.cve", collector.ConfiguredVars(config, collector.NewCVEResolver(authClient, witClient)), nil)

• First arg, Notification Type name (string), here it is "analytics.notify.cve". You need to come up with unique Notification Type name depending on what kind of New Notificatoin you want to support. Later value of this will be used to get registered Resolver and Validator in NotifyController.Send()

• Second arg, ReceiverResolver, it is used to find out list of users to which email should be sent when Notificatin arrives for given Notification Type, more on this later.

• Third arg, ParamValidator, it is used to validate parameter received in Notification payload.

Resolver

ReceiverResolver is responsible to return list of email to which notification sent for given Notification Type. Resolver will get ID attribute as input.

The value of ID attibute should be decided such that the related emails can be fetched. For ex, to find notification email list for workitem.create workitem.go type, one would like to get Workitem.ID for newly created workitem.

You can also decide to set ID with value of codebase_url for analytics.notify.cve cve.go type as with url one can find users who have registred for CVE notification on given Codebase URL.

Resolver will generally get initialized with 'WIT Client' and 'Auth Client' which will be used to query data based on ID to get notification email list.

Template

This is about email template which include email body, subject, headers etc. All email templates are maintained in template folder. For each Notification Type there is one folder with its name.

• body.html - mandatory file which should have email body. It uses golang template link.

• subject.txt - mandatory file which should have subject like for email. It uses golang template link.

1.2. Notification API

Here is sequence diagram of "/api/notify" API. Client will call this API to send Notification Emails.

1.3. Build Project

This project use the dep dependency management system.

1.3.1. Prerequisites

One should have go (version 1.10 or later), git and make installed on the system.

1.3.2. make commands for local development

make all - build everything

Run make all to build the whole project. After this one can find executable created at ./bin/fabric8-notification and run the same to run the Notification service locally.

While running locally, you need to set mandrill.apikey configuration param. This param used in sending notification email. While doing local devl and testing, you can skip send_email part and thus comment in main.go which validate this param.

make preview - test email generation against template

Run make preview to run preview/main.go. This will execute all template generation defined in main.go file. This is useful when you want to check the output of your template. The output email will be stored at ./tmp/ folder with file name having Notification Type name as prefix.

make test-unit-no-coverage - execute unit tests

Run make test-unit-no-coverage to run unit tests without coverage.

make clean

Run make clean clean all artificates generated during build. This is not removing ./tmp/ folder.

1.3.3. Updating WIT/Auth API dependency

This project uses WIT/Auth Client API. Time to time WIT/Auth project dependency should be changed in glide files to get latest WIT/Auth API.

fabric8-notification's Issues

Parameterize Web URLs in templates

Create brief for notification service enhancements

Prepare summary document describing the enhancements we would like to introduce to the notification service.

Add pagination to Comments call

Currently, only scans the first 100 comments on a workitem

"Updated by" is unknown in current API

Notifications are currently working around that by sharing the Token of the person triggering the action.

Use 'what has changed' API for comments/workitem

Currently, no API to determine what has changed

Design WorkItem Created notification email

Scale Profile images correctly

When user has an imageURL from gravatar we can easily append "?s=22" to the URL and we're good, but some have imageURL from github which contain another URL parameter "?v=n" appending "?s=22" to that has no effect.

The image size function need to take the additional parameter into account

Design WorkItem Updated notification email

Inconsistent use of Number-Name

Some locations use Number-Name while other use Name-Number.

return an error if the payload is invalid

in

fabric8-notification/email/notifier.go

Lines 71 to 108 in 304db5b

	func (a *AsyncWorkerNotifier) do(cn contextualNotification) {
	ctx, notification := cn.context, cn.notification
	receivers, vars, err := notification.Resolver(ctx, notification.ID)
	if err != nil {
	log.Error(ctx, map[string]interface{}{
	"type": notification.Type,
	"id": notification.ID,
	"err": err,
	}, "failed to resolve receivers")
	return
	}
	if receivers == nil || len(receivers) == 0 {
	log.Info(ctx, map[string]interface{}{
	"type": notification.Type,
	"id": notification.ID,
	}, "skipping send email as no receivers resolved")
	return
	}
	if vars == nil {
	vars = map[string]interface{}{}
	}
	vars["custom"] = notification.CustomAttributes
	subject, body, headers, err := notification.Template.Render(vars)
	if err != nil {
	log.Error(ctx, map[string]interface{}{
	"type": notification.Type,
	"id": notification.ID,
	"err": err,
	}, "failed to render template")
	return
	}
	a.Sender.Send(ctx, subject, body, headers, receivers)

, if there is no receiver, no email is sent, but there's also no error returned to the caller, which can result in opening issues such as openshiftio/openshift.io#4605

Fail to parse template on missing system.description

{
	"err": "template: workitem.create:75:49: executing \"workitem.create\" at <\"system.description....>: invalid value; expected string",
	"file": "/tmp/go/src/github.com/fabric8-services/fabric8-notification/email/notifier.go",
	"func": "github.com/fabric8-services/fabric8-notification/email.(*AsyncWorkerNotifier).do",
	"id": "workitem.create",
	"identity_id": "46e9afce-5e0d-44fd-aa2b-2040357a4efb",
	"level": "error",
	"line": 89,
	"msg": "failed to render template",
	"pid": 1,
	"pkg": "github.com/fabric8-services/fabric8-notification/email",
	"req_headers": {
		"Accept-Encoding": [
			"gzip"
		],
		"Authorization": "*****",
		"Content-Length": [
			"162"
		],
		"Content-Type": [
			"application/json"
		],
		"User-Agent": [
			"Go-http-client/1.1"
		]
	},
	"req_id": "MwdOyF7UZn-73647",
	"req_payload": "{\"data\":{\"attributes\":{\"id\":\"d3e78d1f-bf18-4a21-9fca-968675d7a91f\",\"type\":\"workitem.create\"},\"id\":\"af2ccbfc-cb07-4376-a150-36afce7143fd\",\"type\":\"notifications\"}}",
	"time": "2017-08-01 08:53:06",
	"type": "d3e78d1f-bf18-4a21-9fca-968675d7a91f"
}

Unknown value work-item.name

The workitem templates refer to a [work-item.name] value. Not sure which value this is intended to be. Using woritem-type.name for now (e.g. bug, scenario etc)

Design WorkItem Comment Created notification email

support cico test coverage job

Issue:
For PR #99, we have observed that the ci.centos.org PR build (coverage) check is failing with following error.

/bin/bash: cico_run_coverage.sh: No such file or directory

Link: https://ci.centos.org/job/devtools-fabric8-notification-coverage/1/console

Fix:
Check whether we can run_tests_with_coverage and get meaningful metrics out of it. If yes, plz add support for run_tests_with_coverage. If we find that the run_tests_with_coverage take similar (almost same) build time as compared to run_tests_without_coverage then we can only have run_tests_with_coverage.

Use service account token issued by Auth to get user's email from Auth service

As an offshoot of fabric8-services/fabric8-auth#237 (comment)

1. When notification service comes up, call Auth service API to request for service account token, and keep it in memory.

2. Subsequently use the token from configuration memory object.

3. On the auth side, check for service account token, and based on that show the email .

Add direct link to comment on comment.create|update

"Open this" links to the WorkItem details. It would be handy if this linked directly to the comment.

Require some additional UI / Backend changes:

• Support anchor in HTML to scroll to the comment
• Backend might need some support to 'fetch all up until this point' or similar. As the requested comment might not be part of the '5 last' comments.

Comment messages are sent as Pointer refs

Don't notify the user that has done the action

Add pagination support for Collaborators call

Align log field "fields.time" to ms

Design WorkItem Comment Updated notification email

CI is broken due to failing tests

See #61

Add graceful shutdown

Avoid the process being killed during rolling update before emails for currently received requests are scheduled.

add title and readme outlining how other components should use notification service

see $subject :)

Create initial Notification service

Support receiving events from WIT

• Create Workitem
• Update WorkItem
• Create Comment
• Update Comment

Should email Collaborators, WorkItem Assignees, WorkItem Creator and Commenters