Project Lifecycle

Introduction

In the following, we describe the setup of the lifecycle of a project. In more general, this is a workflow. The programmatic logic is defined in the Project class.

Overview

States

The workflow for a project serves the following states:

1. draft (initial state)
2. pending
3. open
4. ongoing
5. completed

The current state is stored in field_lifecycle.

Transitions

A project can traverse in the forward direction through the workflow with the following transitions:

1. submit (draft to pending)
2. publish (pending to open)
3. mediate (open to ongoing)
4. complete (ongoing to completed)

Additionally, a project can be reset to the initial state with the transition:

1. reset ({pending, open, ongoing, completed} to draft)

Therefore, a transition is only possible if a project holds certain properties. First of all, a transition from the current state to the new state has to exist. Further, the mediate transition requires that the project has applicants. These implications are also reflected in the access handling for the respective forms and API resources.

The transitions are unambiguous and only change the state of the given project. In contrast, respective forms and API resources contain business logic that changes the given project's properties and triggers other events. For example, the ProjectMediateForm sets the selected participants.

Administrative Forms

The administrative forms are served as minimal snippets to move a project within the project cycle. Current administrative roles are: Administrator. (@todo: Add Manager and Supervisor roles.)

Project Mediation Form

The form is defined in the ProjectMediateForm class.

Path: /projects/{project_uuid}/mediate
Access: The project has state open and has applicants. (@todo: Is not archived.) The user has an administrative role and has permission Use Project Mediate transition.
Required Information: The user has to select at least one participant.
Submit: Triggers the project transition mediate. Sets participants for project.

Technical Notes

• The routes for the administrative forms are defined in project.routing.yml. The transition default is essential to steer the access handling. Further, certain properties are inherited for the rest resources (see below).
• The access handling is defined in the TransitionController class.

API

The workflow uses the Drupal RESTful webservices. The different transitions are defined as RestResources in plugins. The following headers are required:

Authorization: Basic Auth or OAuth2
Content-Type: application/json

Project Mediation Resource

The plugin is defined in the ProjectMediateResource class.

Path: /api/projects/{uuid}/mediate
Access: The project has state open and has applicants. (@todo: Is not archived.) The user has permission Use Project Mediate transition.

GET

Returns information to build form. An example response:

{
    "resource": "project.mediate",
    "data": {
        "type": "project",
        "id": "66adf49e-4661-45f1-9a15-514f42b3d5d5",
        "title": "Wrechipodo Ludrit",
        "applicants": [
            {
                "type": "user",
                "id": "d53114fb-00ec-4039-853a-fa3956b4bcb7",
                "name": "Fredolina Tonito"
            },
            {
                "type": "user",
                "id": "7fbe9008-7e71-4b66-86ab-4de690596d39",
                "name": "Alexandria Frezza"
            }
        ]
    },
    "patch_required": {
        "selected_participants": "Array of uuid's of participants."
    }
}

PATCH

Triggers the project transition mediate and sets selected participants. An example request body:

{
    "selected_participants" : [
        "d53114fb-00ec-4039-853a-fa3956b4bcb7",
        "7fbe9008-7e71-4b66-86ab-4de690596d39"
    ]
}

Besides the usual there are workflow specific responses:

Code	Description
200	The project was mediated successfully.
403	Access denied (see access rules above).
409	There is a conflict between the requested and persistent data.
417	The request body does not have the correct format.
422	There was a problem modifying the project entity.

Technical Notes

• We use the parameter converter ProjectParamConverter to resolve the uuid of the projects.
• The REST routes are build in ProjectRestResourceRoutesTrait. Each route inherits the transition default, _custom_access requirement and parameters option from the parent route of the administrative form. Therefore, the rest resource plugin ID has to match the route ID of the administrative form.