Salesforce Composite Tree API typically refers to an API that allows you to work with tree-like data structures or hierarchical data. Trees are often used to represent data in a hierarchical manner, with a root node and various child nodes branching out from it. Composite Tree APIs provide methods and functions for creating unrelated records of the same type and creating nested records.
I will touch upon both the areas. However the stark difference between this API and Salesforce Graph API is that Graph API can support unrelated objects which may or may not be a part of the same root structure. On the other side, as name suggested, Salesforce Composite Tree API only works on the same root hierarchy. As you can see in the below diagram, the root of this tree is “Person Account” which is at level 1 and Contact Point Phone and Contact Point Email are branches of the Person Account and story goes on.
Benefits
- Because this a tree hierarchy, internal references between objects do not need to explicitly maintained or passed. This is huge benefit over Composite Graph API where you need to explicitly maintain all these references. As you can see in the below diagram, I have not mentioned any references explicitly. If you want to check how this has been maintained in the Graph API, then please check my blog on the Composite Graph API.
- As you can create up to 200 same types of records, you can replace your periodic bulk data load with this simple API.
- Entire composite API call with all the objects and records counts as a single call toward your API limits which is huge win if you are in a tight spot with respect to API usage.
- You can create as many records as possible with respect to Branches. So if you are trying to insert one Person Account and two contact Point Phone, then this Salesforce Composite Tree API is your best shot.
Limitations
- Composite Tree API can support up to a total of 200 records across all branches and roots included.
- Composite Tree API can support up to five records of different types which actually leads to the next point on the limitation.
- This API can provision a sObject trees up to five levels deep.
- All the objects should be connected by either Master-Details or Lookup relationship.
Scenario 1
You have a tree of records which you want to insert without being worried about internal reference check. In this scenario, I am going to insert Person Account, Contact Point Phone and Contact Point Consent in a single transaction. Moreover, I want to repeat this Salesforce Composite Tree API payload structure so that multiple Person Account and it’s related objects can be created.
Solution
URL – /services/data/v56.0/composite/tree/Account
Method – Post
Request body
{
"records": [
{
"attributes": {
"type": "Account",
"referenceId": "ref1"
},
"firstname": "Swagata",
"lastname": "Ray",
"RecordTypeId": "0128V0990010DtWQAU",
"ContactPointPhones": {
"records": [
{
"attributes": {
"type": "ContactPointPhone",
"referenceId": "ContactPointRef1"
},
"TelephoneNumber": "1234566788",
"IsPrimary": "true",
"ContactPointConsents": {
"records": [
{
"attributes": {
"type": "ContactPointConsent",
"referenceId": "ContactPointConsentRef1"
},
"name": "Swagata- Eligibility Consent - Phone",
"PrivacyConsentStatus": "OptIn"
}
]
}
},
{
"attributes": {
"type": "ContactPointPhone",
"referenceId": "ContactPointRef2"
},
"TelephoneNumber": "1234566789",
"IsPrimary": "false"
}
]
}
},
{
"attributes": {
"type": "Account",
"referenceId": "ref3"
},
"firstname": "Marlow",
"lastname": "Bob",
"RecordTypeId": "0128V0009910DtWQAU"
}
]
}Response
{
"hasErrors": false,
"results": [
{
"referenceId": "ref1",
"id": "0017700000KcuNWAAZ"
},
{
"referenceId": "ref3",
"id": "0017700000KcuNXAAZ"
},
{
"referenceId": "ContactPointRef1",
"id": "0Ow77000000Gp7qCAC"
},
{
"referenceId": "ContactPointRef2",
"id": "0Ow77000000Gp7rCAC"
},
{
"referenceId": "ContactPointConsentRef1",
"id": "0ZX77000000CkoDGAS"
}
]
}Explanation
You need to remember that this is a Salesforce Composite Tree API. So everything will start from root which is Account in this scenario. Another point to look into is that the resource URL hit the Account (Root) endpoint. Furthermore, all the child objects are represented as a Branch and then it is further ended up to sub Branch and so on. Records in the request JSON are root node. So you can repeat same payload under Records node to insert multiple records.
Scenario 2
You need to insert multiple records of same type in a single trsaction without using Bulk API where record limit is 200. Salesforce Composite Tree API is ready to do that job with more elegant way.
URL – /services/data/v56.0/composite/tree/Account
Method – Post
Request body
{
"records": [
{
"attributes": {
"type": "Account",
"referenceId": "ref1"
},
"firstname": "Swagata",
"lastname": "Ray",
"phone": "1234567890",
"website": "www.salesforce.com",
"RecordTypeId": "0128V0990010DtWQAU"
},
{
"attributes": {
"type": "Account",
"referenceId": "ref3"
},
"firstname": "John",
"lastname": "Jeff",
"phone": "9234567890",
"website": "www.salesforce.com",
"RecordTypeId": "0128V0990010DtWQAU"
}
]
}Response
{
"hasErrors": false,
"results": [
{
"referenceId": "ref1",
"id": "0017700000KcuNzAAJ"
},
{
"referenceId": "ref3",
"id": "0017700000KcuO0AAJ"
}
]
}Explanation
The beauty of this approach is its simplicity of usage. Addition to that error handling is also effortless because one of the root in the response JSON is marked with hasErrors”: false or true . This helps you to catch the error easily.
Conclusion
Salesforce Composite Tree API is one of the powerful offering in the Composite API realm and can able to reduce the API complexity greatly with it’s straightforward approach and error handling mechanism.
Leave a Reply