Help

Templates tools

Templates covers deliverable templates and project templates (which also serve as opportunity templates), with their tasks, phases, deliverables, statuses, lead scores and custom fields.

Like Setup, this toolset is offered only on accounts where Drum has turned on account setup through the API.

The toolset also has:

Tools

Each tool below shows what the server sends: its description (written for the AI), its kind, the permissions it needs, the fields it returns, and its inputs. An input in a.b or a[].b form is a field inside an object or a list. For the shared rules on results, pages, money and errors, see Results, errors and limits.

get_deliverable_template

Read one deliverable template with its tasks and the ids of all rows. Each row has its record_kind for delete_record. Tasks are concise, and response_format detailed adds their price fields and their resource and cost lines. include_deleted adds deleted_tasks, which restore_record can bring back. A dynamic task with no lines is worth zero, and the warnings say so. A null or empty task field is left out.

   
Title Get deliverable template
Toolsets Templates
Kind Read only, Idempotent
Needs api_read and customisation
Returns id, name, description, status, use_case, default_budget_type, colour, resource_type, contract_value, internal_budget, tasks, deleted_tasks, warnings
Input Type Required Description
deliverable_template_id integer Yes From search_records with kinds deliverable_template.
include_deleted boolean   Add deleted_tasks: the template’s deleted tasks that restore_record can restore.
response_format string   concise (default): id, record_kind, kind, name, item_type, position and description of each task. detailed adds the price fields and the resource and cost lines. One of concise, detailed.

create_deliverable_template

Create one deliverable template, with its tasks and their resource and cost lines if you send them. copy_from_id copies a template with its tasks first, and adds the tasks sent after them. This tool only adds data: change the template with update_deliverable_template and one row with add_deliverable_template_row or update_deliverable_template_row. After a timeout, read the deliverable templates with search_records before you try again. The result gives the fields and the ids of the new tasks and lines.

   
Title Create deliverable template
Toolsets Templates
Kind Writes data
Needs api_create and customisation
Returns id, name, description, status, use_case, default_budget_type, colour, resource_type, contract_value, internal_budget, task_count, tasks, warnings
Input Type Required Description
copy_from_id integer   The template to copy. From search_records with kinds deliverable_template.
name string   Required unless copy_from_id is sent.
description string    
status string   No effect: pickers, projects and proposals use a draft as they use an active template. One of draft, active.
use_case string   Offered on projects, sales or all_types. One of all_types, project, sales.
default_budget_type string   One of fixed_fee, time_and_materials.
colour string   One of red, orange, amber, yellow, lime, green, emerald, teal, cyan, sky, blue, indigo, violet, purple, fuchsia, pink, rose.
resource_type_id integer   From search_records with kinds resource_type.
tasks array of objects    
tasks[].kind string   fixed: quantity x rate. dynamic: sum of lines. One of fixed, dynamic, non_financial.
tasks[].name string Yes  
tasks[].item_type string   One of task, heading, event, process_only.
tasks[].description string    
tasks[].description_html string    
tasks[].delivery_task_name string   Its task name on a project.
tasks[].quantity number    
tasks[].quantity_unit string   One of hour, day, per_item.
tasks[].billable_rate_cents integer   Tax exclusive.
tasks[].resources array of objects    
tasks[].resources[].resource_type_id integer Yes From search_records with kinds resource_type.
tasks[].resources[].quantity number    
tasks[].resources[].quantity_unit string   One of hour, day, per_item.
tasks[].resources[].notes string    
tasks[].resources[].preferred_member_id integer   From search_records with kinds member.
tasks[].costs array of objects    
tasks[].costs[].cost_type_id integer Yes From search_records with kinds cost_type.
tasks[].costs[].name string Yes  
tasks[].costs[].description string    
tasks[].costs[].quantity number    
tasks[].costs[].quantity_unit string   One of hour, day, per_item.
tasks[].costs[].billable_rate_cents integer   Tax exclusive.

update_deliverable_template

