Jobs are the basic unit of work within Syncd. Every job has a "job type", such as client, project or task, which defines its possible properties and relationships to other jobs. Please consult Job Types for a thorough overview.

Job Managers can view, create, update and delete jobs. Other users can only view their assigned jobs. Job Managers are actually managers of a specific job type and all levels beneath that type (see the user / rights / manager-for-job-type-id node returned from User Information). Therefore, managers of the root job type can manage all jobs.

Jobs associated with time entries can not be deleted. Consider making them inactive instead.

Show

Request

GET /jobs/#{job-id}.xml

Optional parameters

Specify include=job_ancestors to include all of the ancestors of the requested job. The ancestors will be nested in the parent node. For example:

GET /jobs/#{job-id}.xml?include=job_ancestors

Response

Fields such as code, url and description should be hidden or display depending upon account settings (see the show-codes, show-links and show-descriptions properties for Job Types). These settings do not affect the API, which will always return these fields and any associated values. However, please respect these settings when developing your user interface.

Status: 200 OK

<job>
  <id type="integer">90</id>
  <job-type-id type="integer">8</job-type-id>
  <!-- if include=job_ancestors -->
  <parent>
    ...
    <parent>
      ...
    </parent>
  </parent>
  <!-- else -->
  <parent-id type="integer">88</parent-id>
  <!-- end -->
  <name>UFO #7856</name>
  <code/>
  <description>Need to enlarge photograph to look for wires</description>
  <url/>
  <!-- active: controls whether this job and its descendents are active
          (note, even if active is true, a job will be effectively inactive if
           one of its ancestors is inactive) -->
  <active type="boolean">true</active>
  <!-- effectively-active: false if this job or any ancestor is inactive -->
  <effectively-active type="boolean">true</effectively-active>
  <!-- if include=timestamps -->
  <created-at type="datetime">2010-02-21T18:18:11Z</created-at>
  <updated-at type="datetime">2010-02-21T18:18:11Z</updated-at>
  <!-- end -->
</job>

List

Managers of the root job type (see User Information) can request any jobs within an account. Other users can only request their own assigned jobs.

Request

All jobs:

GET /jobs.xml

All active jobs:

GET /jobs/active.xml

All inactive jobs:

GET /jobs/inactive.xml

Jobs assigned to the current user:

GET /jobs/my_assignments.xml

Active jobs assigned to the current user:

GET /jobs/my_active_assignments.xml

Inactive jobs assigned to the current user:

GET /jobs/my_inactive_assignments.xml

Children of a particular job (specify root for job_id to find jobs with no parent):

GET /jobs/#{job_id}/children.xml

You can also request active/inactive/assigned children of a job:

GET /jobs/#{job_id}/children.xml
GET /jobs/#{job_id}/children/active.xml
GET /jobs/#{job_id}/children/inactive.xml
GET /jobs/#{job_id}/children/my_assignments.xml
GET /jobs/#{job_id}/children/my_active_assignments.xml
GET /jobs/#{job_id}/children/my_inactive_assignments.xml

Optional parameters

Specify start and end to request a specific range of items. For example:

GET /jobs.xml?start=1&end=4

Specify for=time to limit jobs to those that allow time tracking. An extra allow-time-entries node will be returned for each job, indicating whether the job type associated with the job allows time entries. This is necessary because ancestor jobs will always be included, even if they don't meet the criteria of the filters.

Here's a sample request for all active jobs that can be associated with time entries:

GET /jobs/active.xml?for=time

Similarly, specify for=expenses to limit jobs to those that allow expense tracking. An extra allow-expense-entries node will be returned for each job, indicating whether the job type associated with the job allows expense entries.

GET /jobs/active.xml?for=expenses

Sample requests

Let's say that you'd like to request the current user's assigned jobs that can be associated with time entries. The most efficient way to do this would be to request all of the jobs together in one request:

GET /jobs/my_active_assignments.xml?for=time

If you don't want to request all of the jobs at once, you could request just the root level jobs:

GET /jobs/root/children/my_active_assignments.xml?for=time

You could then request the assigned children of each job:

GET /jobs/#{job_id}/children/my_active_assignments.xml?for=time

Response

Status: 200 OK

<jobs type="array">
  <job>
    <id type="integer">92</id>
    <job-type-id type="integer">7</job-type-id>
    <parent-id type="integer" nil="true"/>
    <name>Artworks</name>
    <code/>
    <description/>
    <url/>
    <active type="boolean">true</active>
    <effectively-active type="boolean">true</effectively-active>
    <!-- allow-time-entries will be returned if for=time
         (note: this value comes from the corresponding job type)-->
    <allow-time-entries type="boolean">true</allow-time-entries>
    <!-- allow-expense-entries will be returned if for=expenses
         (note: this value comes from the corresponding job type)-->
    <allow-expense-entries type="boolean">true</allow-time-entries>
    <!-- assigned will be returned when requesting the current user's assignments
         (assigned=false for ancestors of jobs assigned to the current user which
          are not assigned themselves) -->
    <assigned type="boolean">false</assigned>
  </job>
  <job>
    <id type="integer">93</id>
    <job-type-id type="integer">8</job-type-id>
    <parent-id type="integer">92</parent-id>
    <name>General overhead</name>
    <code/>
    <description/>
    <url/>
    <active type="boolean">true</active>
    <effectively-active type="boolean">true</effectively-active>
    <allow-time-entries type="boolean">true</allow-time-entries>
    <allow-expense-entries type="boolean">true</allow-time-entries>
    <!-- assigned will be returned when requesting the current user's assignments
         (assigned=true for jobs directly assigned to the current user,
          as well as descendents of those assigned jobs) -->
    <assigned type="boolean">true</assigned>
  </job>
  <job>
    ...
  </job>
  ...
</jobs>

Create

A new job's type can be inferred from its parent-id, so it is not necessary to declare job-type-id.

A new job will inherit the assignments and billing rates of its parent, if any exist.

Request

POST /jobs.xml

Include the following data with your request:

<job>
  <!-- name (required, unique for parent-id, max-length=50) -->
  <name>Client interview</name>
  <!-- parent-id (optional id of parent job) -->
  <parent-id>95</parent-id>
  <!-- active (optional boolean, default=true) -->
  <active>true</active>
  <!-- code (optional identifier, max-length=50) -->
  <code>INT</code>
  <!-- description (optional, max-length=255) -->
  <description>3pm Friday</description>
  <!-- url (optional external link, max-length=255) -->
  <url>www.test.com</url>
</job>

Response

Status: 201 Created

<job>
  <id type="integer">#{new-job-id}</id>
  <job-type-id type="integer">9</job-type-id>
  <parent-id type="integer">95</parent-id>
  <name>Client interview</name>
  <code>INT</code>
  <description>3pm Friday</description>
  <url>www.test.com</url>
  <active type="boolean">true</active>
  <effectively-active type="boolean">true</effectively-active>
</job>

Update

Request

PUT /jobs/#{job-id}.xml

Include ANY of the following data with your request:

<job>
  <name>Client interview</name>
  <active>true</active>
  <code>INT</code>
  <description>3pm Friday</description>
  <url>www.test.com</url>
</job>

Response

Status: 200 OK

Delete

Jobs associated with time or expense entries can not be deleted. Instead, deactivate them (update the job, setting active to false).

Request

DELETE /jobs/#{job-id}.xml

Response

Status: 200 OK

Continue to Job Assignments