API: Project Phases

Project phases separate the whole of the project’s duration into smaller, distinct parts where each phase has its own start and end date. Such a phase will then have different focus on certain aspects of project management. E.g. while the first phase might be about gathering requirements, the second phase might be about implementing the requirements and the third phase might be about testing the implementation.

Phases within a project are concrete instances of a phase definition. That way, one or a number of project life cycles can be defined throughout the OpenProject instance and then be reused in different projects. Projects can enable or disable the use of a phase definition in a project and assign dates to the phase instances.

Actions

  • None currently

Linked Properties

Link Description Type Constraints Supported operations Condition
self This project phase ProjectPhase not null READ
definition This definition this phase relies on ProjectPhaseDefinition not null READ
project This project this phase is instantiated in Project not null READ

Local Properties

Property Description Type Constraints Supported operations
id Project phase’s id Integer x > 0 READ
name String READ
active Indicates whether the project phase is currently active within the project Boolean READ
createdAt Time of creation DateTime READ
updatedAt Time of the most recent change to the project phase DateTime READ

Methods

Get a project phase

Gets a project phase resource. This resource contains an instance of a ProjectPhaseDefinition within a project which can then have project specific dates.

id
integer

required path

Project phase id

Example:
1337

200

OK

ProjectPhaseModel
{
  "type": "object",
  "required": [
    "_type",
    "id",
    "name",
    "active",
    "createdAt",
    "updatedAt"
  ],
  "properties": {
    "_type": {
      "type": "string",
      "enum": [
        "ProjectPhase"
      ]
    },
    "id": {
      "type": "integer",
      "description": "The project phase's id",
      "minimum": 1
    },
    "name": {
      "type": "string"
    },
    "active": {
      "type": "boolean"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of creation"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Time of the most recent change to the project phase"
    },
    "_links": {
      "type": "object",
      "required": [
        "self",
        "definition",
        "project"
      ],
      "properties": {
        "self": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "This project phase.\n\n**Resource**: ProjectPhase"
            }
          ]
        },
        "definition": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The definition this phase relies on.\n\n**Resource**: ProjectPhaseDefinition"
            }
          ]
        },
        "project": {
          "allOf": [
            {
              "$ref": "#/components/schemas/Link"
            },
            {
              "description": "The project resource, that is the container of this phase.\n\n**Resource**: Project"
            }
          ]
        }
      }
    }
  },
  "example": {
    "_type": "ProjectPhase",
    "id": 1337,
    "title": "Initiating",
    "active": true,
    "createdAt": "2023-01-20T14:30:00.368Z",
    "updatedAt": "2023-05-23T11:57:48.618Z",
    "_links": {
      "self": {
        "href": "/api/v3/project_phases/23"
      },
      "definition": {
        "title": "Initiating",
        "href": "/api/v3/project_definitions/11"
      },
      "project": {
        "title": "Death Star 3.0",
        "href": "/api/v3/projects/11"
      }
    }
  }
}

404

Returned if the project phase does not exist or the client does not have sufficient permissions to see it.

Required permission: view project phase

{
  "_type": "Error",
  "errorIdentifier": "urn:openproject-org:api:v3:errors:NotFound",
  "message": "The requested resource could not be found."
}
ErrorResponse
{
  "type": "object",
  "required": [
    "_type",
    "errorIdentifier",
    "message"
  ],
  "properties": {
    "_embedded": {
      "type": "object",
      "properties": {
        "details": {
          "type": "object",
          "properties": {
            "attribute": {
              "type": "string",
              "example": "project"
            }
          }
        }
      }
    },
    "_type": {
      "type": "string",
      "enum": [
        "Error"
      ]
    },
    "errorIdentifier": {
      "type": "string",
      "example": "urn:openproject-org:api:v3:errors:PropertyConstraintViolation"
    },
    "message": {
      "type": "string",
      "example": "Project can't be blank."
    }
  }
}