SPMS Documentation

The Science Project Management System (SPMS) is DBCA’s project documentation, approval and reporting platform.

Documentation for common SPMS workflows is split by user role:

• Project owners and teams: Research Scientists and their colleagues create Projects and are primary authors of Project documentation.
• Reviewers: Program Leaders, Regional Leaders, Branch Managers and equivalent heads of SPMS Programs review Project documentation.
• Approvers: Directors as heads of SPMS Divisons approve Project documentation.
• Administrators: SPMS Administrators act system wide with unrestricted permissions.

See also Frequently Asked Questions. The above should enable SPMS users to fulfil their tasks and operate SPMS.

If you need help or contact anyone about a specific Project or Document in SPMS, please make their lives easier and include the URL to the Project or Document. The URL is shown in your browser when you look at the thing you have a question about and starts with https://scienceprojects.dbca.wa.gov.au/.

Interested readers may learn from the Functional Specification in full detail about the User roles (governing permissions and available actions), and how to advance projects through their life cycles through document approvals.

In tech speak, every feature, button, and workflow of SPMS should be defined in the Functional Specification, we should have a test case covering each requirement and most of the application code (badge “Test Coverage”), and all tests should pass (badge “Test Status”).

Installing, running and maintaining SPMS is documented in the Maintainer Documentation; the software architecture and design decisions are discussed in the Developer Documentation.

Project owners and teams

This chapter guides project owners and their teams through their tasks.

Project owners are those who register a Project in SPMS to get departmental approval. They have to author documents and submit them for approval.

Complete your Profile

• Follow the link “My SPMS Profile” in the main menu underneath your name.
• Update your Profile and save.

Create a Project

• Choose the Project type - you cannot change the type later on.
• Fill out Project details. See the FAQ for guidance on thumbnail images, and read the helptext of the form fields.
• Next, add colleagues to the Team list, and fill out the first Document, the Concept Plan.

Oops, wrong project type - now what?

For technical reasons, you cannot change the type of a project once it has been created.

• Create a new project of the correct type.
• Deleting projects is limited to SPMS admins. Notify an SPMS admin to delete the Project of incorrect type. Use the “Share” link to create an email containing direct links to the respective Project or Document.

The reason we restrict deletion of Projects is to retain the history of past Projects. It would be an easy error to make to delete a Project on completion. Instead of being deleted at the end of their active life, Projects go through a formal closure process, creating yet more documentation (reasons, outputs) that adds to the history of the Project. Completed projects are kept with status “Completed and closed”.

Ask a question about a Project or Document

Each Project and Document has a “Share” button. This button opens an email containing a direct link to the Project or Document in question.

Opening a direct link is much faster for the receiver than to hunt through SPMS, searching by project year, number and/or title.

Onboarding a DBCA colleague to SPMS

SPMS maintains a list of User profiles with all the details we need for reporting and display purposes.

SPMS automatically creates a User profile when a new User visits SPMS for the first time.

The profile then needs some more information (full names, affiliations, DBCA Program) which the Users can enter themselves. SPMS does not receive enough information from DBCA’s login system to automatically set the Program, so the User has to set this manually. Setting the Program will infer the User’s Division, which in turn drives the SPMS User experience - BCS staff have more documentation and reporting features available than other Divisions.

Add DBCA colleagues to a Project Team

• If the colleague is new to DBCA, assist them through the onboarding outlined above. Primarily, prompt them to visit SPMS once.
• The DBCA colleague must have visited SPMS prior to that in order to be known to SPMS. They should also update their profile so SPMS gets their name and title right in Team lists.
• At the Project’s detail page, click on the “Add team member” button to select any DBCA colleague.
• Only Project Team members can update Documents.
• Project Team members can add others to the Team.

Caveat: you cannot add a DBCA colleague to a Project Team until they have visited SPMS at least once.

Add an external colleague to a Project Team

To add external colleagues to a Project Team, they also require an SPMS profile. There’s only one little catch - they can’t access SPMS (yet) being external to DBCA. Therefore, you will have to create a profile for them.

• At the Project’s detail page, click on the “Register an external colleague” button to create a new User profile for them.
• As username, choose their givenname_surname in all lower case and separated with an underscore. DO NOT use your own email address here.
• As password, choose any password of your choice. The external user will never login and never need this password. Having a password is a requirement of the software framework SPMS is written in. Set and forget!
• Enter profile details and save the profile.
• Once you have created and saved the new SPMS User profile, you can add them to the Project Team via “Add team member”.
• Student Projects and External Partnerships often have external colleagues.

Caveat: External colleagues will never need to login to SPMS, and do not need to know about this profile.

Document visibility

• Currently, only BCS staff are meant to see Project Documents.
• Members of other Divisions will see no reference to Documents and are not required to fill in any Documents. Less work!
• If you however think you should see more or less Documents than you currently do, please get in touch with the administrators.

Complete and submit a Document

This section applies generally to any SPMS Document.

• Click on any field to enable a rich text editor.
• Follow the guidance in the helptext of the form fields.
• When done updating a field, make sure to click outside of the editable area to close the editor and save the changes to that field.
• Once all fields are updated, finish editing the document by clicking on the “Save” button at the bottom. This saves changes to all fields. Make sure you’ve closed any active editors by clicking outside.
• You can view the edit history through the “History” link at the top, and restore older versions if needed.
• Documents are editable only to those involved (Project team members as per the Project overview, reviewers, approvers), and only when it is their turn to provide input.
• If a Document is read-only, you should not have any reason to update it. If that seems wrong, contact the admins.
• Read-only Documents show the text content including the embedded formatting markup (HTML directives like <style>). Text pasted directly from a MS Word document with track changes enables looks particularly bad.
• In the rich text editor, use the “Source View” button to hand-edit content, and “Clear Formatting” to reset most unwanted style. If the source view shows much unwanted formatting markup, paste the text into a plain-text editor like Notepad and back into SPMS to get rid of invisible formatting markup.

In general, SPMS wants formatting to be restricted to the styles provided by its embedded rich text editor. Start with unformatted text, then format content in SPMS.

Register your Data

• Once the Concept Plan is approved, the Project is near guaranteed to be approved. Now it is time to set up data management.
• Create an account on the Data Catalogue (with its own password - NOT your DBCA password).
• Contact the Data Catalogue admin for write access to your Program(s). They will add you to as “members” of the Data Catalogue “Organization” corresponding to your DBCA Program (or equivalent).
• Create initial metadata entries for all expected datasets on the Data Catalogue.
• Label them with your project code, e.g. SP-2022-001.

Provide a Progress Report

• When an annual report requires an update from your Project(s), you will receive a broadcast email ahead of time, and find any ProgressReport Documents in your TODO list.

Close a Project

