diff --git a/README.md b/README.md index a7c5a6b..7cdcd9c 100644 --- a/README.md +++ b/README.md @@ -6,13 +6,14 @@ # RSE Administration Tool This is a tool for tracking grant applications, managing RSE commitment and reporting on staff expenses and cost recovery. -The site has two users types (Admin and RSE) which have different levels of permissions. RSE users can view, edit and create projects as well as see allocations to projects based on effort (i.e. days). Admin users are able to create allocations on projects (allocated by effort or budget) and view reports on group finance and staffing. -There is a distinction between Allocated Projects (i.e. Directly incurred projects) where staff generate overheads for the university and Service Projects which are effort based and generate overheads for the group or facility. The tool is a web app written using the [Django][django] web framework (Python) and the [AdminLTE][adminlte2] theme. +This readme covers installation, getting started and access to the demo site. Please refer to the [User Guide][userguide] documentation for a description of features. + ## Development install using Poetry + To develop or test the site locally Poetry is used for dependency management. The ideal is that Poetry is simpler than using [conda][conda] and avoids manually creating a [virtualenv][virtualenv]. To configure Poetry; 1. Ensure you have Python >= 3.6 installed @@ -183,3 +184,4 @@ A [separate repo is available](https://github.com/RSE-Sheffield/rseadmin-ansible [django]: https://www.djangoproject.com/ [virtualenv]: https://virtualenv.pypa.io/en/latest/ [poetry]: https://poetry.eustace.io/ +[userguide]: https://rseadmin.readthedocs.io/en/latest/ diff --git a/docs/conf.py b/docs/conf.py index 447b711..5cc153b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -31,6 +31,7 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ + 'sphinx.ext.autosectionlabel' ] # Add any paths that contain templates here, relative to this directory. @@ -55,4 +56,10 @@ html_static_path = ['_static'] # Set the master doc to index (default on read the docs is contents) -master_doc = 'index' \ No newline at end of file +master_doc = 'index' + +# define a custom raw html role +rst_prolog = """ +.. role:: raw-html(raw) + :format: html +""" \ No newline at end of file diff --git a/docs/financialyears/index.rst b/docs/financialyears/index.rst new file mode 100644 index 0000000..aebcd08 --- /dev/null +++ b/docs/financialyears/index.rst @@ -0,0 +1,21 @@ +Financial Years and Salary Grade Points +======================================= + +A financial year represent a finical time period between 1st August to the 31st July. From the 1st August each year, universities adjusts all salaries according to inflation and as such new salary data is published for each finical year. Salary data is required before adding any RSE users as RSE users are required to have a starting salary. + +The RSE Admin tool will use estimates for salary information based on an an inflation rate of 3% for future financial (where salary data is not known or released). The reporting views can provide a breakdown of how any costs are generated which will show where salary data has been estimated. + +Creating a Financial Years +-------------------------- + +A New financial year can be created by selecting **Admin->New Financial Year** from the sites main menu. If you have already created a financial year with salary data this salary data can be copied by choosing the year form the **Copy Salary Band Data from Financial Year** drop down box. Using the default empty value will create an empty financial year and redirects you to the edit financial years view. + +Adding Salary Data +------------------ + + +To view salary data for a financial year select **Admin->Financial Years** from the sites menu. The filter dialogue allows you to change which financial year you are viewing. The :raw-html:`` icon can be used to edit the salary band data of the financial year. + +Salary data is constructed using a the grade point system where *Grade* represents a major change and *Point* represents a point scale within that grade. Within a Grade points may increment which indicates that staff employed at the grade point will automatically increase the point on the 1st January each year. For example an incrementing grade point of G1.1 would increment the following January to G1.2. A on incremental grade point would not change in January (unless a grade point adjustment was made to an RSEs salary see :ref:`Edit Salary Data `). + +From the the edit financial year view, grade points can be created and added using the *Add Grade Point* button where they will be instantly displayed. Grade points can be individually edited or deleted. To return to the financial year view (rather than edit) select the :raw-html:`` icon. diff --git a/docs/index.rst b/docs/index.rst index 91a42e7..cd0ef8a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,19 +1,21 @@ Welcome to RSEAdmin's documentation! ==================================== -.. toctree:: - :maxdepth: 2 - :caption: Contents: - - This is a tool for tracking grant applications, managing RSE commitment and reporting on staff expenses and cost recovery. The site has two users types (Admin and RSE) which have different levels of permissions. RSE users can view, edit and create projects as well as see allocations to projects based on effort (i.e. days). Admin users are able to create allocations on projects (allocated by effort or budget) and view reports on group finance and staffing. There is a distinction between Allocated Projects (i.e. Directly incurred projects) where staff generate overheads for the university and Service Projects which are effort based and generate overheads for the group or facility. The tool is a web app written using the Django web framework (Python) and the AdminLTE theme. +These documents provide an overview of the sites features. For notes on installation and access to demo site please see the `GitHub README.md `_ -Indices and tables -================== -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` +.. toctree:: + :maxdepth: 2 + :numbered: + :caption: User Guide + :hidden: + + financialyears/index + users/index + team/index + projects/index + reporting/index diff --git a/docs/projects/index.rst b/docs/projects/index.rst new file mode 100644 index 0000000..e087d9f --- /dev/null +++ b/docs/projects/index.rst @@ -0,0 +1,76 @@ +Projects and Allocations +======================== + +The RSE Admin tool makes a distinction between projects which are classed as service work (*Service* projects) and projects where staff time is costed onto a research grant (*Allocated* projects). Allocated projects represent staff time costed onto a grant at a percentage of an FTE which will generate an overhead (at a set annual rate) for the institution. Service projects projects represent a commitment in terms of number of RSE days at a set service rate. + +Service projects use the HEI `Transparent Approach to Costing `_ (TRAC) recommendation of 220 working days per year. As such a service project of 220 days represents a full year of RSE commitment and overhead rates should factor this into any calculation to cover staff time. Allocations for RSE staff on service projects are will apply the TRAC calculation to represent the actual (FTE equivalent) time period spent on a project (rather than just the number of service days). This way each allocation has a fair share of holidays and other non working days. Allocations of RSE time onto Allocated projects are always based on a percentage of FTE time and as such always represent the actual time period spent on a project. + +The site makes a distinction between effort and budget reporting on projects. Both forms of project generate an income but the level of staff commitment expected for each is different. I.e. A service project is expected to meet an effort commitment in terms of a number of staff days. Surplus income (day rate less the actual staff costs) will be accumulated as a result. Allocated projects are can be reported by either effort or budget. It is frequently desirable to over-commit staff to ensure that a staffing budget is completely spent. This is required when a project is costed with a higher grade point than the RSE assigned to it. The `Project Summary`_ view provides a summary of project commitment by either budget or effort. + + + +Creating Projects +----------------- + +Projects and clients can be created by either Admin or RSE users however only Admin users can create allocations of RSE effort onto projects. + +Creating Clients +~~~~~~~~~~~~~~~~ + +New projects require a client which is a named person from a department or institution. A new client can be created by selecting **Admin->New Client** from the main menu or by selecting the :raw-html:`` icon from the client drop down in the new project view. + +Adding a New Project +~~~~~~~~~~~~~~~~~~~~ + +A new project can be created by selecting **Admin->New Project** from the main menu. You will then need to choose between a *Service* or *Allocated* project type. + +An internal project represents a project which does not generate income but represents a specific commitment of time. E.g. A contribution in kind (from a core budget) of RSE time to support a research grant, development or delivery of teaching or another FATPOU activity. The *internal* option allows either allocated or service projects to be marked as internal. + +The forms for completing the project details differ depending on the project type. + +Allocated projects have a start date, and end date and a percentage of FTE RSE commitment which represents an expected unit of time in which the project will receive RSE support. The overheads rate is the pro-rata full time equivalent rate which is used to calculate any overheads returned to the institution for the staff time on this project. The salary band used for costing represents the salary used to calculate the cost of staff time on the project. + +Service projects have a start and end date which represents the tie in which a service project may be delivered. The start and end date do not dictate a specific time commitment but rather the range in which the *Number of Service Days* may be completed. The project date range must be at least the FTE equivalent of the number of TRAC service days. The *Charged to RSE account* indicates that staff time should be billed to an RSE account (i.e. the account which accumulated RSE service income at the specified *Service Rate*). Projects which are not billed to the RSE account will generate income but not result in staff time being allocated to any cost code via a staff cost distributions (see :ref:`Cost Distributions ` report). A Service project has an invoice received date which indicates the date in which money enters the RSE account. Not that this may be before or after staff time is changed back to the RSE account. Care should be taken to not span financial years with Service projects to avoid receiving income which is absorbed by the university at the financial year end when there are staff expenditures still to cover the following year. + + +Viewing Projects +---------------- + +A list of projects can be viewed by selecting **Team->Projects** from the main menu. Alternatively projects can be viewed in the client summary view by viewing the list of clients **Team->Clients** and selecting the *Info* button. The project list view can be filtered by type, status and schedule in either view. A clients details can be edited from the client summary view by selecting the :raw-html:`` icon in the *Client Details* box. + + +Project Summary +--------------- + +Selecting a project via the *Info* button on any of the project list views will give a project summary which consists of the following. + +- **FTE Commitment Overview :** This graph shows the allocation of staff effort on the project. Individual staff members can be toggled from the graph by clicking on their name in the figure legend. The red dashed line represents todays date. +- **Project Details Tabbed Summary :** This tabbed information box provides information about the project. The :raw-html:`` icon can be used to edit the projects details. +- **Effort and Distribution Summary :** This tabbed information box provides a summary of the effort and budget summary (Admin users only) of the project based off the allocations within it. The :raw-html:`` icon allows a detailed view (and option to edit) project allocations. The :raw-html:`` icon under the field *Total Staff Costs* provides a break down of how the staff costs have been generated (see :ref:`RSE Staff Costs Breakdown `). +- **RSE Allocations Gantt :** The gantt chart view presents an alternative view of the commitment overview, displaying allocation durations. The gantt percentages represent the percentage of FTE an allocation represents on a grant. + +Project Allocation Details +-------------------------- + +The project allocation details view can be accessed via the :raw-html:`` icon in the *Effort and Distribution Summary* box of the *Project Details* view. The view presents a breakdown of each RSE staff allocation and can be viewed by Effort or budget. Project allocations can be edited or created using the :raw-html:`` icon. + +Creating Project Allocations +---------------------------- + +The *Add an allocation* box will be pre-populated with the following information; + +- **Start Date :** Will be based of the start date of the project +- **End Date :** Will be based of the start date plus any remaining effort at FTE equivalent. +- **FTE Percentage :** Will be based off the FTE percentage used for Allocated Projects or 100.0% for service projects. + +The :raw-html:`` icon next the the RSE selection can be used to view the specific :ref:`RSE Commitment Overview ` of an RSE between the proposed allocation date range. By clicking this icon with no RSE selected a `Team Commitment Overview`_ will be presented between the proposed allocation date range. This is helpful in determining who is available to staff the allocation. + +If the start date or FTE percentage is modified then the :raw-html:`` icon can be used to calculate a new end date based off the remaining effort at FTE equivalent. For Allocated projects the :raw-html:`` icon can be used to calculate an end date from the project based off the selected RSE. + +Return to the `Project Allocation Details`_ view by selecting the :raw-html:`` icon or to the `Project Summary`_ by selecting the :raw-html:`` icon in the project details box. + + +Team Commitment Overview +------------------------ + +A Team and projects overview is available by selecting **Team->Team & Projects Overview** from the main menu. This view provides both a commitment summary view of RSEs allocations on projects ora gantt based view where allocations are grouped by project. Both views can by updated by changing the filters which allow the date range shown and funding states to be displayed. Within the *Commitment (RSE FTE)* tab individual staff members can be toggled from the graph by clicking on their name in the figure legend. The red dashed line represents todays date and the :raw-html:`` icon can be used to rescale the graph from 100% FTE to max (staff may be over committed on projects which are under review). diff --git a/docs/reporting/index.rst b/docs/reporting/index.rst new file mode 100644 index 0000000..c5f0f46 --- /dev/null +++ b/docs/reporting/index.rst @@ -0,0 +1,75 @@ +Reports +======= + +The RSE Admin tool provides a number of useful reports fro team administration. These are only available to Admin users (or RSE users with administrative privileges). + + +Cost Distributions +------------------ + +The cost distribution report provides a breakdown of staff time (as a percentage of their FTE) per project on the current date. Only projects which have a status of funded are included. Internal projects are excluded as are service projects which are not chargeable (in which case the project will generate a surplus service income, see `Service Income`_). + +Selecting *More* on an individual staff member will provide a complete breakdown of of that RSEs cost distribution for all projects for which they have a project allocation. The filter can be used to change the date range to limit this to certain financial years or custom date ranges. Similarly the funding status of projects can be changed to see cost breakdowns for projects which may be under review etc. + + +RSE Costs +--------- + +The RSE costs view provides a breakdown of each RSEs salary costs. It includes the following information which is used to determine the RSEs staffing cost liability. Liability represents salary cost not cost recovered through allocations on projects. + +- **Recovered Salary :** Any recovered salary from allocations on projects (either *Allocated* projects or chargeable *Service* projects) +- **Internal Project Salary :** Any salary cost as a result of allocations on internal projects +- **Non-Recovered Staff Costs :** The salary less the recovered salary. This represents the actual salary cost to the RSE staff members underwriter (as liability considers time on internal projects). + +*Note: That any overheads generated are reported separately and may result in a net cash surplus even if the staff member has a salary liability.* Any overheads generated through allocations of RSS staff on *Allocated* projects can be `viewed per project `_ or in the `Financial Summary`_. + +The detail of how each RSEs salary is calculated can be viewed by selecting the :raw-html:`` icon. This will present the `RSE Staff Costs Breakdown`_ report. + +RSE Staff Costs Breakdown +~~~~~~~~~~~~~~~~~~~~~~~~~ + +This view provide an RSE breakdown per project of any recovered or internal project salary costs. Salary costs are separated into time periods from 1st January to 31st July and 1st August to 31st December as each 1st January date may result in a salary increment and each 1st August date will result in a new financial years salary data. For salary costs which project past know finical years salary values salary increments will be based off the last available finical year and salary inflation will be estimated at 3%. Where salary inflation is estimated this is indicated with *(estimated)* next to the salary band which was used. Inflation estimates are compounded year after year. + +Service Invoicing +----------------- + +The service invoicing report presents a list of *Service* projects with with a filter for *Invoice Received* which has a value of `Outstanding` if there is no specified invoice received date. The :raw-html:`` icon can be selected to edit the project and specify an invoice received date. + +Outstanding invoices for `Active` and `Funded` projects will result in staff time being charged (assuming the project is chargeable) without any income received. Care must be taken with invoicing to ensure that invoices are not received in separate financial years to where RSE allocation have been made. + +Service Income +-------------- + +The service income report shows a summary of *Service* project staff costs (due to RSE allocations) compared with income received through invoicing. *Service* projects do not generate overheads in the same way as *Allocated* projects, instead they may accrue a surplus balance as a result of a rate being charged which is greater than the RSE staff costs. The surplus represents any balance (positive) of deficit (negative). The report shows all service projects which are not internal. The filter range can be used to limit the range of projects which are included. If any part of the project (specified by start and end date) is within the filter range it will be included. Only the portions of the salary calculation for the filter period will however be included. + +The detail of how each projects staff cost is calculated can be viewed by selecting the :raw-html:`` icon. This will present the `Project Staff Costs Breakdown`_ report. + + +Project Costs & Overheads +------------------------- + +The projects costs and overheads report shows any RSE staff costs per project. The view also calculates overheads generated as a result of any *Allocated* projects based on the staff time allocated to the project. Service projects do not generate overheads but are included in this report if they are `charged`. + +The detail of how each Projects staff costs is calculated can be viewed by selecting the :raw-html:`` icon. This will present the `Project Staff Costs Breakdown`_ report. + +Project Staff Costs Breakdown +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +This view provides a project breakdown per RSE of any recovered or internal project salary costs. Salary costs are separated into time periods from 1st January to 31st July and 1st August to 31st December as each 1st January date may result in a salary increment and each 1st August date will result in a new financial years salary data. For salary costs which project past know finical years salary values salary increments will be based off the last available finical year and salary inflation will be estimated at 3%. Where salary inflation is estimated this is indicated with *(estimated)* next to the salary band which was used. Inflation estimates are compounded year after year. + + +Internal Project Costs +---------------------- + +The internal project costs report shows the staff actual costs associated with each internal project. This is the sum of any staff costs incurred through allocations on internal projects. + +The detail of how each Projects staff costs is calculated can be viewed by selecting the :raw-html:`` icon. This will present the `Project Staff Costs Breakdown`_ report. + + +Financial Summary +----------------- + +The financial summary report provides an overview of all finances for a given time period (usually by financial year). A balance for the RSE group is determined from the cost of staff less; any recovered staff costs (see `RSE Costs`_), any service income (see `Service Income`_) and any internal project costs (see `Internal Project Costs`_). + +Each part of the calculation can be broken down into a detailed view by selecting the :raw-html:`` icon. + diff --git a/docs/team/index.rst b/docs/team/index.rst new file mode 100644 index 0000000..6a67e65 --- /dev/null +++ b/docs/team/index.rst @@ -0,0 +1,17 @@ +RSE Team and Salary +=================== + +The *RSE Team* view is available to all users by selecting **Team->RSE Team** from the main menu. The view will display all team members, their usernames and capacity. For Admin users the team members current salary grade point will also be displayed. The :raw-html:`` icon can be used to edit Salary Data for an RSE. The *Info* button will provide a `RSE Commitment Overview`_ for the individual staff member. + + +Edit Salary Data +---------------- + +A salary grade change represents a change to an RSEs salary. Salary grade changes can occur as a result of setting a starting salary or if there is a non incremental change to an RSE salary. Non incremental changes may be the result of promotion or demotion to a different salary grade or to reflect a point increment (from a non incremental salary grade point) due to exceptional contribution. + +The *Edit Salary Data* view will by default have a single salary grade point change which reflects the starting salary of the RSE set when the RSE user was created. Additional salary grade changes can be made by using the drop downs and *Add Salary Grade Change Button*. Individual salary grade changes can be deleted using this view. WARNING: If you remove all salary grade changes then it will not be possible to calculate any cost for the RSE. + +RSE Commitment Overview +----------------------- + +The RSE commitment Overview provides both a stacked commitment graph showing allocations over time and a gantt view of commitments per project. The view can be filtered by date range and funding status. Within the commitment overview graph the red dashed line represents todays date. Hovering the mouse over each stepped point will provide a breakdown of the allocations which contribute to the commitment total. The :raw-html:`` icon can be used to rescale the graph from 100% FTE to max (as the RSE may be over committed on projects which are under review). \ No newline at end of file diff --git a/docs/users/index.rst b/docs/users/index.rst new file mode 100644 index 0000000..e644f35 --- /dev/null +++ b/docs/users/index.rst @@ -0,0 +1,44 @@ +Users and Roles +=============== + +The RSE Admin tool has two distinct user types of *Admin* and *RSE* which have different sets of privileges and information available to them. Try logging into the demo site as both an Admin and RSE user to view the site from the different users perspectives. + + +Admin Users +----------- + +Admin users have the sites full features available including financial and salary data as well as financial reporting. Admin users can not be allocated to projects and are as such not part of the RSE team. + +RSE Users +--------- + +RSE users represent RSE team members and each member of an RSE team should have an account which is used for linking them with project allocations. RSE users have an individual login which allows them to view their own projects and allocations as well as view team activity. A number of the sites features are restricted from RSE users (e.g. financial reports, administrative tools, and salary information). It is possible to have joint RSE and admin users. These must be created as RSE users where there is an option to add administrative privileges + + +User Creation +------------- + +Creating an Admin User +~~~~~~~~~~~~~~~~~~~~~~ + +When you initially configured the site for deployment you will have created an Admin user by issuing the Django `python manage.py createsuperuser` command (alternatively use the demo sites provided login credentials from the README). Additional Admin users can be created by selecting **Admin->Add New User** from the menu and choosing the *Administrator* option from the user type. Once an Admin user is created they will have the option to change their password after logging in from the user menu in the top right corner of the site. + +Creating an RSE User +~~~~~~~~~~~~~~~~~~~~ + +A fresh installation of the site will contain no RSE users. Before creating one you will need to :ref:`create a number of financial years ` and salary information for them. This is required to set the starting salary of an RSE user. + +RSE users can be created by selecting **Admin->Add New User** from the menu and choosing the *RSE* option from the user type. The RSE can be ranted the same permissions as an *Admin* by selecting the *User has administration permission* check box. Once an RSE user is created they will have the option to change their password after logging in from the user menu in the top right corner of the site. + +Viewing and Editing Users +------------------------- + +Admin users can view all users of the site by selecting **Admin->All Users** from the sites menu. Editing the user allows the basic information to be changed. An Admin user can reset any users password via the red **Change Password** button on the user edit form. + +Changes to an RSE users salary must be made from the RSE Team page. + + + + + + diff --git a/rse/templates/project_allocated_new.html b/rse/templates/project_allocated_new.html index 5e39c4f..ef55184 100644 --- a/rse/templates/project_allocated_new.html +++ b/rse/templates/project_allocated_new.html @@ -8,7 +8,7 @@ {% endblock %} {% block title %}RSE Group Administration Tool: {% if edit %}Edit{% else %}New{% endif %} Allocated Project{% endblock %} -{% block page_name %}}RSE Group Administration Tool: {% if edit %}Edit{% else %}New{% endif %} Allocated Project{% endblock %} +{% block page_name %}RSE Group Administration Tool: {% if edit %}Edit{% else %}New{% endif %} Allocated Project{% endblock %} {% block content %}