Configure witboost to use Email notifications

The email notification feature requires an additional section called emailConfig under notifications, related to the email configuration. You can customize the sender name by using the dedicated field. In addition, inside the html section you can customize and the app name, the logo, the footer and the theme used inside the html email. This part of the configuration is mandatory. The default values that you can use for the email template are the following ones:

notifications:
  # email configuration
  emailConfig:
    # whether the email sending is enabled or not
    enabled: true/false
    # the path where the email address can be found in the user entity. Defaults to 'spec.profile.email'.
    userEntityEmailField: 'spec.profile.email'
    # name of the email sender that will be shown to the recipients
    senderName: Witboost
    # configuration related to the html email template
    html:
      # the app name that will be displayed inside the email
      appName: Witboost
      # path of the logo that will be displayed at the top of the email
      # the file must be under the wb-notification-backend plugin folder
      # the default witboost logo is available using the path shown below
      logoPath: 'src/resources/logo.svg'
      # Optional field about the footer information that will be displayed at the bottom of the email, inside the footer
      # you can use html tags inside the string, as shown below for the default value
      footer: '<strong>witboost</strong> is a product by <strong>Agile Lab s.r.l.</strong> <a href="https://www.agilelab.it" style="color: inherit;">www.agilelab.it</a>'
      # theme configuration
      color:
        # primary color that will be used as background color for the footer
        primary: '#00acc1'
        # secondary color that will be used for the notification title and for the link
        secondary: '#00acc1'
        # text color for the body of the notification
        text: '#4e6980'
        # color for the text inside the footer
        footerText: '#ffffff'

You can enable the email notification for each supported event by setting the related sendMail flag to true, as explained above. In this case, you will need to specify an additional configuration section called auth under emailConfig, related to the email account and authentication method to use in order to send the emails. In particular, you will need to specify the information related to the Smtp server of the provider of the email account, and then an authentication method. The supported authentication types are login (based on username and password) and Oauth2.

Example of the configuration using the login authentication:

notifications:
  emailConfig:
    # configuration related to email account information and authentication
    auth:
      # hostname of the smtp server related to the provider used
      host: smtp-mail.provider.com
      # port of the smtp server related to the provider used
      port: 587
      # authentication type: the value can be 'login' or 'oauth2'
      type: login
      # email account to use
      user: witboost@agilelab.it
      # password for the specified email account
      password: passwordValue

Oauth2 authentication

Regarding the Oauth2 authentication, you can find further information about the supported parameters in the related section of the documentation of the used email library: Nodemailer documentation - Oauth2. We are supporting both 2LO and 3-legged authentication.

Example of the configuration using the 2LO Oauth2 authentication (service accounts):

notifications:
  emailConfig:
    # configuration related to email account information and authentication
    auth:
      # hostname of the smtp server related to the provider used
      host: smtp.gmail.com
      # port of the smtp server related to the provider used
      port: 465
      # authentication type: the value can be 'login' or 'oauth2'
      type: oauth2
      # email account to use
      user: witboost@agilelab.it
      # Oauth service client
      serviceClient: serviceClientValue
      # private key used to perform the authentication
      privateKey: privateKeyValue

Example of the configuration using the 3-legged Oauth2 authentication:

notifications:
  emailConfig:
    # configuration related to email account information and authentication
    auth:
      # hostname of the smtp server related to the provider used
      host: smtp.gmail.com
      # port of the smtp server related to the provider used
      port: 465
      # authentication type: the value can be 'login' or 'oauth2'
      type: oauth2
      # email account to use
      user: witboost@agilelab.it
      # Oauth client id
      clientId: clientIdValue
      # Oauth client secret
      clientSecret: clientSecretValue
      # token used to perform the authentication
      accessToken: accessTokenValue
      # token used to refresh the access token
      refreshToken: refreshTokenValue

In order to use the Oauth2 authentication you will need to register the Witboost application and perform additional operations depending on your provider. The Oauth2 flow has been tested using the 3-legged authentication and Gmail provider. If you are going to configure Oauth2 with Gmail, you can follow the steps explained in this tutorial.