microsoft / tilda

Companion tool for the CSCW 2018 academic paper 'Making Sense of Group Chat through Collaborative Tagging and Summarization.' Collaboratively tag Slack conversations to produce structured summarizations.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact [email protected] with any additional questions or comments.

About

Tilda is a research project studying team collaboration over group chat. The Tilda software allows teams to create collaborative summaries of the important parts of their chats, which makes it easier for people to catch up on missed conversations. You can read more about our research in our 2018 CSCW publication.

Using the Hosted Version of Tilda

If you just want use Tilda in your own Slack team, and don't want to go through the steps of deploying it yourself, there is a hosted version run by MIT located at https://tildachat.com. Follow the instructions on that site to get started.

Developing and Deploying your own Tilda

If you'd like to deploy and host your own Tilda, follow these instructions.

Get Slack API Credentials

1. To run your own version of Tilda, you'll need to get an account on api.slack.com. Once you have done so, create a new Slack App and select a Slack Workspace that you will be using for development. Once you have done so, under App Credentials, grab your Slack client ID (SLACK_CLIENT_ID) and secret (SLACK_CLIENT_SECRET) for below.

2. Click on Interactive Components. Then turn on Interactivity. We'll come back to add a URL once the node server is set up.

3. Click on Event Subscriptions. Turn on Enable Events. We'll come back to add a URL once the node server is set up.

4. Click on Bots and add a Bot User. Call it tilda or your preferred name. Select "Always Show My Bot as Online".

5. Under Permissions, click on Install App to Workspace. Authorize the app to have a bot user on your test Slack workspace. This will generate two tokens for you - an OAuth Access Token (SLACK_ACCESS_TOKEN) and Bot User OAuth Token (BOT_USER_OAUTH_ACCESS_TOKEN). Keep track of those. We will come back to this page later.

Setting up node server

1. To run Tilda, you need to either have a hosted server you can run node.js on or use ngrok to test locally.

2. Clone this Github repository into your server space or locally, depending on the above.

3. Go into the folder and type npm init to load all the dependencies for this project.

Setting up MongoDB

1. Follow instructions to install MongoDB on your space or server. Here are installation instructions for Ubuntu.

2. Run MongoDB in the background.

3. Keep track of the URL and port that MongoDB is running on so node can connect to it. If you're running it on the same space as your node.js server and using port 27017 (the default), this should be mongodb://localhost:27017/tilda (MONGO_DB).

Set up HTTPS

1. The Slack API requires that your node server is running with HTTPS. An easy way to do this is to use LetsEncrypt and CertBot. Follow their instructions to get a certificate. Keep track of where you're storing the key file and the certificate file. Tilda's code currently assumes it is stored at /etc/letsencrypt.

Run Node Server

1. Create a .env file in the same folder as your node.js project. Add the following to your .env file:

MONGO_DB=<DB CONNECTION STRING>
SLACK_OAUTH_ACCESS_TOKEN=<SLACK ACCESS TOKEN>
BOT_USER_OAUTH_ACCESS_TOKEN=<BOT ACCESS TOKEN>
SLACK_CLIENT_ID=<SLACK CLIENT ID>
SLACK_CLIENT_SECRET=<SLACK CLIENT SECRET>

2. Look inside app.js for where https_options is declared. Replace the file paths for your file paths to the private key and your certificate, generated by LetsEncrypt. Save the file.

3. In the folder, run node: node app.js. Your node server should now be running! The logging output should say something along the lines of:

restify listening to https://[::]:8080
Connected

You can confirm by going in your browser to the proper URL and port (8080). You should see the following response, showing the server is running properly:

{
"code": "ResourceNotFound",
"message": "/ does not exist"
}

Set up Slack API

1. Head back to api.slack.com to finish configuring the API. Under Interactive Messages, put the following under Request URL: https://[YOUR URL]:8080/api/actions. Now click Save Changes.

2. Go to Slash Commands. You'll need to add all the Tilda slash commands here. These include:

Slash Command	Request URL	Short Description	Usage Hint	Escape info
/~start	https://[YOUR_URL]:8080/api/commands	Start a conversation.
/~end	https://[YOUR_URL]:8080/api/commands	End the conversation.
/~addaction	https://[YOUR_URL]:8080/api/commands	Add an action item.	[action item]	Yes
/~addanswer	https://[YOUR_URL]:8080/api/commands	Add an answer or suggestion to a question.	[answer]	Yes
/~adddecision	https://[YOUR_URL]:8080/api/commands	Add a decision that was made.	[decision]	Yes
/~addidea	https://[YOUR_URL]:8080/api/commands	Add an idea or proposal item.	[idea]	Yes
/~addinfo	https://[YOUR_URL]:8080/api/commands	Add an info item.	[info item]	Yes
/~addquestion	https://[YOUR_URL]:8080/api/commands	Add a question or request for help	[question]	Yes
/~addtag	https://[YOUR_URL]:8080/api/commands	Tag this conversation with keywords	optional: [tag]
/~currentsummary	https://[YOUR_URL]:8080/api/commands	See what notes are in the current summary
/~followchannel	https://[YOUR_URL]:8080/api/commands	Post summaries from another channel here.	[#channelname] [optional: @users] [optional: tags]	Yes
/~instructions	https://[YOUR_URL]:8080/api/commands	Instructions for adding notes.
/~unfollowchannel	https://[YOUR_URL]:8080/api/commands	Stop getting summaries from a channel.	[#channelname]	Yes

3. Go to Event Subscriptions. Under Request URL, put https://[YOUR_URL]:8080/api/events. Slack should confirm the endpoint at this point. Subscribe to the following Workspace Events:

Event Name	Description	Required Scope
reaction_added	A member has added an emoji reaction to an item	reactions:read
star_added	A member has starred an item	stars:read

Then subscribe to the following Bot Events:

Event Name	Description
message.channels	A message was posted to a channel
message.groups	A message was posted to a private channel
message.im	A message was posted in a direct message channel
message.mpim	A message was posted in a multiparty direct message channel

4. Go to Permissions. Under Redirect URLS, add https:[YOUR_URL]:8080/api/oauth and save. Then, under Scopes, add the following permission scopes: channels:history, chat:write:bot, bot, commands, reactions:read, stars:read. You may need to reinstall the app to your Slack workspace with the new permissions.

Set up Slack Workspace

1. Now Tilda should be installed into your test Slack Workspace. One last thing you need to do is to add Tilda's custom emoji reactions. Go to https://[YOUR_WORKSPACE].slack.com/customize/emoji.

Luckily :question: is already there and so is :end:.

Add the following aliases:

• :boom: -> :action:
• :exclamation: -> :answer:
• :bulb: -> :idea:
• :handshake: -> :decision:
• :information_source: -> :info:
• :top: -> :topic:

One more requires adding a custom emoji. Upload the file start.png from this repository. Give it the name :start:.

Done!

You can now begin playing with Tilda in your test workspace. Remember to add @tilda to any channel that you would like to use Tilda for taking notes. If you want to distribute your app to other workspaces beyond the test one, you must click on Manage Distribution on the Slack API page to generate the links to get permissions for other workspaces.

tilda's Issues

look into addtopic

seems like it's missing as a command?