Explain Bot is a slackbot, written in Python and deployed to AWS with CDK. The purpose of this bot is to help users learn about acronyms in use at Blackboard, with a focus around SAFe terms. That said, it is not limited in anyway.
In order to configure and run this application, you will need to have a slack application configured. The easiest way to get started is to login to https://blackboard-sandbox.slack.com with your ADFS credentials, select Customize Blackboard-Sandbox from the space menu, and then click Configure Apps in the left-hand navigation. Once you do this, you will see a link in the top navigation to the right called Build.
On the subsequent page, simply click the Create New App button. Give your app a name and then in the Development Slack Workspace dropdown, select Blackboard-Sandbox. Then click Create App.
On the page that loads when you create your application, you will see a form with App Credentials. Click Show for your Signing Secret and copy that value to the clipboard.
In this project, we need to manually store secrets as plain text in SecretsManager and parameters in the Parameter Store in the region us-east-2 of the aws account (if a different region is used update the variable ssm in all lambda files accordingly). Please create /explainbot/parameters/<dev-prod>/slack_signing_secret in the Parameter store as a secure string and it will be available for access in the code.
Next, click Slash Commands in the left-hand navigation and click Create New Command. Enter a name for your command WITH the slash. I called it /define but the app doesn't care what you call it. In the URL field, put a dummy URL. We will fill this in after we deploy the app. Give it a short description, which is required, and then a usage hint if you like, the click Save.
Now, from the left-hand menu, click Interactivity & Shortcuts. Click the toggle to turn on Interactivity and add a dummy URL to Request URL and click Save Changes. We will fill this in once the application is deployed to AWS.
To continue further, we will need to install the application to the Slack workspace. In the left-hand navigation click Install App and the click Request to Install. This will send a request to DIRE. You should also open a DIRE ticket to ensure they are aware of the request.
Once the app is installed in the Blackboard-Sandbox workspace, the app will provide you the last piece of information we require for deployment. Back in the place where you registered and configured you application, there is a left-hand navigation item for OAuth & Permissions. Click this link and copy the Bot User OAuth Token. Create a OAUTH_TOKEN parameter as a secure string in Parameter Store with the latter token following the hierarchy /explainbot/parameters/<dev-prod>/oauth_token.
For the deployment we used CodePipeline to automate the release process. In order to connect GitHub with the pipeline go to GitHub -> Settings -> Developer Settings -> Personal Access Tokens and create a token (remember to authorize to your organization). Create a GITHUB_TOKEN_NAME secret in Secrets Manager with the newly generated access token. Next, you'll need to create a secret named EXPLAINBOT_ACCOUNT corresponding to the aws account number used to create these project resources
Finally, include another parameter in the Parameter Store /explainbot/parameters/<dev-prod>/approvers as a string and add the APPROVERS with the comma-delimited string that you wish to be able to approve definitions.
In order to fill the database with predetermined information, upload the filed named acronyms.csv from this repo to a bucket named explainbot-initial-data-<dev-prod> in your account (if a different name is required update the lambda file initial_data.py accordingly). In bucket Permissions tab, uncheck Block all public access, and add a bucket policy to allow the action s3:GetObject for Principal:*.
Next, activate the virtual environment. If you are on Windows, execute ./source.bat from the commandline in the project directory. If you are on Mac, execute . .env/bin/activate in the terminal inside the project directory.
Now run pip install --upgrade -r requirements.txt.
To deploy the script, you will need a few things. First, you will need CDK installed. You will also need your environment set up with AWS credentials with appropriate permissions to create assets in AWS. I built and tested on Windows 10 using saml2aws.exe and then a profile based on those credentials with elevated priviliges. My elevated profile is called OKTAPOWERUSER. Replace with your profile name.
The initial deployment will create a CodePipeline pointing to the target branch (ex. branch='feature/dev-branch') that you must specify in explainbot_pipeline_stack line 31. Whenever a commit is pushed to this branch the pipeline will automatically synthesize and deploy changes.
- Boostrap your project:
cdk --profile OKTAPOWERUSER bootstrap - Then deploy:
cdk --profile OKTAPOWERUSER deploy PipelineStackNameand follow the onscreen instructions.
That's it, you are deployed. Now, everytime the infrascture is changed or a new stage is added CodePipeline will mutate itself to reflect changes.
We have created a number of things:
- An Application, that contains...
- API Gateway
- Four Lambdas
- DynamoDb Table
- CloudWatch Event Rule
- Custom Resources that populated that table with the base data
- All the roles and links required to tie the stack together.
Now that the application is running in AWS, the last step is to add the real URLs to the Slack App and then test. To get that value, we need to login to the AWS Management Console, with enough priviliges to view the application. Navigate to API Gateway and select ExplainSlackBotApi. Right click the Invoke URL and copy the link address. Now navigate back to your Slack Application. Click into your application, and on the subsequent screen, click Interactivity & Shortcuts. In the Request URL text box, paste the invoke URL and append add_meaning, so you should end up with https://<api id>.execute-api.us-east-1.amazonaws.com/add_meaning. Click Save Changes.
Now click Slash Commands in the left-hand navigation and then click the pencil icon next to the slash command you created. Paste the Invoke URL into the Request URL text box. It should look like https://<api id>.execute-api.us-east-1.amazonaws.com/. Click Save.
Now simply login to Blackboard-Sandbox.slack.com with your AFDS credentials, and type /define lace and press ENTER. Of course if you called it something other than /define, use your command. It should return the definition. Now, assuming you added yourself as an "UPDATER", type /define CDK Cloud Development Kit and press ENTER. This will load a modal that you can accept as is or edit and then click Submit. You have now defined a new acronym available to all.
Linting is implemented in the pre-commit process, so it's executed before committing the changes to ensure that code styling issues caused by bad patterns are not introduced in the code. Make sure you run pip install --upgrade -r requirements-dev.txt to install the linting and formatting dependencies, then execute pre-commit install to install git hooks in your .git/ directory. Before doing a commit, styling issues are fixed automatically. You must address manually those issues that could not be fixed by the tool. To check for code issues run pre-commit run --all-files.
This is 100% MVP level. There are a number of enhancements, which I will add as issues to this repo. In addition, I wrote this to learn CDK, so feel free to help improve the CDK implementation. I only ask that you create an issue and document what you are changing and why, so I, as well as anyone else that comes along, can learn why you have made that change.