Phases

Phases in Kojo are the work breakdown/activity structure your company has defined. Currently Kojo does not support a nested phase structure (i.e. sub-phases), so external systems should flatten their phase structure if they wish to appopriately code them into Kojo. Depending on how you company chooses to implement them, phases can be defined at a global level or at a per-job level. Global phases do not have an associated job.

tip

Common phases seen in Kojo may include things like; "Rough-In", "Finishing", "Lighting", etc. It is best practice where feasable to standardize phases in order to conduct Job-to-Job analysis on phase estimation accuracy.

Schema

Phase

Name	Type	Description	Example
id	ID	The unique phase ID	"ckmnpybisiy5x08abky4g2d1f"
createdAt	DateTime	When this phase was created	"2021-03-24 17:26:46.983Z"
code	string	The human-readable code to identify this phase	"01-100"
costCategories	CostCategory[]	The cost categories that are allowed to be assigned to this phase	See CostCategory docs
description	string	A description of this phase	"Lighting"
job	Job	The job this phase is associated with	See Jobs docs
updatedAt	DateTime	When this phase was last modified	"2021-03-24 17:26:46.983Z"
defaultGLCode	string?	The default GL code for this phase	"123456"

Queries

Phase

Read a single phase.

Parameters

A phase ID must be specified, OR a job code/ID and phase code.

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
jobCode	string	The code of the job this phase is linked to	"01-300"
jobId	ID	The ID of the job this phase is linked to	"ckmnpybisiy5x08abky4g2d1f"
id	ID	The phase ID	"ckmnpybisiy5x08abky4g2d1f"

Response

A single Phase.

Example Query

query {
  phase(jobCode: "01-200", code: "L") {
    code
    description
    id
  }
}

Example Response

{
  "code": "L",
  "description": "Lighting",
  "id": "ckmnpybisiy5x08abky4g2d1f"
}

phases

Read all phases.

Parameters

Name	Type	Description	Example
jobCode	string	Only request phases for this job	"01-300"
jobId	ID	Only request phases for this job	"ckmnpybisiy5x08abky4g2d1f"

If neither a jobCode or jobId is provided, then only global phases will be returned.

Accepts all standard pagination parameters.

Allowed orderBy fields: code, createdAt, description, id, updatedAt.

Allowed filter fields: code, createdAt, description, id, updatedAt.

Response

A list of Phase objects.

Example Query

query {
  phases(limit: 10, orderBy: code) {
    code
    description
    id
  }
}

Example Response

{
  "phases": [
    {
      "code": "01-100",
      "description": "Lighting",
      "id": "ckmnpybisiy5x08abky4g2d1f"
    }
  ]
}

Mutations

createPhase

Creates a new phase and adds it to the specified job. A job code or ID must be specified in order for this operation to succeed.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
jobCode	string	The job this phase will be linked to	"01-300"
jobId	ID	The job this phase will be linked to	"ckmnpybisiy5x08abky4g2d1f"
defaultGLCode	string?	Optional. The default GL code for this phase	"123456"

If neither a jobCode or jobId is provided, a global phase will be created

Response

The created Phase.

Example Mutation (For Job)

mutation {
  createPhase(
    code: "01-200"
    description: "Rough-in"
    jobId: "ckmnpybisiy5x08abky4g2d1f"
  ) {
    id
  }
}

Example Mutation (Global)

mutation {
  createPhase(
    code: "01-200"
    description: "Rough-in"
  ) {
    id
  }
}

Example Response

{
  "id": "ckds5x1invtwj0804ftyg185b"
}

updatePhase

Updates a phase. A phase ID must be specified, OR a job code/ID and phase code.

Parameters

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
jobCode	string	The code of the job this phase is linked to	"01-300"
jobId	ID	The ID of the job this phase is linked to	"ckmnpybisiy5x08abky4g2d1f"
id	ID	The phase ID	"ckmnpybisiy5x08abky4g2d1f"
defaultGLCode	string	Optional. The default GL code for this phase	"123456"

Response

The updated Phase.

Example Mutation

mutation {
  updatePhase(
    id: "ckmnpybisiy5x08abky4g2d1f"
    description: "Rough-in"
  ) {
    description
  }
}

Example Response

{
  "description": "Rough-in"
}

deletePhase

This deletes a phase from the system on a specific job. This is a potentially unsafe operation which can create holes in cost tracking. All underlying Cost Codes associated with this Phase will also be deleted.

Parameters

Name	Type	Description	Example
id	ID	The phase ID	"ckmnpybisiy5x08abky4g2d1f"

Example Mutation

mutation {
  deletePhase(
    id: "ckds5x1invtwj0804ftyg185b"
  ) {
    id
    deletedAt
  }
}

Example Response

{
  "id": "ckds5x1invtwj0804ftyg185b",
  "deletedAt": "2023-12-19T14:01:20.699Z"
}

upsertPhase

Creates or Updates multiple phases at once.

Parameters

Name	Type	Description	Example
inputs	UpsertInput[]	A list of upsert inputs

Upsert Input

Name	Type	Description	Example
code	string	A unique human-readable code to represent this phase	"01-300"
description	string	A description of the phase	"Salesforce Tower 32nd Floor"
jobCode	string?	The job this phase will be linked to	"01-300"
jobId	ID?	The job this phase will be linked to	"ckmnpybisiy5x08abky4g2d1f"
defaultGLCode	string?	Optional. The default GL code for this phase	"123456"

Response

A list of Phases.

Example Mutation

mutation {
  upsertPhase(
    inputs: [
      {
        code: "01-200"
        description: "Rough-in"
        jobId: "ckmnpybisiy5x08abky4g2d1f"
      }
    ]
  ) {
    id
    code
    description
  }
}

Example Response

[
  {
    "id": "ckds5x1invtwj0804ftyg185b",
    "description": "Rough-in",
    "jobId": "ckmnpybisiy5x08abky4g2d1f"
  }
]