Designing Contact Data Forms

Modified on Thu, 8 Jan at 12:51 PM

Designing Contact Data Forms

This page provides step-by-step instructions for incorporating participant contact details (e.g., name, email, mobile number, address, etc.) into a form in OC4, using both the Form Designer and the Form Template.

Overview

When you capture contact information in a form (for example, allowing a participant to update their phone number or email), OpenClinica 4 supports this through the special contactdata mechanism.

⚠️ Important: Contact data items behave differently from ordinary form data. They are stored in a participant contact record rather than in the study’s clinical data set, and they are subject to stricter access controls.

For more information on how contact data behaves in Study Runner, refer to Understanding Contact Data.

Access & Role Considerations

If any version of a form includes a contactdata item, the form is treated as a contact form.
By default, Clinical Research Coordinators (CRCs) and Investigators can view and edit contact forms. Manual permission tags can be used to override this default, granting access to non-CRCs/Investigators or revoking access for CRCs/Investigators.
For details, see Managing Form Access and Permissions.
Contact data is stored as part of the participant record rather than as form data. Because of this, including contact data in form outputs would be redundant and may create a misleading impression of what was entered on a specific form. As a result, extract and API behavior differ from standard data forms.
- See Understanding Contact Data for retrieving participant contact and clinical data.

Using Form Designer for Contact Data Items

For general instructions, see Using Form Designer.

In Study Designer, open your form in Form Designer.
Add a Text or other suitable item for each contact field you want to collect (for example, First Name, Email Address, Mobile Number).
Remove Item Group Name—contact-data items cannot be placed in an item group.
Set Use as External Value to contactdata.
Select the type of contact data you are collecting from the available options:
- firstname
- lastname
- email
- mobilenumber
- secondaryid

Using Form Template for Contact Data Items

For general instructions, see Using the Form Template.

In the Survey sheet, add a row for each contact field.
For each row, set:
- type = the data type (for example, text)
- label = the question text (for example, Mobile Phone Number)
- name = the internal variable name (for example, mobile_number)
  - Used for referencing the item within the form (for example, relevant logic on another item to check whether it is blank or filled in)
- bind::oc:external = contactdata
- bind::oc:itemgroup = blank. Contact data items cannot be included in item groups.
Add the column instance::oc:contactdata and enter one of the allowed values shown below.
Configure other columns as needed (for example, required, relevant, etc).
ℹ️ Note: Constraints for contact-data items are automatically applied by the system.
Upload the file through the Form Card > Upload button and preview the form.

Formatting and Automatic Constraints

When a field is defined as contactdata, OpenClinica automatically applies type-specific constraints to ensure format and data quality.
These constraints are system-enforced—you do not need to define them manually in the Form Template.

Data Type	Item Type	Automatic Constraint
firstname	text	String length ≤ 35 characters
middlename	text	String length ≤ 35 characters
lastname	text	String length ≤ 35 characters
email	text	String length ≤ 255 characters and must match the following regular expression: *^[A-Za-z0-9!#$%&’+/=?^_`{\|}~-]+(?:\.[A-Za-z0-9!#$%&’+/=?^_`{\|}~-]+)@(?:[A-Za-z0-9](?:[A-Za-z0-9-][A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-][A-Za-z0-9])?$**
mobilenumber	text	String length ≤ 17 characters and must match the following regular expression: ^\+[0-9]{1,3} [0-9]{1,14}$ Accepts either a full international format (e.g., +1 5551234567) or a 10-digit number (assumed country code +1).
streetaddress1	text	String length ≤ 155 characters
streetaddress2	text	String length ≤ 155 characters
country	text	String length ≤ 155 characters
city	text	String length ≤ 155 characters
state	text	String length ≤ 155 characters
postalcode	text	String length ≤ 35 characters
fulldob	date	(Date field; format defined by system locale—no explicit length constraint.)
secondaryid	text	String length ≤ 35 characters
hospitalnumber	text	String length ≤ 35 characters

ℹ️ Note: Mobile phone number is stored internally along with country code (for example +123 456789012345). Once a value has been collected, on either the form or from the Participant Details screen, it will be displayed in that format with country code (including +1 before US phone numbers).
Participants can enter phone numbers in either of the following formats:

+ followed by country code, space, and number (e.g., +1 5551234567)
A 10-digit number (automatically assumed to be U.S. +1)

Notes on Constraints

The constraint, constraint message, and constraint type are automatically populated when the item is identified as contactdata.
If additional validation is needed (for example, regional phone number formats), use a separate constraint expression and validate thoroughly.
For mobile numbers, OpenClinica automatically stores the number with a “+” prefix and country code.

Example: Template Configuration

type	name	label	bind::oc:external	instance::oc:contactdata	required
text	first_name	First Name	contactdata	firstname	yes
text	last_name	Last Name	contactdata	lastname	yes
text	email_address	Email Address	contactdata	email	yes
text	mobile_phone	Mobile Phone Number	contactdata	mobilenumber	no
text	mailing_street1	Street Address Line 1	contactdata	streetaddress1	no
text	mailing_city	City	contactdata	city	no
text	mailing_postal	Postal / ZIP Code	contactdata	postalcode	no

Summary and Best Practices

Use bind::oc:external = contactdata and the appropriate instance::oc:contactdata code for each contact data item.
Do not group contact-data items within an item group.
Validate key fields (e.g., email format, phone number) and mark required appropriately.
Do not add custom constraints that conflict with the system’s automatic rules.
Test the form in a test environment using the same role permissions that will apply in production.