survey_custom_certificate_template/docs/AUTOMATIC_FIELD_MAPPING.md

Automatic Field Mapping

Overview

The Survey Custom Certificate Template module includes an automatic field mapping feature that recognizes common placeholder patterns and automatically maps them to appropriate survey or participant data fields. This reduces manual configuration effort and makes the certificate setup process more intuitive.

How It Works

When a DOCX template is uploaded, the system:

1. Extracts all placeholders matching the {key.*} pattern
2. For each placeholder, attempts to automatically map it to a data source
3. Recognizes common field name patterns (e.g., "name", "email", "date")
4. Maps recognized patterns to appropriate survey or participant fields
5. Defaults to "Custom Text" for unrecognized placeholders

Supported Field Patterns

Survey Fields

These placeholders map to data from the survey.survey model:

Placeholder Pattern	Maps To	Description
{key.title}	survey_title	Survey title
{key.survey_title}	survey_title	Survey title
{key.course_name}	survey_title	Survey title (course name alias)
{key.course}	survey_title	Survey title (course alias)
{key.coursename}	survey_title	Survey title (no underscore)
{key.survey_name}	survey_title	Survey title (survey name alias)
{key.surveyname}	survey_title	Survey title (no underscore)
{key.description}	survey_description	Survey description
{key.survey_description}	survey_description	Survey description
{key.course_description}	survey_description	Survey description (course alias)
{key.coursedescription}	survey_description	Survey description (no underscore)

Participant Fields

These placeholders map to data from the survey.user_input model or related partner:

Name Fields

Placeholder Pattern	Maps To	Description
{key.name}	partner_name	Participant's full name
{key.participant_name}	partner_name	Participant's full name
{key.participantname}	partner_name	Participant's full name (no underscore)
{key.partner_name}	partner_name	Participant's full name
{key.partnername}	partner_name	Participant's full name (no underscore)
{key.student_name}	partner_name	Participant's full name (student alias)
{key.studentname}	partner_name	Participant's full name (no underscore)
{key.user_name}	partner_name	Participant's full name (user alias)
{key.username}	partner_name	Participant's full name (no underscore)
{key.fullname}	partner_name	Participant's full name
{key.full_name}	partner_name	Participant's full name

Email Fields

Placeholder Pattern	Maps To	Description
{key.email}	partner_email	Participant's email address
{key.participant_email}	partner_email	Participant's email address
{key.participantemail}	partner_email	Participant's email address (no underscore)
{key.partner_email}	partner_email	Participant's email address
{key.partneremail}	partner_email	Participant's email address (no underscore)
{key.student_email}	partner_email	Participant's email address (student alias)
{key.studentemail}	partner_email	Participant's email address (no underscore)
{key.user_email}	partner_email	Participant's email address (user alias)
{key.useremail}	partner_email	Participant's email address (no underscore)

Date Fields

Placeholder Pattern	Maps To	Description
{key.date}	completion_date	Survey completion date
{key.completion_date}	completion_date	Survey completion date
{key.completiondate}	completion_date	Survey completion date (no underscore)
{key.finish_date}	completion_date	Survey completion date (finish alias)
{key.finishdate}	completion_date	Survey completion date (no underscore)
{key.completed_date}	completion_date	Survey completion date (completed alias)
{key.completeddate}	completion_date	Survey completion date (no underscore)
{key.create_date}	create_date	Survey submission date
{key.createdate}	create_date	Survey submission date (no underscore)
{key.submission_date}	create_date	Survey submission date
{key.submissiondate}	create_date	Survey submission date (no underscore)

Score Fields

Placeholder Pattern	Maps To	Description
{key.score}	scoring_percentage	Score as percentage
{key.scoring_percentage}	scoring_percentage	Score as percentage
{key.scoringpercentage}	scoring_percentage	Score as percentage (no underscore)
{key.percentage}	scoring_percentage	Score as percentage
{key.percent}	scoring_percentage	Score as percentage
{key.grade}	scoring_percentage	Score as percentage (grade alias)
{key.result}	scoring_percentage	Score as percentage (result alias)
{key.scoring_total}	scoring_total	Total score points
{key.scoringtotal}	scoring_total	Total score points (no underscore)
{key.total_score}	scoring_total	Total score points
{key.totalscore}	scoring_total	Total score points (no underscore)
{key.points}	scoring_total	Total score points

Unrecognized Placeholders

If a placeholder doesn't match any of the recognized patterns, it will be automatically set to "Custom Text" type with an empty value. Users can then:

1. Manually select a different data source from the dropdown
2. Enter custom text to replace the placeholder
3. Leave it empty (placeholder will be replaced with an empty string)

Case Insensitivity

The automatic mapping is case-insensitive. All of the following will map correctly:

• {key.Name} → partner_name
• {key.NAME} → partner_name
• {key.name} → partner_name
• {key.NaMe} → partner_name

Examples

Example 1: Basic Certificate

Template placeholders:

Certificate of Completion

This certifies that {key.name} has successfully completed
{key.course_name} on {key.date}.

Score: {key.score}%

Automatic mappings:

• {key.name} → Participant Field: partner_name
• {key.course_name} → Survey Field: survey_title
• {key.date} → Participant Field: completion_date
• {key.score} → Participant Field: scoring_percentage

Example 2: Detailed Certificate

Template placeholders:

{key.title}

Awarded to: {key.participant_name}
Email: {key.email}
Completion Date: {key.completion_date}
Grade: {key.grade}%
Total Points: {key.points}

Description: {key.description}

Automatic mappings:

• {key.title} → Survey Field: survey_title
• {key.participant_name} → Participant Field: partner_name
• {key.email} → Participant Field: partner_email
• {key.completion_date} → Participant Field: completion_date
• {key.grade} → Participant Field: scoring_percentage
• {key.points} → Participant Field: scoring_total
• {key.description} → Survey Field: survey_description

Example 3: Custom Placeholders

Template placeholders:

Certificate

Student: {key.student_name}
Course: {key.coursename}
Institution: {key.institution}
Instructor: {key.instructor}

Automatic mappings:

• {key.student_name} → Participant Field: partner_name
• {key.coursename} → Survey Field: survey_title
• {key.institution} → Custom Text: (empty - user must configure)
• {key.instructor} → Custom Text: (empty - user must configure)

Benefits

1. Faster Setup: Reduces manual configuration time
2. Intuitive: Uses common naming conventions
3. Flexible: Supports multiple variations of the same field
4. Safe: Defaults to custom text for unknown fields
5. User-Friendly: Users can still override automatic mappings

Technical Implementation

The automatic mapping is implemented in the _auto_map_placeholder() method of the survey.custom.certificate.wizard model. This method:

1. Extracts the field name from the placeholder
2. Converts it to lowercase for case-insensitive matching
3. Checks against survey field patterns
4. Checks against user field patterns
5. Returns the appropriate value_type and value_field
6. Defaults to 'custom_text' if no match is found

The method is called automatically during template parsing in _parse_template_placeholders(), which creates placeholder records with the automatic mappings pre-configured.

Validation: Requirements 2.5

This feature validates Requirement 2.5 from the requirements document:

Acceptance Criteria 2.5: WHEN the system recognizes standard fields THEN the Survey System SHALL automatically populate the Value column with appropriate data sources

The implementation successfully:

• ✓ Recognizes standard field patterns
• ✓ Automatically populates the Value column
• ✓ Maps to appropriate data sources (survey.survey and survey.user_input)
• ✓ Supports a wide range of common naming conventions
• ✓ Provides sensible defaults for unrecognized fields