Including Nested Payloads with SData for SalesLogix

When you’re developing an application or customization using SData for SalesLogix, the fewer trips you make to the server the better. Moving data back and forth across the wire will always be the biggest bottleneck in your code, so making use of embedded payloads will save you some trips by bringing all the data you’re after back in one pass.

Before we get into things, what exactly are nested payloads? Maybe a better term might be “included” payloads. Either way, when you request an entity, or entities, via SData, some part of the entity might be missing, or incomplete. Why? Because of the way that relationships work in the entity model. For example, if you request an Account entity, the AccountManager is a relationship to the User entity. These relationship properties are not included by default in the Account entity unless you tell SData you want those too. If you include related entities, such as the AccountManager, when you get back the Account entity you’ll have an nested payload inside the Account payload. So, no need to make another trip back to the server to get the AccountManager. One thing to keep in mind, including related entites will increase the size of the data coming back in the SData feed, this is why these are not included by default, so be sure only include them when you really need them.

Adding An Included Entity In An SData URL

I think it is important to know what the SData URL looks like when doing anything with the client library. I think it helps to understand what you’re ultimately ending up with. It also helps to see what the data coming back looks like using your browser by using the URL. When you want to include related entities you simple add an “include” parameter to the query string. For example, consider this URL to get a specific account:

http://localhost:3333/sdata/slx/dynamic/-/accounts('AA2EK0013023')

Now, to include the AccountManager entity as an embedded payload, add to the URL as follows:

Now when the Account entity comes back it will include an nested payload for the AccountManager, but also a collection of payloads for each Contact related to the Account – all in one trip to the server.

Including Related Entities Using the C# Client Library

Now that you know what the URL with includes look like, let’s take a look at how to write the code and how to use the nested payloads. We’ll use the example above to get a single Account and include the AccountManager and all related Contacts for the Account as nested payloads.

using Sage.SData.Client.Atom;
using Sage.SData.Client.Core;
using Sage.SData.Client.Extensions;
//...
var service =new SDataService("http://localhost:3333/sdata/slx/dynamic/-/", "admin", "");
var req =new SDataSingleResourceRequest(service);
req.ResourceKind ="Accounts";
req.ResourceSelector ="'AA2EK0013023'";
// We have to include the entities we want returned as nested payloads
req.QueryValues.Add("include", "Contacts,AccountManager");
// We can access normal properties of the Account
varstring accountName = payload.Values["AccountName"].ToString();
// Now get nested payload for AccountManager
var accMgrPayload = (SDataPayload)payload.Values["AccountManager"];
// We can access properties in the AccountManager payload
var accMgrUserName = accMgrPayload.Values["UserName"].ToString();
// Get nested Contacts collection of payloads
var contactsPayloadCollection = (SDataPayloadCollection)payload.Values["Contacts"];
// And iterate through each one
foreach (SDataPayload contactPayload in contactsPayloadCollection)
{
// We can access properties in this Contact payload
var contactLastName = contactPayload.Values["LastName"].ToString();
}

The key is to just access the property in the entity and cast it to either an SDataPayload or a SDataPayloadCollection. Cool beans.

Ryan Farley is the Director of Development for Customer FX and creator of slxdeveloper.com. He's been blogging regularly about SalesLogix since 2001 and believes in sharing with the community. He loves C#, Javascript, Python, web development, open source, and Linux. He also loves his hobby as an amateur filmmaker.