Submissions

Submission-related functionality is accessed through client.submissions. For example:

from pyodk.client import Client

client = Client()
data = client.submissions.get_table(form_id="my-form")["value"]

_patch(instance_id, review_state, form_id=None, project_id=None)

Update Submission metadata.

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced.	required
review_state	str	The current review state of the submission.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None

_put(instance_id, xml, form_id=None, project_id=None, encoding='utf-8')

Update Submission data.

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced.	required
xml	str	The submission XML.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None
encoding	str	The encoding of the submission XML, default "utf-8".	'utf-8'

add_comment(instance_id, comment, project_id=None, form_id=None)

Create a Comment.

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced.	required
comment	str	The text of the comment.	required
project_id	int | None	The id of the project this form belongs to.	None
form_id	str | None	The xmlFormId of the Form being referenced.	None

Returns:

Type	Description
Comment	An object representation of the newly-created Comment.

create(xml, form_id=None, project_id=None, device_id=None, encoding='utf-8', attachments=None)

Create a Submission.

Example submission XML structure:

<data id="my_form" version="v1">
  <meta>
    <instanceID>uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44</instanceID>
  </meta>
  <name>Alice</name>
  <age>36</age>
  <selfie>profile.jpg</selfie>
</data>

If provided, each attachment file name must match a file name reference (just the file name, not a directory path) in the submission XML, otherwise Central will reject the upload since the file is not expected. For example, an image question named bird with a XML value <bird>pigeon.jpg</bird> will allow uploading an attachment named pigeon.jpg. Central assumes that clients (you), will ensure unique file name references in the submission XML if necessary, e.g. Central will only store one pigeon.jpg file across all questions in a given submission. You may provide directory paths to pyodk e.g. ["/home/u/pigeon.jpg"], but only the file name is used to identify the file in the upload to Central.

File attachments are sent in chunks of 16 KB by default. Advanced users can customize the chunk size on the session.

Parameters:

Name	Type	Description	Default
xml	str	The submission XML.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None
device_id	str | None	An optional deviceID associated with the submission.	None
encoding	str	The encoding of the submission XML, default "utf-8".	'utf-8'
attachments	Iterable[PathLike | str] | None	The file paths of the attachment(s) to upload.	None

edit(instance_id, xml, form_id=None, project_id=None, comment=None, encoding='utf-8')

Edit a submission and optionally comment on it.

Example edited submission XML structure:

<data id="my_form" version="v1">
  <meta>
    <deprecatedID>uuid:85cb9aff-005e-4edd-9739-dc9c1a829c44</deprecatedID>
    <instanceID>uuid:315c2f74-c8fc-4606-ae3f-22f8983e441e</instanceID>
  </meta>
  <name>Alice</name>
  <age>36</age>
</data>

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced. The instance_id each Submission is first submitted with will always represent that Submission as a whole. Each version of the Submission, though, has its own instance_id. So instance_id will not necessarily match the values in the XML elements named instanceID and deprecatedID.	required
xml	str	The submission XML.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None
comment	str | None	The text of the comment.	None
encoding	str	The encoding of the submission XML, default "utf-8".	'utf-8'

get(instance_id, form_id=None, project_id=None)

Read Submission metadata.

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None

Returns:

Type	Description
Submission	An object representation of the Submission's metadata.

get_table(form_id=None, project_id=None, table_name='Submissions', skip=None, top=None, count=None, wkt=None, filter=None, expand=None, select=None)

Read Submission data.

Parameters:

Name	Type	Description	Default
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None
table_name	str | None	The name of the table to be returned.	'Submissions'
skip	int | None	The first n rows will be omitted from the results.	None
top	int | None	Only up to n rows will be returned in the results.	None
count	bool | None	If True, an @odata.count property will be added to the result to indicate the total number of rows, ignoring the above paging parameters.	None
wkt	bool | None	If True, geospatial data will be returned as Well-Known Text (WKT) strings rather than GeoJSON structures.	None
filter	str | None	Filter responses to those matching the query. Only certain fields are available to reference (submitterId, createdAt, updatedAt, reviewState). The operators lt, le, eq, neq, ge, gt, not, and, and or are supported, and the built-in functions now, year, month, day, hour, minute, second.	None
expand	str | None	Repetitions, which should get expanded. Currently, only * (star) is implemented, which expands all repetitions.	None
select	str | None	If provided, will return only the selected fields.	None

Returns:

Type	Description
dict	A dictionary representation of the OData JSON document.

list(form_id=None, project_id=None)

Read all Submission metadata.

Parameters:

Name	Type	Description	Default
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project the Submissions belong to.	None

Returns:

Type	Description
list[Submission]	A list of the object representation of all Submissions' metadata.

list_comments(instance_id, form_id=None, project_id=None)

Read all Comment details.

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project the Submissions belong to.	None

Returns:

Type	Description
Iterable[Comment]	A list of all Comments.

review(instance_id, review_state, form_id=None, project_id=None, comment=None)

Update Submission metadata and optionally comment on it.

Parameters:

Name	Type	Description	Default
instance_id	str	The instanceId of the Submission being referenced.	required
review_state	str	The current review state of the submission.	required
form_id	str | None	The xmlFormId of the Form being referenced.	None
project_id	int | None	The id of the project this form belongs to.	None
comment	str | None	The text of the comment.	None