feat(#10509): support uploading attachments in contact forms

[cliftonmcintosh]

Description

This PR adds attachment support to contact forms, enabling file uploads and binary field attachments similar to what already exists for report forms.

What's Implemented

Following discussion in #10509, the implementation was simplified to match report form behavior: all attachments attach to the main contact document only, regardless of form structure.

Backend Changes

1. File Widget Attachments: Files uploaded through Enketo file widgets are extracted from FileManager and attached to the contact document
2. Binary Field Attachments: Base64-encoded binary fields (signatures, drawings) are extracted from XML and attached with XPath-based naming
3. Attachment Naming: Uses consistent patterns matching report forms:
   • File widgets: user-file-{filename}
   • Binary fields: user-file/{form-id}/{xpath}
4. Edit Preservation: Attachments automatically persist when editing contacts via _defaults() merge

Implementation Details

• Location: ContactSaveService.prepareSubmittedDocsForSave() (following @jkuester's guidance)
• Code Added: ~30 lines in processAllAttachments() method
• Services Reused: AttachmentService, FileManager, Xpath utility
• Pattern: Mirrors EnketoService.xmlToDocs() for report forms

Test Coverage

Test Type	Count	Location
Unit Tests	8	webapp/tests/karma/ts/services/contact-save.service.spec.ts
cht-form Integration	2	tests/integration/cht-form/default/contact-with-attachments.wdio-spec.js
E2E Tests	5	tests/e2e/default/contacts/contact-attachments.wdio-spec.js

Unit tests are intended to verify:

• File widget extraction and attachment to main document
• Binary field extraction with XPath-based naming
• Multiple attachments (mixed types) all attach to main document

E2E tests are intended to verify:

• Create contact with single image attachment
• Create contact with multiple attachments (image + document)
• Edit contact preserves existing attachments

All added tests passing ✅

Manual Testing Performed

• Created contacts with photo attachments via person-create form
• Verified attachments saved to CouchDB with correct naming (user-file-{filename})
• Verified edit form displays existing attachment filename
• Confirmed multiple contacts can have attachments independently

Details about manual testing

Testing Photo Upload on Contact Create

Step 1: Modified the Contact Form

Please note that form modifications have not been committed. The file was modified locally.

File: config/default/forms/contact/person-create.xml

1a. Added field to instance data (~line 922)

<notes/>
<photo/>
<user_for_contact>

1b. Added binding (~line 1062)

<bind nodeset="/data/person/notes" type="string"/>
<bind nodeset="/data/person/photo" type="binary"/>
<bind nodeset="/data/person/user_for_contact/create" ...

1c. Added upload widget to body (~line 1159)

<input ref="/data/person/notes" appearance="multiline">
  <label ref="jr:itext('/data/person/notes:label')"/>
</input>
<upload ref="/data/person/photo" mediatype="image/*">
  <label>Photo</label>
  <hint>Take a photo or select from gallery</hint>
</upload>
<group ref="/data/person/user_for_contact"/>

---

Step 2: Compiled and Uploaded the Form

2a. Compiled the form

./scripts/build/build-config.sh

2b. Uploaded to CouchDB

Deleted the existing form and posted the new version:

# Got current revision and deleted
REV=$(curl -s http://medic:password@localhost:5984/medic/form%3Acontact%3Aperson%3Acreate | python3 -c 'import sys,json; print(json.load(sys.stdin)["_rev"])')
curl -X DELETE "http://medic:password@localhost:5984/medic/form%3Acontact%3Aperson%3Acreate?rev=$REV"

# Uploaded new version
curl -X POST "http://medic:password@localhost:5984/medic" \
  -H "Content-Type: application/json" \
  -d @api/build/default-docs/form-contact-person-create.doc.json

2c. Refreshed the browser

Hard refresh with Cmd+Shift+R.

Step 3: Tested the Upload

1. Navigated to a health facility in CHT
2. Clicked "New person" to create a contact
3. Filled out required fields (name, DOB, sex)
4. Scrolled to the "Photo" field and uploaded an image
5. Submitted the form

Step 4: Verified the Attachment Was Saved

Queried CouchDB directly:

curl -s "http://medic:password@localhost:5984/medic/_find" \
  -H "Content-Type: application/json" \
  -d '{"selector": {"type": "person"}, "limit": 5}' | python3 -m json.tool | head -50

Looked for:

• "photo": "filename.png" - the field value
• "_attachments": { "user-file-filename.png": {...} } - the stored attachment

Test Result

Contact created: "Photo Contact"

Attachment saved:

"photo": "Screenshot 2026-01-26 at 09.06.22-9_30_5.png"

"_attachments": {
  "user-file-Screenshot 2026-01-26 at 09.06.22-9_30_5.png": {
    "content_type": "image/png",
    "length": 413623
  }
}

---

Testing the Edit Form (Display Existing Attachment)

Step 1: Modified the Edit Form

Please note that form modifications have not been committed. The file was modified locally.

File: config/default/forms/contact/person-edit.xml

1a. Added field to instance data (~line 1013)

<notes/>
<photo/>
<meta tag="hidden">

1b. Added binding (~line 1166)

<bind nodeset="/data/person/notes" type="string"/>
<bind nodeset="/data/person/photo" type="string" readonly="true()" relevant="../photo != ''"/>
<bind nodeset="/data/person/meta/created_by" type="string" ...

Note: The binding used:

• type="string" (not binary) because we were displaying the filename, not uploading
• readonly="true()" to prevent editing
• relevant="../photo != ''" to only show when a photo exists

1c. Added read-only input to body (~line 1284)

</input>
<input ref="/data/person/photo">
  <label>Current Photo</label>
  <hint>Existing attachment (read-only)</hint>
</input>
<group ref="/data/person/user_for_contact"/>

Step 2: Compiled and Uploaded the Edit Form

2a. Compiled the form

./scripts/build/build-config.sh

2b. Uploaded to CouchDB

Deleted the existing form and posted the new version:

# Got current revision and deleted
REV=$(curl -s http://medic:password@localhost:5984/medic/form%3Acontact%3Aperson%3Aedit | python3 -c 'import sys,json; print(json.load(sys.stdin)["_rev"])')
curl -X DELETE "http://medic:password@localhost:5984/medic/form%3Acontact%3Aperson%3Aedit?rev=$REV"

# Uploaded new version
curl -X POST "http://medic:password@localhost:5984/medic" \
  -H "Content-Type: application/json" \
  -d @api/build/default-docs/form-contact-person-edit.doc.json

2c. Refreshed the browser

Hard refresh with Cmd+Shift+R.

Step 3: Tested Viewing the Existing Attachment

1. Navigated to "Photo Contact" (the contact created in Part 1)
2. Clicked "Edit" to open the edit form
3. Scrolled to the "Current Photo" field
4. Verified the filename was displayed

Test Result

Contact edited: "Photo Contact"

Photo field displayed: ✅ Yes - filename shown as read-only

Filename shown: Screenshot 2026-01-26 at 09.06.22-9_30_5.png

Status: ✅ Existing attachment filename correctly displayed in edit form

Screenshots

Empty person create form with photo field

Person create form with photo added

Person edit form with photo shown

---

Not in Scope for V1

Per discussion in #10509, these are deferred:

• UI Preview on Edit: Attachments persist when editing, but users cannot see previews of existing attachments (can be added in V2) preview on edit is included as per @dianabarsan's request in feat(#10509): support uploading attachments in contact forms #10570
• Multi-Document Routing: Attachments in sibling/repeat sections all attach to main document (matches report behavior)
• Contact-Summary Integration: Per issue description, this is out of scope

AI Disclosure

AI Assistance: This PR was developed using Claude Code.

How AI was used:

• Analysis of existing codebase patterns (EnketoService, AttachmentService) for consistency
• Code generation for the processAllAttachments() method
• Test writing following TDD methodology
• Documentation and planning

Human oversight:

• I reviewed all generated code for correctness, security, and consistency with project patterns
• I ran all tests manually to verify functionality
• I made architecture decisions (V1 simplified approach based on reviewer feedback)
• I iterated on implementation based on code review feedback
• All commits include co-author attribution

Closes #10509

Code review checklist

• UI/UX backwards compatible: No UI changes in this PR. Existing contact forms continue to work unchanged.
• Readable: Concise, well named, follows the style guide, documented if necessary.
• Documented: Configuration and user documentation on cht-docs - Form authors will need guidance on adding upload fields
• Tested: Unit tests, cht-form integration tests, and E2E tests all passing
• Internationalised: No user-facing text added
• Backwards compatible: Works with existing data and configuration. Existing contact forms without upload fields are unaffected.

License

The software is provided under AGPL-3.0. Contributions to this project are accepted under the same license.

[cliftonmcintosh]

@dianabarsan I've created a draft PR with some initial work so that I can get feedback and see if this is the right direction to go.

[dianabarsan]

Nice quick work! Thanks for adding the AI disclosure, that's super helpful when trying to make sense of some complexities that AI tends to add.
I added a few comments below, mainly as a path to simplify things.
Thanks a lot for the quick turn on this!

[dianabarsan]

Wow! this function!

I think the existence of this function is because the code is built to allow attachments for any of the documents the contact form creates. However, for reports, we only attach binary files for the main document. I think that following this model should be sufficient for the first iteration of this work: following the report format and only allowing attachments for the main document.

[cliftonmcintosh]

This attempt to allow attachments for any of the documents the contact form creates us because in a comment on the issue, @jkuester said

The tricky part is going to be handling the fact that contact forms can create multiple documents (primary doc, sibling docs, repeated child docs), and ensuring that attachments are mapped to the correct document. I think, for each file attachment we will need to look up where in the XML structure it came from, and then map that to the corresponding document. Because of this, I am not sure if there is anything we can easily reuse from xmlToDocs directly, but we can at least borrow the logic for processing FileManager files and binary fields to use in our logic that can be added to ContactSaveService.prepareSubmittedDocsForSave.

[cliftonmcintosh]

What I think would be helpful is guidance on

1. What the XML looks like for contact forms. What elements do they have? Are there a limited set of objects that can show up as the primary, the sibling or the repeated child docs? Which ones can have attachments?
2. Which documents we should support attachments for. Are we limiting it to the primary like @dianabarsan is suggesting we do? Or do we need or want to support attachments on the sibling and child docs that @jkuester mentions are possible?

[dianabarsan]

I asked Josh to clarify this comment about attachments to child docs, we are in a bit of a disagreement and my preference would be to keep things simple.

For sample contact forms, you can always look at the default config contact forms, though these would not have child documents. I will search for a real-world example that does have child documents.

[cliftonmcintosh]

I asked Josh to clarify this comment about attachments to child docs, we are in a bit of a disagreement and my preference would be to keep things simple.

Sounds good. I'm happy to take whichever path the team decides is best.

For sample contact forms, you can always look at the default config contact forms, though these would not have child documents.

Thanks for the tip!

I will search for a real-world example that does have child documents.

Thank you!

[cliftonmcintosh]

Based on Josh's reply to your questions, it looks like you two are in agreement about starting with a simple approach. I will be happy to update this PR so that we only support attachments on the main document.

[cliftonmcintosh]

For sample contact forms, you can always look at the default config contact forms, though these would not have child documents. I will search for a real-world example that does have child documents.

Thanks again for pointing me to that directory, @dianabarsan. I have a couple of follow-up questions

• If I am trying to write realistic tests, are there particular contact forms that it might be good to choose for my tests? For example, person-create or person-edit?
• What is a realistic example of having an attachment to the main document for one of those forms? For example, in person-create xml, would we see an attachment at something like /data/person/photo or /data/person/notes/attachment or data/person/ephemeral_dob/birth_certificate? I'd like to be able write tests that are realistic.

[dianabarsan]

What is a realistic example of having an attachment to the main document

Because this feature has never existed, I do not believe we have one. I have heard of deployments wanting to upload PDFs, others to upload signatures (?).

As for a report that has child documents, I found a few examples in private configs and all of them follow this model: https://github.com/medic/cht-core/blob/master/config/default/forms/contact/clinic-create.xml where the main contact gets created along with a primary contact.
There might be some more elaborate examples out there, but I think for the tests we're good to go with this

[cliftonmcintosh]

@dianabarsan

I have a question about process. If a PR is still in draft and the branch becomes out-of-date with the base branch, is it okay if I rebase or does your team prefer a merge commit instead?

I'm inclined to rebase until the PR is out of draft status because it keeps the commit history looking cleaner without a merge commit, but I'm happy to follow whatever convention your team prefers.

[dianabarsan]

If a PR is still in draft and the branch becomes out-of-date with the base branch, is it okay if I rebase or does your team prefer a merge commit instead?

We general preference is to merge, because rebase loses all intermediary review comments which are very valuable to understand code progression. So please, avoid rebasing. We only rebase when the branch has additional commits (commits accidentally cherry picked) which makes reviewing very difficult.

[dianabarsan]

because it keeps the commit history looking cleaner without a merge commit,

we ALWAYS squash and merge, so the commit history gets lost anwyay.

[dianabarsan]

There is more info about process in the docs: https://docs.communityhealthtoolkit.org/community/contributing/code/workflow/#opening-pull-requests

[cliftonmcintosh]

I've run through manual testing again to

• create a person with an attachment
• edit the person (and be able to see the attachment)
• remove an attachment during edit
• add an attachment during edit
• replace an attachment during edit
• verify that the DB data is correct (no orphan attachments)
• verify that attachments with special characters in their names are sanitized and can be viewed in edit

Here's a recording of that

Screen.Recording.2026-02-09.at.09.16.52.mov

[cliftonmcintosh]

It looks like the ci-integration-all-all flaked out. When this happens, should I post asking for a re-run? Or just know that eventually someone will re-run it if needed?

[dianabarsan]

I re-ran the test and it passed. I didn't have time today to do a full review, just took a quick look at the latest commits and I'm really liking the new traversals! Thanks!
I'll do the full review tomorrow.

[mrjones-plip]

When this happens, should I post asking for a re-run?

Yeah - here or in slack!

[dianabarsan]

So awesome!

[cliftonmcintosh]

@dianabarsan
Is this character limitation a problem for places that use other writing systems? Will the files always be named with Latin characters? Do we need to adjust the sanitization?

[dianabarsan]

Good point. I am nooooot sure. I suppose we could ask @binokaryg or @bhishankc about how files are named in Nepali. The safer option would be to only strip out special characters?

[mrjones-plip]

I propose we keep this as is. In order of relevance, here's why I think this:

1. we have many examples of using a-zA-Z as "safe"
2. While Nepali likely is an alphabet we should support, this feature is actually initially being deployed in East Africa. As well, what about Arabic? What about Cyrillic?
3. There's a larger idea called universal acceptance (UA) that we should consider.

I think the approach should be, at a later date, do an audit of our code for UA and address this concern then.

[mrjones-plip]

After thought: Maybe there's a defensive code happy path where if a file is named تصدير and the result of sanitizeFileName() returns an empty string in which case we give the filename of a UUIDv7 instead?

Right now a file is uploaded called تصدير , we'd return a file name called user-file-, if I'm following the code correctly. Maybe worth an update 🤷 (oh maybe files without suffixes (eg .png) aren't allowed by enketo/browser?)

[binokaryg]

User-generated files can sometimes have Devanagari script in their names. Devanagari script is common across Nepali, Hindi, and other regional languages.

For example, a user could capture an image and rename it to "घर.jpg" in Nepali for easier identification later.

It would be good to support UTF-8 characters if not too difficult.

[dianabarsan]

Thank you @binokaryg !

[cliftonmcintosh]

Following up here to see if there is any action needed right now. Are we going to stick with things the way they are for this PR and adjust later or do we want an adjustment like the one that @mrjones-plip suggested:

Maybe there's a defensive code happy path where if a file is named تصدير and the result of sanitizeFileName() returns an empty string in which case we give the filename of a UUIDv7 instead?

[cliftonmcintosh]

Please let me know if there are any actions I need to take on this PR. I can't do any merging, so I assume someone else will merge if this is still considered to be approved.

[dianabarsan]

I was expecting a follow-up on the conversation about non-latin characters in file names. We would at least add a unit test showing what happens when you have a file containing only non-latin characters in its name.

[cliftonmcintosh]

I was expecting a follow-up on the conversation about non-latin characters in file names. We would at least add a unit test showing what happens when you have a file containing only non-latin characters in its name.

Thanks for clarifying the expectations. I've updated the sanitization function so that it uses a UUID when there are no characters that match the regex. Unit test added as well. Please let me know if we want anything else.

[mrjones-plip]

Thanks for keeping this PR moving Cliff and Diana!

I think the unit test is great and the UUID handling is icing on the cake. I defer to Diana to finalize the review on the last changes.

[dianabarsan]

Awesome! One small request inline.

[dianabarsan]

One request about storing the regex in a variable, so it's absolutely clear we're sanitizing with the same rules.

[cliftonmcintosh]

Yes. Of course. Done!

[dianabarsan]

Awesome!

[cliftonmcintosh]

I'm unfamiliar with the CHT process for merging approved PRs. Does the PR stay unmerged until the target version of CHT is almost ready to be released?

Let me know if there is anything I need to be doing or if there is anything that needs updating before merging.

[mrjones-plip]

Hey @cliftonmcintosh ! Thanks for reaching out. For external contributors, the process is that the person who reviewed the PR is the one who merges it. If you have no more pending feedback to tend to and the PR has been approved, you're good to go! (which both are true here ; )

I've kicked off CI again in hopes it was a fluke that it didn't pass before 🤷

[dianabarsan]

I can merge when we believe it's ready, but @cliftonmcintosh comes up with the best questions! I think we would need an answer for these questions, the worst that can happen is that we ungracefully crash if a sub-document has an image attachment.

[cliftonmcintosh]

I can merge when we believe it's ready, but @cliftonmcintosh comes up with the best questions! I think we would need an answer for these questions, the worst that can happen is that we ungracefully crash if a sub-document has an image attachment.

@dianabarsan I'll be happy to explore this. I will dig in to find examples of sub-documents. If you have pointers for where I might find some to test with in the default config, please let me know. That might save us a little time.

I am traveling today through Monday so likely won't get back to this until Tuesday.

Diana code reviewing

[dianabarsan]

Nevermind. I tested this myself. The attachment gets added to the main doc.

[cliftonmcintosh]

Nevermind. I tested this myself. The attachment gets added to the main doc.

Great! Thanks. I was just investigating to try to figure that out.

[mrjones-plip]

while the issue is closed, for next time @cliftonmcintosh, instead of running the whole build config as you mentioned in Step 2: Compiled and Uploaded the Form, if you install CHT Conf which can do any/all of the build calls, enables a much more targeted upload of a specific form:

cht  --local upload-contact-forms -- person-create

As this JUST calls upload-contact-forms for JUST the one form, it will be much faster than the 10 calls in the build conf script processing ALL the contact and app forms in default config.

Right now I'm hoping to test a branch build of your work, and when coupled with Docker Helper, I can be up and running very quickly! (though, admittedly, I can't find images for your branch so I may have to build them 🤷 ). Docker helper is of course not good for core dev work like in this branch - but ideal for ad hoc testing.

[cliftonmcintosh]

if you install CHT Conf which can do any/all of the build calls, enables a much more targeted upload of a specific form:

cht  --local upload-contact-forms -- person-create

Thanks for the tip!