Change the fields of one deliverable template. Omit a field to keep it, and send null to clear it. This tool does not change rows: use add_deliverable_template_row, update_deliverable_template_row and delete_record. default_budget_type is the budget type of the template, not the kind of a task. The result gives the fields and task_count, and get_deliverable_template reads the tasks.

   
Title Update deliverable template
Toolsets Templates
Kind Writes data, Idempotent
Needs api_update and customisation
Returns id, name, description, status, use_case, default_budget_type, colour, resource_type, contract_value, internal_budget, task_count, tasks, warnings
Input Type Required Description
deliverable_template_id integer Yes From search_records with kinds deliverable_template.
name string    
description string or null   null clears it.
status string   No effect: pickers, projects and proposals use a draft as they use an active template. One of draft, active.
use_case string   Offered on projects, sales or all_types. One of all_types, project, sales.
default_budget_type string   One of fixed_fee, time_and_materials.
colour string or null   null clears it.
resource_type_id integer or null   From search_records with kinds resource_type. null clears it.

add_deliverable_template_row

Add one row to a deliverable template: a task, or a resource or cost line of a task. row takes the keys of that row type, as get_deliverable_template shows them, and deliverable_template_task_id names the task of a new line. A new task can include its resources and costs, or copy_from_id copies a task of the same template with its lines. position (1 is first) places the row, and without it the row goes last, and row_type is the kind of the row for delete_record. After a timeout, read the template with get_deliverable_template before you try again.

   
Title Add deliverable template row
Toolsets Templates
Kind Writes data
Needs api_create and customisation
Returns deliverable_template_id, row_type, record_kind, row, rows, warnings
Input Type Required Description
deliverable_template_id integer Yes From search_records with kinds deliverable_template.
row_type string Yes One of deliverable_template_task, deliverable_template_task_resource, deliverable_template_task_cost.
deliverable_template_task_id integer   row_type deliverable_template_task_resource or deliverable_template_task_cost: the task, from get_deliverable_template.
position integer   1-based place in the row’s list.
row object Yes The keys of row_type, as get_deliverable_template shows that row.
row.kind string   fixed: quantity x rate. dynamic: sum of lines. One of fixed, dynamic, non_financial.
row.name string    
row.item_type string   One of task, heading, event, process_only.
row.description string    
row.description_html string    
row.delivery_task_name string   Its task name on a project.
row.quantity number    
row.quantity_unit string   One of hour, day, per_item.
row.billable_rate_cents integer   Tax exclusive.
row.resource_type_id integer   From search_records with kinds resource_type.
row.notes string    
row.preferred_member_id integer   From search_records with kinds member.
row.cost_type_id integer   From search_records with kinds cost_type.
row.copy_from_id integer   A task of the same template to copy, from get_deliverable_template.
row.resources array of objects    
row.resources[].resource_type_id integer Yes From search_records with kinds resource_type.
row.resources[].quantity number    
row.resources[].quantity_unit string   One of hour, day, per_item.
row.resources[].notes string    
row.resources[].preferred_member_id integer   From search_records with kinds member.
row.costs array of objects    
row.costs[].cost_type_id integer Yes From search_records with kinds cost_type.
row.costs[].name string Yes  
row.costs[].description string    
row.costs[].quantity number    
row.costs[].quantity_unit string   One of hour, day, per_item.
row.costs[].billable_rate_cents integer   Tax exclusive.

update_deliverable_template_row

Change one row of a deliverable template by row_type and id (from get_deliverable_template). Only the keys sent change, and null clears a field. This tool does not accept child lines: add a line with add_deliverable_template_row. A task keeps its kind unless you send kind, and a task with lines cannot become non_financial. position (1 is first) moves the row, and delete_record deletes a row with its row_type as kind.

   
Title Update deliverable template row
Toolsets Templates
Kind Writes data, Idempotent
Needs api_update and customisation
Returns deliverable_template_id, row_type, record_kind, row, rows, warnings
Input Type Required Description
deliverable_template_id integer Yes From search_records with kinds deliverable_template.
row_type string Yes One of deliverable_template_task, deliverable_template_task_resource, deliverable_template_task_cost.
id integer Yes Row id, from get_deliverable_template.
position integer   1-based place in the row’s list.
row object   The keys to change, as get_deliverable_template shows that row.
row.kind string   fixed: quantity x rate. dynamic: sum of lines. One of fixed, dynamic, non_financial.
row.name string    
row.item_type string   One of task, heading, event, process_only.
row.description string or null   null clears it.
row.description_html string or null   null clears it.
row.delivery_task_name string or null   Its task name on a project. null clears it.
row.quantity number    
row.quantity_unit string   One of hour, day, per_item.
row.billable_rate_cents integer   Tax exclusive.
row.resource_type_id integer   From search_records with kinds resource_type.
row.notes string or null   null clears it.
row.preferred_member_id integer or null   From search_records with kinds member. null clears it.
row.cost_type_id integer   From search_records with kinds cost_type.

