Syncd API Guide

A developers' guide to accessing Syncd programmatically.

Search API Guide

API Basics

Users and Groups

Jobs

Time Tracking

Expense Tracking

Billing Rates

Job Assignments

Job assignments link a user or group (including "all users") to a job or all jobs. Because jobs can be hierarchical, it's important to understand the following:

Job assignments are automatically inherited if descendant jobs have no assignments of their own.
If any assignments are created for a job, its parent's assignments will no longer apply to the job. None of the parent's assignments will be copied automatically to the child (even though this happens when overriding assignments using Syncd's web interface).

Only Job Managers can view, create and delete job assignments. If you'd like to view assigned jobs instead of job assignments, use the Jobs interface.

Show

Request

GET /job_assignments/#{job-assignment-id}.xml

Optional parameters

The following optional parameters can be used to include extra data:

include=[users,
         user_groups,
         jobs]

Response

 1 Status: 200 OK
 2 
 3 <job-assignment>
 4   <id type="integer">#{job-assignment-id}</id>
 5   <!-- if assigned to all users --->
 6   <users>all</users>
 7   <!-- else if assigned to no users --->
 8   <users>none</users>
 9   <!-- else if assigned to a user -->
10   <!--   if include=users -->
11   <user>
12     ...
13   </user>
14   <!--   else -->
15   <user-id type="integer">#{user-id}</user-id>
16   <!-- else if assigned to a user group --->
17   <!--   end -->
18   <!--   if include=user_groups -->
19   <user-group>
20     ...
21   </user-group>
22   <!--   else -->
23   <user-group-id type="integer">#{user-group-id}</user-group-id>
24   <!--   end -->
25   <!-- end -->
26   <!-- if assigned to all jobs --->
27   <jobs>all</jobs>
28   <!-- else if include=jobs -->
29   <job>
30     ...
31   </job>
32   <!-- else -->
33   <job-id type="integer">#{job-id}</job-id>
34   <!-- end -->
35   <!-- if include=timestamps -->
36   <created-at type="datetime">2008-01-08T03:47:52Z</created-at>
37   <updated-at type="datetime">2008-01-08T03:47:52Z</updated-at>
38   <!-- end -->
39 </job-assignment>

List

Any user can view their own assignments.

Request

All job assignments:

GET /job_assignments.xml

Assignments to a particular job (includes assignments to all jobs & inherited assignments):

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

Direct assignments to a particular job (excludes assignments to all jobs & inherited assignments):

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

Assignments related to a particular user (includes assignments to the user's groups and all users):

GET /users/#{user-id}/job_assignments.xml

Direct assignments to a particular user (excludes assignments to the user's groups and all users):

GET /users/#{user-id}/job_assignments/direct.xml

Assignments for a particular user group:

GET /user_groups/#{user-group-id}/job_assignments.xml

Since all assignments to user groups are direct, there's no separate method for requesting only direct assignments.

Optional parameters

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

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

The following optional parameters can be used to include extra data:

include=[users,
         user_groups,
         jobs]

For example:

GET /job_assignments.xml?include=users,user_groups,jobs

Response

1 Status: 200 OK
2 
3 <job-assignments type="array">
4   <job-assignment>
5     ...
6   </job-assignment>
7   ...
8 </job-assignments>

Create

Request

POST /job_assignments.xml

Include the following data with your request:

 1 <job-assignment>
 2   <!-- A user or group must be included -->
 3   <!--   To specify a user: -->
 4   <user-id>#{user-id}</user-id>
 5   <!--   To specify a user group: -->
 6   <user-group-id>#{user-group-id}</user-group-id>
 7   <!--   To specify all users: -->
 8   <users>all</users>
 9   <!--   To specify no users: -->
10   <users>none</users>
11   <!-- A job or all jobs must be included -->
12   <!--   To specify a job: -->
13   <job-id>#{job-id}</job-id>
14   <!--   To specify all jobs: -->
15   <jobs>all</jobs>
16 </job-assignment>

For example, to assign a user to a specific job:

1 <job-assignment>
2   <user-id>25</user-id>
3   <job-id>14</job-id>
4 </job-assignment>

Response

 1 Status: 201 Created
 2 
 3 <job-assignment>
 4   <id type="integer">#{new-job-assignment-id}</id>
 5   <user-id type="integer">25</user-id>
 6   <job-id type="integer">14</job-id>
 7   <!-- if include=timestamps -->
 8   <created-at type="datetime">2008-01-08T03:47:52Z</created-at>
 9   <updated-at type="datetime">2008-01-08T03:47:52Z</updated-at>
10   <!-- end -->
11 </job-assignment>

Delete

Request

DELETE /job_assignments/#{job-assignment-id}.xml

Response

Status: 200 OK

Continue to Activities