Jobs
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}.xmlOptional 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_ancestorsResponse
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.
1 Status: 200 OK 2 3 <job> 4 <id type="integer">90</id> 5 <job-type-id type="integer">8</job-type-id> 6 <!-- if include=job_ancestors --> 7 <parent> 8 ... 9 <parent> 10 ... 11 </parent> 12 </parent> 13 <!-- else --> 14 <parent-id type="integer">88</parent-id> 15 <!-- end --> 16 <name>UFO #7856</name> 17 <code/> 18 <description>Need to enlarge photograph to look for wires</description> 19 <url/> 20 <!-- active: controls whether this job and its descendents are active 21 (note, even if active is true, a job will be effectively inactive if 22 one of its ancestors is inactive) --> 23 <active type="boolean">true</active> 24 <!-- effectively-active: false if this job or any ancestor is inactive --> 25 <effectively-active type="boolean">true</effectively-active> 26 <!-- if include=timestamps --> 27 <created-at type="datetime">2010-02-21T18:18:11Z</created-at> 28 <updated-at type="datetime">2010-02-21T18:18:11Z</updated-at> 29 <!-- end --> 30 </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.xmlYou 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.xmlOptional 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=timeResponse
1 Status: 200 OK 2 3 <jobs type="array"> 4 <job> 5 <id type="integer">92</id> 6 <job-type-id type="integer">7</job-type-id> 7 <parent-id type="integer" nil="true"/> 8 <name>Artworks</name> 9 <code/> 10 <description/> 11 <url/> 12 <active type="boolean">true</active> 13 <effectively-active type="boolean">true</effectively-active> 14 <!-- allow-time-entries will be returned if for=time 15 (note: this value comes from the corresponding job type)--> 16 <allow-time-entries type="boolean">true</allow-time-entries> 17 <!-- allow-expense-entries will be returned if for=expenses 18 (note: this value comes from the corresponding job type)--> 19 <allow-expense-entries type="boolean">true</allow-time-entries> 20 <!-- assigned will be returned when requesting the current user's assignments 21 (assigned=false for ancestors of jobs assigned to the current user which 22 are not assigned themselves) --> 23 <assigned type="boolean">false</assigned> 24 </job> 25 <job> 26 <id type="integer">93</id> 27 <job-type-id type="integer">8</job-type-id> 28 <parent-id type="integer">92</parent-id> 29 <name>General overhead</name> 30 <code/> 31 <description/> 32 <url/> 33 <active type="boolean">true</active> 34 <effectively-active type="boolean">true</effectively-active> 35 <allow-time-entries type="boolean">true</allow-time-entries> 36 <allow-expense-entries type="boolean">true</allow-time-entries> 37 <!-- assigned will be returned when requesting the current user's assignments 38 (assigned=true for jobs directly assigned to the current user, 39 as well as descendents of those assigned jobs) --> 40 <assigned type="boolean">true</assigned> 41 </job> 42 <job> 43 ... 44 </job> 45 ... 46 </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:
1 <job> 2 <!-- name (required, unique for parent-id, max-length=50) --> 3 <name>Client interview</name> 4 <!-- parent-id (optional id of parent job) --> 5 <parent-id>95</parent-id> 6 <!-- active (optional boolean, default=true) --> 7 <active>true</active> 8 <!-- code (optional identifier, max-length=50) --> 9 <code>INT</code> 10 <!-- description (optional, max-length=255) --> 11 <description>3pm Friday</description> 12 <!-- url (optional external link, max-length=255) --> 13 <url>www.test.com</url> 14 </job>
Response
1 Status: 201 Created 2 3 <job> 4 <id type="integer">#{new-job-id}</id> 5 <job-type-id type="integer">9</job-type-id> 6 <parent-id type="integer">95</parent-id> 7 <name>Client interview</name> 8 <code>INT</code> 9 <description>3pm Friday</description> 10 <url>www.test.com</url> 11 <active type="boolean">true</active> 12 <effectively-active type="boolean">true</effectively-active> 13 </job>
Update
Request
PUT /jobs/#{job-id}.xmlInclude ANY of the following data with your request:
1 <job> 2 <name>Client interview</name> 3 <active>true</active> 4 <code>INT</code> 5 <description>3pm Friday</description> 6 <url>www.test.com</url> 7 </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}.xmlResponse
Status: 200 OK
