REST API:composite record Resource

Manage Composite Object records using the REST API.

Learn more:

Working with Composite Objects
REST API Conventions and Considerations.

About the Examples

The examples on this page work on the following composite object:

That composite object is composed of the following objects and relationships:

Cases and Users: Many-to-One relationship. The relationship alias is notifyUser.
Cases and Comments: One-to-Many relationship. The relationship alias is comments.
Cases and Tags: Many-to-Many relationship. The junction object CaseTags. The relationship alias is tags.

(In this scenario, assume that the case system specifies whether the case represents a technical issue or an enhancement request. The tags are used to identify cases that apply to the GUI, or functionality (or both), as well as to mark important items.)

Requirements

Composite object relationships must be established by specifying the Cascade Rules and Aliases.
The cascade rules must permit the read, update, or delete operation requested.
The logged-in user must have the permissions needed to access and/or modify the object in question.

Record access:

In general, any user who can access an object can view all of the records it contains. (To access the object, they must be granted access to an application that contains it.)
One special case occurs when a record is owned by some other member of their team. In that case, the record becomes invisible, unless View permission has enabled in their Role Permissions, or unless their Access Profile gives them Global View permission.
Another special case occurs when Record Level Visibility has been enabled for an object, and visibility criteria has been specified for an individual record. In that case, a user who can see the record only when (a) They have been granted access to an application that contains the object, and (b) They match the visibility criteria specified for that record.
Users with Add permission enabled in Role Permissions or the Access Profile can add records
Users with Update permission enabled in Role Permissions or the Access Profile can update records
Users with Delete permission enabled in Role Permissions or the Access Profile can delete records

Access to records owned by other team members:

Read: View permission enabled in Role Permissions

unless Record Level Visibility has been enabled, and visibility criteria has been specified for a record. (In that case, only users who match the criteria can read the record.)

Update: Update permission enabled in Role Permissions
Delete: Delete permission enabled in Role Permissions

Get a composite Record

To get an object record's fields along with fields from related object records:

Use a Dynamic Search.
Or use the REST execSQL resource to fetch records from joined tables.

Add a composite Record

Considerations

As with all adds and updates, fields are optional.
Aliases are optional, as well.
For records specified within an alias, an Update is performed if the <id> field is present. Otherwise an Add is performed.
For records in an M:N relationship, a new record is added to the junction object, as needed.

Method: POST

URI: https://{yourDomain}/networking/rest/record/{objectName}

Request

<platform>
    <record>
        <field1>...</field1>
        <field2>...</field2>
         ...
        <alias1>
           <objectName>
               <id>...</id>        <!--OPTIONAL-->
               <field>...</field>
                ...
           </objectName>

           <objectName>
               <id>...</id>        <!--OPTIONAL-->
               <field>...</field>
                ...
           </objectName>
            ...
        </alias1>

        <alias2>
          ...
        </alias2>

         ...
    </record>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
        <id>...</id>   <!-- ID of the root record in the newly created composite -->
    </message>
</platform>

See also: REST API:Error Codes

Example: Add Comments and Tags When a Case is Added

Add a record in a One to Many and a Many to Many relationship.

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <record>
    <subject>TITLE OF CASE</subject>
    <comments>                        <!-- comments alias -->
      <comment>                          <!-- comment record -->
        <description>COMMENT TEXT           <!-- No ID => New comment -->
        </description>
        <myDate>2010-11-12T13:14:15Z</myDate>
      </comment>
    </comments>
    <tags>                            <!-- tags alias -->
      <tag>                              <!-- tag record -->
        <tag_id>234tyu678uio</tag_id>       <!-- ID => Existing tag -->
        <tag_text>high priority</tag>
      </tag>
      <tag>
        <tag_text>TAG TEXT</tag>            <!-- No ID => New tag -->
      <tag>
      </tag>
    </tags>
  </record>
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <message>
    <code>0</code>
    <description>Success</description>
    <id>54181298</id>
  </message>

Update a composite Record

Considerations

The considerations listed under Create a composite Record apply to updates. In addition:

For any alias that specifies a related object, all related records that are to be kept need to be included. For any related record that is not included:

In a one-to-many relationship, the related record is deleted.
In a many-to-many relationship, the linking record in the junction object is deleted. The related record is only deleted if cascade rules allow it and it is an orphan (no other records link to it).

Method: PUT

URI: https://{yourDomain}/networking/rest/record/{objectName}/{recordId}

Request

<platform>
    <record>
        <id>...</id>
        <field1>...</field1>
        <field2>...</field2>
         ...
        <alias1>
           <objectName>
               <id>...</id>        <!--OPTIONAL-->
               <field>...</field>
                ...
           </objectName>

           <objectName>
               <id>...</id>        <!--OPTIONAL-->
               <field>...</field>
                ...
           </objectName>
            ...
        </alias1>

        <alias2>
          ...
        <alias2>

         ...
    </record>

    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Example: Update User when a Case is Added

