Table of Contents generated with DocToc
- Introduction
- Dictionary
- Domain Model
- Functional requirements
- Non-functional requirements
- Architecture
- Interface specification (Podio)
- Reports
- General requirements
- UC.3.1 Point distribution of all circles
- UC.3.2 Overall breakdown of circles’ Energy Points
- UC.3.3 Overall breakdown of roles’ Energy Points
- UC.3.4 Overall breakdown of basis points and cash assignment in EPA
- UC.3.5 Get a table of roles with energy points over X months for a given circle
- UC.3.6 Timeline of energy points for individuals, roles, or circles over a given time period
- UC.3.7 Chart for each Individual, showing what Circles/Roles give them the most BPs
- UC.3.8 Chart for each Circle, showing what Individuals give the circle the most BPs
The purpose of this document is to provide technical specification of Energy Points Application. The document sets the boundaries to the scope of application and describes all functional and non-functional (technical) requirements.
The content is intended to be entry point for any developer to start designing the technical aspects of application (database model, screens, screen flows, technology stack) and writing the code. But it is assumed that, during their work, developers will always cooperate closely with business users (people who will use the application) and agree with them any relevant details which are not covered by the document (user interface stuff like how exactly the screens should look like, colors, messages, labels, validations for particular fields, etc.).
Important:
The application described in this specification takes its origins from holacracy concept so it’s essential for anyone who reads this document to be familiar with it in first place. Following link is a good place to start:
https://hbr.org/2016/07/beyond-the-holacracy-hype
| Term | Definition |
| Energy Points Application (EPA) | Application which specification is described in this document. |
| Circle | In a holacracy, a group of Roles working toward the same purpose; in essence, a team that forms or disbands as the organization’s needs change. |
| General Company Circle | The only Circle not nested within another. It contains any other Circle and its sub-Circles. |
| Role | In a holacracy Circle, a set of responsibilities for a certain outcome or process. Roles can be created, revised, or destroyed; Individuals usually have more than one, in multiple Circles. |
| Individual | Member of the organization that can belong to one or more circles. |
| Energy Point | During Tactical Meetings Energy Points are assigned to Roles and Circles. The more points the more role is energized by its contributor (the more effort he/she put in it). |
| Tactical Meeting | Meeting held periodically, once a month, which gathers all Individuals that belong to the given Circle. During the meeting they discuss the work done and assign Energy Points to the Roles. |
| KPI | Key Performance Indicators are assigned to Roles and Circles. Based on the KPIs, the work of contributors to the Roles is assessed and exchanged to Energy Points. |
| Bonus | (optional) Financial compensation allocated to an individual based on his/her energy points relative to total energy points for a given time period. |
| Podio | Already existing application where the Organization Structures are created. Then it is imported into EPA. |
| Organization Structure (OS) | Organization Structure consists of Circles, sub-Circles and Roles. It changes once a month. |
-
Circle can have other Circles inside which are called sub-Circles.
-
Circle can have Roles inside.
-
Circle can’t have Roles and sub-Circles at the same time. If this is a case (Roles + sub-Circles) we handle it like for example in case of "Learning Space" Circle (refer to “July Circles” sheet in Structure and Strategy EP): Within “Learning Space” Circle we have 3 sub-Circles, including one called “Learning Space” again - this is the special sub-Circle dedicated solely for Roles of “Learning Space” Circle.
-
Individuals can belong to:
-
One or more Roles within Circle
-
Circle if he belongs to any Role within the Circle
-
Circle if he belongs to any Role within any of its sub-Circles at any level downwards the hierarchy.
-
-
Tactical Meetings are held for each Circle separately, starting from the lowest-level sub-Circles and going upwards.
Below please find the list of types of users that will interact with the system. It includes also external systems if there are any.
| Actor | Description |
| Standard User | Default role for any Individual in the organization. Can assign energy points for roles in the circles that he/she is a member of. |
| Lead Link | A Lead link can make changes to the circle(s) of which he/she is lead link, but not any others. This will be the user who holds Lead Link Role in given Circle. |
| Member of X Role | Depending on a Role in a Circle that Individual holds, he can have certain privileges. |
| Administrator | Manages the whole Organization Structure. This will be the user who holds one defined Role (Lead Link) in "Structure & Strategy" or the “GCC” Circle. |
| Technical Administrator | This is built-in role in EAP, it has nothing to do with Organization Structure. It’s always present and assigned to at least 2 people. |
This process is run every month. It populates Energy Points application with current Organization Structure for previous month. Then users of the application populates it with relevant data (Energy Points).
Prerequisites: Files with OS structure from Podio
Main scenario:
-
Technical Administrator uploads files with OS structure.
-
Automatic validation is performed:
-
whether structure is not broken (no disconnected Circles)
-
whether all Circles have Lead Links
-
-
The uploaded OS is displayed on application screen.
-
The uploaded OS has status "New".
Alternative scenario:
-
Technical Administrator uploads files with OS structure.
-
Automatic validation is performed
-
Validation fails.
-
Log message with details (why failed?) is displayed to Administrator.
-
OS is not loaded.
Example of loaded OS:
Prerequisites: OS with status "New".
Main scenario:
-
Administrator displays OS.
-
Administrator validates OS (manually checks if import succeeded).
-
He defines "Threshold" and “Total Relative Points” values for Roles and Circles.
-
He defines whether the "Thought Leader" feature is active.
- If active, he defines whether during assigning of energy points (B1.1) users can see all others’ points, or just see selected "Thought Leaders".
-
He can mark some Roles as not energised.
-
After making any needed changes he marks OS as "Validated".
-
Constraint: There can’t be more than 1 OS with status "Validated" at any time.
Alternative scenario:
-
Administrator displays OS structure.
-
He comes to conclusion that OS structure is invalid.
-
Administrator delete OS structure so it can be revised and imported once again from Podio.
Example of OS:
Prerequisites: OS with status "Validated".
Main scenario:
-
All Individuals can browse all Circles they belong to.
-
Lead Link of the Circle can mark some Roles as not energised.
-
Any Individual can change assignments of weights to Role in a Circle, that is:
-
By default there is an assumption that everyone in a given Role contributes to it equally (so weight for each member is the same and equals: 1 divided by number of members for the Role).
-
Any Individual can change the mentioned default assignment, for example he can decide that contribution of one member is 80% and the second one is 20%. The final decision about assignment belongs to Lead Link.
-
Weights for the Role must sum up to 100%.
-
-
After making any needed changes Lead link marks Circle as "Active".
Prerequisites: All Circles and Roles have assigned EPs.
Main scenario:
- GCC Lead Link sets global value: "Total amount to be paid". This is used in report module.
Prerequisites: All Circles and Roles have assigned EPs and "Total amount to be paid" value is set.
Main scenario:
-
Administrator changes status of OS to "Finished".
-
Data from OS is now available in reporting module.
Prerequisites: Circle with status "Active" and contains Role(s).
Main scenario:
Remark: The whole scenario usually takes place after the meeting of the whole team is held (all members of the Circle). The purpose of the meeting is to discuss how the Roles were energised.
-
Standard User browses OS.
-
He assigns Energy Points to all Roles in the Circle.
-
Energy Points he assigns for Roles in given Circle have to add up to "Threshold" value (suggestion: we should have toggles here with sliders that people can adjust as well as numbers that can be changed manually or toggled up/down).
-
He can see allocation of EP made by other users (but can’t change it).
Prerequisites: All Energy Points for Roles are assigned.
Main scenario:
Remark 1: The whole scenario usually takes place after the meeting of the whole team is held (all members of the Circle). The purpose of the meeting is to share the metrics and KPI’s of the Circle to know how much effort was put or the value created by the Circle.
Remark 2: Assigning EP is started from the bottom of the hierarchy (leaf) and goes up to (GCC).
-
All Individuals assign EP to Circles they belong to. Important: assigning takes place only on Circle level, not for Roles within Circles.
-
Energy Points assigned to given Circle have to add up to "Total relative points" value.
-
All Individuals can see allocation of EP made by other users (but can’t change it).
Description: This is the main screen that is visible to Standard User just after entering the application. It consists of:
-
Short statistics about number of Circles and Roles Standard user belongs to (in current "Validated" OS).
-
List of all Circles Standard user belongs to. For details please see UC.2.
-
Link to screen with reports
Main scenario:
-
User enters Dashboard screen.
-
User starts UC.2.
Alternative scenario:
-
User enters Dashboard screen.
-
User starts UC.3.
Description: Standard user can browse the whole OS which is in "Validated" status. All information for OS, if not stated otherwise elsewhere, is visible to Standard user (that is for example: who is member of what Role).
Standard User uses the list also for assigning Energy Points. For details see B1.1.
Main scenario:
-
User enters Dashboard screen.
-
User sees the OS with all information.
Description: Standard User has access to several types of reports. All of them are described in detail in another section of the document.
Description: All Individuals including Standard Users before using EPA must log in to it, using credentials (login + password) supplied by Administrator. After first login, or after login with password changed by Administrator for any reason, password must be changed by Standard User.
Main scenario:
-
User enters Login screen.
-
User enters credentials
-
User is successfully logged into application.
-
User is redirected to UC.1.
Alternative scenario:
-
User enters Login screen.
-
User enters wrong credentials
-
User gets information that login attempt failed.
-
User can try to log in once again.
-
If user fails to log in three times in a row - he gets form which he can fill in and ask administrator for new password.
Lead Link can perform at least the same actions as Standard user + any other that is specifically attributed to him in the processes’ description (like UC.B1.3).
Administrator can perform at least the same actions as Lead Link + Member of X Role + any other that is specifically attributed to him in the "Business processes" section.
Description: This functionality relates to adding/editing/blocking Individuals that can use EPA.
Main scenario:
-
Technical Administrator enters screen for managing Individuals.
-
He can add new Individual. To that end he:
-
Provides unique "login"
-
Provides password. Password needs to be changed by Individual during first login.
-
Provides "Podio name" for Individual (like: “Jay Larson”). Based on that matching is done when files from Podio are imported. Matching is needed to match Roles/Circles (from Podio) to Individual (from EPA).
-
Alternative scenario:
-
Technical Administrator enters screen for managing Individuals.
-
He can see all Individuals that can or could use EPA.
-
He can select one/many Individuals and block/unblock them (blocked Individual can’t login to application).
Alternative scenario:
-
Technical Administrator enters screen for managing Individuals.
-
He can see all Individuals that can or could use EPA.
-
He can click Individual to see detailed information for that Individual.
-
From there he can:
- Change password for Individual. New password needs to be changed by Individual during first login.
Prerequisite: Feature of defining "Thought Leaders" must be switched on for OS by Administrator.
Main scenario:
-
On "UC.2 Browse Circles" screen user can check/uncheck “Is Thought Leader” flag for each member of the Circle .
-
Lead Link is automatically checked as "Thought Leader".
| no | Description |
| 1 | All actions in EPA should be accessible as links/buttons (for example: to assign EP for Circle we need to click at Circle link and it points us to proper form). There should be no need to enter any commands (like in terminal windows). |
| 2 | There shouldn’t be the need of too much navigation within EPA. Ideally the whole process of assigning EP should take place on one screen. Using application should be as simple as possible. |
| 3 | Technology stack: Web Client (browser): Google Chrome (min. 53.0), Safari (min. 9), Firefox (min. 47), IE (min. 9) Web Client (technology): HTML 5, CSS 3, Angular 2 Backend (Technology): PHP, Apache, Ubuntu Database: MySQL, Ubuntu |
| 4 | Before entering EPA any Individual must log in to it. Administrator creates users/passwords, but roles for current month are based on PODIO. |
| 5 | There must be the possibility to run the app in more than one location at the same time. Each location uses its own instance of the app and there is no guarantee that there is a working network connection between them. There should be the way to synchronize these instances manually (triggered by Administrator) and automatically (every X hours). Below you can find example of how it was already implemented for other application used in Tunapanda: https://github.com/tunapanda/wp-remote-sync |
Web application will be created using Single Page Application architecture pattern.
Organization Structure is loaded from two files generated from Podio (details described as part of B1 business process). The structure of the files is the following:
The above files are what the EPA should expect as input. However, they will be provided as CSV files not in XLSX binary format.
Currently, files generated from Podio, are transformed into temporary format which contains only needed information from EPA perspective:
And then loaded using scripts to WorkBook. Final version of the workbook can be check out here (July Circles and July Roles sheets are relevant):
The whole process (loading XLSX files, filtering out only needed information and loading into EPA) should be automatic.
-
Reports are generated for every OS in "Finished" state.
-
All reports accessible from "Reports" screen (UC.3) as links to specific reports.
Main scenario:
-
Report is generated for GCC and its sub-circles.
-
User can click on any sub-circle and the same report is generated for that sub-circle together with all sub-circles of sub-circle.
-
Reports are shown in the form of the pie chart.
Point distribution of all circles
Main scenario:
-
User can select appropriate OS and click "Generate report" button.
-
Report for given OS and all its Circles is generated.
Example of generated report for one Circle (this was taken from September Circles, Structure & Strategy EP) :
Overall breakdown of circles’ Energy Points
Prerequisites: UC.3.2 calculations should be made first.
Main scenario:
-
User clicks link with Circle which contains Roles.
-
Report for given Circle and all its Roles is generated.
Example of generated report for one Circle is provided below (it was taken from September Roles, Employment Circe, Structure & Strategy EP). Employment Circle got 6412 points to distribute. Process of distribution of points between Circles is described in UC.3.2.
Overall breakdown of roles’ in Energy Points
Prerequisites: UC.3.3 calculations should be made first.
Main scenario:
-
User can select appropriate OS and click "Generate report" button.
-
Report for given OS and all its Circles is generated.
Algorithm for generating the report:
-
For every Individual in OS (like: Jacky Kimani) go down to the level of Role he/she is assigned to. In report UC.3.3 it’s Employment Circle, "Lead Link" Role (there are more Roles Jacky is assigned to but we go one by one).
-
Take value of "%" column for the Role (11,43%) and multiply it with weight value assigned to Jacky Kimani for that Role (weight can be for example: 80%).
-
The outcome from point above multiply by "%" assigned to Employment Circle (28,89%).
-
Go up the hierarchy and multiply the value with "%" assigned to Circle that contains Employment Circle (Positioning Strategic Grouping Circle in our case - 22,20%). Finish when GCC is reached.
-
Repeat 1-4 steps for every Role for given Individual and sum up all values from step 4.
-
The outcome in step 5 is "Proportion" value for one Individual. Now it should be repeated for everyone.
-
Multiply "Proportion" value with money that is to be distributed between members of OS for given month (19,778 in our example). In such a way you get “Bonus” value.
Example of calculations for September OS (weight for this calculations is assumed to be equally distributed between Circle members, that is weight for each member = 1/number of members):
| Name | Proportion | BPs | Bonus |
| John Gitonga | 0.1075 | 1075 | 2,126 |
| Susan Nempiris | 0.0114 | 114 | 225 |
| Dennis Lighare | 0.0198 | 198 | 391 |
| Patrick Gichini Waruingi | 0.0245 | =Proportion * 10000 | 484 |
| Fredrick Odhiambo | 0.0342 | =Proportion * 10000 | 676 |
| Mwalugha Bura | 0.0377 | =Proportion * 10000 | 746 |
| Kelvin Mungai | 0.0179 | =Proportion * 10000 | 353 |
| Jacky Kimani | 0.0335 | =Proportion * 10000 | 663 |
| Cetric Oyavo | 0.0049 | =Proportion * 10000 | 96.2 |
| Luka Sopia | 0.0372 | =Proportion * 10000 | 736 |
| Onesmus Muturi | 0.0499 | =Proportion * 10000 | 987 |
| Zahra Ismail | 0.0303 | =Proportion * 10000 | 600 |
| Josephine Miliza | 0.0488 | =Proportion * 10000 | 964 |
| Renice Owino | 0.0248 | =Proportion * 10000 | 490 |
| Minzilet Ijai | 0.0215 | =Proportion * 10000 | 426 |
| Jay Larson | 0.0609 | =Proportion * 10000 | 1,205 |
| Mick Larson | 0.0484 | =Proportion * 10000 | 957 |
| James Otieno | 0.0354 | =Proportion * 10000 | 699 |
| Elias Kinyua | 0.0345 | =Proportion * 10000 | 682 |
| Nixon Kanali | 0.0551 | =Proportion * 10000 | 1,089 |
| Elizabeth Ochieng | 0.0364 | =Proportion * 10000 | 719 |
| Dickson Morande | 0.0144 | =Proportion * 10000 | 284 |
| Maureen Moraa | 0.0147 | =Proportion * 10000 | 291 |
| Jackyletty | 0.0337 | =Proportion * 10000 | 667 |
| Michael Okiri | 0.0042 | =Proportion * 10000 | 83.8 |
| Anne Nyokabi | 0.0681 | =Proportion * 10000 | 1,348 |
| Wendy Mwangi | 0.0106 | =Proportion * 10000 | 209 |
| Mohammed Dena | 0.0295 | =Proportion * 10000 | 583 |
| cecilia wangui mukima | 0.0261 | =Proportion * 10000 | 516 |
| Wambua Mutunga | 0.0228 | =Proportion * 10000 | 450 |
| Mikael Lindqvist | 0.0000 | =Proportion * 10000 | 0 |
| Mia Tengco | 0.0015 | =Proportion * 10000 | 29.8 |
| Total Amount to be paid | 1.0000 | 19,778 |
Remarks:
-
Only "BPs’ and “Bonus" columns should be visible for users.
-
"Proportion" column is included for the sake of clarity but should not be shown to users.
-
"Total Amount to be paid" is manually entered in the EPA.
Main scenario:
-
User selects Circle for which report is generated.
-
User enters the number of months for which report is generated.
-
Report is generated for a given period and Circle. It shows a table with the following columns: Role, % of the total (energy points for the Role for given period / energy points for all Roles for given period within Circle), percent change of EP (positive or negative) between first and last month in the period for which points are calculated. All columns are sortable. Energy points for Roles are taken from "Total" column for each Role for given Circle (for example: Overall breakdown of roles’ in Energy Points, Secretary = 27)
Main scenario:
-
User can enter type of report (Individuals/Roles/Circles) and period (3 months/6 months/ 1 year/ other)
-
Report is generated in the form of timeline.
-
The following values are taken into consideration when the report is generated:
-
Circles - "Total" column for given Circle
-
Role - "Total" column for given Role
-
Individual - For each Role Individual belongs to, "Total" column for that Role divided by number of people within the Role, then sum up all values.
-
Main scenario:
-
User selects Individual for whom the report is generated.
-
User selects whether BPs should be aggregated by Circles or Roles.
-
By default BPs are calculated according to algorithm from UC.3.4 (we start at Role level and then go up the hierarchy until we reach GCC). But user can additionally select whether BPs calculation stops at any level of the OS hierarchy (at any intermediate Circle).
-
User selects OS.
-
Report is generated in the form of sortable table with the following columns: Role/Circle, Total BPs earned.
Main scenario:
-
User selects Circle for whom the report is generated.
-
User selects OS.
-
Report is generated in the form of sortable table with the following columns: Individual, Total BPs provided.