citrus-cms/resources/views/guide/work-permit-replacer.md

Work Permit Replacer System

📋 User Guide - What You Need to Know

⚠️ Important Notes for Users

Before using the Work Permit Replacer system, please ensure:

1. Excel Template Format: Your Excel document must contain placeholders in the correct format
2. Data Completeness: All required work permit information must be filled in the system
3. Project Assignment: Work permits must be assigned to the correct project zone
4. Document Linking: The Excel template must be linked to the appropriate document type

🔍 Quick Checklist for Users

• Excel template has placeholders in curly braces {PLACEHOLDER_NAME}
• Work permit data is complete and up-to-date
• Project information is correctly set in the system
• Document type is properly assigned to work permits
• Company and personnel information is filled in

📝 Common User Issues

"My placeholders are not being replaced"

• Check if work permit data is complete
• Verify project zone assignment
• Ensure document type is linked

"Some fields are empty after replacement"

• Fill in missing work permit information
• Check if all required fields are populated
• Verify personnel and company details

"Wrong data is appearing in my document"

• Check work permit assignments
• Verify project zone settings
• Review company and personnel information

---

🔧 Technical Documentation

Overview

The Work Permit Replacer system is a dynamic document template engine that automatically replaces placeholders in Excel documents with actual data from the work permit database. This system supports both old and new format placeholders for backward compatibility.

How It Works

1. Core Function

The system uses the workPermitReplacerExcel2() function located in app/Functions/work-permit-replacer-excel2.php to process Excel documents and replace placeholders.

2. Data Source

The system fetches work permit data from the database using the following query:

$workPermitUsers = db("work_permit_documents")
    ->select([
        'work_permit_documents.*',
        'subcontractors.*',
        'work_permit_documents.sign_order as personel_sign_order',
        'subcontractors.sign_order as firma_sign_order',
    ])
    ->leftJoin("subcontractors", "work_permit_documents.company", "subcontractors.company_name_ru")
    ->where("zone", "like", "%{$project}%")
    ->where("assigned_documents", "like", "%{$documentInfo->slug}%")
    ->get();

3. Placeholder Formats

The system supports two placeholder formats:

Old Format (Legacy)

{job_description + personel_sign_order + _field_name}
{company_code + personel_sign_order + _field_name}

New Format (Current)

{job_description + firma_sign_order + "_" + personel_sign_order + _field_name}
{company_code + firma_sign_order + "_" + personel_sign_order + _field_name}

4. Supported Fields

The system automatically replaces all fields from the work permit documents table, including:

• Basic Information: name_surname, id_no, level, description
• Company Details: company, company_code, job_description
• Document Information: document_code, document_number, revision
• Dates: date_of_issue, attorney_date, certificate_date
• Status: status, dept, zone, third_party
• Certificates: certificates_number, attorney, duty

Troubleshooting Guide

Issue: Placeholders Not Appearing

If placeholders are not being generated or replacements are not working, follow these steps:

1. Check Database Connection

Verify that the database connection is working and the required tables exist:

• work_permit_documents
• subcontractors

2. Verify Project Zone Matching

The system filters work permit documents by project zone. Ensure:

->where("zone", "like", "%{$project}%")

• The project value from weldLog is correctly set
• The zone field in work_permit_documents contains the project name
• Use wildcards if the zone field contains partial project names

3. Check Document Assignment

Verify that the document is assigned to the work permit:

->where("assigned_documents", "like", "%{$documentInfo->slug}%")

• The assigned_documents field should contain the document slug
• Use wildcards if multiple documents are assigned

4. Validate Subcontractor Join

The system joins with the subcontractors table:

->leftJoin("subcontractors", "work_permit_documents.company", "subcontractors.company_name_ru")

Ensure:

• work_permit_documents.company field exists and has values
• subcontractors.company_name_ru field exists and matches
• The join condition is correct for your data structure

5. Check Required Fields

Verify that these essential fields are populated:

• job_description - Used for placeholder generation
• company_code - Used for placeholder generation
• personel_sign_order - Used for placeholder generation
• firma_sign_order - Used for new format placeholders

6. Debug Data Retrieval

Add debugging to check what data is being retrieved:

// Add this after the database query
dd($workPermitUsers->toArray());

7. Verify Placeholder Format

Check that your Excel template uses the correct placeholder format:

Old Format Example:

{WELDER001_name_surname}
{COMP001_company_name}

New Format Example:

{WELDER001_FIRM001_name_surname}
{COMP001_FIRM001_company_name}

Issue: Partial Replacements

If only some placeholders are being replaced:

1. Check Field Values

Ensure that the field values in the database are not null or empty:

• String fields should contain actual text
• Date fields should be in a valid format
• Numeric fields should contain numbers

2. Verify Field Names

Check that the field names in your placeholders exactly match the database field names:

• Field names are case-sensitive
• Use underscores for spaces
• Check for typos in field names

3. Handle Special Characters

Some fields may contain special characters that need escaping:

• Check for quotes, brackets, or other special characters
• Ensure proper encoding in the Excel template

Issue: Performance Problems

If the replacement process is slow:

1. Optimize Database Query

• Add indexes on frequently queried fields
• Limit the result set if possible
• Use caching for repeated queries

2. Reduce Excel Processing

• Process only necessary sheets
• Limit the number of cells processed
• Use batch processing for large documents

Best Practices

1. Template Design

• Use consistent naming conventions for placeholders
• Group related fields logically
• Test with sample data before production use

2. Data Validation

• Ensure all required fields are populated
• Validate data formats (dates, numbers, etc.)
• Handle null/empty values gracefully

3. Error Handling

• Implement proper error logging
• Provide fallback values for missing data
• Test edge cases and error scenarios

4. Testing

• Test with various project configurations
• Verify placeholder generation for all document types
• Test backward compatibility with old format placeholders

Common Error Messages

"No work permit users found"

• Check project zone configuration
• Verify document assignment
• Ensure database tables have data

"Placeholder replacement failed"

• Check field name spelling
• Verify data types match
• Ensure required fields are populated

"Database connection error"

• Check database credentials
• Verify table structure
• Check database permissions

Maintenance

Regular Checks

• Monitor database performance
• Verify data integrity
• Update placeholder formats as needed
• Test with new document types

Updates

• Keep the function updated with new field requirements
• Maintain backward compatibility
• Document any changes to placeholder formats
• Test thoroughly before deployment

---

For additional support or questions about the Work Permit Replacer system, please refer to the development team or check the system logs for detailed error information.