get_project_template

Read one project or opportunity template with its phases, deliverables, statuses, lead scores and custom fields, and the ids of all rows. Send project_template_id, or baseline_use_case to read the baseline of Project Settings or Opportunity Settings, which has the statuses, lead scores and number generators. Each row has its record_kind for delete_record. include_deleted adds the deleted rows, which restore_record can bring back.

   
Title Get project template
Toolsets Templates
Kind Read only, Idempotent
Needs api_read and customisation
Returns id, name, description, status, use_case, baseline, default, code, contract_type, default_rate_card, numbering, phases, deliverables, statuses, lead_scores, custom_fields, warnings
Input Type Required Description
project_template_id integer   From search_records with kinds project_template. Or send baseline_use_case.
baseline_use_case string   project or opportunity, to read that baseline instead of an id. One of project, opportunity.
include_deleted boolean   Add the deleted rows. Default false.

create_project_template

Create one extra project or opportunity template, with its phases and deliverables if you send them. copy_from_id copies a template with its phases, deliverables, bookings and custom fields first, and adds the rows sent after them. This tool only adds data and never makes a baseline: change the template with update_project_template and one row with the row tools. After a timeout, read the project templates with search_records before you try again. Phases are for project templates only.

   
Title Create project template
Toolsets Templates
Kind Writes data
Needs api_create and customisation
Returns id, name, description, status, use_case, baseline, default, code, contract_type, default_rate_card, numbering, phases, deliverables, statuses, lead_scores, custom_fields, warnings
Input Type Required Description
use_case string Yes A template for projects or for opportunities. One of project, opportunity.
copy_from_id integer   The template to copy. From search_records with kinds project_template.
name string   Required unless copy_from_id is sent.
description string    
status string   One of draft, active.
contract_type string   One of fixed_price, time_and_materials.
default boolean   New projects or opportunities use a default template.
default_rate_card_id integer   An active account rate card, from search_records with kinds rate_card.
phases array of objects    
phases[].name string Yes  
phases[].description string    
phases[].colour string   A phase colour. One of gray, red, orange, yellow, blue, green, indigo.
deliverables array of objects    
deliverables[].deliverable_template_id integer Yes From search_records with kinds deliverable_template.
deliverables[].name string    
deliverables[].project_template_phase_name string   A phase of the template, by name.

update_project_template

Change the fields of one project or opportunity template, or of a baseline (Project Settings or Opportunity Settings) with baseline_use_case. Omit a field to keep it, and send null to clear it. This tool does not change rows: use add_project_template_row and update_project_template_row. code and the numbering fields are for a baseline only, and defer_number_until_quote for the opportunity baseline only.

   
Title Update project template
Toolsets Templates
Kind Writes data, Idempotent
Needs api_update and customisation
Returns id, name, description, status, use_case, baseline, default, code, contract_type, default_rate_card, numbering, phases, deliverables, statuses, lead_scores, custom_fields, warnings
Input Type Required Description
project_template_id integer   From search_records with kinds project_template. Or send baseline_use_case.
baseline_use_case string   project or opportunity, to change that baseline instead of an id. One of project, opportunity.
name string    
description string or null   null clears it.
status string   One of draft, active.
contract_type string   One of fixed_price, time_and_materials.
default boolean   New projects or opportunities use a default template.
code string or null   The type code of a baseline. null clears it.
default_rate_card_id integer or null   An active account rate card, from search_records with kinds rate_card. null clears it.
part_one_generator string or null   null clears it.
part_two_generator string or null   null clears it.
part_three_generator string or null   null clears it.
code_separator string or null   null clears it.
number_padding integer or null   Digits of the sequence. null clears it.
all_time_starting_number integer or null   null clears it.
joining_year_starting_number integer or null   null clears it.
number_prefix string or null   null clears it.
number_suffix string or null   null clears it.
client_number_padding integer or null   Digits of the client number. null clears it.
defer_number_until_quote boolean   Opportunity baseline only.

add_project_template_row

