Setup tools
Setup covers an account’s catalogs: resource types, cost types, custom fields, milestone types, project roles, booking types and rate cards, and the proposal numbering.
Drum offers Setup, Templates and Proposal templates only on accounts where it has turned on account setup through the API. They are for setting up an account, usually during onboarding.
Each save_ tool creates a record when you send no id, and changes the record when you send one. It has no idempotency key, because names need not be unique. Before you retry one after a timeout, check with search_records or list_settings_records whether the first call worked.
The toolset also has search_records, and delete_record and restore_record with the catalog kinds. get_account_settings and list_settings_records are also in Templates and Proposal templates.
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_account_settings
Read the setup of one account, with ids: templates of deliverables, projects, opportunities and proposals, resource types, cost types, rate cards, custom fields, milestone types, booking types, project roles, project and opportunity statuses, and lead scores. Call this first, before you add or change setup records. A section that you cannot see in Settings is empty. Find one record by name with search_records.
| Title | Get account settings |
| Toolsets | Setup, Templates, Proposal templates |
| Kind | Read only, Idempotent |
| Needs | api_read, and customisation or read_quotes |
| Returns | account, deliverable_templates, project_templates, project_statuses, lead_scores, proposal_templates, resource_types, cost_types, rate_cards, custom_fields, milestone_types, booking_types, project_roles |
This tool takes no input.
list_settings_records
List the records of one setup kind with all their setup fields, one page at a time, for example the entries of a rate card or the permissions of a project role. Find a record’s id with search_records: this tool is for what search_records does not give, the setup fields and the deleted records. include_deleted adds the deleted records, which restore_record can bring back. has_more is true when more records exist, and offset reads the next page.
| Title | List settings records |
| Toolsets | Setup, Templates, Proposal templates |
| Kind | Read only, Idempotent |
| Needs | api_read, and the read permission of the kind’s settings screen |
| Returns | kind, records, count, limit, offset, has_more |
| Input | Type | Required | Description |
|---|---|---|---|
kind |
string | Yes | The setup kind to list. One of milestone_type, deliverable_template, deliverable_template_task, project_template, project_status, lead_score, project_template_custom_field, project_template_deliverable, proposal_template, custom_field, resource_type, cost_type, rate_card, proposal_template_rate_card, project_role, booking_type. |
include_deleted |
boolean | Add the deleted records. Default false. | |
limit |
integer | Default 25, maximum 100. | |
offset |
integer | Default 0. |
save_resource_type
Create or update one resource type (a staff role), as Settings > Staff Roles does: send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the resource types with search_records before you try again. default_member_ids makes the role the default billable role of those members, and optional_member_ids lets those members also bill under it. Each of the two lists replaces the set of members of that list, and delete_record or restore_record with kind resource_type deletes or restores the role.
| Title | Save resource type |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, name, description, colour, line_item_code, default_members, optional_members |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The resource type to update, from search_records with kinds resource_type. Omit to create. | |
name |
string | Required when creating. | |
description |
string or null | null clears it. | |
colour |
string or null | null clears it. | |
line_item_code_id |
integer or null | Default line item code for billing, from search_records with kinds line_item_code. null clears it. | |
default_member_ids |
array of integers | Replaces the set of members with this default role. From search_records with kinds member. | |
optional_member_ids |
array of integers | Replaces the set of members who can also bill under this role. From search_records with kinds member. |
save_cost_type
Create or update one cost type, as Settings > Cost Types does. Send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the cost types with search_records before you try again. default_finance_account_id must be an expense account that the caller can see, and default or expense_default true moves that flag from the cost type that had it. To delete or restore, use delete_record or restore_record with kind cost_type.
| Title | Save cost type |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, name, description, line_item_code, default_finance_account, show_on_cost_to_complete_estimates, include_summary_line, default, expense_default |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The cost type to update, from search_records with kinds cost_type. Omit to create. | |
name |
string | Required when creating. | |
description |
string or null | null clears it. | |
line_item_code_id |
integer or null | Default line item code for billing, from search_records with kinds line_item_code. null clears it. | |
default_finance_account_id |
integer or null | Default expense account, from search_records with kinds finance_account. null clears it. | |
show_on_cost_to_complete_estimates |
boolean | Show the type in cost to complete estimates. | |
include_summary_line |
boolean | Add a summary line for the type on invoices. | |
default |
boolean | The default cost type for project expenses. | |
expense_default |
boolean | The default cost type for expense claims. |
save_custom_field
Create or update one project custom field, as Settings > Custom Fields does: send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the custom fields with search_records before you try again. field_type is set on create and cannot change. options replaces the options of a select or multiselect field, which needs two or more, and number_unit applies to a number field only. To delete or restore, use delete_record or restore_record with kind custom_field.
| Title | Save custom field |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, label, field_type, helper_text, placeholder, number_unit, options |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The custom field to update, from search_records with kinds custom_field. Omit to create. | |
label |
string | Required when creating. | |
field_type |
string | Required when creating. Set on create only. One of text, long_text, link, number, date, date_and_time, select, multiselect, single_file, multiple_files. |
|
helper_text |
string or null | Help text under the field. null clears it. | |
placeholder |
string or null | Text in the empty field. null clears it. | |
number_unit |
string or null | The unit of a number field. null clears it. | |
options |
array of strings | Replaces the options of a select or multiselect field. |
save_milestone_type
Create or update one milestone type, as Settings > Milestone Types does. Send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the milestone types with search_records before you try again. To delete or restore a milestone type, use delete_record or restore_record with kind milestone_type.
| Title | Save milestone type |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, name, colour |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The milestone type to update, from search_records with kinds milestone_type. Omit to create. | |
name |
string | Required when creating. | |
colour |
string or null | null clears it. |
save_project_role
Create or update one project or opportunity role, as Settings > Project Roles does: send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the project roles with search_records before you try again. use_case is set on create and cannot change, and a permission left out of permissions does not change. account_role_id limits who can hold the role, and the last role of a use case cannot be deleted with delete_record (conflict last_project_role).
| Title | Save project role |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, name, use_case, position, allow_multiple, primary_role, account_role, permissions |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The role to update, from search_records with kinds project_role. Omit to create. | |
name |
string | Required when creating. | |
use_case |
string | A role on projects or on opportunities. Set on create only. Default project. One of project, opportunity. |
|
position |
integer | 1-based place in the list of roles of the use case. | |
allow_multiple |
boolean | More than one person may hold the role on a project. | |
primary_role |
boolean | A primary role, which the project filters show. | |
account_role_id |
integer or null | Only members with this account role can hold the role. From search_records with kinds account_role. null clears it. | |
permissions |
object | The project permissions of the role. A permission left out does not change. | |
permissions.edit_all_time_entries |
boolean | ||
permissions.view_scheduled_invoices |
boolean | ||
permissions.create_scheduled_invoices |
boolean | ||
permissions.update_scheduled_invoices |
boolean | ||
permissions.delete_scheduled_invoices |
boolean | ||
permissions.view_invoices |
boolean | ||
permissions.create_invoices |
boolean | ||
permissions.update_invoices |
boolean | ||
permissions.delete_invoices |
boolean | ||
permissions.view_progress_claims |
boolean | ||
permissions.create_progress_claims |
boolean | ||
permissions.update_progress_claims |
boolean | ||
permissions.delete_progress_claims |
boolean | ||
permissions.view_budgets |
boolean | ||
permissions.update_budgets |
boolean | ||
permissions.delete_budgets |
boolean | ||
permissions.view_contract_value |
boolean | ||
permissions.view_internal_budget |
boolean | ||
permissions.view_resourcing |
boolean | ||
permissions.edit_resourcing |
boolean | ||
permissions.allow_over_budget_resourcing |
boolean |
save_booking_type
Create or update one booking type, as Settings > Booking Types does. Send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the booking types with search_records before you try again. resource_type_ids replaces the set of resource types that the booking type allows. To delete or restore, use delete_record or restore_record with kind booking_type.
| Title | Save booking type |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, name, description, colour, default_resource_type, resource_types |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The booking type to update, from search_records with kinds booking_type. Omit to create. | |
name |
string | Required when creating. | |
description |
string or null | null clears it. | |
colour |
string or null | null clears it. | |
default_resource_type_id |
integer or null | The role of a new booking, from search_records with kinds resource_type. null clears it. | |
resource_type_ids |
array of integers | Replaces the set of resource types that the booking type allows. From search_records with kinds resource_type. |
save_rate_card
Create or update one account rate card with its entries, as Settings > Rate Cards does: send no id to create, or its id to update. Omit a field to keep it, and send null to clear it. After a timeout, read the rate cards with search_records before you try again. is_default true makes the card the account default and expires the previous default. entries are role rates (resource_type) and member rates (member), each matched by id or by its rateable, and entries left out are kept. delete_record deletes an entry (kind rate_card_entry) or the card (kind rate_card).
| Title | Save rate card |
| Toolsets | Setup |
| Kind | Writes data |
| Needs | api_create to create or api_update to change, and customisation |
| Returns | deleted, warnings, id, name, description, status, effective_date, is_default, default_on_activation, project, proposal_budget, entries |
| Input | Type | Required | Description |
|---|---|---|---|
id |
integer | The rate card to update, from search_records with kinds rate_card. Omit to create. | |
name |
string | Required when creating. | |
description |
string or null | null clears it. | |
status |
string | Default active. One of draft, active, expired. |
|
effective_date |
string | The first day of the card, yyyy-mm-dd. Default today. | |
is_default |
boolean | Make the card the account default. | |
entries |
array of objects | Role and member rates. Entries left out are kept. | |
entries[].id |
integer | An entry of the card, from list_settings_records. Omit to add or match by rateable. | |
entries[].rateable_type |
string | resource_type for a role rate, member for a member rate. Required for a new entry. One of resource_type, member. |
|
entries[].rateable_id |
integer | From search_records with kinds resource_type or member. Required for a new entry. | |
entries[].billable_rate_cents |
integer | The hourly rate in cents, tax exclusive. 0 is refused unless allow_zero_value. | |
entries[].allow_zero_value |
boolean | Keep a zero rate. |
get_proposal_numbering
Read how proposal (quote) numbers are made, as Settings > Proposal Numbering shows it: the three generator parts, prefix, suffix, separator, padding and starting numbers. generator_options lists the values that each generator part accepts. Change the numbering with update_proposal_numbering.
| Title | Get proposal numbering |
| Toolsets | Setup |
| Kind | Read only, Idempotent |
| Needs | api_read and customisation |
| Returns | part_one_generator, part_two_generator, part_three_generator, number_prefix, number_suffix, code_separator, number_padding, all_time_starting_number, joining_year_starting_number, generator_options, warnings |
This tool takes no input.
update_proposal_numbering
Change how proposal (quote) numbers are made, as Settings > Proposal Numbering does. Omit a field to keep it, and send null to clear it. A part with no generator is left out of the number. get_proposal_numbering gives the current numbering.
| Title | Update proposal numbering |
| Toolsets | Setup |
| Kind | Writes data, Idempotent |
| Needs | api_update and customisation |
| Returns | part_one_generator, part_two_generator, part_three_generator, number_prefix, number_suffix, code_separator, number_padding, all_time_starting_number, joining_year_starting_number, generator_options, warnings |
| Input | Type | Required | Description |
|---|---|---|---|
part_one_generator |
string or null | The first part of the number. null clears it. | |
part_two_generator |
string or null | The second part of the number. null clears it. | |
part_three_generator |
string or null | The third part of the number. null clears it. | |
number_prefix |
string or null | Text before the number. null clears it. | |
number_suffix |
string or null | Text after the number. null clears it. | |
code_separator |
string or null | Text between the parts, for example -. null clears it. | |
number_padding |
integer or null | Digits of the sequence, 0 to 7. null clears it. | |
all_time_starting_number |
integer or null | The first number of an all time sequence. null clears it. | |
joining_year_starting_number |
integer or null | The first number of a sequence that starts again each year. null clears it. |