Notifications (Stack9-core v3.0)

Overview

In Stack9 Core v2.1, it was introduced the ability to set up notifications with attachments for operations (create, takeOwnership) and/or workflow actions. Each notification can be configured with user fields and/or user groups to be notified when the specific operation/action is executed.

In order to start using notifications, a hook type message must be added to the entity definition using a native Stack9 queue called _sendNotificationHandle. See more native handlers

{
  "hooks": [
    {
      "type": "message",
      "hookType": "AfterChange",
      "functionName": "_sendNotificationHandler"
    }
  ]
}

Definition

operation: Required (create or takeOwnership)
action: Required only if operation is proceedToStep. It accepts (proceedToStep || approveWorkflow || rejectWorkflow)
emailTemplateId: Optional Sendgrid template Id. If not specified, default value will be the value configured for the environment variable WORKFLOW_NOTIFICATION_SEND_GRID_DEFAULT_TEMPLATE_ID
recipient: Required object with the user fields and/or user group codes to be notified.
attachments: Optional object with printable document codes and/or custom document functions to generate documents to be sent as attachments.

"notifications": [
  {
    "operation": "create",
    "emailTemplateId": "d-1234567389fe4a84be8e41cd8ead333c",
    "recipient": {
      "userGroups": [],
      "userFields": ["user_id"]
    },
    "attachments": {
      "printableDocuments": ["user_report"],
      "documentFunctions": ["generate-excel-file"]
    }
  },
  {
    "operation": "proceedToStep",
    "action": "newtoreview",
    "emailTemplateId": "d-1234567389fe4a84be8e41cd8ead333c",
    "recipient": {
      "userGroups": [],
      "userFields": ["reviewer_id"]
    },
    "attachments": {
      "printableDocuments": ["user_report", "order_list"],
      "documentFunctions": []
    },
  },
  {
    "operation": "takeOwnership",
    "emailTemplateId": "d-1234567389fe4a84be8e41cd8ead333c",
    "recipient": {
      "userGroups": [],
      "userFields": ["user_id"]
    },
    "attachments": {
      "printableDocuments": [],
      "documentFunctions": []
    }
  },
  {
    "operation": "proceedToStep",
    "action": "approve",
    "emailTemplateId": "d-1234567389fe4a84be8e41cd8ead333c",
    "recipient": {
      "userGroups": [],
      "userFields": ["user_id"]
    },
    "attachments": {
      "printableDocuments": ["test_1"],
      "documentFunctions": ["native/example-document-function"]
    }
  },
  {
    "operation": "proceedToStep",
    "action": "reject",
    "emailTemplateId": "d-1234567389fe4a84be8e41cd8ead333c",
    "recipient": {
      "userGroups": [],
      "userFields": ["user_id"]
    },
    "attachments": {
      "printableDocuments": [
        "test_1",
        "test_2",
        "test_3"
      ],
      "documentFunctions": ["native/example-document-function"]
    }
  }
]

Recipients

Recipients are the users who will receive the notification. Can be specified any field from the form that has relationship with user entity or user group codes.

userFields: Array of user fields, must be a field that has relationship with user entity.
userGroups: Array of user group codes, if specified, all users from the group will be notified.

Attachments

Printable Documents
- In Stack9 core v2.1 it was added a new column code to the printable_document entity. To generate a PDF file from a printable document and send as an attachment in the email notification, one or more codes can be specified in the attachments.printableDocuments property.
```
{
  "attachments": {
    "printableDocuments": ["user_report", "activities"]
  }
}
```

Customise attachments using document functions

Custom functions can be added to the attachments.documentFunctions to generate a custom document with a different extension and sent as attachment in the email notification.

Document functions must be placed in the stack9/document-functions directory and should return an array of documents to be attached to the email notification.

class ExampleDocumentFunction {
  constructor(context) {
    this.services = context.services;
  }

  async exec() {
    const file = await this.services.entity.export('test_notification', {
      $where: {
        id: this.entity.id,
      },
    });

    return {
      documents: [
        {
          filename: `Test`,
          mimetype: `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet`,
          data: file, // buffer[]
        },
      ],
    };
  }
}

module.exports = {
  exec: args => new ExampleDocumentFunction(args).exec(),
  timeout: 5000,
};

User notification storage

Now in Stack9 Core v3.0, it was added a new feature that allows users notifications records to be stored by the notification engine through API endpoint allowing records management.

The new feature structure looks like this on MongoDB:

notification notification1

Note: The content field is an object which has it owns parameters.

Parameters

The notifications can be filter by status, sorted by field and/or order, paginated by limit and/or skip.

  GET /api/notifications?status=seen&sortField=_id&sortOrder=desc&limit=25&skip=5

Returns:

[
  {
    "_id": "61a5a71bbbc2b722ccc5b9e2",
    "user_id": 1,
    "entity_key": "test_notification",
    "entity_id": 2,
    "content": {
      "icon": "http://",
      "title": "Ella Ferreira has created the record123",
      "message": "Testing notification handlebars Ella Ferreira",
      "due_date": "6 minutes ago"
    },
    "timestamp": "2021-11-30T04:22:51.495Z",
    "seen": true
  }
]

Note: Default value for status is all and sort by order is desc.

Stack9 also has the count feature which shows how many notifications the user has.

GET /api/notifications/count?status=all

Returns:

{
  "count": 2
}

Note: Default value for count is all.

Users are able to manage their notifications easily.

PUT /api/notifications/mark;

See below examples of how the notifications are set as seen or unseen.

{
  "ids": ["61777e720e81d5980f417ca6", "6171f884aa767a5347dd6b34"],
  "status": "seen",
  "after": "2021-10-09 00:57:06"
}

{
  "ids": ["61777e720e81d5980f417ca6", "6171f884aa767a5347dd6b34"],
  "status": "unseen",
  "after": "2021-10-09 00:57:06"
}

Note: The after field is optional.