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