Inviting a contributor

This page covers the most common journey in the app: someone at a production company adds a contributor to one of their projects, the contributor receives an email, follows the link, gives consent, answers the survey, and sees a confirmation page.

It’s the pilot example for this section — every other flow follows the same structure. If you’re customising translations or email templates for your deployment, this page is a worked example of what’s available and where to change it.

What happens

sequenceDiagram
    actor Producer
    participant App as Your app
    actor Contributor

    Producer->>App: Add contributor (with name and email)
    App->>Contributor: Sends invitation email
    Contributor->>App: Clicks "do the survey" in email
    App-->>Contributor: Welcome screen
    Contributor->>App: Begins survey
    App-->>Contributor: Answers questions
    Contributor->>App: Submits final answer
    App-->>Contributor: Confirmation screen

The three actors:

• Producer — a user at a production company who works on a project. They use the app’s “contributors” page to invite people.
• Contributor — the person being invited. They never log in initially; the invitation email contains a one-use link that opens the survey directly.
• App — your branded deployment of the contribute app. The screens the contributor sees, the email they receive, and the wording on both are all subject to your customisation.

Step 1 — Producer adds the contributor

The producer opens the project’s contributors page, clicks Add, fills out a form, and submits.

What the producer sees

The page is the project’s contributors view — there’s an “Add” button in the top-right corner of the toolbar. Clicking it opens an Add new contributor dialog.

The dialog has these fields:

Field	What it’s for
Role	The contributor’s job on the project (selected from your role list)
Name	The contributor’s name
Email	Where the invitation email will be sent
Diamond Code (optional)	A pre-issued anonymous identifier, if you’ve enabled the Diamond Code feature
”This email belongs to an agent” toggle	When ticked, the email is treated as going to an agent rather than the contributor directly — this changes the wording in the invitation email
Episodes	For multi-episode projects, which episodes the contributor worked on

The dialog footer has Add and Cancel buttons.

What the producer customisable

The visible text in this dialog is controlled by translations in tep-configuration:

What you see	Translation key
Dialog title “Add new contributor”	Projects.manage-contributors.add-new-contributor.title
”Role” label	Projects.manage-contributors.add-new-contributor.labels.role
”Name” label	Projects.manage-contributors.add-new-contributor.labels.name
”Email” label	Projects.manage-contributors.add-new-contributor.labels.email
”Diamond Code” label	Projects.manage-contributors.add-new-contributor.labels.diamond-code
”Agent email” toggle label	Projects.manage-contributors.add-new-contributor.labels.is-indirect-email
”Add” / “Cancel” buttons	common.add / common.cancel

All of these can be customised in your client’s translation overrides — see What you can customise below.

Known gap

The success message (“Contributor added successfully”) and the generic failure message (“Failed to add contributor”) that pop up after the producer submits the form are currently shown only in English. They cannot be localised in the current build of the app. Validation messages (e.g. “email is required”) are localised. This is a known issue and is tracked for a future release.

Step 2 — Invitation email is sent

When the producer submits the form, the app sends an invitation email to the address they entered. The email is the survey-invite email — the main thing the contributor will ever receive from the app.

What the contributor receives

The email has:

• Your branding (logo, colours, footer image)
• A personalised greeting using the contributor’s name
• The project name and an optional “ambassador” name (a friendly face at the production company)
• An optional custom message set by the producer on the project
• A prominent call-to-action button — by default labelled “Do the 2 minute survey now”
• A link to associate the survey with an existing account (for contributors who already have one)
• An unsubscribe link

The CTA button takes the contributor straight to the survey, no login required.

What you can customise

The email is fully customisable per client:

• The whole email template — you can supply your own branded version. The default is shipped as part of the app for each client; if you don’t override, you inherit the TEP default.
• The email subject line — set in your translations, with two variants depending on whether the project has a named ambassador.
• The URLs in the email — three URLs are embedded (the survey link, the associate-with-existing-account link, and the unsubscribe link). All three are templated in your client config so they point at your deployment.

See What you can customise below for the file locations.

Step 3 — Contributor opens the link

The contributor clicks the CTA button in the email and lands on the survey welcome screen.

What the contributor sees

A welcome page introducing the survey, with a “Begin” button.

If the link is broken or expired (e.g. the producer revoked the invitation), the contributor instead sees an error page explaining the situation.

(If you’ve enabled the Diamond Code feature, this is not where contributors see their code — codes are assigned at submit time and shown on the sign-out page that follows. See Step 6. Returning contributors who already have a code may see it on this welcome page too, but on the typical first-time invite flow nothing Diamond-Code-related is visible here.)

Three possible landing experiences

Experience	When it happens
Welcome page	The link is valid and unused — the typical case
Error page	The link is invalid, revoked, or expired
Login redirect	The contributor already has an account and arrives via a retake link, in which case they’re sent to log in first

The login redirect ends up using Ory’s authentication screens (the identity provider used by the app). The text and email content for Ory’s login code and password recovery emails are configured in Ory, not in your tep-configuration. We can document Ory’s customisation separately if you need to localise those messages.

Step 4 — Contributor answers the survey

The contributor works through a sequence of questions. The questions and their order are defined by your survey configuration.

What the contributor sees

• One question at a time, with answer options
• Auto-advance to the next question shortly after they select an answer (default: 750ms)
• For deaf or hard-of-hearing contributors, a British Sign Language video alternative on questions where one is provided
• For “Other” answers on multi-choice questions, a small dialog to enter free text

