{"id":19371417,"url":"https://github.com/michael-ortiz/aws-on-call-notifier","last_synced_at":"2026-06-02T16:03:15.186Z","repository":{"id":47487723,"uuid":"368875095","full_name":"michael-ortiz/aws-on-call-notifier","owner":"michael-ortiz","description":"A simple notification architecture to remind employees through email or sms their on-call shifts. No need to have a document and keep forgetting your on-call shift schedule! 🤓","archived":false,"fork":false,"pushed_at":"2021-09-24T18:09:05.000Z","size":171,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-07T00:38:09.850Z","etag":null,"topics":["aws","cdk","email","notification-service","notifications","on-call","sms"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/michael-ortiz.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-05-19T13:15:22.000Z","updated_at":"2022-07-05T18:16:02.000Z","dependencies_parsed_at":"2022-09-03T04:51:44.166Z","dependency_job_id":null,"html_url":"https://github.com/michael-ortiz/aws-on-call-notifier","commit_stats":null,"previous_names":["michael-ortiz/aws-on-call-notifier"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-ortiz%2Faws-on-call-notifier","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-ortiz%2Faws-on-call-notifier/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-ortiz%2Faws-on-call-notifier/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/michael-ortiz%2Faws-on-call-notifier/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/michael-ortiz","download_url":"https://codeload.github.com/michael-ortiz/aws-on-call-notifier/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240495032,"owners_count":19810537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cdk","email","notification-service","notifications","on-call","sms"],"created_at":"2024-11-10T08:18:23.433Z","updated_at":"2026-06-02T16:03:15.104Z","avatar_url":"https://github.com/michael-ortiz.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🔔 On-Call Notifier 📩\n\n\n\n\n## Summary Introduction\n\nOn-Call-Notifier is a small project will remind employees when their [On-Call](https://en.wikipedia.org/wiki/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](https://aws.amazon.com/cdk/) to create the cloud infrastructure, and make use of [Clean Architecture](https://blog.cleancoder.com/uncle-bob/2012/08/13/the-clean-architecture.html) software design principles for the lambda code.\n\n\n\n\n## 🏗 The Architecture\n\n\n\n![](https://personal-public-bucket.s3.amazonaws.com/OnCallNotifierArquitecture.png)\n\n\n\n**AWS Services used and what they are used for:**\n\n* [**Cloud Watch Events**](https://docs.aws.amazon.com/AmazonCloudWatch/latest/events/WhatIsCloudWatchEvents.html)\n\n  Invokes the *notifier lambda* automatically by using a cron expression. \n\n  https://docs.aws.amazon.com/lambda/latest/dg/services-cloudwatchevents-expressions.html\n\n* [**Lambda**](https://aws.amazon.com/lambda/)\n\n  Fetches schedule information for the current date. If there is a `Schedule` Item, user information will be fetched, which then triggers the notification process to notify the employee or user.\n\n* [**DynamoDB**](https://aws.amazon.com/dynamodb/)\n\n  A non-relational database that will store the users and on-call schedule information. \n\n* [**SES**](https://aws.amazon.com/ses/)\n\n  AWS Service used to send email notifications.\n\n* [**SNS**](https://aws.amazon.com/sns)\n\n  AWS Service used to send text messages (SMS) notifications.\n\n\n\n## 🏎 Before we begin\n\nPlease follow the instructions until the end to fully configure this project. All steps are required for a full deployment.\n\n\n\n## ⚙️ Project Settings Configuration\n\nThe `configurations.ts` file, contains the required configurations that you must enter in order to start sending notifications.\n\n**File Location**:\n\n````\nlib/settings/configurations.ts\n````\n\n\n\nBe sure to enter your information on every `\u003cCHANGE_ME\u003e` as is required to begin sending notifications.\n\n\n\n## 📚 Database Configuration\n\nBefore 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\n\n\n\n**Files Location**:\n\n````\n/lib/dynamodb/data/users.json\n/lib/dynamodb/data/schedule.json\n````\n\n\n\n### Users Data\n\n`users.json`\n\nThis 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.\n\n```json\n{\n    \"on_call_users\": [\n        {   \n            \"PutRequest\": {\n                \"Item\": { \n                    \"user_id\": { \"S\": \"1\" },\n                    \"name\": { \"S\": \"User Name\" },\n                    \"phone_number\": { \"S\": \"+1XXX5550100\" },\n                    \"email_address\": { \"S\": \"email@mail.com\" },\n                    \"alerts\": {\n                        \"M\": {\n                            \"email\": { \"BOOL\": true },\n                            \"sms\": { \"BOOL\": true }\n                        } \n                    }\n                }\n            }\n        }\n    ]\n}\n```\n\n\n\n### Schedule Data\n\n`schedule.json`\n\nThe 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.\n\n```json\n{\n  \"on_call_schedule\": [\n        {   \n            \"PutRequest\": {\n                \"Item\": {\n                    \"user_id\": { \"S\": \"1\" },\n                    \"start_date\": { \"S\": \"yyyy-mm-dd\" },\n                    \"end_date\": { \"S\": \"yyyy-mm-dd\" }\n                }\n            }\n        }\n    ]\n}\n```\n\n\n\n### Schedule Item\n\n```json\n{\n  \"user_id\": { \"S\": \"1\" },\n  \"start_date\": { \"S\": \"2021-05-20\" },\n  \"end_date\": { \"S\": \"2021-05-20\" }\n}\n```\n\n---\n\n`user_id`\n\nA unique ID for the user or employee.\n\n*Type:* `String`\n\n----\n\n`start_date`\n\nThe start date of the on-call shift in ISO 8601 date format.\n\n*Type:* `String`\n\n----\n\n`end_date`\n\nThe end date of the on-call shift in ISO 8601 date format.\n\n*Type:* `String`\n\n----\n\n\n\n### User Item\n\n```json\n{ \n  \"user_id\": { \"S\": \"1\" }, \n  \"name\": { \"S\": \"User name\" },\n  \"phone_number\": { \"S\": \"+1XXX5550100\" },\n  \"email_address\": { \"S\": \"email@mail.com\" }, \n  \"alerts\": {\n    \"M\": {\n      \"email\": { \"BOOL\": true },\n      \"sms\": { \"BOOL\": true }\n    } \n  }\n}\t\n```\n\n---\n\n`user_id`\n\nA unique ID for the user.\n\n*Type:* `String`\n\n----\n\n`name`\n\nThe user's name.\n\n*Type:* `String`\n\n---\n\n`phoneNumber`\n\nE.164 format phone number.  The user will receive an SMS notification to this address if configured in the `alerts` section.\n\n*Type:* `String`\n\n---\n\n`email_address`\n\nA [verified](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses-procedure.html) email address. The user will receive a email notification to this address if configured in the `alerts` section.\n\n*Supports*: `\u003cYour Name\u003eexample@mail.com` format.\n\n*Type:* `String`\n\n---\n\n`alerts`\n\nThe users alert preferences.\n\n*Type:* `Map\u003cString, Boolean\u003e`\n\n---\n\n\n\n## ✅ Verify Email Address\n\nIn order to recieve email messages with the SES service, you must verify your email in your AWS Console.\n\n\n\nFollow the instructions in the official documentation:\n\nhttps://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses-procedure.html\n\n\n\n## 🚀 Install \u0026 Deploy Instructions ⛅️\n\n\n\nAfter passing all the previous stages you are now ready to begin the deployment stage!\n\n\n\n**Prerequisites**: \n\nIf this is your first time using CDK, **please follow** the pre installation instruction in the official documentation.\n\nhttps://docs.aws.amazon.com/cdk/latest/guide/getting_started.html#getting_started_prerequisites\n\n\n\nNext, in the project root folder, from your favorite Terminal, execute the following commands:\n\n```shell\nnpm run build\ncdk deploy\n```\n\n\n\nOnce your deploy is successful, let's go ahead and load or user's data our DynamoDB table:\n\n```shell\nnpm run load-users-data \n```\n\n\n\nNow, close the execution output, and execute the next command:\n\n```sh\nnpm run load-schedule-data\n```\n\n\n\nYou 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.\n\n\n\n## ⏳ Testing Locally\n\n\n\nIf you wish to run this project locally, you can do so by installing the [SAM CLI](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html). 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.\n\n\n\nTo configure the local environment variables required by the lambda, find the `local.json` file:\n\n```\nfunctions/lambda-notifier/local.json\n```\n\n Mainly, you must change the `SOURCE_EMAIL` to your corresponding [**verified**](https://docs.aws.amazon.com/ses/latest/DeveloperGuide/verify-email-addresses-procedure.html) email address.\n\n\n\nOnce everything is configured, run the following command to start the lambda:\n\n```json\nnpm run start:local-lambda\n```\n\n\n\nRead more about running local lambdas here:\n\nhttps://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-using-invoke.html\n\n\n\n## Useful CDK commands\n\n * `npm run build`   compile typescript to js\n * `npm run watch`   watch for changes and compile\n * `npm run test`    perform the jest unit tests\n * `cdk deploy`      deploy this stack to your default AWS account/region\n * `cdk diff`        compare deployed stack with current state\n * `cdk synth`       emits the synthesized CloudFormation template\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichael-ortiz%2Faws-on-call-notifier","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmichael-ortiz%2Faws-on-call-notifier","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmichael-ortiz%2Faws-on-call-notifier/lists"}