This is a custom integration for the University of Washington between Slack and R25, part of the CollegeNET Series25 scheduling solution's web service API.
From within any Slack channel where the integration has been enabled, the following slash commands can be executed:
/r25 help/r25 [building code] [room number]/r25 [building code] [room number] now/r25 [building code] [room number] tomorrow/r25 [building code] [room number] +1/r25 [building code] [room number] +2/r25 [building code] [room number] breaks/r25 [building code] [room number] next break
/r25 kne 130 breaks
From within any Slack channel type /r25 followed by a building code, such as 'arc' or 'kne', followed by the room number. If the building code and room number match supported rooms, then the schedule for that room will be retrieved and posted into the Slack channel.
You may also get schedules for days in the future by following the room number with either the 'tomorrow' keyword, or a plus and a number, such as '+1'. Any number of days in the future may be requested, but large numbers don't resolve data.
Adding the 'breaks' keyword after the query space returns the break periods between scheduled classes and events, along with their durations. The key phrase 'next break' may be used to only retrieve the next upcoming break for a space.
This project uses Serverless for Node.js on top of AWS Lambda. Serverless handles deployment and setup. See the Serverless docs for generating credentials to the hosting cloud platform. All AWS infrastructure for this project can be utilized under the AWS Free Tier. Using a serverless architecture allows for rapid deployment for minimal cost and maintenance.
A Slack app must be created and named first.
Uses a Slack custom integration / app. The app uses the Slash Command functionality, and points it's outbound request as a POST to the AWS Lambda address (obtained from AWS once Lambda function has been deployed). The Slack Token ID is also needed in the Serverless configuration as an environment variable, and the Lambda function will use the app Token ID to ensure that the request coming into Lambda came from your Slack instance.
Two functions are defined: a parse function and a R25 web service (r25ws) function.
- Parse: verify the command can be processed and send feedback to Slack with result
- r25ws (handler): Communicate with the R25 web service to gather schedule information and then respond appropriately to Slack
Glues the two Lambda functions together, allows the parse handler to pass command information to the r25ws handler. Can later be used to trigger additional or different functions depending on later developments. All configuration and AWS permissions are defined in the serverless.yml file.
Environment variables are stored as .json files in a folder named 'env-vars' in the root of the project directory. Store secrets, such as R25 Web Service API credentials, Slack ID Tokens, etc. in these json files. Below are examples:
{
"user": "r25 web service username",
"password": "r25 web service password",
"baseUrl": "https://webservices.collegenet.com/r25ws/wrd/{instance name}/run/"
}{
"dev": {
"slack-token": "xxxxxxxxxxxxxxxxxxxxxxxx"
},
"prod": {
"slack-token": "xxxxxxxxxxxxxxxxxxxxxxxx"
}
}Automated testing implemented with Mocha, Chai, and simple-mock. CI integrated on github (github actions). These tests ensure that basic functionality continues to work properly. Setting the stage in serverless.yml to 'dev' allows for testing on a remote server without affecting production instance(s). Set up a separate 'team' on Slack, and create a custom integration app for testing out / development and use the separate slack token for access. More than one stage of the program can also be deployed to Lambda simultaneously, as each deployment will create a separate endpoint on AWS.
npm run test
npm run coverage
Automated testing enabled on github actions. Secrets are saved on github under the repository settings and are retrieved at runtime by the test runner environment.
From a terminal in the project root, run npx sls deploy [function -f {function_name}]. npx ensures that the local installation of serverless is used, rather than any possible globally-installed version (sls is an alias for serverless).
NOTE The stage DOES NOT override what is saved in the serverless configuration file (serverless.yml)! Update the stage setting in the file to either "dev" or "prod" before running the above deploy command.
To make sure the current yml syntax is compatible with changes to Serverless updates and upstream changes to AWS Services, run npx sls info to see any deprecation warnings or errors.
Updating spaces.json requires updating the parse function.
All contributions, issues/bug reports, and questions are welcome.