REST API:composite record Resource

REST API:composite record Resource

From LongJump Support Wiki

REST API:composite record Resource
Jump to: navigation, search

Manage Composite Object records using the REST API.

Learn more:

Contents

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:

File:Lock-tiny.gif

Access to records owned by other team members:

File:Lock-tiny.gif

Get a composite Record

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

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://na.longjump.com/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://na.longjump.com/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://na.longjump.com/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

Method
GET
URI
https://na.longjump.com/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 in the primary record
  • {fieldname} specifies a field in the primary record (e.g. name)
  • {alias}.* specifies all fields in a secondary record
  • {alias}.{fieldname} specifies a field in a secondary record (e.g. tag.id)
...etc.
  • filter - Filtering criteria to filter the records
  • 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>
   ...
   <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 Additional Information
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)
Personal tools