Jobs
Jobs in Kojo are the top level organization for construction, service or maintenance projects that your company is working on. In some external systems they may also be called "Projects" (Procore, PlanGrid). Other systems may have "Work Orders" (COINS) or "Service Jobs" (Sage) or use a "type" field to indicate special project types, but Kojo does not make such a distinction. These concepts should map directly to Jobs in Kojo.
important
If your system uses "sub-jobs" to classify phases, the Phase entity in Kojo should be used.
Schema​
Job​
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID | The unique job ID | "ckmnpybisiy5x08abky4g2d1f" |
| code | string | A unique human-readable code to represent this job | "01-300" |
| createdAt | DateTime | When this job was created | "2021-03-24 17:26:46.983Z" |
| defaultLocation | Location? | The default location for orders associated with this job | See Location docs |
| defaultTaxCode | TaxCode? | The default tax code to use for orders associated with this job | See TaxCode docs |
| locations | Location[] | The locations associated with this job | See Location docs |
| name | string | The job name | "Salesforce Tower 32nd Floor" |
| phases | Phase[] | The phases of this job | See Phase docs |
| costCategories | CostCategory[] | The cost categories of this job | See CostCategory docs |
| startDate | DateTime? | When this job was started | "2021-03-24 17:26:46.983Z" |
| state | JobState | The current state of the job | OPEN |
| users | User[] | The users tied to this job | See User docs |
| updatedAt | DateTime | When this job was last modified | "2021-03-24 17:26:46.983Z" |
| nextPurchaseOrderCounter | Number | Next purchase order number | 100 |
| isWorkOrder | boolean | is job a work order | true |
Enums​
JobState​
| Value | Description |
|---|---|
| OPEN | The job is currently active. |
| CLOSED | The job has been closed or cancelled |
Queries​
job​
Read a single job. You must specify either the job ID or the job code.
Parameters​
| Name | Description | Example |
|---|---|---|
| id | The ID of the job to fetch | "ckmnpybisiy5x08abky4g2d1f" |
| code | The code of the job to fetch | "01-300" |
Response​
A single Job object.
Example Query​
query {
job(code: "01-300") {
code
id
name
}
}
Example Response​
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
}
jobs​
Read all jobs, with pagination.
Parameters​
Accepts all standard pagination parameters.
Allowed orderBy fields: code, createdAt, id, name, startDate, updatedAt.
Allowed filter fields: code, createdAt, id, name, startDate, state, updatedAt.
Response​
A list of Job objects.
Example Query​
query {
jobs(limit: 10, orderBy: code) {
code
id
name
}
}
Example Response​
[
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
},
{
"code": "01-301",
"id": "ckmnpybi7ag5x08abky4g2d1f",
"name": "Kojo Center NE"
}
]
Mutations​
addLocationToJob​
Adds a Location to a job.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| jobId | ID | The job ID. | "ckmnpybisiy5x08abky4g2d1f" |
| locationId | ID | The location ID. | "ckb91ih6801ny0733cq3xncft" |
Response​
Returns the Job to which the location was added.
Example Mutation​
mutation {
addLocationToJob(
jobId: "ckmnpybisiy5x08abky4g2d1f"
locationId: "ckb91ih6801ny0733cq3xncft"
) {
id
}
}
Example Response​
{
"id": "ckmnpybisiy5x08abky4g2d1f"
}
removeLocationFromJob​
Removes a Location from a job. Either the job id or job code must be provided to uniquely identify which
job to remove the location from.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| jobId | ID | The job ID. | "ckmnpybisiy5x08abky4g2d1f" |
| jobCode | String | The job code. | "01-301" |
| locationId | ID | The location ID. | "ckb91ih6801ny0733cq3xncft" |
Response​
Returns the Job to which the location was removed.
Example Mutation​
mutation {
removeLocationFromJob(
jobId: "ckmnpybisiy5x08abky4g2d1f"
locationId: "ckb91ih6801ny0733cq3xncft"
) {
id
}
}
Example Response​
{
"id": "ckmnpybisiy5x08abky4g2d1f"
}
addUserToJob​
Adds a User to a job.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| jobId | ID | The job ID. | "ckmnpybisiy5x08abky4g2d1f" |
| userId | ID | The user ID. | "ckb91ih6801ny0733cq3xncft" |
Response​
Returns the Job to which the user was added.
Example Mutation​
mutation {
addUserToJob(
jobId: "ckmnpybisiy5x08abky4g2d1f"
userId: "ckb91ih6801ny0733cq3xncft"
)
}
Example Response​
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
}
removeUserFromJob​
Removes a User from a job.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| jobId | ID | The job ID. | "ckmnpybisiy5x08abky4g2d1f" |
| userId | ID | The user ID. | "ckb91ih6801ny0733cq3xncft" |
Response​
Returns the Job from which the user was removed.
Example Mutation​
mutation {
removeUserFromJob(
jobId: "ckmnpybisiy5x08abky4g2d1f"
userId: "ckb91ih6801ny0733cq3xncft"
) {
code
id
name
}
}
Example Response​
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
}
createJob​
Creates a new job.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| code | string | A unique human-readable code to represent this job | "01-300" |
| defaultLocationId | ID | The id of default location for orders associated with this job | "ckmnpybisiy5x08abky4g2d1f" |
| defaultTaxCodeId | ID | The id of the default tax code to use for orders associated with this job | "ckmnpybisiy5x08abky4g2d1f" |
| name | string | The job name | "Salesforce Tower 32nd Floor" |
| startDate | DateTime? | When this job was started | "2021-03-24 17:26:46.983Z" |
| state | JobState | The current state of the job | OPEN |
Response​
The created Job.
Example Mutation​
mutation {
createJob(
code: "01-300"
name: "Salesforce Tower 32nd Floor"
state: OPEN
) {
code
id
name
}
}
Example Response​
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
}
updateJob​
Updates a job. You must specify either the job ID or the job code.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| id | ID | The ID of the job to update. | "ckmnpybisiy5x08abky4g2d1f" |
| code | string | The code of the job to update. If both id and code are provided, the job's code will be updated to this value. | "01-100" |
| defaultLocationId | ID | The id of default location for orders associated with this job | "ckmnpybisiy5x08abky4g2d1f" |
| defaultTaxCodeId | ID | The id of the default tax code to use for orders associated with this job | "ckmnpybisiy5x08abky4g2d1f" |
| name | string? | The job name | "Salesforce Tower 32nd Floor" |
| state | JobState? | The current state of the job | OPEN |
| startDate | DateTime? | When this job was started | "2021-03-24 17:26:46.983Z" |
Response​
The updated Job.
Example Mutation​
mutation {
updateJob(
id: "ckmnpybisiy5x08abky4g2d1f"
name: "Salesforce Tower 32nd Floor"
state: OPEN
) {
code
id
name
}
}
Example Response​
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
}
upsertJobs​
Creates or Updates multiple jobs.
Parameters​
| Name | Type | Description | Example |
|---|---|---|---|
| code | string | The code of the job to update. | "01-100" |
| name | string | The job name | "Salesforce Tower 32nd Floor" |
| defaultLocationId | ID? | The id of default location for orders associated with this job | "ckmnpybisiy5x08abky4g2d1f" |
| defaultTaxCodeId | ID? | The id of the default tax code to use for orders associated with this job | "ckmnpybisiy5x08abky4g2d1f" |
| state | JobState? | The current state of the job | OPEN |
| startDate | DateTime? | When this job was started | "2021-03-24 17:26:46.983Z" |
Response​
A list of Jobs.
Example Mutation​
mutation {
upsertJobs(
inputs: [
{
id: "ckmnpybisiy5x08abky4g2d1f"
name: "Salesforce Tower 32nd Floor"
state: OPEN
}
]
) {
code
id
name
}
}
Example Response​
[
{
"code": "01-300",
"id": "ckmnpybisiy5x08abky4g2d1f",
"name": "Salesforce Tower 32nd Floor"
}
]
updatePurchaseOrderJobNextCounter​
Updates the counter for purchase order number generation. Only works if purchase order number generation is set up on a Job basis. Example: If the current PO number for a job (123) is 100, setting nextCounter to 500 will result in the next Purchase Order to start counting from 500.
important
This feature needs to be enabled by customer support request.
caution
If the counter value is already in use, the system will keep incrementing by 1 until a free slot is found.
Example Mutation​
mutation {
updatePurchaseOrderJobNextCounter(jobId: "clplwnip7019r8ohueet287tv", nextCounter: 10){
id
name
nextPurchaseOrderCounter
}
}
Example Response​
{
"data": {
"updatePurchaseOrderJobNextCounter": {
"id": "clplwnip7019r8ohueet287tv",
"name": "SFMTA 3rd Street Rail",
"nextPurchaseOrderCounter": 10
}
}
}