There’s no “save and resume later” — the survey is short enough to complete in one sitting (the design target is two minutes).

What you can customise

• The survey itself — the question list, the answer options, the order, and the conditional branching are all set by your survey configuration in tep-configuration (per client and per variant — e.g. nz-standard, cdn-standard).
• The wording of questions and answers — your survey translations control all the on-screen text.
• The survey “chrome” — the page title, progress indicator, navigation buttons, and so on.

Step 5 — Contributor submits

After the final question, the contributor lands on a consent and submit screen. For contributors who have an existing account elsewhere in the system, this screen can also offer to associate the survey response with that account.

What the contributor sees

• A summary of consent (what they’re agreeing to by submitting)
• A name and email field if they’re not already known to the system
• A “Submit” button

If their email matches an existing account, one of these dialogs may appear before they can complete:

Dialog	Purpose
Org-user choice	Their email matches a production-company user account — would they like to associate this survey with that account?
Org-user associate invite	Confirms sending the association invite
Contribute-account block	Their account state prevents this submission and explains what they need to do

On submit, the survey response is saved and they’re redirected to a confirmation page.

What you can customise

The text on this screen and in the three association dialogs is fully translatable:

• Most strings are under the Survey.consent-page.* keys (see your survey-ui translations)
• Account-association dialog text uses the auth.Associate.* keys
• Success and error messages (e.g. “survey submitted”, “email already associated”) use Survey.consent-page.success.* and Survey.consent-page.errors.*

Step 6 — Confirmation

The contributor sees a confirmation that their response was submitted. For contributors who arrived as anonymous (the typical case), this same page also signs them out of the app.

If the Diamond Code feature is enabled, this sign-out page displays the contributor’s freshly-assigned Diamond Code, explaining what it is and inviting them to save it for future surveys. Contributors who have an account can also see their Diamond Code later in their profile.

What you can customise

Consolidated view of everything you can change for this flow.

Translations (visible text)

Translations live in the tep-configuration repository. The override hierarchy, from lowest to highest priority:

1. Global defaults: tep-configuration/translations/{locale}/main/
   • projects.json — producer-side strings (contributor management, etc.)
   • survey-ui.json — survey chrome and consent-page strings
   • common.json — generic buttons and labels (add, cancel, …)
   • auth.json — authentication and account-association strings
2. Your client’s overrides: tep-configuration/clients/{client}/translations/{locale}/overrides.json
   • Where you put per-client overrides. Anything you set here wins over the global defaults.
3. Your survey variant’s overrides: tep-configuration/clients/{client}/surveys/{variant}/translations/{locale}/variant-overrides.json
   • Where you put per-variant overrides for survey-specific strings (e.g. an NZ-variant override).

Keys called out in the steps above (e.g. common.add, Projects.manage-contributors.add-new-contributor.title, Survey.consent-page.success.survey-submitted) can all be set in any of these layers.

The invitation email

The survey-invite email is fully customisable per client. You can:

• Override the entire email template — supply your own {client}-survey-invite.mjml in tep-api/src/modules/communication/emailTemplates/ (a customisation TEP applies as part of your client onboarding). If you don’t override, you inherit the default tep-survey-invite.mjml.
• Customise the subject line — set surveyInviteWithAmbassadorSubject and surveyInviteNoAmbassadorSubject in your client’s translations.
• Add or change branding — the email template references your logo, colours, and footer image.

URLs in the email

Three URLs are embedded in the email. All three are configured per client and not hardcoded:

URL purpose	Config key
Survey link (the CTA button)	linkToSurveyUrl
Associate-existing-account link	associateUrl
Unsubscribe link	unsubscribeUrl

These are typically set when your client is onboarded and point at your deployment’s domain (e.g. https://contribute.your-broadcaster.com/). They’re templated with ${inviteToken} and ${projectId} placeholders that the app fills in for each contributor.

Survey content and structure

The survey itself — questions, answer options, ordering, branching — is defined per variant in tep-configuration/clients/{client}/surveys/{variant}/config.json. The wording is in the matching variant-overrides.json translation files (see Translations).

Variations for your deployment

Your deployment	What’s different
CDN, NZ, Omni, TEP	All four clients ship with branded versions of the invitation email. The flow is otherwise the same.
Omni	The app does not send reminder emails for Omni — contributors get the one initial invitation and that’s it. Other clients receive follow-up reminders if the contributor hasn’t responded.
NZ standard survey	The NZ survey variant is shorter (some questions are skipped) and includes a 16+ age filter. The structure of the flow is the same.
Self-service / QR-code entry	Some deployments let contributors arrive via a QR code or a general sign-up link without an invitation email at all. They skip Steps 1 and 2 and go straight to the welcome screen.
Existing contributor	If the producer invites someone who already has a Contribute account, a different email — “you’ve been added to a project” — is sent instead of the standard invitation. The contributor’s experience from the welcome page onwards is identical.
Diamond Code enabled	An optional Diamond Code field appears on the Add-contributor dialog. After submission, the contributor sees their assigned code on the sign-out page that follows the survey. Contributors with an account can also see their code in their profile.

Need more detail?

The engineering reference for this flow — including code paths, source files, and notes for developers — is in Inviting a contributor (internal).