Intratime slack app

Application to clock in intratime app using using slack.

Introduction

Intratime slack app is an application that allows you to clock in the Intratime application using the slack client and get this related info.

You only need to enter your intratime credentials (they will be stored in an encrypted database) and write a single command to clock your actions or get information about them.

This application has the following capabilities:

• Clock your entry, pause, return or out action.
• Get your total worked time (clocked).
• Get your clock history.
• Get your worked time history.

---

How to use

Considerations before starting

• All messages generated as a result of any command are of private visibility, thus avoiding flooding public conversations and preventing the rest of the users from seeing your information or actions.

• When the account is created using the intratime credentials, the password is stored in encrypted form.

• Requests and slack content to the server (where the application is running) are encrypted. (This encryption is external to the application, using NGINX as reverse proxy).

• The intratime-bot service will only deal with requests made by slack, using a signature key. This prevents unwanted access in external applications.

• Most commands can be launched via user interface or directly with parameters. Commands without parameters will activate the GUI. See the /help command for more information available command parameters.

User management

Register your app user

First of all, it is necessary to have an intratime and slack account. From here, we will have to sign up in this app using the /sign_up command in the slack chat and then introducing your intratime credentials in the related fields.

Note: There are no password type fields, so the password will be written in raw in the field. Be careful with this.

Update your app user

If you have ever modified your credentials in intratime (in the intratime application), then you will need to update your credentials in this app as well, to do so use the /update_user command and enter your new credentials:

Delete your app user

In case you want to delete your user in this app, you can do it with the command /delete_user.

Clock your actions

Once the user is registered (you only need to do it once), you can clock your action (IN, PAUSE, RETURN or OUT) in the intratime application using the /clock command.

It is also possible to activate this command directly by passing it one of the following actions: IN, PAUSE, RETURN OUT.

/clock <action>

If the action is successful, the following message will be displayed:

This functionality also filters out possible inconsistent clockings, such as trying to clock a RETURN without a previous PAUSE. In this case, we can see messages like the following:

Check your total worked time

A very useful feature is to check how long we have been working, making the calculation based on the clockings we have made. We can do this calculation on a daily, weekly or monthly basis.

For this you can use the /time command.

It is also possible to activate this command directly by passing it one of the following parameters: today, week, month.

/time <parameter>

Check your clock history

Do you need to check the clocks made? This command shows you all the information of the clockings made in the current day, week or month.

For this you can use the /clock_history command.

It is also possible to activate this command directly by passing it one of the following parameters: today, week, month.

/clock_history <parameter>

Note: This information will be shown in the private conversation that each user has with the slack application.

Check your worked time history

Do you want to know how many hours you worked each day? This commands shows you a list of time worked for each day in the specified range, on the current day, week or month.

For this you can use the /time_history command.

It is also possible to activate this command directly by passing it one of the following parameters: today, week, month.

/time_history <parameter>

Note: This information will be shown in the private conversation that each user has with the slack application.

Check your current day summary

If you want to get a summary of the time worked and clockings made today, you can use directly the /today command. This command has not parameters.

/today

Get help info

In case you need information about the available commands and parameters, you can run the command /help, to display the following help menu:

---

App components

This application consists of the following services:

• intratime-bot: Main service that attends to all slack requests and communicates with the rest of services and components to carry out the request.

• mongo-service: Storage and database service.

• mongo-express: Service to visualize and make queries in a graphic way in the database service.

The implemented structure can be seen in the following figure:

---

How to deploy

Configure your slack app

First you will have to create a slack application. You can create one from this website https://api.slack.com/.

Get slack app credentials

Once created, you will have to obtain your app tokens. You can find it in OAuth & Permissions section. It will have a format like the following:

OAuth Access Token

xoxp-xxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx

Bot User OAuth Access Token

xoxb-xxxxxxxxxxxxx-xxxxxxxxxxxxx-xxxxxxxxxxxxxxxxxxxxxxxx

It will also be necessary to obtain the signing secret key to verify that the requests come from our slack app. You can find this key in Basic information section.

Set your token scopes

A Slack app's capabilities and permissions are governed by the scopes it requests. You can configure them in OAuth & Permissions section. The current token scopes are as follows:

• Bot token scopes: channels:history, commands, groups:history
• User Token Scopes: chat:write

Set your interactivity endpoint

All the interactions with the graphic slack components (in this case the modal windows and forms are used) have to be attended from a specific endpoint.

This endpoint belongs to the intratime-bot service with the /interactive URI , so it will be necessary to indicate in the Interactivity & Shortcuts section the Request URL for this endpoint. For example:

https://<domain_name>/interactive

Define your commands

Commands enable users to interact with your app from within Slack. In this case, we have to define the following commands:

• /sign_up: https://<domain_name>/sign_up
• /clock: https://<domain_name>/clock
• /update_user: https://<domain_name>/update_user
• /delete_user: https://<domain_name>/delete_user
• /clock_history: https://<domain_name>/clock_history
• /time: https://<domain_name>/time
• /time_history: https://<domain_name>/time_history
• /today: https://<domain_name>/today
• /help: https://<domain_name>/help

Configure your app settings

You have to configure the intratime slack bot application modifying the settings.py file.

In addition, you have to update the .env file to enter your mongo and mongo-express credentials.

In case of modifying default ports ..., take a look at the docker-compose.yaml file and update to your new values.

Run the app

Once the application is configured (see the previous steps), Running the application is very simple, you just need to have installed docker and docker-compose, and execute the following command in root directory.

docker-compose build && docker-compose up

All services will be automatically started.

You can check if the configuration and deployment has been done correctly by running the unit and integration tests.

Note: The unit and integration tests must be run separately

You can run these tests with pytest module. For example, inside test/unit folder, we can run:

pytest -v --tb=short .

The same process must be done to launch the integration tests.

---

Contributions

Any doubt or suggestion, you can create issues and/or make pull requests :)