aptivate / kashana

Aptivate logframe django project

Kashana

Kashana is an open source logframe management tool for planning and evaluating projects, used and written by Aptivate.

Contents

• Installation
  • System requirements
  • Prerequisites (Ubuntu)
  • Downloading the source code
  • Setting up a development environment
  • Running a local development server
  • Setting up data
  • Deployment with fabric
  • API
  • Running Javascript tests
• Use cases

Installation

System requirements

• POSIX-compliant system (tested on Linux)
• Python 2.7
• Node JavaScript platform
• Apache + WSGI (for production)
• MySQL
• Recommended at least 1GB of RAM

Prerequisites (Ubuntu)

sudo apt-get install python-virtualenv nodejs npm python-git python-pip mysql-client libmysqlclient-dev

Downloading the source code

git clone https://github.com/aptivate/kashana.git

Setting up a development environment

In the deploy directory, run:

./bootstrap.py
./tasks.py deploy:<environment name>

<environment name> refers to one of the local_settings.py.* files under django/website directory. These contain, amongst other things the details for the MySQL database. So to deploy the dev environment you would enter:

./tasks.py deploy:dev

This script wants to create a MySql database. DYE's MySql database manager assumes your MySQL root password is in /root/mysql_root_password; this task will ask for a sudo password in order to access this file.

Running a local development server

Run local development server with ./manage.py runserver

Setting up data

1. You'll need to create a superuser to access the Django admin interface at eg http://127.0.0.1:8000/admin/

   cd django/website
   ./manage.py createsuperuser
   

2. You'll need to create a Log frame (eg http://127.0.0.1:8000/admin/logframe/logframe/add/).

3. You'll need to add some entries to the (RAG) Ratings table. A bug prevents these being created in the admin interface but you can update the table with MySQL:

   cd django/website
   ./manage.py dbshell
   
   mysql> INSERT INTO logframe_rating (name, color, log_frame_id) VALUES('On track','green',1);
   

   etc

   where the 1 is the ID of your logframe

   You can rate results and indicators

