On-Call-Notifier is a small project will remind employees when their On-Call shift starts through email or text messages (SMS). This project is completely serverless (no need to manage or provision servers) and is hosted in AWS. We use AWS CDK to create the cloud infrastructure, and make use of Clean Architecture software design principles for the lambda code.
AWS Services used and what they are used for:
-
Invokes the notifier lambda automatically by using a cron expression.
https://docs.aws.amazon.com/lambda/latest/dg/services-cloudwatchevents-expressions.html
-
Fetches schedule information for the current date. If there is a
ScheduleItem, user information will be fetched, which then triggers the notification process to notify the employee or user. -
A non-relational database that will store the users and on-call schedule information.
-
AWS Service used to send email notifications.
-
AWS Service used to send text messages (SMS) notifications.
Please follow the instructions until the end to fully configure this project. All steps are required for a full deployment.
The configurations.ts file, contains the required configurations that you must enter in order to start sending notifications.
File Location:
lib/settings/configurations.ts
Be sure to enter your information on every <CHANGE_ME> as is required to begin sending notifications.
Before you can start receiving notifications, you fill your on-call schedule. This project contains 2 main DynamoDB (non-relational) tables that contain the information about when and to whom the notifications are going to be sent. The users.json and schedule.json files contain the data that will be preloaded into the DynamoDB database. Be sure to fill this with your respective information
Files Location:
/lib/dynamodb/data/users.json
/lib/dynamodb/data/schedule.json
users.json
This file should contain a list of all the users that can be notified. Their contact information must be present for them to receive a notification. You can also disable a notification for a user if they prefer not to receive them initially. Also, keep in mind that the user_id must be included in the schedule.json item as its used as a reference key.
{
"on_call_users": [
{
"PutRequest": {
"Item": {
"user_id": { "S": "1" },
"name": { "S": "User Name" },
"phone_number": { "S": "+1XXX5550100" },
"email_address": { "S": "[email protected]" },
"alerts": {
"M": {
"email": { "BOOL": true },
"sms": { "BOOL": true }
}
}
}
}
}
]
}schedule.json
The schedule table contains the information about the start and end dates of a user's on call shift. The user will be notified on the start_date when the lambda runs.
{
"on_call_schedule": [
{
"PutRequest": {
"Item": {
"user_id": { "S": "1" },
"start_date": { "S": "yyyy-mm-dd" },
"end_date": { "S": "yyyy-mm-dd" }
}
}
}
]
}{
"user_id": { "S": "1" },
"start_date": { "S": "2021-05-20" },
"end_date": { "S": "2021-05-20" }
}user_id
A unique ID for the user or employee.
Type: String
start_date
The start date of the on-call shift in ISO 8601 date format.
Type: String
end_date
The end date of the on-call shift in ISO 8601 date format.
Type: String
{
"user_id": { "S": "1" },
"name": { "S": "User name" },
"phone_number": { "S": "+1XXX5550100" },
"email_address": { "S": "[email protected]" },
"alerts": {
"M": {
"email": { "BOOL": true },
"sms": { "BOOL": true }
}
}
} user_id
A unique ID for the user.
Type: String
name
The user's name.
Type: String
phoneNumber
E.164 format phone number. The user will receive an SMS notification to this address if configured in the alerts section.
Type: String
email_address
A verified email address. The user will receive a email notification to this address if configured in the alerts section.
Supports: <Your Name>[email protected] format.
Type: String
alerts
The users alert preferences.
Type: Map<String, Boolean>
In order to recieve email messages with the SES service, you must verify your email in your AWS Console.
Follow the instructions in the official documentation:
https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses-procedure.html
After passing all the previous stages you are now ready to begin the deployment stage!
Prerequisites:
If this is your first time using CDK, please follow the pre installation instruction in the official documentation.
https://docs.aws.amazon.com/cdk/latest/guide/getting_started.html#getting_started_prerequisites
Next, in the project root folder, from your favorite Terminal, execute the following commands:
npm run build
cdk deployOnce your deploy is successful, let's go ahead and load or user's data our DynamoDB table:
npm run load-users-data Now, close the execution output, and execute the next command:
npm run load-schedule-dataYou can validate that everything is working fine by adding an Item into DynamoDB a Schedule Item where the start_date = your current date in yyyy-mm-dd format. Manually execute the lambda from the console.
If you wish to run this project locally, you can do so by installing the SAM CLI. You must make sure that the DynamoDB tables are loaded and there is at least an Item in the on_call_schedule table has an item where the start_date is your current date.
To configure the local environment variables required by the lambda, find the local.json file:
functions/lambda-notifier/local.json
Mainly, you must change the SOURCE_EMAIL to your corresponding verified email address.
Once everything is configured, run the following command to start the lambda:
npm run start:local-lambdaRead more about running local lambdas here:
npm run buildcompile typescript to jsnpm run watchwatch for changes and compilenpm run testperform the jest unit testscdk deploydeploy this stack to your default AWS account/regioncdk diffcompare deployed stack with current statecdk synthemits the synthesized CloudFormation template