Update Users when a Case is Added in a Many to One relationship

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <record>
    <subject>TITLE OF CASE</subject>
    <notifyUser>
      <USER>
        <username>regulartenant@platform.com
        </username>
        <first_name>Tenant</first_name>
        <id>3f7fe2ab59ca400a946d612b9eb6a867
        </id>
        <last_name>LJ</last_name>
        <language>en</language>
        <customer_language>en</customer_language>
      </USER>
    </notifyUser>
  </record>
</platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <message>
    <code>0</code>
    <description>Success</description>
    <id>1994856670</id>
  </message>
</platform>

Example: Update User when a Case is Updated

Update Users when a Case is Updated in a Many to One relationship

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <record>
    <submitter>Platform Tenant</submitter>
    <myDate>2010-11-12T13:14:15Z</mydate>
    <notifyUserLookup>3f7fe2ab59ca400a946d612b9eb6a867</notifyUserLookup>
    <notifyUser>
      <USER>
        <id>3f7fe2ab59ca400a946d612b9eb6a867</id>
        <last_name>Fernwalader</last_name>
      </USER>
    </notifyUser>
  </record>
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>

Example: Update Case Record Only

Update Records in Cases Only

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <record>
    <id>1360212503</id>
    <subject>CASE SUMMARY</subject>
    <myDate>2010-11-12T13:14:15Z</myDate>
    <submitter>Platform Tenant</submitter>
  </record>
  <message>
    <code>0</code>
    <description>Success</description>
  </message>
</platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <message>
    <code>0</code>
    <description>Success</description>
  </message>

Example: Update Records

Update records of One to Many and Many to Many relationships, with multiple records in each relationship

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <platform>
    <record>
      <subject>CASE SUMMARY</subject>
      <myDate>2010-11-12T13:14:15Z</myDate>
      <comments>
        <comment>
          <id>1059386098</id>
          <description>UPDATED COMMENT TEXT
          </description>
          <myDate>2010-11-12T13:14:15Z</myDate>
        </comment>
        <comment>
          <id>1764597553</id>
          <description>UPDATED TEXT FOR COMMENT #2
          </description>
          <myDate>2010-11-12T13:14:15Z</myDate>
        </comment>
      </comments>
      <tags>
        <tag>
          <tag_id>234tyu678uio</tag_id> 
          <tag_text>high priority</tag>
        </tag>
        <tag>
          <tag_id>879uty534rwe</tag_id> 
          <tag_text>GUI</tag>
        <tag>
      </tags>
    </record>
    <message>
      <code>0</code>
      <description>Success</description>
    </message>
  </platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <platform>
    <message>
      <code>0</code>
      <description>Success</description>
    </message>
  </platform>

Delete a composite Record

Considerations

If cascade delete is not enabled, only the primary object is deleted.
If cascade delete is enabled:
- In a one-to-many relationship, the related object is deleted, as well.
- In a many-to-many relationship, the junction table link is removed.
  The related object is only deleted if it is an orphan (no more objects are pointing to it).

Method: DELETE

URI: https://{yourDomain}/networking/rest/record/{objectName}/{recordId}

Response

<platform>
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Example: Delete During Update in a Many to Many Relationship

Delete related records when a Case is Updated in a Many to Many relationship

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
    <record>
      <subject>CASE SUMMARY</subject>
      <myDate>2010-11-12T13:14:15Z</myDate>
      <comments>
        <comment>
          <id>860906505</id>
          <description>COMMENT TEXT</description>
          <myDate>2010-11-12T13:14:15Z</myDate>
        </comment>
      </comments>
      <tags>
        <tag>
          <tag_id>234tyu678uio</tag_id> 
          <tag_text>high priority</tag>
        </tag>
        <tag>
          <tag_id>879uty534rwe</tag_id> 
          <tag_text>GUI</tag>
        <tag>
      </tags>
    </record>
    <message>
      <code>0</code>
      <description>Success</description>
    </message>
  </platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <platform>
    <message>
      <code>0</code>
      <description>Success</description>
    </message>
  </platform>

Example: Delete all related records

Delete all related records

In case of Many to Many relationship, if the orphan delete flag is on, any orphan tags not related to cases should be deleted

Request

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <platform>
    <record>
      <subject>CASE SUMMARY</subject>
      <comments>
        <comment>
          <description>COMMENT #1
          </description>
        </comment>
        <comment>
          <description>COMMENT #2
          </description>
        </comment>
      </comments>
      <tags>
        <tag>
          <tag_id>234tyu678uio</tag_id> 
          <tag_text>high priority</tag>
        </tag>
        <tag>
          <tag_id>879uty534rwe</tag_id> 
          <tag_text>GUI</tag>
        <tag>
      </tags>
    </record>
    <message>
      <code>0</code>
      <description>Success</description>
    </message>
  </platform>

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
    <message>
      <code>0</code>
      <description>Success</description>
      <id>1194170623</id>
    </message>
