API_CopyMasterDetail

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.

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 Quick Base 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, Quick Base attempts to map predecessors as follows:

  • If the original detail records map to each other as predecessors, Quick Base duplicates this predecessor relationship when the records are copied.

  • If the original detail records map to predecessors that belong to a different master record, Quick Base 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, Quick Base 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.  Quick Base maps predecessor relationships as follows:

  • 2 has predecessor 1 and 11.  When the records are copied, Quick Base sets the predecessor field for record 102 to 101, and ignores predecessor 11.

  • 3 has predecessor 12.  When the records are copied, Quick Base leaves the predecessor field for record 103 blank.

  • 4 has predecessor 3.  When the records are copied, Quick Base sets the predecessor field for record 104 to 103.



top

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:

<relfids>7,9</relfids>

To copy all relationships (default), omit this parameter or set to "all".

no

 no

 

ticket

 

The ticket needed for application access.

yes, one of:

  • ticket
  • username/password
  • user token

yes

 

usertoken

The user token is an alternative means of authentication, used for API access. User tokens cannot be used to access the Quick Base UI.

yes, one of:

  • ticket
  • username/password
  • user token

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 Quick Base but it will be returned in the response. One possible use is to maintain state in the calling application.

no

no

top

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.

top

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.

top

URL alternative

Copy master and detail records

https://target_domain/db/target_dbid?a=API_CopyMasterDetail&destRID=0&sourcerid=1
&copyfid=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>