Using Extended Properties

Published by Rob Watt on November 9, 2015

Last updated on July 29, 2024

The reality of all enterprise platforms is the need to customize the data model. To accommodate this, OrderCloud designed a property called Extended Properties (XP) to allow enterprise customization of the OrderCloud data model. OrderCloud exposes the xp property on most resources allowing you to build a JSON object containing your custom properties. The JSON object can be as complex and deeply-nested as necessary. Additionally, the xp property is available for filtering in all list endpoints. Extended Properties allows you to overcome platform rigidity. To optimize the use of our data model, and to help you fully implement your B2B scenarios, we created a schema-less solution with xp and exposed it on virtually every API resource. We may not have Product.YourSpecialDataPoint, but we do have Product.xp.YourSpecialDataPoint.

What is XP?

The entire xp object must be 8000 bytes or less and must be a valid JSON object. Any key-value pairs of numbers, strings, booleans, arrays, and even other objects can be used.

Note, XP should be consistently typed per object. This means if you add a custom property specialField on User and store a string value, every other User should have specialField populated with a string or be null. If you create a User later where specialField stores an nested object instead, you'll want to go back an update all your Users or risk latent errors interacting with the API.

This is very similar to how you might think about creating your own database tables, not all rows needs to have the same values optionally populated, but the structure needs to be consistent with XP for each object type.

Adding XP

Let's say one of the requirements for your solution includes storing the age and gender of users. You can accomplish this by storing those data points in the user's xp. If you do not include JSON, xp will be set to null by default on all parent objects. To declare xp, simply replace the null value with the valid JSON.

API Reference: Create a new user

1POST https://api.ordercloud.io/buyers/{buyerID}/users HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json; charset=UTF-8
4
5  {
6    "Username": "janesmith",
7    "Password": "test12345",
8    "FirstName": "Jane",
9    "LastName": "Smith",
10    "Email": "jsmith@company.com",
11    "Phone": "555-555-5555",
12    "TermsAccepted": null,
13    "Active": true,
14    "xp": {
15      "Gender": "Female",
16      "Age" : 26
17    },
18    "AvailableRoles": [],
19    "DateCreated": "2019-06-04T20:35:36.38+00:00",
20    "PasswordLastSetDate": "2019-07-12T00:03:58.28+00:00"
21  }

Nesting XP

Let's say requirements have shifted and the solution now requires the ability to store information about the user's employment details, specifically job title and department. This can easily be accomplished using nested objects within xp.

API Reference: Create or update a user

1PUT https://api.ordercloud.io/buyers/{buyerID}/users/{userID} HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json; charset=UTF-8
4
5  {
6    "Username": "janesmith",
7    "Password": "test12345",
8    "FirstName": "Jane",
9    "LastName": "Smith",
10    "Email": "jsmith@company.com",
11    "Phone": "555-555-5555",
12    "TermsAccepted": null,
13    "Active": true,
14    "xp": {
15      "Gender": "Female",
16      "Age" : 26,
17      "EmploymentDetails" : {
18        "Position": "Developer",
19        "Department": "Tech"
20      }
21    },
22    "SecurityProfileID": "FullAccess",
23    "AvailableRoles": [],
24    "DateCreated": "2019-06-04T20:35:36.38+00:00",
25    "PasswordLastSetDate": "2019-07-12T00:03:58.28+00:00"
26  }

Modifying XP

Now let's say Jane Smith receives a promotion. To update her job title we can use PATCH to modify the relevant data. Instead of sending the entire user object, we can send the xp key and the object that we want to update, the other xp (gender and age) will persist.

API Reference: Partially update a user

1PATCH https://api.ordercloud.io/buyers/newbuyer/users/userID HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json; charset=UTF-8
4
5  {
6    "xp": {
7      "EmploymentDetails" : {
8        "Position": "Senior Developer",
9        "Department": "Tech"
10      }
11    }
12  }

Deleting XP

The only way to remove a specific xp from your resource is to use the Update (PUT) method. First GET the resource, then copy the response body returned, paste it into your PUT request and omit the xp key/value you wish to remove. Alternatively, if you don't need it actually deleted, you are able to set any xp's value to null. In the example below, we're removing the "Age" xp from this user.

API Reference: Get a single user

1GET https://api.ordercloud.io/buyers/{buyerID}/users/{userID} HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json; charset=UTF-8
4
5  {
6    "Username": "janesmith",
7    "Password": "test12345",
8    "FirstName": "Jane",
9    "LastName": "Smith",
10    "Email": "jsmith@company.com",
11    "Phone": "555-555-5555",
12    "TermsAccepted": null,
13    "Active": true,
14    "xp": {
15      "Gender": "Female",
16      "Age" : 26,
17      "EmploymentDetails" : {
18        "Position": "Developer",
19        "Department": "Tech"
20      }
21    },
22    "AvailableRoles": [],
23    "DateCreated": "2019-06-04T20:35:36.38+00:00",
24    "PasswordLastSetDate": "2019-07-12T00:03:58.28+00:00"
25  }

Then, use the response body from the request above (without the xp you wish to remove).

API Reference: Create or update a user

1PUT https://api.ordercloud.io/buyers/{buyerID}/users/{userID} HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json; charset=UTF-8
4
5  {
6    "Username": "janesmith",
7    "Password": "test12345",
8    "FirstName": "Jane",
9    "LastName": "Smith",
10    "Email": "jsmith@company.com",
11    "Phone": "555-555-5555",
12    "TermsAccepted": null,
13    "Active": true,
14    "xp": {
15      "Gender": "Female",
16      "EmploymentDetails" : {
17        "Position": "Developer",
18        "Department": "Tech"
19      }
20    }
21  }

Indexing XP

In order to filter on an xp key, you first need to create an xp index for it. After adding an xp index, all xp values for the matching ThingType/Key will be optimized to allow indexing. If you added an xp index after a lot of data has already been created, it can take a few minutes to process the retroactive update to those xp values.

Product and Submitted Order xp do not need to be indexed in order to be filtered since they are powered by our premium search functionality.

Filtering on XP

Not only can xp be used to extend the functionality of your application, but you can use filters to search for indexed xp values on any given resource. After all, how much benefit would xp provide if you couldn't query a subset of objects based on a specific xp value? All of the filtering capabilities that apply to regular values on OrderCloud objects also apply to xp values. This means you can search with all of the standard operators available (=,<,>). Below is an example of filtering for a deeply nested value in xp.

1GET https://api.ordercloud.io/buyers/newbuyer/users?xp.EmploymentDetails.Department=Tech HTTP/1.1
2Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
3Content-Type: application/json; charset=UTF-8

Note how the dot (".") notation is used in the query string to filter on the specified deeply nested xp field. Check out the advanced querying guide to learn more.

Conclusion

xp is a very powerful feature to extend the capabilities of your application. It provides the flexibility developers need to meet challenging requirements, giving you the ability to provide a highly customized solutions. Head over to the API Console to try it for yourself!

Still have questions?
Ask in our Community Channel