API v1.0.66 Release Notes

Released on Thursday, December 7, 2017

New Features

Customized Platform Object ID Generation

A big question we get from clients a lot is "How can I make the OrderCloud API IDs work nicely with the IDs from my ERP or other internal systems?".

Prior to API 1.0.66, you could either set the ID manually (which is a pain if you want incrementation to work well) or you could settle for the default platform random GUID, and keep track of your ERP integration ID in an xp, or some other work around.

We've added a new feature that aims to make this process much, much simpler! Incrementation Config allows you to create a customized pattern for ID generation.

Incrementation Config

1{
2  "ID": "",
3  "Name": "",
4  "LastNumber": 0,
5  "LeftPaddingCount": 0
6}

The important parts here are the LastNumber and the LeftPaddingCount.

Examples:

Objective: Every order from a buyer should start with the buyer company's name, TestCorp, so that it can be differentiated easily by the supplier. The total number of characters for an ID can only be 20 characters long. (ex: TestCorp-00000000001)

1. Create the Incrementor Config

POST /v1/incrementors/

1{
2  "ID": "config01",
3  "Name": "Bob",
4  "LastNumber": 0,
5  "LeftPaddingCount": 10
6}

1. Create the order using the Incrementor Config

POST /v1/orders/outgoing

1{
2    "ID":"TestCorp-{config01}"
3}

returns as:

1{
2  "ID": "TestCorp-00000000001",
3...
4}

If you make another order with this Incrementor Config, you'll get TestCorp-00000000002 and so on.

This Incrementor Config can be used for both object creation, and PATCH/PUT updates. Additionally, once created, the Incrementor Config's LastNumber reflects the last number incremented to. So, if the last ID generated by config01 was TestCorp-00000000011, the LastNumber for config01 would be 11 at that moment.

Caveats:

1 - Left-padding does not represent a maximum value for the ID. If you have

1{
2  "ID": "config01",
3  "Name": "Bob",
4  "LastNumber": 0,
5  "LeftPaddingCount": 1
6}

when you get to 99, the ID will continue incrementing. If you're using it as in the above example, where your ERP expects ONLY x number of characters, this is going to cause some problems.

2 - While you can reuse the same incrementator on different endpoints -- such as using config01 for both products and orders, for some reason -- the incrementation will be across both endpoints.

EX:

1Order 1 with `config01` - `Order-00000000001`
2Product 1 with `config01` - `Product-00000000002`
3Order 1 with `config01` - `Order-00000000003`
4Order 1 with `config01` - `Order-00000000004`
5Order 1 with `config01` - `Order-00000000005`
6Product 1 with `config01` - `Product-00000000006`

3 - If you're not careful about how you handle your asynchronous API calls, it's much easier to accidentally try to create duplicate IDs. So be hygienic with your async calls!

4 - If you decide to reset the incrementor's LastNumber, you can end up trying to create duplicate IDs again. Be careful!

Allowing a Buyer User to impersonate a Buyer User from a different company

Now, instead of a Buyer User only being able to impersonate a Buyer User within the same Buyer, a Buyer User can impersonate a Buyer User in a different Buyer, as long as they're within the same Seller organization.

This is useful if you have a customer user that works for multiple of your customers. This allows them to interact within those buyers uniquely, but maintain their user account easily.

Bug Fixes

Duplicate Products returned in ME Product Lists

We've fixed a problem where, sometimes in very large catalogs with complicated category structures, a user using a GET me/products list would return some duplicate products. This fix should also show some minor performance improvements for very large catalog list calls.

Post-Submit Order Changes Triggered Promotion Evaluation

Previously, if you tried to alter an order with a promotion after it had been submitted, and the promotion had expired, your alteration would throw an error. We've fixed this so that promotions are never evaluated after order submit now.

Various performance improvements and other small bug fixes.

What it says on the tin.