• The months before annual reporting are a good time to initiate project closure for any completed or otherwise finished projects.
• You can close a Project by clicking on the “Request Closure” button on the Project’s detail page. This generates a Project Closure Document.
• Fill out and submit the Project Closure Document for review.
• There are several flavours of Project Closure determining what comes next:
  • The Project was completed successfully, and all progress was reported in the last annual report. There is no need for a final Progress Report.
  • Same, but some progress was made after the last annual report. A final Progress Report is required.
  • The Project is suspended. No Progress Report will be required. The Project might be resumed later.
  • The Project is terminated. No Progress Report will be required.
• Update the Project’s datasets on the Data Catalogue. This is the last time someone with intimate knowledge of the data is around to do so. This preserves the Project’s data outputs, and your name will live on in the metadata.

Find Help

The following steps aim to solve any problems. Ideally they are followed in this sequence:

• Read this documentation carefully.
• Consult the Frequently Asked Questions.
• Ask the admins.
• If you think you’ve encountered a bug, feel free to open an issue here.
• If you feel that the documentation is missing something, or is unclear on something, your feedback would be highly appreciated and will help us to improve the documentation.

Reviewers

This chapter guides reviewers through their tasks.

SPMS Reviewers are the heads of SPMS Programs: Program Leaders, Regional Leaders, Branch Managers. In SPMS terminology, we call them all “reviewers”, and call their organsational units “SPMS Programs”.

They have to review and endorse Documents related to Projects of their SPMS Program.

Review a Document

Every Document will be submitted to the reviewer in the first instance. The reviewer is encouraged to

• Edit any text where appropriate - e.g. small typos or formatting.
  • Click into any text block to toggle the editor.
  • Edit any number of text blocks.
  • After editing, save the document with the green save button at the bottom.
  • Saving a Document creates a new revision in the Document history (top right). Changes are reversible.

Take actions on the Document:

• Avaliable actions are offered in the sidebar at the top right under “Actions”.
• Request a revision from the authors for bigger changes. We expect that communcation regarding these changes can happen through fastest and preferred channels outside of SPMS, such as MS Teams, email, or a simple chat.
• Once happy with the Document, the reviewer must submit the Document for approval.
• If a button was pressed unintentionally, the reviewer can reverse the action with an opposite action, e.g. a Document can be withdrawn from approval to be edited some more.
• Every action will create a new TODO item for involved staff. They will see this when they next visit SPMS in their TODO list.
• Every action will offer to notify involved staff via email.

Review a Project Plan

Before a Project Plan can be submitted for approval, the reviewer must enter Endorsements of the Biometrician, Data Manager (once enabled), Herbarium Curator, and Animal Ethics Committee as required.

Endorsements are parallel approval processes of unlreated parties which may happen in any order. Therefore, they are not modelled as approval actions, but as special features of the Project Plan.

Find required Endorsements

The sidebar lists the status of all Endorsements - not required, required, granted, or denied.

Enter Endorsements

• The Program Leader can enter Endorsements by editing the respective field in the Project Plan Document.
• Some require to scroll down the page. Endorsements can be selected from the respective drop-down menu.
• On saving the Document, the Endorsement status in the sidebar will update.
• Once all required Endorsements are granted, the Action “submit for approval” will be unlocked and visible.

Manage SPMS emails

SPMS prefixes the subject of all emails sent from the system with [SPMS]. This allows to create an inbox rule to e.g. move all SPMS emails into an inbox subfolder, e.g. named “SPMS”.

Export a Document to PDF

Every Document can be exported to PDF through the link at the page top right. PDFs can be “generated” (freshly recreated) and “downloaded” (last saved PDF version). PDFs contain a nicely formatted header indicating the approval status and hyperlinks to SPMS.

Approvers

This chapter guides approvers through their tasks.

SPMS Approvers are the Executive Directors of SPMS Divisions, or a nominated person of their choice.

They have to approve Documents related to Projects of their SPMS Division.

Manage SPMS emails

SPMS lets users opt into sending emails about requested Actions. At the level of an approver, these can add up considerably. Email inbox rules help to manage the stream of SPMS notifications:

• SPMS prefixes the subject of all emails sent from the system with [SPMS].
• This allows to create an inbox rule to e.g. move all SPMS emails into an inbox subfolder, e.g. named “SPMS”.

Approve a Document

Whenever a Document turns up in the “My TODOs” list (and optionally sends an email about this), an approver has the options to:

• Edit any text where appropriate - e.g. small typos or formatting.
  • Click into any text block to toggle the editor.
  • Edit any number of text blocks.
  • After editing, save the document with the green save button at the bottom.
  • Saving a Document creates a new revision in the Document history (top right). Changes are reversible.

Take actions on the Document:

• Avaliable actions are offered in the sidebar at the top right under “Actions”.
• Request a revision from the reviewers (level 2) or authors (level 1) for bigger changes. We expect that communcation regarding these changes can happen through fastest and preferred channels outside of SPMS, such as MS Teams, email, or a simple chat.
• Once happy with the Document, the approver must approve or reject the Document.
• Approving a Document will make the Document’s text read-only. The life cycle of a Document is explained at Document Life Cycles.
• Approving a Document will move its Project into the next life cycle stage. The life cycle of Projects is explained at Science Projects and Core Functions.
• If a button was pressed unintentionally, the approver can reverse the action with an opposite action.
• Every Document’s approval status can be reset, and the Document can be fast-tracked to the desired life cycle stage.
• Every action will create a new TODO item for involved staff. They will see this when they next visit SPMS in their TODO list.
• Every action will offer to notify involved staff via email.

If an action is not available or something seems odd, contact the system administrators to rectify the situation.

Administrators

This chapter guides administrators (admins) through their tasks.

SPMS admins have backstage access to all data and have permissions to perform any action.

SPMS maintainers in contrast have access to the database backend and can easily and safely modify data in bulk.

The role of admin, maintainer, and developer is currently shared.

Download a data snapshot

Go to the Project list and click “Download Projects” to get a full list of Projects with their details. Do not update this spreadsheet - do update projects directly in SPMS instead.

Close annual reporting cycle

• Close any progress reports which are “in approval” through Menu > Backstage > Batch-approve all Progress Reports.
• This can be done as soon as the annual report content is print ready.
• Approving a Progress Report reverts its Project from “update requested” to its normal “approved and active” state.

Prepare SPMS for a new annual reporting cycle

Instruct the Directorate to solicit the following actions from SPMS Project Teams through an email broadcast:

• Initiate Project Closure for any complete, suspended, or terminated Project (SP or CF). These projct types require a formal approval process and might solicit a last Progress Report.
• Close any completed Student Project or External Partnership. These project types close immediately without any approval process.
• Register and seek approval for any new Project, especially those which have progressed significantly since the last annual report.
• Update all External Partnerships. Their Project details will be used in the annual report.
• Remember that only members of a Project Team have permission to update Project Documents, and they can add other SPMS Users to the Team to give colleagues write permissions.

Allow sufficient time for Project teams to register their new Projects and author Project Closure documents, and SCMT to discuss and approve Project closures.

