BigTime's task api provides access to all of the tasks assigned to any project in the system. Tasks cannot exist unless they are assigned to a project. The api will let you see tasks by staffer assigned as well (if assignments are filled out).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /task/listByProject/{ProjectSid}?{showCompleted=True/False} HTTP RESPONSE: (array of Task objects ("basic" view -- see below for details)
By default, we return only tasks that are "in process", but you can pass ShowCompleted=True to see tasks that are archived as well.
In addition to pulling a list of tasks from the system, you can also pull the current totals for time/expenses and invoice line item amounts on a per-task basis. That information is useful for budget reporting -- but it's not a part of the default view for task data.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /task/BudgetStatusByProject/{ProjectSid} HTTP RESPONSE: (array of TaskBudgetStatus objects (see below for details)
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /task/ListByStaffer/{StaffSid}?{showCompleted=True/False} HTTP RESPONSE: (array of Task objects ("basic" view -- see below for details)
By default, we return only tasks that are "in process", but you can pass ShowCompleted=True to see tasks that are archived as well.
You can use a simple GET request to pull the details associated with a single task. Note that the DETAIL view fields will be returned by default. You should also note that a user cannot pull data for an entity they are not permitted to view in the BigTime program. This can often become a problem when back-end services are using the api without system-wide permissions.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP GET: /task/detail/{TaskSid}?&View={Detailed/Basic} HTTP RESPONSE: (Task object -- see below for details)
Note that only the fields listed in the AddUpdate view (below) should be included in your post to this url. Any other data will be ignored. BigTime doesn't care about the order in which field data is posted, and none of the fields are case sensitive. Note that any validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to create a task withing a project you don't have rights to access).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP Post: /task/detail POST CONTENT: {TaskSid: 0, ProjectSid:0, Tasknm:"Test New Task"} You can include ANY of the AddUpdate fields below, but you MUST include the required (*) fields. HTTP RESPONSE: (new Task object -- see below for details)
Note that only the fields listed in the AddUpdate and Update views (below) should be included in your post to this url. Any other data will be ignored. Note again, validation errors will return a 400 error, and an invalid permission will return a 405 (eg - attempting to update tasks you don't have rights to access).
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP Post: /task/detail/{taskSid} POST CONTENT: {TaskSid: 123, notes: "this is an updated note..."} ** You can include ANY of the AddUpdate/Update fields below. However - you cannot "zero-out" or remove any of the required (*) fields. HTTP RESPONSE: (updated Task object -- see below for details)
As long as there is no time/expense data logged against a task, BigTime will allow you to delete it through the api.
HEADERS: X-Auth-Token:{YourAPIToken}, X-Auth-Realm:{YourFirmId} HTTP DELETE: /task/detail/{sid} HTTP RESPONSE: 200 is a successful delete.
For each of the operations listed above, you will post or "get" one or more task objects. The list below is a complete catalog of fields available through the api (including the views within which those fields are found). Take special note of the AddUpdate views. Required fields are flagged with an "*" character.
Field | Type | Description | View(s) |
---|---|---|---|
TaskSid | Integer | Unique SID code for this task (0 for new tasks). | Basic, Detailed, AddUpdate* |
ProjectSid | Integer | The SystemId of the project to which this task is assigned | Basic, Detailed, AddUpdate* |
ProjectLinkValue ProjectLinkType |
String Enum |
If you know a project's full displayName or it's Id, but not the project's SystemId, then you can still create a task. Just use these 2 alternate properties instead of the ProjectSid field and BigTime will automatically LOOKUP the correct ProjectSid value for you. ProjectLinkType Values: FindBySystemId(default) = 0; FindByProjectDName=2; FindByProjectCode=3; |
AddUpdate* |
TaskNm | String | Task "name" (or title) | Basic, Detailed, AddUpdate* |
TaskGroup | String | BigTime supports two-level task lists, and project plans can include a mix of tasks/sub-tasks. Any task with a TaskGroup is considered a sub-task. You can group tasks together in reports/UI by assigning them the same TaskGroup value. | Basic, Detailed, AddUpdate |
FullName | String | The fullname is another way of referencing a task. FullName is a read-only property that combines TaskGroup and TaskNm in TaskGroup:TaskNm format. A task with a TaskGroup value of "Design" and a TaskNm value of "Initial Project Plan" would have a FullName value of "Design:Initial Project Plan" |
Basic, Detailed |
TaskType (TypeLinkValue) |
Integer string |
Unique Id of the task's type. Every task in the system is assigned a type, and users can manage workflow and settings for each type individually. Think of the type as a "template" into which a given task will fit. Note that I assign a TYPE when I first create a task and then cannot alter that setting. TaskTypeName can be used in place of TypeSid if you know the full/unique name of this task type, but not the BigTime TypeSid code. If you specify TaskTypeName, then it will be ignored if TypeSid is set (TaskTypeName is valid ONLY for AddTask). |
Basic, Detailed, AddOnly* |
TaskType_nm | String | The NAME of the type to which this task is assigned. | Basic, Detailed |
CurrentStatus (StatusLinkValue) |
Integer string |
The current status is the current workflow "stage" for a task. While firms may have the same workflow stages for all of their task types, each type can support custom workflow. CurrentStatusName can be used in place of CurrentStatus if you know the full/unique name of this status code, but not the BigTime Id. If you specify CurrentStatusName, then it will be ignored if CurrentStatus is set (CurrentStatusName is valid ONLY for AddUpdate operations). |
Basic, Detailed, AddUpdate |
CurrentStatus_nm | String | Status "string" value (for display). | Basic, Detailed |
TaskId | String | If a project's tasks are re-orderd by the user, then we assign a taskId to each of them (so that the user's preferred order can be maintained). | Basic, Detailed, AddUpdate |
Priority | String | HIGH MEDIUM or LOW. | Basic, Detailed, AddUpdate |
Notes | String | Basic, Detailed, AddUpdate | |
AssignCount | Integer | Total number of staff members assigned to this task. | Basic, Detailed |
AssignmentList | LIST({Sid,Nm}) Post LIST(Sid) |
The Detailed view returns an array of objects ({Sid:0, Nm:""}) with the StaffSid and Nm of any staffer assigned to the task. Then, if you need to update the staffers assigned to a task, you can post back a simple list of StaffSid values (eg - [1,2,3]). Setting this value will REMOVE any old assignments and REPLACE them with the staffers posted to this field. | Basic, Detailed, AddUpdate |
AssignmentNames | String | While the AssignmentList[] array has an entry for every assigned staffer, this property returns a simple csv list of names as a string (useful for display). | Basic, Detailed |
AssignLinkListValue AssignLinkListType |
StringEnum |
If you know a staff member's name or their email, but not their BigTime StaffSid, then you can still create a task assignment. Just use these 2 alternate properties instead of the AssignmentList field and BigTime will automatically LOOKUP the correct StaffSid value(s) for you (note: separate multiple values with a comma (","). AssignListLinkType Values: FindByStaffSid(default) = 0; FindByFullName(First+Last)=1; FindByLastName=2; FindByEMail=3; |
AddUpdate* |
DueDt | Date | Date on which a task is "due." | Basic, Detailed, AddUpdate |
StartDt | Date | Tasks can have duration as well as due date. If a task has duration, it has a StartDt | Basic, Detailed, AddUpdate |
FeeOrExpense | Integer | If you are going to setup a budget for a task (eg - so that user can bill time/expenses against it) -- then use this value to determine whether the task appears on the user's timesheet, thier expense entry form(s) or both. Values are an enum (FeeOnly, ExpenseOnly, FeeAndExpense). | Basic, Detailed, AddUpdate |
BudgetHours | Numeric | HOURLY budget for the task | Basic, Detailed, AddUpdate |
BudgetFees | Numeric | Fee budget (eg - hours * bill rate). Note that we are tracking the budget for billable fees (not input cost). | Basic, Detailed, AddUpdate |
BudgetExps | Numeric | Expense (billable) budget. | Basic, Detailed, AddUpdate |
BudgetTotal | Numeric | Fee+Expense budget (useful for display). | Basic, Detailed |
PerComp | Numeric | Tasks can be active/complete, or they can be "partially completed" (often, firms like to track "percentage complete" on tasks so that they can track costs vs budget more carefully). This number is a decimal value between 0 and 1 (eg - a percentage). | Basic, Detailed, AddUpdate |
IsArchived | True/False | Setting this value to TRUE will automatically change the PerComp value to 100%. Likewise, setting the PerComp value to <1 (eg <100%) will change this archived value to FALSE. | Basic, Detailed |
DefaultQBClass | Integer | The SID code of the QuickBooks class to which time/expenses attached to a given task should be linked. Note that the system maintains a setting to indicate wehere a transactions class data should come from -- and the default hierarchy is STAFFER, PROJECT, TASK (based on the elements time or expense data is atttached to). | Basic, Detailed, AddUpdate |
IsSeriesMaster | True/False | If the task is a RECURRING engagement, then this value indicates that it is a series "master" (eg - changing it's values will change ALL of the non-archived tasks in the series). This is a read-only value. | Basic, Detailed |
MasterTaskSid | Integer | If this task is a RECURRING engagement, use this value to get the TaskSid for it's series "master." | Basic, Detailed |
ParentSid | Integer | Tasks can be arranged in a hierarchy using the parentSid value. | Basic, Detailed, AddUpdate |
NoCharge | True/False | TRUE if this task should be considered NoCharge for billing purposes. | Basic, Detailed, AddUpdate |
Field | Type | Description |
---|---|---|
TaskSid | Integer | Unique SID code for this task (0 for new tasks). |
HoursInput | Numeric | Total hours input against the task to date. |
HoursBill | Numeric | Total billable hours input against the task to date. |
FeesInput | Numeric | Total billable hours * bill rate input against the task to date. |
FeesCost | Numeric | Total input hours * cost rate input against the task to date. |
ExpensesInput | Numeric | Total expenses (cost) input against the task to date. |
ExpensesBillable | Numeric | Total expenses (billable) input against the task to date. |
TotalWip | Numeric | Total fees+expenses (billable) that have NOT been invoiced yet on a task. |