Incorrect documentation/API Mock for instanceID

In all examples of the API documentation, instanceID (and other tokens) is documented as having the form uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44. The mock server also requires this format as an input.

This is no longer correct: database stores tokens without the "uuid:", and calls to the live server do not accept this format, but rather simply 85cb9aff-005e-4edd-9739-dc9c1a829c44.

Dirty tricks are needed when you want to create test cases that work both on live and mock server.

I believe that an instanceID is permitted to have a uuid: prefix, but it is not required (though @LN should correct me if I'm wrong). There are a few factors that influence whether an instanceID has a uuid: prefix:

  • If a submission has a meta/instanceID field or an instanceID field, ODK Central will use the value of that field.
  • I believe that a form created using XLSForm will have a meta/instanceID field. The value for that field will have the uuid: prefix.
  • If a submission does not have a meta/instanceID or instanceID field, Central will generate an instanceID without the uuid: prefix.

You can ensure that an instanceID has a uuid: prefix by using a form with a meta/instanceID (or instanceID) field, then sending a submission whose value for that field has a uuid: prefix.

Tokens in Central (for sessions / app users / form drafts) have a little bit of a different format. For example, there are no hyphens.

Ok, I have to re-check, since I never have used extended metadata. Just one example: List all submissions (without extended metadata) returns a uuid-less version of id, and a deviceId not mentioned in the docs, which is NA in my case because I uploaded via API

(in R-Data frame format)

    instanceId submitterId deviceId                createdAt updatedAt
1 2ba7b619-f49a-43b4-9167-afc4f332c13d           5       NA 2020-11-04T15:21:40.237Z        NA

Good point about deviceId, I'll make a note about adding that to the API docs!

The X-Extended-Metadata header shouldn't affect the value of the instanceID. If the submission XML includes an instanceID with a uuid: prefix, then the API should return that same instanceID. For the submission XML to include an instanceID, the form needs to have a <meta><instanceID/></meta> or <instanceID/> field.

Let me understand: When I upload a XSLX, I do not get an instanceId with uuid.
If I understand correctly, the XML generated internally from XSLX is effectively used, the retained XSXL is for reference only.

Since I do not get a instanceID with uuid, it means that the conversion does not create the meta information.

Is this logic correct?

Interesting, that does seem unusual.

Yes, exactly. Does the XML of the form contain a <meta><instanceID/></meta> field? If so, then I think the next thing to check is whether the submission XML contains a value for that field and whether it contains a uuid: prefix.

I'm not sure this is directly related to your case, but we noticed that the Central frontend doesn't display the uuid: prefix when displaying the instanceID in the submissions table. In other words, if an instanceID includes the uuid: prefix, the API will return that unchanged, but the frontend will hide it. (The uuid: prefix is included in the export.) We'll change this behavior with v1.1 so that the frontend displays the uuid: prefix if the instanceID has one.

Interesting to know, but I believe this is not what I see, because I only work on the level of API and occasionally apiary, despite its quirks.