Create a new annual reporting cycle

Precondition:

• All Projects, their documentation, and their approval are up to date.
• Project closures are initiated and approved. Projects with “closure pending final update” will participate in the upcoming annual report.

Action:

• Create a new BCS Annual Report.
• Select all participating Divisions. This is likely only BCS.
• Enter the reporting year.
• Chapter images and introductions can be updated later on.
• Open/close dates are not acted upon, they are optional.

On creation of a new annual report, and only when it is created for the first time, all relevant projects will enter the life cycle state “update requested” and spawn a new Progress Report (SP and CF) or StudentReport (STP). This populates the “My Tasks” portfolio of each User, but will not send email notifications.

Post action:

• Broadcast to all involved staff that annual reporting season is now open.
• Members of External Partnerships do now have to provide a Progress Report, but need to update Project details or close them where appropriate.

View Projects of other Divisions

• Edit your own profile and set your own Program to one of the intended Division.
• Now the Project List will show only Projects of that Division.

Onboard Users

New SPMS Users must set a Program in their Profile.

• See also “Authors > Onboarding a DBCA colleague”.
• Make them visit SPMS once if they are DBCA staff. This creates an SPMS profile.
• Edit their Profile and set the correct Program if they haven’t yet.
• Set special roles (see below) as required through User Groups.

Onboard Reviewers

If a Program Leader appointment changes, a Superuser must:

• Update the Program, set new Program Leader. This is shown in the Project list and the Annual Report.
• Edit new Program Leader’s User profile, add to SPMS Group SMT. This gives the User permission as a reviewer for their own projects, and any other project in their division (as a stand-in for an unavailable PL if needed).

Onboard Approvers

If a Director or their Approver changes, a Superuser must:

• Update the Division, set the Director and/or Approver. This is shown in the Project List and the Annual Report, and used to determine who can approve Documents for a Division.

Onboard special roles

The special roles of Biometrician, Herbarium Curator, Animal Ethics representative (unused), and Data Manager (unused), are appointed by a Superuser as SPMS groups in the respective Users’ profiles.

• Only a superuser can update the User Group.
• BM or PL can grant BM’s approval in Project Plans.
• AE or PL can grant AE approval in Project Plans.
• Each role needs to setup an email inbox rule.
• Each role needs to be trained personally.

Frequently Asked Questions

Many questions will be covered by the instructions to specific user roles. Here is a collection of frequently asked questions providing further guidance:

Where are my projects?

The SPMS home page will display projects you supervise or participate in under “My Projects”.

Note:

• “My Tasks”, “My Projects”, and “My Collaborations” expand/collapse when clicked on.
• A black star indicates that you lead the project as “project owner”.
• A hollow star indicates that you are part of the project team.

Where can I search for other projects?

The “Browse all Projects” allows you to filter projects by any of the columns. Click on any of the column headings to sort or filter the list. You can type to filter the dropdown menus!

“Browse all Projects” is also available in the top menu bar under “Projects”.

Which projects will be discussed at the next SCMT meeting?

On the SPMS home page, in the “Projects” section, click “View xxx projects awaiting SCMT approval” to expand a list of project documents (Concept Plans and Project Closures) awaiting SCMT approval.

This selection is of particular interest to SCMT members as pre-read for the SCMT meeting.

Is there anything SPMS wants me to do?

If there are any documents awaiting your input, and possibly any approval actions, they will be shown on the SPMS home page under “My Tasks”. Click each link, update the content as appropriate, save the changes, and if appropriate, execute any approval steps shown under “Actions”.

Note: Save your changes to documents before leaving the page or executing any actions. Make sure you leave the active fields by clicking outside before saving!

I’m updating a Project or Document, but the updates don’t save

When updating a text field, click inside the field to enable the editor. When done, click outside to close the editor and save the changes to the field. Update as many fields as many times as you like.

To save the changes to all fields, hit the green “Save” button. You only need hit “Save” after all the fields have been updated.

Possible problems:

• If you “Save” and an editor is still enabled on a field, your edits to that field will not be saved.
• If you close the page without hitting “Save”, no edits will be saved at all.

Why can’t I submit my project’s related documents for review, or request project closure?

Only project team members can execute these life cycle steps. If you can’t, but feel you should be able to, an existing project team member has to add you to the team.

My Document is read-only and the content looks garbled.

SPMS shows editable text with embedded formatting enabled. Once read-only, e.g. when a Document has been submitted up the approval chain, or when approved, content is shown as supplied by the authors. This includes all the normally invisible formatting.

You can see a Document properly laid out through both the PDF export and (if it’s a Progress Report or a Student Report) in the print preview of the current Annual Report.

How can I change the project type?

Behind the scenes, SPMS creates different items when a project is created. It is not possible to migrate the content of the different fields and documents without the risk of data loss. Therefore, SPMS does not allow to change project types after their creation. If you still need to change a project type, please do:

• Create new project with the correct type. Copy/paste or re-type relevant fields.
• Ask the admins to delete the old project of incorrect type.

The admins can delete a project:

• Delete the (child-)project on the detail page, then
• delete the (parent-)project on the overview page.

SPMS requires this two-step deletion process due to a known bug in one of its third party libraries.

Why can’t I update my project or edit documents?

You need to be on the project team to have write permission to the project or its documents. Furthermore, only “new” documents are editable - that’s when the project team is meant to fill in the document. Once a document is submitted for review to the Program Leader (“reviewers”), only they can edit it. Once a document is submitted to the Directorate (“approvers”), again only they can edit it.

If you wish to update a document sitting with your Program Leader “in review”, you can “recall” it from review, edit it, and resubmit it for review.

How do I update Team lists?

After updating a User’s details, such as affiliation or title, you need to re-save the Project’s details to refresh the cached team list. An admin can refresh team lists in bulk, e.g. during editing of the annual report.

Can I download documents?

You sure can! The “View PDF” link above each document will create a beautifully laid out PDF with a cover page indicating its approval status and project details. The PDFs have links in the page headers back to their online counterparts in SPMS.

The “Create PDF” link does not work

Likely there’s some invisible markup in at least one of the document’s fields. This can happen if the content has been copy-pasted from MS Word, EndNote, or web pages.

Cut and paste the content into a simple text exitor like Notepad, then back into SPMS to remove this invisible markup. Do not use “clever” text processors like MS Word, as they “understand” and preserve the invisible markup we want to get rid of. Do use simple text editors like Notepad, which actively discard invisible markup.

How can I make my project stand out?

Provide a tagline, a project summary, and a nice thumbnail image!

Tagline

Can you sell your project in one sentence to a non-expert audience? (Currently disabled)

Project Summary

The description is the place to explain the project in up to three paragraphs to the interested reader, much like a publication’s abstract.

Project thumbnails

Project thumbnails are used as section thumbnails in the annual report and as thumbnails to represent the project online.

