Incorrect documentation/API Mock for instanceID

Development
1

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.

2

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.

3

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
4

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.

5

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?

6

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.

7

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 .csv.zip export.) We'll change this behavior with v1.1 so that the frontend displays the uuid: prefix if the instanceID has one.

8

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.