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:

API_CopyMasterDetail will not copy or import any records if it detects any of the following conditions:

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:

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:


predecessorcopied.png

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

yes

 

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

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/bdb5rjd6 HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_CopyMasterDetail

<qdbapi>
   <ticket>2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25</ticket>
   <apptoken>dtmd897bfsw85bb6bneceb6wnze3</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, intuit.quickbase.com.

Import detail records to a different master record

POST https://<target_domain>/db/bdb5rjd6 HTTP/1.0
Content-Type: application/xml
Content-Length:
QUICKBASE-ACTION: API_CopyMasterDetail

<qdbapi>
   <ticket>2_bdh78chd4_dpsx_b_dnbypa8d372j5rb6vt6kfdx7ty25</ticket>
   <apptoken>dtmd897bfsw85bb6bneceb6wnze3</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, intuit.quickbase.com.

top

URL alternative

Copy master and detail records

https://<target_domain>/db/<dbid>?a=API_CopyMasterDetail&destRID=0&sourcerid=
1&copyfid=6&ticket=<your_ticket>&apptoken=dtmd897bfsw85bb6bneceb6wnze3

where <target_domain> is the domain against which you are invoking this call, for example, intuit.quickbase.com.

Import detail records to a different master record

https://<target_domain>/db/<dbid>?a=API_CopyMasterDetail&destrid=3&sourcerid=
1&ticket=<your_ticket>&apptoken=dtmd897bfsw85bb6bneceb6wnze3

where <target_domain> is the domain against which you are invoking this call, for example, intuit.quickbase.com.

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>

top   

© 1999-2013 Intuit Inc. All rights reserved. Legal Notices.