• The thumbnails should use a standard image format, such as JPEG (.jpeg, .jpg) or PNG (.png).
• The thumbnails should be oriented correctly. If the thumbnail stands on its side, edit (rotate) the original file and re-upload.
• The aspect ratio should be 3:2 to 1:1 (width:height).
• The horizontal resolution should be at least 600 pixels.
• The vertical resolution should be at least 600 pixels.
• Larger images will be resized automatically, preserving aspect ratio, to fit a maximum width of 600 pixels and a maximum height of 600 pixels.
• The image should not contain too much detail or too much contrast.

Background images for divisional programs

Program images could be used as page-width chapter images in the annual report, and as background images online.

• The aspect ratio should be exactly 2:1 (width:height).
• The horizontal resolution should be at least 2480 pixels.
• The vertical resolution should be at least 1240 pixels.
• Larger images will be resized automatically, preserving aspect ratio, to fit a maximum width of 2480 pixels and a maximum height of 1240 pixels.
• The horizon, if shown, should be as level as possible and in the middle or top third - avoid the bottom third (this is where headings will be overlaid).
• The image should not contain very dark (shady) or bright (sun glare) areas.

What will happen when a new ARAR is kicked off?

A new Annual Research Actitivy Report (ARAR) is created every year. It will request updates from all Science Projects, Core Functions, and Student Projects. It will include project level details from all existing External Collaborations.

• You will get one broadcast email when the ARAR process starts.
• SPMS will not email you separately for progress reports
• SPMS will show any progress reports requiring your input under “My Tasks”

Before the ARAR gets kicked off, make sure to get your things in SPMS up to date:

• Create new projects, start their approval process
• Close old projects (some will have a closure process incolving document approval)
• Update team lists on projects.

This will prevent SPMS from unknowingly requesting updates from long dead projects (which create extra effort to get rid off again).

Can I provide ARAR updates before the new cycle begins?

No, not really - only kicking off a new ARAR cycle will create the documents you need to update. They simply don’t exist earlier. If you need to provide early updates (e.g. because of field work), use the latest progress reports as starting point (copy out the text), and email the new version to the system administrator.

What happens in the last weeks before a new ARAR comes around?

The ARAR update process has three phases, relative to the last SCMT meeting before the ARAR process starts. (This meeting has the power to approve requested project closures).

1. Before the last SCMT meeting before the ARAR: PLs and Scientists review their projects, request closure / termination / suspending where required, and update the team lists.
2. At the last SCMT meeting before the ARAR: SCMT discusses and approves/rejects Project Closure documents, and terminates / suspends projects as appropriate.
3. After the last SCMT meeting: SPMS admins (Julian/Florian) create a new ARAR when instructed to by the Directorate. This will generate Progress Reports for all active and closing ScienceProjects, all active CoreFunctions, and all active StudentProjects.

Running through updates in this order will speed up the update process considerably by preventing the confusion (as there’s no staff training ahead of the ARAR process) and required subsequent individual coaching from the ARAR admins to involved staff members to back each falsely project open out of the ARAR update process.

What happens during the ARAR reporting phase?

The general purpose of SPMS is to encourage project management through the correct approval of related project documentation, and to audit the human decisions. However, sometimes we need to fast-track some processes and override the system. A system admin with sufficient permissions can do so.

• SPMS admins assist DBCA staff with the updates and their approval. Some projects and documents get stuck and need a superuser to reset approvals.
• Given a draft of the organigram, the developer updates the print version.
• Any other changes to the report structure are applied by the developer upon request from the Directorate.

How can I exclude an unwanted regular progress report?

A progress report was requested in error for a project that should have been started the project closure process.

• An SPMS admin can force close the project, which deletes the current progress report, excludes the project from the annual report, generates a project closure form, and sets the project status to “closing”.
• Force closing a project can be reverted if needed.

How can I exclude an unwanted “final” progress report?

A project with a closure form in status “closing pending final progress report” is triggered by creating a new annual report. The annual report creates the final progress report. Instead of filling in and approving the final progress report, we want to close the project and remove the last and empty (dud) progress report.

• Closure form: reset approval status, change closure goal to “completed without final progress report”, and fast forward closure form approval, skipping email notifications. This pushes the project status to “completed”.
• Delete the empty final progress report.

Why can’t I update a progress report?

Only users added as project team members can update that project’s documents, including the progress reports.

• The creator of a project is added as a team member automatically.
• Other project authors have to be added by the project’s creator or an admin.

How is a project plan endorsed and approved?

As a Program Leader, I have received a notification email about a Project Plan which needs to be approved. I cannot see the button to approve the project plan but I’m not sure why.

• SPMS shows in the sidebar whether the endorsements of Biometrician (always required), the Herbarium Curator (if plant specimen collection involved) and the AEC (if animal handling involved) are required.
• Any SPMS user who is part of the Group “BM” / “HC” / “AEC” can set the endorsement field inside the main document to “Granted” or “Denied”, then save.
• Once endorsements are given, the Program Leader will be shown the “approve” button, which sets the project to “active” without the need for additional Directorate approval.

How can I change how project team members are shown in the team list?

To change a project team member’s affiliation (and update the cached version):

• Staff > Browse SPMS users > User details, (e.g. field “Affiliations” > update affiliation “Curtin University”) > Save User.
• Left column shows user’s projects (where the users occur on project teams) > open each project in a new tab.
• Each project: Manage Team > “edit” membership > save. This updates the cached project team list.
• Update all (admins only): Backstage > update caches.

Getting started

The most common and fun things to do in SPMS revolve around project approval and taking the “ow” out of the “how” of annual reporting.

Gone are the days of emailing MS Word documents - the future is here, and it’s all in your browser. SPMS will tell you what to do (your Tasks), offer shortcuts to your Projects, and allow you to browse other Projects and Reports. If there are urgent or new Tasks, SPMS will notify you via email.

Login

SPMS uses the DBCA Single-Sign-On login, provided by Microsoft’s Office 365. Once-off, SPMS will redirect you to login.microsoftonline.com, which you already have used to login to other Parks & Wildlife online services, such as Office 365.

Remember to use your email address (including @dbca.wa.gov.au), not your user name.

Feel free to select “Keep me signed in”, and let your browser “remember the password”. At this point, you already are logged into your computer with the same credentials, so letting the browser keep you logged in is no extra security risk.

Your browser will remember your login status for a few weeks. However, for security reasons, SPMS will occasionally ask you to provide your login again.

SPMS recommends to use Google Chrome or Mozilla Firefox for optimal browsing experience.

Find a Project

On the “Browse all Projects” page you can filter and search for projects.

Project Life Cycles

First, let’s have a look at the game of snakes and ladders that is SPMS’s project life cycle management.

There are three main workflows:

• Project creation and approval (“New” to “Active”),
• providing annual ARAR updates (“Active” to “Updating” and back), and
• project closure (goal: “Completed”).

