Enable SMTP Notifications

To configure SMTP:

  1. Log in to Apiary platform as an administrator;
  2. In the left menu select Admin > SMTP;
  3. Enable SMTP;

  4. Fill in the following fields:

    • Host - the IP-address or hostname of the SMTP server;
    • Port - the port number of the SMTP server;
    • Username - login of the sender;
    • Password - password of the sender;
        • if you're using HashiCorp Vault to store the user password, follow the instruction how to integrate Vault and Apiary here
    • Connection security - the use of security protocol (NONE, STARTTLS, SSL/TLS);
    • From - the mail address, from which you will receive notifications.

  5. Click Save to apply the settings.

  6. To check if all SMTP settings are correct, click + Test e-mail configuration. Using this option, you can send test e-mail message to your mailbox:

    • To - the e-mail address, to which the test e-mail will be sent;
    • Subject - title of the e-mail;
    • Message - body of the e-mail.

  7. Click Send test e-mail.

Absolute links

To form absolute link in the letter, it is necessary to indicate domain name in the user.ini file:

  1. Open the console of the virtual machine;
  2. Open the file /opt/hw-fh/config/user.ini (root privileges required);

  3. Add the option f.deck.base.url to the [main] section and specify domain name:

    f.deck.base.url = http(s)://Apiary.example.com:port_number

  4. To apply changes, run the command:

    /opt/hw-fh/bin/reconfig

Add custom letter templates

To add custom letter templates to the platform:

  1. Open the console of the virtual machine;

  2. Create a new directory, f.e.:

    mkdir /opt/letter-templates

  3. Upload new letter template to your directory. Important: template name must be email_notifications.json;

  4. Open the file /opt/hw-fh/config/user.ini (root privileges required);

  5. Add the option f.notification.template.dir to the [main] section and indicate path to the letter template:

    f.notification.template.dir = /opt/letter-templates

  6. To apply changes, run the command:

    /opt/hw-fh/bin/reconfig

Letter template format

Letter template format (file email_notifications.json):

```
"email_new_issue":{
  "subject": "[{{product}}] New issue in project {{project.name}}: {{issue.name}}",
  "body": "There is 1 new issue \n{% if project %}\n{{deck_base_url}}/projects/{{project.id}} ({{ project.name }})\n{% endif %}\n{% if issue %}\n{{deck_base_url}}/projects/{{project.id}}/issues?issueId={{issue.id}} ({{ issue.name }}) {{ issue.status }}\n{% endif %} {% if issue %}\n{{ issue.name }}\n{% endif %}\n{% if issue and issue.description %} {{issue.description}}\n{% endif %}"
  },
"email_issue_status_change":{ 
  "subject": "{{product}}] New chat message in {{project.name}}: {{issue.name}}", 
  "body": "There is 1 new chat message \n{% if project %}\n{{deck_base_url}}/projects/{{project.id}} ({{ project.name }})\n{% endif %}\n{% if issue %}\n{{deck_base_url}}/projects/{{project.id}}/issues?issueId={{issue.id}} ({{ issue.name }}) {{ issue.status }}\n{% endif %} {% if issue %}\n{{ issue.name }}\n{% endif %}\n{% if issue and issue.description %} {{issue.description}}\n{% endif %}" 
  }
}
```

Use predefined variables to add to the letter information about project, issues, users, and other information, f.e.:

  • product - platform name;

  • deck_base_url - absolute link to a project or an issue, example:

    • {{deck_base_url}}/projects/{{project.id}} - absolute link to a project ID;
    • {{deck_base_url}}/projects/{{project.id}}/issues?issueId={{issue.id}} - absolute link to an issue ID;

  • user - information about user,f.e.:

    • id - user ID (example: {{user.id}});
    • login - user login (example: {{user.login}});
    • first_name - username (example: {{user.first_name}});
    • last_name - user last name (example: {{user.last_name}});
    • email - user E-mail (example: {{user.email}});
    • is_admin - user role is administrator (example: {{user.is_admin}});
    • is_bot - user is bot (example: {{user.is_bot}});
    • created - user creation date (example: {{user.created}});

  • issue - information about issue,f.e.:

    • id - issue ID (example: {{issue.id}});
    • project_id - project ID where issue is registered (example: {{issue.project_id}});
    • name - issue name (example: {{issue.name}});
    • sla - automatically set SLA value (example: {{issue.sla}});
    • sla_manual_set - manually set SLA value (example: {{issue.sla_manual_set}});
    • created - date of issue creation (example: {{issue.created}});
    • completed - date of issue completion (example: {{issue.completed}});

  • project - information about project,f.e.:

    • id - project ID (example: {{project.id}});
    • name - project name (example: {{project.name}});
    • description - project description (example: {{project.description}});
    • connection_name - connection name of the project (example: {{project.connection_name}});
    • start_date - project start date (example: {{project.start_date}});
    • completion_date - project completion date (example: {{project.completion_date}});
    • scope - project scope (example: {{project.scope}});
    • project_type - project type (example: {{project.project_type}});

See also