'An undeclared property' when trying to create record via Web API

Question

I am getting an error which I just cannot seem to debug. I am trying to create a custom activity entity via custom HTML/JavaScript web resource.

The user clicks a button and the following params:

var params = {
    '[email protected]': '/rob_faqs(guid-here)',
    'rob_source': 180840000,
    'subject': 'Signpost',
    'actualstart': new Date(),
    'actualend': new Date()
};

Are passed to this URL:

https://dynamicsorg/api/data/v8.2/rob_quickactions/

With the following headers:

xhr.setRequestHeader('OData-MaxVersion', '4.0');
xhr.setRequestHeader('OData-Version', '4.0');
xhr.setRequestHeader('Accept', 'application/json');
xhr.setRequestHeader('Content-Type', 'application/json; charset=utf-8');
xhr.setRequestHeader('Prefer', 'return=representation');

This gives me a HTTP code of 400 (bad request) and this error message:

An undeclared property 'rob_faqid' which only has property annotations in the payload but no property value was found in the payload. In OData, only declared navigation properties and declared named streams can be represented as properties without values.

Interestingly, I get this error whether I use an actual GUID or if I put some gibberish in there (suggesting it is not to do with the value being passed in).

I can create the records manually via the standard form.

I am using the odata.bind elsewhere within the same project with no errors.

Answer 1

When you want to set the value of a lookup field during the creation or update of a (new) record via the web API, you have to use either the Schema Name or the Logical Name of the lookup followed by the bind annotation.

• For default fields like primarycontactid the logical name has to be used (first column in the screenshot).
• For custom fields like rob_FaqId the schema name has to be used (second column in the screenshot).

var params = {
    '[email protected]': '/rob_faqs(guid-here)',
    'rob_source': 180840000,
    'subject': 'Signpost',
    'actualstart': new Date(),
    'actualend': new Date()
};

Screenshot of a solution > entities > your entity > fields:

So the general structure to create a new record with an already set lookup field via the web API is this:

{
  "[email protected]": "/relatedentitys(guid)" //don't forget the plural 's'
}

Or another example from the official documentation. How to create a new account record and directly assign an already existing contact as the primary contact.

var newAccountRecordObj = {
  "name": "Sample Account",
  "[email protected]": "/contacts(00000000-0000-0000-0000-000000000001)"
}

Answer 2

After a good night's sleep I realised my error. To set the value of a lookup field, you need to use the relationship scheme name, and not the property name.

Once I changed that, all worked fine.

Answer 3

While the accepted answer is correct in this instance, it doesn't seem to be the whole story. In some cases it's necessary to use <logical name>_<entity name>. For instance when doing a POST sharepointdocumentlocations, I had to use:

"[email protected]": "/contacts(xxxx)"
"[email protected]" "/sharepointdocumentlocations(xxx)"

This may be something to do with the fact that those relationships can point to more than one type of entity, but I haven't found any Microsoft documentation about it.

Answer 4

@Andy's answer was right track for more esoteric naming but I wasn't able to mentally map what they meant for my data.

To find my working value I ended up brute force trying all the unique variations of 20+ references to new_mylookupfield (and any partner fields as well) found in the metadata xml:

https://$yourCRMInstance.api.crm.dynamics.com/api/data/v9.2/$metadata

In my case none of the documented Schema names or relationship names worked - it ended up being (for lookup field: new_mylookupfield/entity: new_mycustomentity):

{[email protected]: "/systemusers(guid)"}