Project creation and approval will require solving two side quests, Concept Plan and Project Plan approval.

Active projects are allowed to be worked on, and will require annual progress reports.

Closing a project requires an intricate, multi-step process, which we’ll discuss here in detail.

Project Creation and Approval

Create a new Science Project

• On the SPMS home page click Create New Project
• In the Project Type dropdown box select Science Project
• Enter a project title and divisional program (and as many other fields as you can fill in), then click Save Changes
• In the Overview tab, enter team members. External team members must first be registered with SPMS (see below - Register external colleague). Once registered, click Add team member and select them as you would any staff member. Click Edit Project Details to provide additional information such as location, then click Save Changes.
• In the Concept Plan tab, enter the details of your concept plan, then click Save Changes.
• Submit the concept plan for review (Submit for review button) by your Program Leader.

Core Functions look the same as Science Projects, however they are maintained by SPMS admins.

Create a new External Collaboration

• On the SPMS home page (https://scienceprojects.dbca.wa.gov.au) click Create New Project
• In the Project Type dropdown box select External Collaboration
• Enter a project title and divisional program, then click Save Changes
• In the Overview tab, enter team members. External collaborators must first be registered with SPMS (see below - Register external colleague). Once registered, click Add team member and select them as you would any staff member.
• Click Edit project details, then under Collaboration details enter the collaboration name and budget.

Create a new Student Project

• On the SPMS home page (https://scienceprojects.dbca.wa.gov.au) click Create New Project
• In the Project Type dropdown box select Student Project
• Enter a project title and divisional program, then click Save Changes
• In the Overview tab, enter team members. If student is external you must first register them with SPMS (see below - Register external colleague). Once registered, click Add team member and select them as you would any staff member.
• Click Edit project details, then under Student project details enter the study level and academic organisation.

Managing project teams

Add a dbca employee as team member

Before SPMS can add dbca employees to teams, they have to login once in person, so that SPMS adds them to its internal user database.

A user that has never logged in cannot be added to teams or into project roles.

Register an external colleague

• Click on the project Overview tab or open Menu > Staff
• Click Register external colleague
• Provide a username (use givenname_surname) and password (can be same as username) and click Save Changes (first screen).
• On the second screen, enter as many user details as you can and click Save Changes.
• External colleagues can be natural persons or groups/organisations. Choose to “Show as Group” accordingly.
• External colleagues will not show up on the team list in the ARAR or on the project overview page. They are however useful to list on the project, as they are real persons interacting directly with the project.

Now the new user can be added to project teams or project roles.

Note External colleagues cannot login to SPMS, unless they have a dbca account and email. However, a profile needs to be created as shown here in order to add them to project team lists and represent them with their correct name and attribution.

Managing privileged user roles

The application’s superusers can manage members of the “reviewer” (all Program Leaders and SCMT members) and “approver” (Directorate) group, as well as set the SCD program’s details, such as current program leader.

Also, representatives of Biometrician (BM), Herbarium Curator (HC), Data Manager (DM), and Animal Ethics Committee (AE) are managed by superusers.

If you feel you should be in either of these groups, contact the system administrators.

Closing a Project

Closing a Science Project

The official way to initiate the closure process an active Science Project is for the project team to hit the “Request Closure” button.

• “Request Closure” will create a Project Closure form and forward the project to the status “Closure Requested”.
• The project team has to update the Project Closure, the submit for review.
• The Program Leader, then the Directorate have to approve the form.
• On approval of the Project Closure, the project turns to status “Closing”, which means that a last ARAR update has to be provided.
• When the next ARAR comes around, a Progress Report (ARAR update) is requested.
• The project team has to update the Progress Report and submit it for review and approval.
• Approval of the Progress Report will automatically mark the project as “completed”.

Notes:

• If a project is in the process of Project Closure approval (status “Closure Requested”), and an ARAR cycle is started, no Progress Report will be requested from the project - the Project Closure has to be approved first, then the Directorate can request the final Progress Report.
• If a project is “Active”, but really should have been “Closing” (and working on the Projcet Closure document), and an ARAR came around, incorrectly asking the project to provide a standard Progress Report, the Directorate can “Force Closure”, which will delete the Progress Report, create a Project Closure, and fast-forward the project into the correct status “Closure Requested”. Now, the Project Closure can be submitted and approved, then the Directorate can immediately request a final Progress Report.
• The Directorate can (when asked to, and at their discretion), suspend or terminate a project to indicate that although the project goals have not been met, the project is currently or permanently set aside and not being worked on.
• The Directorate can also force-choke a project into status “Completed” without due process. With great power comes great responsibility.
• The Directorate can reactivate suspended, terminated, and completed projects.

Closing a Student Project

The project team can “Request Closure” of any active Student Project. Since there is no formal closure process, the project simply will be marked as “Completed”.

If the Student Project is in the middle of an ARAR update, the project team can still choose to “Cancel update and request closure”, which will mark the project as “Completed” and delete the Progress Report. Since SPMS cannot decide whether this Progress Report is required or not, it is up to the team to decide the appropriate action.

Closing an External Collaboration

Project-level details of an External Collaborations will be included in an ARAR, but no separate Progress Report will be requested. Therefore it is important for staff to keep the project details and team lists of External Collaborations updated, and close them as appropriate.

There is no formal closure process of External Collaborations, so, as with Student Projects, “Request Closure” will simply mark them as “Completed” and remove them from any active ARAR.

Interaction with the Data Catalogue

The Project Closure document will want to know where the data and digital artefacts are. The place for them is the data catalogue.

A semi-official “what goes where” guide, including instructions for the data catalogue, can be found on the Marine Science Wiki.

Please note that every researcher is still (as per divisional guidelines) responsible to backup their data in two separate places, and put a third copy on the data catalogue.

Our data catalogue is a warehouse of metadata ( = a phone book for datasets) which holds links to, or (third!) copies of, departmental datasets. The catalogue is not a complete backup for data and - although the server and the database are backed up, and there are fail safes in place - with enough bad luck, can lose its copy of datasets.

So, the third copy on the data catalogue will be the one that is discovered and accessed by Departmental colleagues most oftenly, whereas the first and second backups are the point of truth, and a restore point, for the dataset.

Functional Specification

User roles

There are many things that can be done with projects and documents, but some actions are only available to a restricted audience and/or only at certain times or under certain circumstances.

SPMS’s philosophy is to be permissive, but log everything. The point of truth for project approval is the SCMT; necessarily, SPMS will always require to be brought up to speed with the latest SCMT decisions.

After 4 years of development and honing workflows and user interface, SPMS implements all known SCD rules and workflows around project approval. If things go to plan, SPMS will show “the right buttons” to allow appropriate actions.

SPMS features a role-based permission system, based on three roles:

Project teams

Team members and holders of project roles have the “submit” permission for their respective project and its related documents. This allows them to execute approval actions, e.g. submitting a document for review, or requesting project closure.

Project roles are Project Owner, Data Custodian and Site Custodian. All three default to the creator of a new Project, but can be updated at any time. The Project Owner is added as “Supervising Scientist” to the project team when a project is created. The Project Owner, and any other team members, can add/edit Team membership.

Only team members of a project can update a document and execute any life cycle steps, such as submitting related documents for review, or requesting closure.

Only DPaW staff are notified when the team is emailed. SPMS leaves prompting contributions from external collaborators to personal communication as (and when) appropriate by DPaW staff.

Program Leaders

Members of SCMT (all Program Leaders) have the permission to “review”. This allows them to review documents (Concept Plans, Project Plans, Progress Reports, Closure Forms, Student Reports), update them if appropriate, and submit further up the approval chain, or request updates from the authors.

Program Leaders can review other programs’ projects as well, because: * some projects are registered under one SCD program, but administered under another * PLs can stand in for each other * we assume (as everything is logged), that no PL will act without SCMT’s approval

Program Leader permissions are global (for all projects and documents). Only the direct Program Leader is notified when actions from reviewers are requested. SPMS leaves the edge case of prompting another PL for input as (and when) appropriate to the directly involved and notified PLs.

Directorate

Representatives of the SCD Directorate (e.g. Director’s EA) have the authority to approve documents, or manage annual reports such as the ARAR. Approval of documents will reflect the decisions of the SCMT and Directorate, and will cause projects to proceed in their life cycle.

Directorate permissions are global (for all projects and documents).

Only explicitly nominated representatives of the Directorate are notified when actions from the Directorate is required.

Special Roles

Project Plans require endorsement of the Biometrician (mandatory), the Herbarium Curator (if plants are collected), an Animal Ethics representative (if animals are involved), and (soon) the Data Manager (to setup the project’s data management).

Special Roles will find Project Plans requiring their endorsement in their Tasks, and will receive an email when a new Project Plan requires their attention.

For each Project Plan, the following should happen:

• SPMS sends an email when the Project Plan is created
• BM reads the “Methodology” section, discusses with team as required
• HV reads the “No. specimens” section, discusses with team as required
• Soon: DM trains team to create datasets on the [Internal Data Catalogue](http://data.dbca.wa.gov.au), sets them up with a high performance computing (HPC) environment if required, and points out documentation on data management.
• The Program Leader enters AE endorsement as per (external to SPMS) communication with the Animal Ethics Committee.
• Endorsement is granted or denied by setting the respective “endorsement” fields in the Project Plan to “granted” or “denied”, respectively, and saving the document. This action is logged in the document history.
• The Project Plan can only proceed in its life cycle once all required endorsements are granted.

Note Special Roles are granted the privilege to edit Project Plans even after these have been approved, in order to facilitate their adding of endorsements where required.

Project Life Cycles

This section goes into the full detail about the supported Project types and their life cycles. In a nutshell, Project approval in SPMS is like playing a board game. Newly created projects spawn documents, which have to be filled in and sent through their own approval work flow. Approval of documents advances projects to new life cycle stages.

Science Projects and Core Functions

Science Projects have

• a two-stage approval process,
• annual reporting requirements,
• a two-stage closure process, and
• a few admin shortcuts to force-choke projects into the correct status.

Core Functions have the same documentation as Science Projects, but as ongoing Divisional business, have no formal approval or closure process.

Science Project Approval

• Create new Science Project
• Update and submit ConceptPlan
• ConceptPlan approval creates ProjectPlan
• Update and submit ProjectPlan
• ProjectPlan approval activates Project

Science Project Annual Reporting

• Users get one central email broadcast about Annual Report
• Users find all Progress Reports requiring their input in “My Tasks”, update and submit them
• If an update is rejected, it will turn up in “My Tasks” again

Science Project Closure

There are many ways to retire a ScienceProject.

• Submitters (and their line management) can “request closure” on active projects to create a Project Closure form:
  • “Request closure” button creates Project Closure document;
  • Approval of Project Closure document advances the project to status “Closing pending final update”;
  • The next ARAR will create a final Progress Report;
  • Approval of the final Progress Report will close the project.
• Approvers can force-choke any project into closure from almost any active state.
• Approvers can terminate or suspend active projects to reflect a change in strategy, take a project out of the circulation without due closure process.

All steps are reversible.

External Partnerships

Partnerships have no approval or closure process, and require no separate annual updates. Simply registering, updating project details every now and then, and closing them as required will be enough.

Student Projects

Student Projects have no approval workflow or closure process, but require simple annual progress reports.

Progress reports requiring your input will turn up in “My Tasks” as well.

Document Life Cycles

All documents share the same approval work flow:

• Submitters (project team) update the content, then submit for review.
• Reviewers (project’s program leader) reject or submit for approval.
• Approvers (Directorate) reject (to reviewers or submitters) or approve the document.
• Approvers can reset the document to “new” and fast-track it through its approval stages.

Document approval will often advance their project to a new stage. Revoking document approval will return the project into the previous stage.

The individual documents differ only in the actions caused by their approval.

Publication approval

Publication types

Definition: Media released publicly or internally with a defined approval process

• peer reviewed journal articles
• reports
• conference abstracts
• posters
• info sheets
• fact sheets
• book chapters
• all endnote publication types?
• social media posts (involves Zoran and Margaret)
• Threatened fauna and flora recovery plans
• Translocation proposals

step 1: review by PL step 2: review by A/Dir

Publication

External, possibly peer-reviewed, publication:

• Peer-reviewed paper
• Report

Commonality: Public document written in the affiliation of DPaW.

• Author compiles draft
• Author discovers publication approval guideline
• Author reads publication approval guideline
• Guideline requests author to seek informal feedback from Project leader
• Publication may link to SPP

• Author starts online publication approval process (creates form):

  • manuscript ID (auto) MS-YYYY-NNN
  • title
  • synopsis (plain english)
  • management implications (text)
  • author team (text, not User)
  • manuscript (file)
  • attachments (file) x n
  • related projects (text): SPMS projects, non-SPMS projects
  • formatted citation
  • RIS (text)
  • DOI

• Author submits form (“in review”), which opens checkbox: notify (depending on required roles) PL, BM, HerbC (if plants) but not Fauna folks (if fauna), plus possibly other roles.

• Approval roles:

  • PL
  • BM
  • HC (if “involves plant taxonomy”)
  • possible other roles

• Approval roles may choose to litigate feedback from higher roles via “send email”
• Approval roles see open publications in “My Tasks”
• “Seek external feedback” creates email with blank recipients and attaches whole manuscript and attachments
• “Seek internal feedback” creates email with blank recipients with only a link to pub approval detail page
• “Seek author feedback” creates email to author with link
• Author can update manuscript any time while “in review”
• Author can “re-submit” the publication, which sends an email notification to reviewers pending endorsement
• Reviewer roles other than PL endorse, which sets flag and sends notification to other roles
• PL approves (status “approved”)
• Once all approvals are given, author gets notified to submit manuscript
• Author and PL can “retract” at any time (status “retracted”)
• Authors can “delete”
• Author goes through publication process with publisher
• If successful, author attaches final manuscript, DOI, citation and presses “published”
• “published” notifies librarian with citation
• ARAR builds publication list from “published”

REQ Publication guideline must be discoverable REQ Updated guidelines relevant to SPMS need to be published REQ Publication has authors

TODO should we retain deleted forms?

Recovery plans

RP are a tool to identify actions needed to improve the conservation status of exactly one species (fauna or flora). State RPs cover 10 years, interim RPs cover 5 years.

The review and approval process exists to ensure and audit that the plan:

• is achievable,
• is correct from the reviewing role’s perspective, and
• conforms to relevant corporate policy.

Model fields

• document - file
• for each role: involves_X (y/n), determines whether role needs to review
• for each role: endorsed by role Y, editable only to members of role
• citation metadata as required
• authors - either plain text or SPMS user list

Life cycle

• RP is prepared by staff member who keeps working version on their desk.
• RP is uploaded to SPMS as read-only PDF copy.
• User provides criteria which determine required review roles.
• SPMS shows document as “draft”.
• User submits document for review and approval.
• SPMS shows document status as “in review”.
• SPMS notifies each involved role by email containing instructions and URL.
• Each role can follow URL in email to RP and read the plan.
• Each role can choose to provide feedback, which opens an email to author allowing the reviewer to provide private, direct feedback to author.
• Prompted by reviewer feedback or by own volition, authors can update the document and (during saving) opt in to notify reviewers pending endorsement.
• Any reviewer content with document can endorse
• Certain reviewer roles will only be notified by email once other roles have endorsed the document:
• In parallel: district, regional staff, spec & comm branch, pricipal zoologist or botanist),
• then Manager Species and Comm Ken Atkins
• then A/Dir Conservation
• If nationally threteaned species in other (interstate) jurisdictions, the document is sent (external to SPMS) to Commonwealth who have their separate process.
• If Commonwealth agencies are involved, their feedback is handled by (TODO insert role here).
• Once all reviewers have endorsed, email notification for approval is sent to Dir SCD.
• SPMS shows document as “in approval”.
• Dir SCD can either provide feedback via email, or approve.
• SPMS turns record read-only to prevent tampering and shows document as “approved”.
• SPMS notified librarian of approval, sending URL, citation and document.
• Document is filed and released to public (both external to SPMS).

Questions

• Where is the point of truth for the approved document?
• SPMS should rename “PL” to accommodate “Branch Manager”, eg. “PL or BM”

Translocation proposals

• written by staff, staff and external person, rarely only external
• endorsement process depends on origin and destination of animal to be translocated
• endorsed by principal zoologist or senior botanist
• endorsed by animal ethics committee (Manda Page will know)
• endorsed by Manager Species and Comm Ken Atkins
• endorsed by A/Dir Conservation
• approved by Dir SCD
• publication to intranet (?) and filing

Roles

• TODO: fill from above

Maintainer Documentation

Set up development environment

The year is 2022, the OS is Ubuntu 22.04 LTS, support for Python 2.7 is waning. pipenv and poetry are unusable for Python 2.7 projects. We need a new setup.

• Install pyenv.
• Install shell completions, e.g. fish: https://gist.github.com/sirkonst/e39bc28218b57cc78b6f728b8da99f33
• Good pyenv intro: https://realpython.com/intro-to-pyenv/
• Use pyenv to install Python 2.7.18.
• Clone SPMS repo.
• Inside SPMS repo, run pyenv local 2.7.18 to create a .python-version file.
• Find path to python2.7 with which python2.7 (e.g. /home/USERNAME/.pyenv/shims/python2.7).
• Create a virtualenv with virtualenv -p /home/USERNAME/.pyenv/shims/python2.7 .venv.
• Activate virtualenv with source .venv/bin/activate.fish.
• Install dependencies with pip install -r requirements_docker.txt.
• Deactivate virtualenv with deavtivate.

Alternatives: Develop with Docker / docker-compose following https://docs.docker.com/samples/django/.

Day to day development

• Enter SPMS repo.
• Activate virtualenv with source .venv/bin/activate.fish (or shell of your choice).
• Ballmer.jpg
• Run tests with fab test.
• Deactivate virtualenv with deavtivate.

Release

Pre-release

• Write tests.
• Write docs (user manual).
• Commit changes.
• Build Dockerfile locally and test changes:
  • docker build -t dbcawa/sdis:latest . or fab dbuild
  • docker run -it dbcawa/sdis:latest
• Portainer is a great UI to run and inspect local Docker images.

Release

• Edit .env with new SDIS_RELEASE.
• Deactivate virtualenv with deavtivate.
• Activate virtualenv with source .venv/bin/activate.fish to read new SDIS_RELEASE
• Run fab tag to create a new git tag, push commits, then push the tag.
• GH Actions will build and publish the Docker image to ghcr.io.

Deploy

• Open Rancher UI and edit the UAT config for SPMS workload to the new version number. This will download the Docker image (which can take a few mins), then hot-swap the images.
• Apply migrations if any through a shell on the respective workload with ./manage.py migrate.
• Once running and tested, edit PROD. Since the Docker image is already downloaded, this step will be fast. Run db migrations if necessary.

Documentation

The docs source is part of the SPMS source. The docs are built and hosted on readthedocs.org, where a GitHub incoming webhook automatically builds the docs on every GitHub push. An alternative would be a GitHub action to build the docs and host on github-pages.

• Update docs as needed.
• Build and view locally: fab docs.
• Commit changes (only docs source is committed, locally built docs are gitignored) and push.
• Readthedocs will automatically pull, build, and host the docs.
• Both the SPMS code repo and the SPMS app link to the hosted docs.

Developer Documentation

This chapter discusses the design philosophy behind the software architecture of SPMS. To get up and running in your own development environment, consult the README.

Polymorphic inheritance

Projects and documents are implemented using django-polymorphic data model inheritance. This allows us to easily extend a base model with all the common fields, but more importantly, it allows us to reduce duplication of shared business logic.

Problems arise when combining with other packages, e.g. django-fsm transitions can be inherited, but the user permissions need to match the exact data model.

Finite State Machine

Product life cycle management for projects and documents is implemented with django-fsm, which contributes a set transition graph, gate checks, pre and post transition signals, and user level permissions (to be used with caution on polymorphic models).

Permissions

The business logic of finding and linking audiences to actions is kept in the transition permissions, which are lambda functions calling the instance’s “submitter”, “reviewer” and “approver” functions, which “know” the correct audiences. This keeps the business logic inside the document and project models.

• Everyone is allowed to “view”
• Project teams are allowed to “change” project and document details
• Project teams are allowed to “submit” documents for review, retract them, and request project closure.
• All SCMT members (program leaders) are allowed to “review” documents
• All Directorate representatives are allowed to “approve” things and fast-track projects through their life cycles to re-align SPMS with reality.

Notably, there are no customisations to Django permissions in place. Django-fsm accepts either hard-coded permission strings, or lambda functions.

Hard-coded permission strings are referred from django_fsm’s has_perm to django.contrib.auth.models.PermissionMixin’s has_perm, which requires properly named “app.permission_model” permissions. The “model” part is hard-coded, and will not be correct if the transition is inherited to a polymorphic child model. This will prevent permission strings to be used.

Lambda functions however can accept arguments, such as model functions declared as properties. Properties can be inherited, and overwritten in child models where necessary. This means that lambda functions used in transition permissions can be inherited without problems. An added benefit is the somewhat cleaner design of keeping the definition and source of permissions together with the transitions with the model.

Finding the right audience for notifications and write permissions

To restrict editing of documents to the correct audience, pythia.documents.admin.DocumentAdmin.get_readonly_fields refers to Document.get_users_with_change_permissions(), which in turn returns the audience corresponding to its status.

The current implementation permits the respectively involved users and their line management to edit documents.

This keeps the business logic with the field status it depends on at the model. The previous implementation to use post-save signals setting (custom) document permissions, and letting views determine read-only fields from these permissions, was more indirect, extremely error-prone and hard to understand.

Django Admin

Building the UI from the Django admin saves some development time, as Django admin already provides CRUD views. However, it takes away the “plain old admin backdoor”, takes away human-readable URLs, requires some advanced workarounds and overrides, and inflicts another layer of complexity.

In retrospect, using Django’s admin interface as front-end will work beautifully for simple CRUD applications, but cause far more trouble than time savings when trying to design, maintain, and evolve a highly complex application with ever-changing requirements to the UI and workflows.

API

Planned, needed, coming up.

Continuous Integration and TDD

After four years of “scraping over the line” in “whatever it takes” mode, we now finally are implementing Test Driven Development. See the badges on GitHub and at the top of this documentation for current build status and test coverage.

The ideal development work flow

• Translate feature requests by stakeholders into functional specs
• Translate functional specs into tests
• Write code, add docstrings
• Document intended usage of new fatures in user docs
• Add/adjust UI elements, feature tours (joyride.js), tooltips

Testing

Objects and database persistence

One intriguing bug we found had us scratching our heads for longer than we liked. Consider a test case involving a Project subclass, e.g. ScienceProject. ScienceProjects have transitions, which spawn subclasses of Documents, which have their own transitions. A Document’s final “approve” transition will trigger the corresponding transition on their Project object.

On one hand, accessing the attributes of the document’s FK to the project (d.project) will fetch the new, changed project from memory.

On the other hand, accessing the project directly will fetch the old, unchanged object fresh from the database. It will appear as the transitions had no effect.

To synchronise db and memory, the reference to the project has to be saved to db.

p = ScienceProjectFactory.create()
d = p.documents.instance_of(ConceptPlan).get()
d.first_transition()
d.next_transition()
d.final_transition_that_triggers_project_transition()

# p is unchanged
self.assertEqual(p.status, UNCHANGED_STATUS)
# d.project is changed
self.assertEqual(d.project.status, CHANGED_STATUS)
p = d.project
p.save()

self.assertEqual(p.status, CHANGED_STATUS)

Technical Documentation

This chapter links automatically extracted code documentation with the source code.

NOTE Until SPMS is upgraded to Django 1.8, autodocs will fail to extract docstrings from modules using Django image fields and django-fsm state fields. Refer directly to the docstrings inside code if they don’t show up below.

pythia Package

pythia.widgets Module

class pythia.widgets.AreasWidgetWrapper(widget)

Bases: django.forms.widgets.Widget

build_attrs(extra_attrs=None, **kwargs)

Helper function for building an attribute dictionary.

id_for_label(id_)

media

render(name, value, *args, **kwargs)

value_from_datadict(data, files, name)

class pythia.widgets.ArrayFieldWidget(attrs=None)

Bases: django.forms.widgets.TextInput

media

render(name, value, *args, **kwargs)

value_from_datadict(data, files, name)

class pythia.widgets.CheckboxSelectMultiple(attrs=None, choices=())

Bases: django.forms.widgets.SelectMultiple

id_for_label(id_)

media

render(name, value, attrs=None, choices=())

class pythia.widgets.InlineEditWidgetWrapper(widget)

Bases: django.forms.widgets.Widget

Custom InlineEditWidgetWrapper.

Adapted from django.contrib.admin.widgets.RelatedFieldWidgetWrapper.

Changes 2014: We reverted to store HTML, not Markdown in pythia.fields.Html2TextField.

Enable lines with “MARKDOWN” comments to convert HTML edited in the widget to Markdown in the db field.

build_attrs(extra_attrs=None, **kwargs)

Helper function for building an attribute dictionary.

id_for_label(id_)

media

render(name, value, *args, **kwargs)

Custom render method.

If the form has not been injected to the widget, failover to the original widget.

url refers to the POST location used by TinyMCE’s AJAX save function. If we’re on an add page, we don’t want to POST save anything.

value_from_datadict(data, files, name)

widget_overrides = ((<class 'pythia.widgets.ArrayFieldWidget'>, u'pythia.handsontable("%s", "%s");'), (<class 'django.forms.widgets.TextInput'>, u'pythia.inlineEditTextInput("%s", "%s");'), (<class 'django.forms.widgets.Textarea'>, u'pythia.inlineEditTextarea("%s", "%s");'), (<class 'django.forms.widgets.Select'>, u'pythia.inlineEditSelect("%s", "%s");'), (<class 'django.forms.widgets.Widget'>, u'pythia.inlineEditWidget("%s", "%s");'))

class pythia.widgets.LocationWidget(attrs=None)

Bases: django.forms.widgets.MultiWidget

DIRECTION_CHOICES = ((u'', u'---'), (u'N', u'N'), (u'NNE', u'NNE'), (u'NE', u'NE'), (u'ENE', u'ENE'), (u'E', u'E'), (u'ESE', u'ESE'), (u'SE', u'SE'), (u'SSE', u'SSE'), (u'S', u'S'), (u'SSW', u'SSW'), (u'SW', u'SW'), (u'WSW', u'WSW'), (u'W', u'W'), (u'WNW', u'WNW'), (u'NW', u'NW'), (u'NNW', u'NNW'))

decompress(value)

format_output(rendered_widgets)

media

class pythia.widgets.NumberInput(attrs=None)

Bases: django.forms.widgets.TextInput

input_type = u'number'

media

pythia.models Module

Custom User model

A custom User model provides

Custom model mixins and managers

Coming soon.

pythia.documents.models Module

pythia.documents.admin Module

pythia.documents.templatetags.documents Module