3094514 - Error message returned from OData API upsert request: "Entity expects a complex key but a single-valued key [...] is used" - SAP SuccessFactors HXM Suite

The following error message is found in the response payload of an upsert API request: 

{
            "editStatus": null,
            "httpCode": 500,
            "index": 1,
            "inlineResults": null,
            "key": null,
            "message": "Entity expects a complex key but a single-valued key [...] is used",
            "status": "ERROR"
}

NOTE: 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

As an example, if we perform a cost center record upsert like this:

{
        "__metadata": {
            "uri": "FOCostCenter(externalCode='ABC')"
        },
        "externalCode": "ABC",
        "name": "Cost Center A",
        "startDate": "/Date(1572566400000)/",
        "status": "A"
}

The following response is given:

{
            "editStatus": null,
            "httpCode": 500,
            "index": 1,
            "inlineResults": null,
            "key": null,
            "message": "Entity expects a complex key but a single-valued key ['ABC'] is used",
            "status": "ERROR"
}

Using the cost center example again: this error occurs because the FOCostCenter entity has 2 business keys defined in its metadata: externalCode and startDate, and in our request payload we've only passed the externalCode inside the parenthesis (key predicate). The key predicate should always contain all the values that compose the entity's key, which uniquely identifies a record.

NOTE: If you're passing multiple records inside a single request payload, and one of them has this issue, all the other records will not be upserted and will have the following status in the response: 202 Accepted. This happens because the API checks the request format first, before processing the records, and if one record has an incorrect payload format, the other records will not be processed.

Example: Upsert request with two records: one has the correct format and the other is incorrect

Request payload

{
        "__metadata": {
            "uri": "FOCostCenter(externalCode='ABC')"
        },,
        "externalCode": "ABC",
        "name": "Cost Center ABC",
        "startDate": "/Date(1572566400000)/",
        "status": "A"
},

{
        "__metadata": {
            "uri": "FOCostCenter(externalCode='DEF', startDate=datetime'2019-11-01T00:00:00')"
        },
        "externalCode": "DEF",
        "name": "Cost Center DEF",
        "startDate": "/Date(1572566400000)/",
        "status": "A"
}

Response payload

{
            "editStatus": null,
            "httpCode": 500,
            "index": 1,
            "inlineResults": null,
            "key": null,
            "message": "Entity expects a complex key but a single-valued key ['ABC'] is used",
            "status": "ERROR"
}

{
            "editStatus": null,
            "httpCode": 202,
            "index": 2,
            "inlineResults": null,
            "key": "FOCostCenter/externalCode=DEF,FOCostCenter/startDate=2019-11-01T00:00:00.000+02:00",
            "message": null,
            "status": "ACCEPTED"
}

As demonstrated, although the 'Cost Center DEF' record has a correct formatting and data, it is not upserted and processed because of the incorrect formatting detected on the other record.

When key predicate is used in your upsert payload format, always pass all the business key field values. You can confirm which fields are business keys by checking the entity's metadata, or the OData API Data Dictionary tool inside your SuccessFactors instance (Admin Center -> OData API Data Dictionary).

Example: business keys of the FOCostCenter entity, shown in the OData API Data Dictionary

upsert, odata, api, error, failed, fails, failing, message, payload, request, records, record, not, updated, inserted, created, modify, unable, possible, cannot, entity , KBA , LOD-SF-INT-ODATA , OData API Framework , LOD-SF-INT , Integrations , Problem