</platform>

Dynamic Search for composite Records

Note: Performing a complex composite search on objects having multiple relationships may result in too many records being joined. This leads to longer response time by the REST API.

Method: GET

URI

https://{yourDomain}/networking/rest/record/{objectName}?{query_parameters}

Sample Search: ?fieldList=name,id&filter=name contains 'smith' & sortby='id'

Query Parameters

fieldList - A comma-separated list of field names to retrieve

The asterisk (*) wildcard specifies all fields
{fieldname} specifies an individual field (e.g. name)

(Use the REST API:field Resource to get a complete list of fields.)

For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
alias.* specifies all fields in the aliased object.

filter - Filtering criteria to filter the records

For more examples, see Filter Expressions in REST APIs and the REST API Examples.)

pageSize - Number of records to retrieve from the result set in order to make a "page".
page - Number of the logical page in a database result set. The first page is page "zero" (0).

Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.

getTotalRecordCount returns the number of total records.
Causes the following structure to be returned, where N is the total number of records:

<platform> 
   <status>
   <packageDeploy>
   ...
   </packageDeploy>
   </status>
   <message>
      <code>0</code>
      <description>Success</description>
   </message>

   <!-- added by the query param -->
   <totalRecordCount>N</totalRecordCount> 
</platform>

sortBy - Field name for primary sort
Ex: &sortBy=name
sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
Ex: &sortOrder=desc
sortBy2 - Field name for secondary sort
sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)

For more information, see: Specifying Query Parameters in REST APIs

Response

    ....
    <message>
        <code>0</code>
        <description>Success</description>
    </message>
</platform>

See also: REST API:Error Codes

Example: Search on root object fields

Search on root object fields. This is a normal, single-object search. It returns no related objects.

Request

https://{{domain}}/networking/rest/record/myCase?fieldList=*
https://{{domain}}/networking/rest/record/myCase?fieldList=id,subject,submitter

Example: Return all fields in a composite relationship

Search on fields in objects myCase and the related comment object (alias comments) in a One to Many relationship. Return all fields from both objects.

Request

https://{{domain}}/networking/rest/record/myCase?fieldList=id,subject,comments.description
https://{{domain}}/networking/rest/record/myCase?fieldList=*,comments.*

Example: Search multiple related objects

Search records in objects with One to Many and Many to Many relationships:

One to Many search is for the objects myCase and comment (alias comments)
Many to Many search is for the objects myCase and tag (alias tags)

Request

https://{{domain}}/networking/rest/record/myCase?fieldList=id,subject,submitter,number,comments.description,tags.description

Response

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<platform>
  <record>
    <id>1046950288</id>
    <submitter />
    <subject>CASE SUMMARY</subject>
    <number />

    <comments>
      <comment>
        <id>42937437</id>
        <description>COMMENT #1</description>
      </comment>
      <comment>
        <id>250916192</id>
        <description>COMMENT #2</description>
      </comment>
    </comments>

    <tags>
        <tag>
          <tag_id>234tyu678uio</tag_id> 
          <tag_text>high priority</tag>
        </tag>
        <tag>
          <tag_id>879uty534rwe</tag_id> 
          <tag_text>GUI</tag>
        <tag>
    </tags>

  </record>
</platform>

Example: Search composite objects using a filter criteria

Search records in objects with One to Many and Many to Many relationships, specifying filter criteria ('contains').

One to Many search is for the objects myCase and comment (alias comments)
Many to Many search is for the objects myCase and tag (alias tags)

Request

https://{{domain}}/networking/rest/record/myCase?fieldList=id,subject,submitter,number,comments.description,tags.description&filter=tags.description contains 'Test'

Fields

Name	Type	Required On	Description
id	String	Update	Record Id
{alias}	String	Add or Update	Name assigned to the object relationship
All other fields as defined for object records (optional)

Search

where to start

Feedback

customize and design

resources

Tools

Personal tools

REST API:composite record Resource

Contents

About the Examples

Requirements

Get a composite Record

Add a composite Record

Example: Add Comments and Tags When a Case is Added

Update a composite Record

Example: Update User when a Case is Added

Example: Update User when a Case is Updated

Example: Update Case Record Only

Example: Update Records

Delete a composite Record

Example: Delete During Update in a Many to Many Relationship

Example: Delete all related records

Dynamic Search for composite Records

Example: Search on root object fields

Example: Return all fields in a composite relationship

Example: Search multiple related objects

Example: Search composite objects using a filter criteria

Fields