AgileApps Support Wiki Pre Release

Difference between revisions of "REST API:composite record Resource"

From AgileApps Support Wiki
imported>Aeric
m (Text replace - '{domain}' to '{{domain}}')
imported>Aeric
 
(2 intermediate revisions by the same user not shown)
Line 491: Line 491:


===Dynamic Search for composite Records===
===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
;Method:GET


;URI:<tt>{{platformURL}}/rest/record/{objectName}?{query_parameters}</tt>
;URI:<tt>{{platformURL}}/rest/record/{objectName}?{query_parameters}</tt>
:;Sample Search:
:;Sample Search:
::<tt><nowiki>?fieldList=name,id & filter=name contains 'smith' & sortby='id'</nowiki></tt>
::<tt><nowiki>?fieldList=name,id&filter=name contains 'smith' & sortby='id'</nowiki></tt>


{{:REST API:Dynamic Search}}
{{:REST API:Dynamic Search}}

Latest revision as of 05:30, 25 October 2019

Manage Composite Object records using the REST API.

Learn more:

About the Examples

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

CASE Object Relationships.png

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:

Lock-tiny.gif

  • 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:

Lock-tiny.gif

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.)

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://{yourDomain}/networking/rest/record/{objectName}
Request
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <record>
       <field1>...</field1>
       <field2>...</field2>
        ...
       <alias1>
          <objectName>
              <id>...</id>        
              <field>...</field>
               ...
          </objectName>

          <objectName>
              <id>...</id>        
              <field>...</field>
               ...
          </objectName>
           ...
       </alias1>

       <alias2>
         ...
       </alias2>

        ...
   </record>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>...</id>   
   </message>

</platform> </syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <platform> 

 <record>
   <subject>TITLE OF CASE</subject>
   <comments>                        
     <comment>                          
       <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_text>TAG TEXT</tag>            
     <tag>
     </tag>
   </tags>
 </record>
 <message>
   0
   <description>Success</description>
 </message>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <platform> 

 <message>
   0
   <description>Success</description>
   <id>54181298</id>
 </message>

</syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <record>
       <id>...</id>
       <field1>...</field1>
       <field2>...</field2>
        ...
       <alias1>
          <objectName>
              <id>...</id>        
              <field>...</field>
               ...
          </objectName>

          <objectName>
              <id>...</id>        
              <field>...</field>
               ...
          </objectName>
           ...
       </alias1>

       <alias2>
         ...
       <alias2>

        ...
   </record>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<?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> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <platform> 

 <message>
   0
   <description>Success</description>
   <id>1994856670</id>
 </message>

</platform> </syntaxhighlight>

Example: Update User when a Case is Updated

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

Request
<syntaxhighlight lang="xml" enclose="div">

<?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>
   0
   <description>Success</description>
 </message>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <platform> 

 <message>
   0
   <description>Success</description>
 </message>

</platform> </syntaxhighlight>

Example: Update Case Record Only

Update Records in Cases Only

Request
<syntaxhighlight lang="xml" enclose="div">

<?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>
   0
   <description>Success</description>
 </message>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <platform> 

 <message>
   0
   <description>Success</description>
 </message>

</syntaxhighlight>

Example: Update Records

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

Request
<syntaxhighlight lang="xml" enclose="div">

<?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>
     0
     <description>Success</description>
   </message>
 </platform>

</syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 

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

</syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<?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>
     0
     <description>Success</description>
   </message>
 </platform>

</syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> 

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

</syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<?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>
     0
     <description>Success</description>
   </message>
 </platform>

</syntaxhighlight>

Response
<syntaxhighlight lang="xml" enclose="div">

<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <platform> 

   <message>
     0
     <description>Success</description>
     <id>1194170623</id>
   </message>

</platform> </syntaxhighlight>

Dynamic Search for composite Records

Notepad.png

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
  • 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:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

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

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • 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
<syntaxhighlight lang="xml" enclose="div">
   ....
   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

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
<syntaxhighlight lang="xml" enclose="div">

<?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> </syntaxhighlight>

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)
Retrieved from "https://agileappscloud.info/aadev-src/index.php?title=REST_API:composite_record_Resource&oldid=12755"