Add client.submissions.edit to edit an existing submission

[lognaturel]

Use cases

Building block for a data cleaning pipeline that treats Central as the source of truth. User realizes one systematic error was made, they script identifying all of those errors and confirming them, then building updated submissions and submitting them using this method. They also specify a comment that looks something like "Scripted fix for fields foo, bar, baz".

Some kinds of issues I've fixed using similar building blocks:

• bad character encoding in CSV attachment (so you have F�� in your submissions)
• systematic place name misspellings (open field for administrative region, you want to normalize "Banaadir", "Bandir" to "Banadir")
• error in select underlying value that was fixed in later form version (so submissions from early form version have ff for female instead of f).

Proposed inputs

instance_id: str
form_id: str
comment: str
xml: str - a string representation of the new XML to submit. Must have the correct deprecatedID and a new instanceID

project_id: Optional[int] = None

Proposed output

Exception in case of any error state.

None in case of success. It could be an object representing the submission metadata after the update but I expect this would generally be ignored.

[lindsay-stevens]

@ln could you please share any more details on the intended use cases?

It seems to imply modifying a Submission and a Comment, so Central will return the updated data and there would be two different data types (one from each call). What would you expect to receive back from this method? e.g.

1. A tuple of the data like (Submission, Comment)
2. A generic complex type for the relationship like SubmissionComments, (since there can be many comments per submission, possibly even listing all comments on the submission) like

class SubmissionComments:
    submission: Submission
    comments: Set[Comment]

3. Nothing
4. Something else?

[lognaturel]

Ah yes, thank you for those questions.

more details on the intended use cases?

This would be a building block for a data cleaning pipeline that treats Central as the source of truth. So maybe a user realizes one systematic error was made, they script identifying all of those errors and confirming them, then building updated submissions and submitting them using this method. They also specify a comment that looks something like "Scripted fix for fields foo, bar, baz".

Some kinds of issues I've fixed using similar building blocks:

• bad character encoding in CSV attachment (so you have F�� in your submissions)
• systematic place name misspellings (open field for administrative region, you want to normalize "Banaadir", "Bandir" to "Banadir")
• error in select underlying value that was fixed in later form version (so submissions from early form version have ff for female instead of f).

I think over time we could look into helping users e.g. generate updated submissions from edits made in pandas. For now this method would help build these pipelines even if the hardest part is still updating the submission (but examples will help).

What would you expect to receive back from this method?

I would expect nothing back in case of success and an exception if anything goes wrong. My sense is that in this kind of scripting context mutators generally don't need to return the result of their mutations. The script may do follow-up work but it's more likely to be in the context of the full dataset rather than with the submission that was just mutated.

Does this seem valuable to you?