Tola Activity

The build status of the bootstrap4 branch is:

TolaActivity extends the functionality of TolaData to include a set of forms and reports for managing project activities for a Program. It includes workflow for approving and completing projects as well as sharing the output data. TolaActivity functionality is intended to allow importing and exporting of project-specific data from 3rd party data sources or excel files.

Creating a local TolaActivity instance

Running a local instance of TolaActivity makes development much faster and eliminates your dependence on access to any of MC's TolaActivity instances. These instructions should get you up and running with a minimum of fuss if you have macOS or one of the many Ubunten. If they do not, pull requests are accepted.

Install the bits

TolaActivity requires Python 2. MC uses MySQL as Django's datastore.

macOS

On macOS, you can use Homebrew to install Python 2 alongside the system Python 2 installation as shown in the following:

$ brew install python@2
$ brew install pip
$ brew install mysql mysql-utilies
$ brew install py2cairo pango
$ git clone https://github.com/mercycorps.org/TolaActivity.git
$ cd TolaActivity
$ git checkout dev
$ virtualenv -p python2 TolaActivty --no-site-packages venv # need to specify Python 2 for systems that might have Python 3 as default system version
$ source venv/bin/activate
$ mkdir config
# Place settings.secret.yml into config/ directory
$ cp config/sample-settings.secret.yml config/settings.secret.yml
$ pip install -r requirements.txt
$ pip install --upgrade google-api-python-client

Edit the configuration file as described in Modify the config file.

Ubuntu

On Ubuntu and its derivatives, Python 2 is the default, so the following should get you going on any current Python 2 version for most Ubuntu-family distros (Ubunten):

$ python --version
$ # Make sure output from above indicates Python 2
$ sudo apt install mysql-server libmysqld-dev mysql-utilities mysql-client
$ sudo apt install libsasl2-dev python-dev libldap2-dev libssl-dev
$ git clone https://github.com/mercycorps.org/TolaActivity.git
$ git checkout dev
$ virtualenv TolaActivty --no-site-packages
$ cd TolaActivity
$ source bin/activate
$ mkdir config
# Place settings.secret.yml into config/ directory
$ pip install -r requirements.txt
$ pip install --upgrade google-api-python-client

Edit the configuration file as described in Modify the config file.

Modify the config file

Edit config/settings.secret.yml. Find the node named, "DATABASES" and set the database PASSWORD as appropriate. The result should resemble the following:

32 DATABASES:
33  default:
34    ENGINE: "django.db.backends.mysql"
35    NAME: "tola_activity"
36    USER: "admin"
37    PASSWORD: "SooperSekritWord"
38    OPTIONS: {"init_command": "SET default_storage_engine=MYISAM",}
39    HOST: "localhost"
40    PORT: ""

Don't change the USER entry unless you know why you need to do that. Save and exit.

Set up Django's MySQL backing store

CREATE DATABASE 'tola_activity';
CREATE USER 'admin';
GRANT ALL ON tola_activity.* TO 'admin'@'localhost' IDENTIFIED BY 'SooperSekritWord';

Set up Django

Set up the Django database:

$ python manage.py migrate

Operations to perform:
  Apply all migrations: admin, auth, authtoken, contenttypes, customdashboard, formlibrary, indicators, reports, sessions, sites, social_django, workflow
  Running migrations:
  Applying contenttypes.0001_initial... OK
  Applying auth.0001_initial... OK

  [output deleted]

  Applying workflow.0014_remove_stakeholder_sector... OK
  Applying workflow.0015_stakeholder_notes... OK
  Applying workflow.0016_auto_20170623_1306... OK

If you get this error during migration `social_django.0005_auto_20160727_2333`

django.db.utils.OperationalError: (1071, 'Specified key was too long; max key length is 1000 bytes')

The social_django app creates a unique_together relationship between two rows that concatenate to a value too long for the destination row. Manually change the following two fields:

social_auth_association.server_url to varchar(100)
social_auth_association.handle to varchar(100)

In the MySQL CLI:

mysql> USE tola_activity;
mysql> ALTER TABLE social_auth_association MODIFY server_url varchar(100) NOT NULL;
mysql> ALTER TABLE social_auth_association MODIFY handle varchar(100) NOT NULL;

...then re-run the migration as normal

$ python manage.py migrate

Start the server:

$ python manage.py runserver
Performing system checks...

System check identified 1 issue (0 silenced).
March 20, 2018 - 11:51:55
Django version 1.11.2, using settings 'tola.settings.local'
Starting development server at http://0.0.0.0:8000/
Quit the server with CONTROL-C.

Configuring OAuth authentication

When running a local instance, we use Google's OAuth API for authentication to TolaActivity. There exists a bug in the API library that requires an ugly manual workaround before you can actually log in and starting using TolaActivity. The following procedure is a workaround for this bug until the bug is well and truly crushed.

Start the TolaActivity server as described in the previous section
Open the home page in a web browser
Click the "Google+" link below the login button to authenticate with Google OAuth
Login as normal using your MercyCorps SSO login
What should happen is that you get logged in and redirected to to the TolaActivity home page. Likely as not, though, you'll get a screen remarkably similar to the one in the following figure. You guessed it, that means you've hit the bug.
Stop the TolaActivity server
Open a MySQL shell and connect to the tola_activity database

Get the id of the record Google OAuth added to the TolaActivity user table:

mysql> SELECT id,username,first_name,last_name FROM auth_user;
+----+----------+------------+-----------+
| id | username | first_name | last_name |
+----+----------+------------+-----------+
|  1 | kwall    | Kurt       | Wall      |
+----+----------+------------+-----------+

Note the value for id to use in the next step.

Insert the id value from the auth_user table into the user_id field of the workflow_tolauser table:

INSERT INTO workflow_tolauser (name, privacy_disclaimer_accepted, user_id) VALUES (YOURNAME, 1,1);

Restart the Tola Activity server

$ python manage.py runserver
Performing system checks...

System check identified no issues (0 silenced).
March 26, 2018 - 23:38:10
Django version 1.11.2, using settings 'tola.settings.local'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.

Refresh the browser window and you should be at the logged in and immediately redirected to the TolaActivity home page
Rejoice!

Loading demo data

Get a recent dump from the demo instance from someone
Kill the TolaActivity server
Make a backup of the current tola_activity DB if it's precious

Drop and recreate the tola_activity DB:

DROP DATABASE 'tola_activity';
CREATE DATABASE 'tola_activity';

Execute the SQL script you were given to load the data:
```
$ mysql -u root -p tola_activity < demo_data.sql
```

bdylanwalker/TolaActivity