Don't forget to check out our JSON RESTful APIs, they can help you utilize and extend Quickbase with ease.
Overview
Use API_CopyMasterDetail to copy a master record with its detail records, or to import only the detail records from one master record into a different master record. For example, you could copy a master Project record and its detail Task records. You also could import only the Task records from a selected master Project record into a different Project record.
You invoke this call on a table-level dbid for the master table to which you are copying or importing records.
API_CopyMasterDetail copies or imports all fields in selected records, regardless of the fields' permission and Auto-Fill settings. (When Auto-Fill is enabled, a field's value is copied when a user clicks the "Add Similar" button to add a new Project.)
This API does not copy file attachments with the records.
This API cannot exclude certain fields.
To copy or import records:
-
You must have appropriate permissions: view and create permission in both the master and detail tables to copy records, and view and create permission in the detail tables to import records.
-
The master table must contain a report link field as part of the relationship with each detail table. If the report link field does not exist for a relationship with a detail table, detail records for that table are not copied. You must have permission to view the report link fields.
To confirm that the report link field exists, view the relationship and check that the master table has a report link field whose target field is the reference field listed under the detail table. -
The key field for each table from which records will be copied or imported must be Record ID.
API_CopyMasterDetail will not copy or import any records if it detects any of the following conditions:
-
Records containing unique fields, such as custom key fields.
-
More than ten levels of recursion
-
Looping relationships. Loops occur when tables have reciprocal relationships. Because conditional reference fields can be configured with looping relationships, the API will not copy detail records from any relationship where the report link field points to a conditional reference field. (Read more about conditional reference fields.)
The figure below illustrates a looping relationship; the application contains three tables (Countries, Employees, and Cities), and has three one-to-many relationships linking each table to the other two tables:
If you have unique fields, looping relationships, or more than ten levels of recursion, you can use the relfids parameter to include only specific relationships, or disable recursion (by setting the recurse parameter to false).
How Quickbase maps predecessor relationships when it copies records
Tasks in a project usually occur in a specific order and one task cannot start until another task finishes. This means that one task depends on another one. A predecessor task is a task that must finish before another task can begin. When you specify a predecessor for a task, you set up a dependency between two tasks (which is why predecessors are sometimes also called dependencies). A successor task is a task that cannot start until another task finishes. (Read more about predecessors.)
If a detail record contains a predecessor field, Quickbase attempts to map predecessors as follows:
-
If the original detail records map to each other as predecessors, Quickbase duplicates this predecessor relationship when the records are copied.
-
If the original detail records map to predecessors that belong to a different master record, Quickbase cannot map the predecessor relationship because there is no corresponding copy of those detail records.
-
If the original detail record maps to predecessor records that fall into both of these categories, Quickbase maps those predecessors that it can.
Consider this example of copying master and detail records in a Project Management application, illustrated below. You copy a master Project record, called "Software Release", with detail Task records 1, 2, 3, 4. The new master record is called "Copy of Software Release" and has detail records 101, 102, 103, 104. The application has another master Project record, called "Product Review", with detail Task records 11 and 12. Quickbase maps predecessor relationships as follows:
-
2 has predecessor 1 and 11. When the records are copied, Quickbase sets the predecessor field for record 102 to 101, and ignores predecessor 11.
-
3 has predecessor 12. When the records are copied, Quickbase leaves the predecessor field for record 103 blank.
-
4 has predecessor 3. When the records are copied, Quickbase sets the predecessor field for record 104 to 103.
Request parameters
| Parameter | Value | Required for Copy (destrid=0)? | Required for Import? |
|---|---|---|---|
|
destrid |
The record id of the destination record to which you want the records copied. If you want to copy the source master record and its detail records, set this to 0. If you want to import detail records from a different master record, set this to the record id of the master record to which you want to import the detail records. |
yes |
yes |
|
sourcerid |
The record id of the source record from which you want to copy detail records. |
yes |
yes |
|
copyfid |
The field id of a text field used in the name of the new record, if destrid = 0. The name becomes “Copy of field value". This field cannot be a lookup, append-only text, or formula field. It also cannot be a unique or snapshot field. |
yes |
no |
|
recurse |
Set this parameter to true to copy all detail records associated with the master record's detail records recursively. This API supports up to 10 levels of recursion. Defaults to true. |
no |
no
|
|
relfids
|
A list of comma-separated report link field ids that specify the relationships you want to be copied. For example:
To copy all relationships (default), omit this parameter or set to "all". |
no |
no
|
|
ticket
|
The ticket needed for application access. |
yes, one of:
|
yes
|
|
usertoken |
The user token is an alternative means of authentication, used for API access. User tokens cannot be used to access the Quickbase UI. |
yes, one of:
|
|
|
apptoken
|
Supply a valid application token. |
yes, if app tokens are being used by this application |
yes, if app tokens are being used by this application |
|
udata
|
A string value that you want returned. It will not be handled by Quickbase but it will be returned in the response. One possible use is to maintain state in the calling application. |
no |
no |
Response values
| Element Name | Value |
|---|---|
|
action |
Echoes the originating request, for example, API_CopyMasterDetail. |
|
errcode |
Identifies the error code, if any. (See the Error Codes appendix for a list of possible error codes.) 0 indicates that no error was encountered. |
|
errtext |
Text that explains the error code. "No error" indicates that no error was encountered. |
|
parentrid |
The record id of the record to which the details records were copied. This is either the destination rid that was passed in or the rid of the new master record that was created. |
|
numcreated |
The total number of new records created by the copy. |
Sample XML Request
Copy master and detail records
POST https://target_domain/db/target_dbid
HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_CopyMasterDetail
<qdbapi>
<ticket>auth_ticket</ticket>
<apptoken>app_token</apptoken>
<udata>mydata</udata>
<destrid>0</destrid>
<sourcerid>1</sourcerid>
<copyfid>6</copyfid>
</qdbapi>
where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.
Import detail records to a different master record
POST https://target_domain/db/target_dbid
HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_CopyMasterDetail
<qdbapi>
<ticket>auth_ticket</ticket>
<apptoken>app_token</apptoken>
<udata>mydata</udata>
<destrid>3</destrid>
<sourcerid>1</sourcerid>
</qdbapi>
where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.
URL alternative
Copy master and detail records
https://target_domain/db/target_dbid?a=API_CopyMasterDetail&destRID=0&sourcerid=1
©fid=6&ticket=auth_ticket&apptoken=app_token
where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.
Import detail records to a different master record
https://target_domain/db/target_dbid?a=API_CopyMasterDetail&destrid=3&sourcerid=1
&ticket=auth_ticket&apptoken=app_token
where target_domain is the domain against which you are invoking this call, for example, quickbase.com. Read about this notation.
Sample response
<?xml version="1.0" ?>
<qdbapi>
<action>API_CopyMasterDetail</action>
<errcode>0</errcode>
<errtext>No error</errtext>
<parentrid>3</parentrid>
<numcreated>4</numcreated>
</qdbapi>