Add one row to a project or opportunity template: a phase, a deliverable (from a deliverable template), a status, a lead score or a custom field. row takes the keys of that row type, as get_project_template shows them. Phases go on an extra project template, statuses and custom fields on a baseline, and lead scores on the opportunity baseline. A custom field default goes in the default field that agrees with the field type. row_type is the kind of the row for delete_record. After a timeout, read the template with get_project_template before you try again.

   
Title Add project template row
Toolsets Templates
Kind Writes data
Needs api_create and customisation
Returns project_template_id, row_type, record_kind, row, rows, warnings
Input Type Required Description
project_template_id integer Yes From search_records with kinds project_template.
row_type string Yes One of project_template_phase, project_template_deliverable, project_status, lead_score, project_template_custom_field.
position integer   1-based place in the row’s list.
row object Yes The keys of row_type, as get_project_template shows that row.
row.name string    
row.description string    
row.colour string   A phase or status colour. One of gray, red, orange, yellow, blue, green, indigo.
row.deliverable_template_id integer   From search_records with kinds deliverable_template.
row.project_template_phase_id integer   A phase of the template, from get_project_template.
row.project_template_phase_name string   Or a phase name.
row.complete_status boolean   A project in this status is complete.
row.default boolean   The one status or lead score of a new record.
row.default_successful_status boolean   The status of a won opportunity.
row.default_lost_status boolean   The status of a lost opportunity.
row.sales_status_type string   One of standard, won, lost.
row.percentage integer   0 to 100.
row.custom_field_id integer   From search_records with kinds custom_field.
row.default_value string   For a text or select field.
row.default_number_value number   For a number field.
row.default_date_value string   yyyy-mm-dd.
row.default_array_value array of strings   For a multiselect field.
row.primary_filter boolean   A select field shown as a dashboard column and filter.

update_project_template_row

Change one row of a project or opportunity template by row_type and id (from get_project_template). Only the keys sent change, and null clears a field. position (1 is first) moves the row in its list, and project_template_phase_id moves a deliverable to another phase of the template. A custom field default must agree with the field type, and delete_record deletes a row with its row_type as kind.

   
Title Update project template row
Toolsets Templates
Kind Writes data, Idempotent
Needs api_update and customisation
Returns project_template_id, row_type, record_kind, row, rows, warnings
Input Type Required Description
project_template_id integer Yes From search_records with kinds project_template.
row_type string Yes One of project_template_phase, project_template_deliverable, project_status, lead_score, project_template_custom_field.
id integer Yes Row id, from get_project_template.
position integer   1-based place in the row’s list.
row object   The keys to change, as get_project_template shows that row.
row.name string    
row.description string or null   null clears it.
row.colour string or null   A phase or status colour. null clears it.
row.deliverable_template_id integer   From search_records with kinds deliverable_template.
row.project_template_phase_id integer or null   A phase of the template, from get_project_template. null clears it.
row.project_template_phase_name string   Or a phase name.
row.complete_status boolean   A project in this status is complete.
row.default boolean   The one status or lead score of a new record.
row.default_successful_status boolean   The status of a won opportunity.
row.default_lost_status boolean   The status of a lost opportunity.
row.sales_status_type string   One of standard, won, lost.
row.percentage integer   0 to 100.
row.custom_field_id integer   From search_records with kinds custom_field.
row.default_value string or null   For a text or select field. null clears it.
row.default_number_value number or null   For a number field. null clears it.
row.default_date_value string or null   yyyy-mm-dd. null clears it.
row.default_array_value array of strings   For a multiselect field.
row.primary_filter boolean   A select field shown as a dashboard column and filter.

sync_project_template_custom_fields

Copy the custom fields of a template to its active projects or opportunities, as the Sync To Active Projects button does. On each project, it adds the missing fields with their defaults and removes the empty fields that no template names. The sync runs in the background and gives the warning custom_fields_sync_queued. Ask the user before you call this tool.

   
Title Sync project template custom fields
Toolsets Templates
Kind Writes data, Destructive, Idempotent
Needs api_update, api_delete and customisation
Returns id, name, description, status, use_case, baseline, default, code, contract_type, default_rate_card, numbering, phases, deliverables, statuses, lead_scores, custom_fields, warnings
Input Type Required Description
project_template_id integer Yes From search_records with kinds project_template.