Designing Forms Including PII Data

This page provides step-by-step instructions for incorporating participant PII (Personally Identifiable Information) details (e.g., name, email, mobile number, address, etc.) into a form in OC4.

Overview

When you capture PII in a form (for example, allowing a participant to update their phone number or email), OpenClinica 4 supports this through: 

1. PII (Encrypted) item type in Form Designer or 
2. the contactdata mechanism in the form template.

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

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

Access & Role Considerations

• If any version of a form includes a PII 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.
• PII data is stored as part of the participant record rather than as form data. Because of this, including PII 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 PII and clinical data.

Using Form Designer for PII Data Items

For general instructions, see Using Form Designer.

1. In Study Designer, open your form in Form Designer.
2. Add a PII (Encrypted) item, shown with a padlock icon (?), for each PII field you want to collect.
3. From the Contact Data Typedropdown in the item’s configuration panel, select the type of PII data the field will collect. The following options are available:
   • firstname — participant’s first name
   • middlename — participant’s middle name
   • lastname — participant’s last name
   • email — email address
   • mobilenumber — mobile phone number
   • streetaddress1 — first line of street address
   • streetaddress2 — second line of street address
   • city — city
   • state — state
   • country — country
   • postalcode — postal or ZIP code
   • fulldob — full date of birth (the item is automatically treated as a Date type)
   • secondaryid — alternate participant ID
   • hospitalnumber — hospital ID number
4. Configure any other required settings for the item, such as whether the field is required.
5. Save your form as a draft and preview it to confirm the fields behave as expected.

ℹ️ Note:  The Item Group, Use External Value, Item Description, and Short Display Name fields are not available for PII (Encrypted) items.

When you download a form that contains PII (Encrypted) items as a template, those items appear in the spreadsheet with the bind::oc:external column set to contactdata and the instance::oc:contactdata column populated with the PII data type you selected.

Using Form Template for PII Data Items

For general instructions, see Using the Form Template.

1. In the Survey sheet, add a row for each PII field.
2. 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. PII data items cannot be included in item groups.
3. Add the column instance::oc:contactdata and enter one of the allowed values shown below.
4. Configure other columns as needed (for example, required, relevant, etc).
   ℹ️ Note: Constraints for contactdata items are automatically applied by the system.
5. Upload the file through the Form Card > Upload button and preview the form.

Formatting and Automatic Constraints

Regardless of whether the PII (encrypted) item type is selected in Form Designer or contactdata is configured for a field in the form template, 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.

ℹ️ 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

Summary and Best Practices

• Use the PII (Encrypted) item type in Form Designer to add PII data fields without manual configuration. The system automatically handles the external value, item group, and field constraints.
• Use bind::oc:external = contactdata and the appropriate instance::oc:contactdata code for each contact data item.
• Do not group PII (encrypted) / contactdata 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.