4. You can add Risk ratings through the admin interface (eg http://127.0.0.1:8000/admin/logframe/riskrating/add/). These have a name like Low, Medium, High

5. For setting the reporting intervals, add Milestones for your LogFrame (eg http://127.0.0.1:8000/admin/logframe/milestone/add/).

   These have a name eg Baseline, Y1, Y2, Y3 or Baseline, 2017, 2018, 2019 and a date.

   You are not tied to years - you can specify any kind of time period. Now you can add targets for Indicators.

6. Now you can add Results via the dashboard. (e.g. http://127.0.0.1:8000/dashboard/) The first couple of levels of the results hierarchy have only one entry. These are usually:

   1. Impact/Goal
   2. Outcome

   The next two levels can have many items:

   3. Output
   4. Sub-output level

   If you expand the tree beyond this level, you're adding Activities.

7. You can add TA (Technical Assistance) Types (e.g. http://127.0.0.1:8000/admin/logframe/tatype/add/) and Activity Status codes (e.g. http://127.0.0.1:8000/admin/logframe/statuscode/add/)

Deployment with fabric

We have created deployment scripts using fabric to make it possible to deploy to a remote server with ssh access.

You will need to add a named entry to host_list in deploy/project_settings.py (see production for an example)

You will need a settings file with the same name, for example django/website/local_settings.py.production

and a config file under the apache directory (see apache/production.conf)

Then under the deploy directory you would do:

./fab.py production deploy

replacing production with the name you specified previously

API

All URLS except creation are /logframes/<logframe_pk>/<itemtype>/<item id> URLS for creation are /logframes/<logframe_pk>/<itemtype> Actions determined by request type:

PUT = update
DELETE = delete
POST = create

The code to get the logframe exists in logframe.views.OverviewMixin. It's a method called get_logframe.

The code for the backend that does the work on the logframe lives under django/website/logframe/api.

Running Javascript tests

If you are using recent Ubuntu, then install npm which will also install nodejs. Because of a name conflict with another package it will be named nodejs instead of node, so you will have to create a symlink yourself (assuming you don't have amateur radio node package installed):

sudo ln -s /usr/bin/nodejs /usr/local/bin/node

We'll need phantomjs to run tests:

sudo npm install -g phantomjs
sudo npm install -g grunt

Install local dependencies by switching to directory alfie/javascript and running:

npm install

This will install all the necessary packages including Gulp which we use for defining and running tasks. Currently following tasks are defined (and at least somewhat useful):

grunt test (runs tests)
grunt jshint (checks code with JSHint)
grunt templates (compiles templates to src/lib/templates.js)
grunt watch (runs JSHint and compiles templates when either change)

Use cases

1. A multi-stakeholder and multi-organisation team operates in dozens or hundreds of villages and urban areas across Zambia. They need Android-based support to coordinate their work. They are assessing well-being, using ODK or similar on their tablets / phones. They may also be coordinating the delivery of some services -- perhaps health education, for example. They may be helping people to fill out forms to apply for various types of aid, or to register for different relations with the government bureaucracies. They need to have a well-being assessment tool that tracks the impact of their work and the work of the other development agencies in the area. How do they coordinate their activities? How do they collaborate? How are their documents hosted? Could Kashana be all or part of the solution?
2. Let us imagine that an organisation gets a grant to work with us and their Ghanaian chapter. They would like to provide an inexpensive tool for coordinating the work of their Ghanian chapter via mobile phone or very inexpensive tablet. They also need to show their donors / funders that their work in promoting local participation in Ghana is improving local life outcomes. If Kashana is to help, it needs to provide a way of assessing life impacts (or tracking life impact assessments) as well as coordinating local activities (tasks, calendar, etc. for local teams and a coordinating group).
3. We have a financial tracking system called CASH. The people using CASH want to know how money will be divided up between the different elements of the logframe, and also between the different people who are responsible for spending the money. They are only slightly concerned about tracking impacts within CASH -- as long as the money gets spent and they know what they have to do in order to effectively use their whole budget, they are happy.
4. Various triple-bottom-line companies want to keep track of key performance indicators (outputs) as well as the social and environmental impacts of their work (outcomes), in a way that integrates with their daily work. Kashana might give those small and medium-size ethical businesses a way to manage their workflows and their policies at the same time as tracking impact, in a way that makes it easy to learn and steer. Having a simple way to connect the outputs (what the business is selling) to impacts (of various kinds) within a shared collaboration-support environment (Kashana, the intranet) can let those businesses see what's going on with a minimum of switching back and forth between a dozen different applications or interfaces. Also, it can reduce the need to enter data multiple times.

kashana's Issues

Ability to collapse/expand TA and Other Budget sections

Provide ability to collapse/expand TA and Other Budget sections in Activity form. This is important where you have too many entries in each section or you are not using one of the sections, in which case you would rather have it collapsed or even hidden.

Add 'quantity' and 'unit price' for Other budget

Add 'quantity' and 'unit price' for 'Other budget' line item. This will make budgets data entry more flexible and will support reporting

Add Blue color code for Ratings

Add blue color as one of the ratings colors so that we can use the extended RAG+B system where:

R - Off track (Bad)
A - At risk (Just Ok)
G - On track (Good)
B - Exceed (Super)

How do I restrict user/group access to a particular result area?

How do I restrict user/group access to a particular logframe result area?

Update to run on Python3

Hello. I am a trial user of kashana and I was wondering, is there a plan to update the codebase for Python 3 as Python 2 is no longer supported?

Added risk ratings not showing in UI

I added risk ratings (Low, Medium, High) using the admin section, but they are not appearing in the front-end user interface.

Dockerfile or image for Kashana?

Hi all,
I'm just starting to experiment with Kashana and am having a go at building a Docker image from the git hub readme installation instructions.
So far, it fails at the bootstrap.py stage, but I'll persevere and make the Dockerfile available if anyone would like it.
Has anyone else used Kashana with Docker? If so please can you share your Dockerfile or image ?
Has anyone recently been through the installation in structions with a vanilla ubuntu install, as the virtualenv is currently failing.
Thanks,
Jason

Installation video

We've had a couple of requests for a how-to video for installing Kashana

There are no logframes for me to view.

I just tried to do a brand new deploy:dev on master.

Created a user with manage.py createsuperuser. There were no logframes for me to view. Looks like a default logframe should be created but the dashboard shows me no logframes.

Provide total budget figure at each level

Provide total budget figure for the whole activity i.e. TA + Other budget.
Also provide cumulative total budget at each result area level.

History and comments

When will you implement this feature in your roadmap?
"History and comments – so you can remember how and why you changed your plan"

Deployment with Fabric fails

Hey guys,

I am trying to deploy the the Kashana App via SSH to a remote server.
I followed the instructions in the documentation and created the respective configurations, however the deployment stops in its tracks pretty early with:

Fatal error: Incompatible ssh peer (no acceptable kex algorithm)
Underlying exception:
Incompatible ssh peer (no acceptable kex algorithm)
Aborting.

I attempted to fix this by adding a respective conf file in the ssh config and by updating fabric/paramiko(both in the ve and globally) as github recommends, but it did not work for me.

Can you recommend anything else? Thanks for your help!

How to deploying Kashana with apache2 Webserver

Kindly help me to deploy Kashana to production instance with Apache webserver. I managed to deploy a dev instance using the inbuilt webserver, but having challenges setting production instance. I've installed Kashana on a AWS cloud virtual machine. I copied the production.conf file in apache subfolder to /etc/apache2/sites-available and adjusted some paths there to match my Kashana root folder which is /opt/kashana/
I also allowed access to ports 80, 443 & 8000 in AWS for my server host.
When I try to access the host I get the error below:

---

Forbidden
You don't have permission to access / on this server.

---

Monthly report

Can you provide a monthly report in addition to quarterly and annual reports

Installing Kashana

Does anyone has made already a video for installing kashana ? Or is it anyone able to help me install it ?

Help with making changes to the "Indicator" Structure

Hello, I am not sure wether this is the right channel, but I am trying to develop a fork of Kashana that integrates some changes for the NGO "Aktion Sodis" from Germany. However, I encounter many difficulties in making changes in the codebase and seeing any kind of outcome from them. I know this is a very broad question, but maybe someone could get in touch with me and try to help me out with understanding the project structure in general?

A short overview of the goal:
For starters, I basically want to clone the "Source:" textfield in the Indicator, rename it to "Questions", and add it to every indicator.

What I already did:
-added it to the logframe/models.py
-added it to the .CSS and SCSS files
-added a handlebar-template in the JS templates

• added the editable-text to the static/js/views/indicator/container.js

I have seen models added in the migration-files, and reloaded the static files and cleaned the cache from my browser.

The problem:
Changes do not present themselves, not even simple changes in the handlebar-templates (eg. changing the default text for the Question-textbox).

Thanks for your help in advance!

Bad request 400

Hi,

I'm getting a Bad request 400 message when I navigate to http://127.0.0.1:8000/
I've installed it on a Ubuntu machine on DigitalOcean.

$ ./manage.py runserver
Performing system checks...
System check identified no issues (0 silenced).
August 31, 2017 - 04:00:35
Django version 1.8.18, using settings 'settings'
Starting development server at http://127.0.0.1:8000/
Quit the server with CONTROL-C.
[31/Aug/2017 04:00:45] "GET /dashboard HTTP/1.1" 400 26

Re-write javascript tests to make meaning clearer

After the code review with @daniell I'm trying to understand the meaning of these tests. The assertioncount isn't counting assertions, its just counting the elements of the generated list of elements that satisfy some conditions.

If we look at the setup:

    var ids = ["1", "2", "3"],
            models = _.map(ids, function(n){return {id: n};}),
            MyListView = AddOneList.extend({
                itemView: BB.View.extend({
                    render: function(){
                        var content = this.model.get('id') || "empty";
                        this.$el.html(content);
                    },
                }),
            });

... then clauses like this make a bit more sense:

        it("Blank element if max size not yet reached", function() {
            var listView = new MyListView({
                maxLength: 4,
                collection: new BB.Collection(models)
            });
            listView.render();

            var assertionCount = 0;
            listView.$el.children("div").each(function (i, el) {
                var contents = $(el).html();
                if (contents==="empty") {
                    expect(true).toBe(true);
                    assertionCount++;
                } else if (contents === "") {
                    expect(false).toBe(true);
                } else {
                    expect(_.contains(ids, contents, "ID rendered is from list")).toBe(true);
                    assertionCount++;
                }
            });
            expect(assertionCount).toEqual(4);
        })});

What we'er doing here is looking at the output of a rendered list view with the model ["1", "2", "3"]. This should contain four divs containing "1", "2", "3", and "empty" -- because that' show the blank element gets rendered. And none of those divs should be properly empty (none of them have content = ""). I think we can do much better.

I'm thinking instead of .each() we could use .map() to project a list of the contents of the list of divs, and then make some simpler assertions about those:

• there should be four elements: "1", "3", "3", "empty", and no empty elements.

something like this??...

contents = listView.$el.children("div").map(function(){ return this.html(); })
expect(contents.get().join()).toBe("1,2,3,empty")

No way to order results in the frontend

I'm trying to change the order of activities or result area entries but it is not working. I'm doing that in the backend by change the value of the 'Order' field. It would nice if you can provide drag-and-drop visual ordering in the front-end (Dashboard)

Automatically set the activitiy status based on activity's start and end dates

Can the status of an activity be automatically set based on the activity's start and end dates
Can the rating of the bottom-most level result area directly above the activities be automatically set based on compound status of the activities below it.
Can the rating of the other result area levels be automatically set based on the ratings of the result area levels below it.

Mobile data collection with WQ.io?

Integrating mobile data collection through ODK etc. might be a really good idea, but I guess it would be much easier and potentially better to integrate a mobile data collection framework that is also based on Django?
See: https://wq.io/

The resulting mobile apps run with Cordova (or in the browser), which might also allow to integrate some more features from Kashana directly in the app.

Last but not least they have a forms converter from ODK:
https://github.com/wq/xlsform-converter

How to align Kashana year to a financial year starting month of October

How to I setup Kashana such that the project year starts in October and ends September and the Annual plan export report picks the correct year.

No UserPreferences created; logframe view crashes

I just did a new deploy:dev on master and, as there were no logframes (#21) I went over to /admin/logframe/logframe/ and created me one called test. Now I see it listed in the dashboard, but when I follow the link I get RelatedObjectDoesNotExist at /dashboard/test/.

Exception Value: User has no preferences.

You'd expect a user with no preferences would be easy to please.

Grepping for preferences in the source, I can't see anywhere where the preferences object gets created. Tests pass because the user object is mock.Mock()

And I suspect local user testing worked because a pre-existing user in the database got preferences added by the migration

But I can't see any code to create a preferences object for a new user.

Request Method: GET
Request URL: http://127.0.0.1:8000/dashboard/test/

Django Version: 1.8.13
Python Version: 2.7.11
Installed Applications:
('django.contrib.auth',
 'django.contrib.contenttypes',
 'django.contrib.sessions',
 'django.contrib.sites',
 'django.contrib.messages',
 'django.contrib.humanize',
 'django.contrib.staticfiles',
 'django.contrib.admin',
 'rest_framework',
 'django_tables2',
 'jstemplate',
 'django_extensions',
 'django_assets',
 'floppyforms',
 'rest_framework_nested',
 'main',
 'logframe',
 'contacts',
 'dashboard',
 'appconf',
 'export')
Installed Middleware:
('django.middleware.common.CommonMiddleware',
 'django.contrib.sessions.middleware.SessionMiddleware',
 'django.middleware.csrf.CsrfViewMiddleware',
 'django.contrib.auth.middleware.AuthenticationMiddleware',
 'django.contrib.messages.middleware.MessageMiddleware',
 'django.middleware.clickjacking.XFrameOptionsMiddleware')


Traceback:
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/django/core/handlers/base.py" in get_response
  132.                     response = wrapped_callback(request, *callback_args, **callback_kwargs)
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/django/views/generic/base.py" in view
  71.             return self.dispatch(request, *args, **kwargs)
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/braces/views.py" in dispatch
  107.             request, *args, **kwargs)
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/django/views/generic/base.py" in dispatch
  89.         return handler(request, *args, **kwargs)
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/django/views/generic/base.py" in get
  158.         context = self.get_context_data(**kwargs)
File "/home/mark/workspace/kashana/django/website/logframe/mixins.py" in get_context_data
  80.         lf = self.get_logframe()
File "/home/mark/workspace/kashana/django/website/dashboard/mixins.py" in get_logframe
  27.         logframe = user.preferences.last_viewed_logframe
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/django/utils/functional.py" in inner
  226.         return func(self._wrapped, *args)
File "/home/mark/workspace/kashana/django/website/.ve/local/lib/python2.7/site-packages/django/db/models/fields/related.py" in __get__
  480.                     self.related.get_accessor_name()

Exception Type: RelatedObjectDoesNotExist at /dashboard/test/
Exception Value: User has no preferences.

How to remove(delete) TA/Other Budget entry?

Provide a way to delete a TA or Other budget entry from Activity

popup says "setup milestone first" when trying to monitor an indicator

Set two milestones for a log frame for 1st Jan 2018 and 1st April 2018
Create an indicator with those milestones
If you then try to monitor this indicator, you get a popup that says "setup milestone first"

Cloning activity and its child nodes

Provide a way to clone an activity and its child nodes to make it easy to capture multiple similar activities being done at different time periods or different locations

Add "Other budget" types

Add "Other budget" types, in the same way we have TA types. This will help to group other budget lines and associate each category with a budget code from Financial system for example. Provide free-text field to enter budget code for each budget type.