From 4893aa2ca5dd7809eec342907534d2c69e7cdf9c Mon Sep 17 00:00:00 2001
From: Bernardo Anderson <bern.anderson@proton.me>
Date: Wed, 17 Jun 2026 13:13:25 -0500
Subject: [PATCH] CP-14193 Add external_id persistence tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

What
Adds test coverage confirming DocuSeal already persists the submitter
`external_id` field end-to-end — through both the service layer and the
API request path. No production code changes.

Why
ATS will now send `external_id` (`ats-user-<id>`) on every submitter so
it can match submitters by stable user id instead of mutable email.
These tests pin DocuSeal's existing pass-through behavior so it cannot
regress silently.

How to test
bundle exec rspec spec/lib/submissions/create_from_submitters_spec.rb \
  spec/requests/submissions_spec.rb
---
 .../create_from_submitters_spec.rb            | 30 +++++++++++++++++++
 spec/requests/submissions_spec.rb             | 11 +++++++
 2 files changed, 41 insertions(+)

diff --git a/spec/lib/submissions/create_from_submitters_spec.rb b/spec/lib/submissions/create_from_submitters_spec.rb
index bea0be319..49fb4b101 100644
--- a/spec/lib/submissions/create_from_submitters_spec.rb
+++ b/spec/lib/submissions/create_from_submitters_spec.rb
@@ -92,4 +92,34 @@ def call(template:, submitters_order:)
       expect(submitter_uuids).not_to include(template.submitters[1]['uuid'])
     end
   end
+
+  describe 'external_id' do
+    let(:attrs_with_external_id) do
+      template.submitters.map.with_index do |s, index|
+        { 'uuid' => s['uuid'], 'email' => Faker::Internet.email,
+          'external_id' => "ats-user-#{index + 1}" }.with_indifferent_access
+      end
+    end
+
+    it 'persists external_id provided on each submitter' do
+      submissions = described_class.call(
+        template:,
+        user:,
+        submissions_attrs: [{ 'submitters' => attrs_with_external_id }.with_indifferent_access],
+        source: :api,
+        submitters_order: 'simultaneous'
+      )
+
+      persisted = submissions.first.submitters.sort_by do |s|
+        template.submitters.index { |ts| ts['uuid'] == s.uuid }
+      end
+      expect(persisted.map(&:external_id)).to eq(%w[ats-user-1 ats-user-2])
+    end
+
+    it 'leaves external_id blank when not provided' do
+      submissions = call(template:, submitters_order: 'simultaneous')
+
+      expect(submissions.first.submitters.map(&:external_id)).to all(be_nil)
+    end
+  end
 end
diff --git a/spec/requests/submissions_spec.rb b/spec/requests/submissions_spec.rb
index 327efdb3d..57b311eba 100644
--- a/spec/requests/submissions_spec.rb
+++ b/spec/requests/submissions_spec.rb
@@ -139,6 +139,17 @@
       expect(response.parsed_body[1]['email']).to eq('jane.doe@example.com')
     end
 
+    it 'persists external_id passed on each submitter' do
+      post '/api/submissions', headers: { 'x-auth-token': author.access_token.token }, params: {
+        template_id: templates[0].id,
+        send_email: true,
+        submitters: [{ role: 'Employee', email: 'john.doe@example.com', external_id: 'ats-user-42' }]
+      }.to_json
+
+      expect(response).to have_http_status(:ok)
+      expect(Submission.last.submitters.first.external_id).to eq('ats-user-42')
+    end
+
     it 'returns an error if the submitter email is invalid' do
       post '/api/submissions', headers: { 'x-auth-token': author.access_token.token }, params: {
         template_id: templates[0].id,