Syncd API
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}.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