2996107 - OData API upsert error "Entity expects a complex but a single-valued key [...] is used" - SAP SuccessFactors HXM Suite

You're upserting a record via OData with a field which represents an association (ie. relationship or reference) to another existing record and are getting an error similar to the one below:

Image/data in this KBA is from SAP internal systems, sample data, or demo systems. Any resemblance to real data is purely coincidental.

• SAP SuccessFactors HXM Suite
  • OData API

The entity that is being upserted has a complex key (composed by more than one field/business key), but only one business key is being passed. Using the example above as context:

• The Position entity has two business keys: 'code' and 'effectiveStartDate';
• Only 'code' is being passed as the record's URI, which is not enough to uniquely identify the existing record.

All the business keys of the entity's existing record which you're referring to must be passed to compose a valid URI:

You can see the business keys of each entity by consulting the OData API Dictionary while logged into your SuccessFactors instance and navigating to Admin Center -> OData API Dictionary, or you may open the official SF OData API reference guide and search for the entity you're working with:

• SAP SuccessFactors HXM Suite OData API: Reference Guide

SAP SuccessFactors HXM Suite OData API: Reference Guide

2976724 - How to upsert with association for Custom MDF Objects in SuccessFactors OData API (inline)

upsert, insert, update, failure, fail, failed, fails, failing, error, unable, to, not, working, unsuccessful, successful, edit, employee central, ec, sf , KBA , LOD-SF-INT-ODATA , OData API Framework , LOD-SF-INT , Integrations , LOD-SF-INT-EC , Employee Central SFAPI & OData Entities , Problem