CSV Import Formatting & Directory Ingestion

The TeamSigs CSV Import Engine enables organization administrators to bulk-provision, update, and synchronize hundreds or thousands of employee profiles within seconds. With TeamSigs' flat-rate model of $149/year for unlimited seats, organizations can upload their complete global roster without incurring per-seat charges or licensing limits.

Dynamic CSV Column Generation

Unlike rigid directory systems that enforce hardcoded contact fields, TeamSigs dynamically generates CSV column templates based on the variables declared in your active templates.

Variable Classification in CSV Generation

When an administrator clicks Download Sample CSV on /team, the system scans all master templates configured in the workspace:

1. Included: Directory Variables ({{variable}}):
   • Standard employee attributes (e.g., job_title, phone, department, office_location).
   • Managed centrally by administrators; strictly read-only for employees on /my-signature.
2. Included: Delegated Variables ({{variable#}}):
   • Self-managed employee attributes (e.g., linkedin_url#, pronouns#, booking_link#).
   • Can be pre-populated by administrators via CSV, with employees permitted to modify their values on /my-signature.
3. Excluded: Locked Corporate Variables ({{variable*}}):
   • Organization-wide parameters (e.g., company_name\*, company_logo_url\*, website\*, disclaimer\*).
   • Never included in CSV columns. Corporate variables reside exclusively in templates.template_data and are governed via the Template Editor.

Standard & Dynamic Column Specifications

Column headers in the imported CSV are case-insensitive and order-independent. The email column is mandatory.

Technical Ingestion Standards

To guarantee data integrity across global multi-lingual directories:

• File Format: Plaintext .csv (Comma Separated Values).
• Character Encoding: UTF-8 (with or without BOM). When saving from Microsoft Excel, select *CSV UTF-8 (Comma delimited) (.csv)** to ensure accented characters, umlauts, and non-Latin alphabets render correctly.
• Delimiter Detection: The parser automatically sniffs and supports both commas (,) and semicolons (;), ensuring standard European spreadsheet exports operate without manual adjustment.
• Payload Limit: Maximum file size is 5 MB per batch (supporting rosters exceeding 20,000 employees).
• Formula Injection Prevention: Values prefixed with mathematical operators or formula characters (=, +, -, @) are automatically neutralized to eliminate CSV formula injection risks during external spreadsheet export.

Upsert Logic & Matching Protocol

TeamSigs employs an intelligent upsert (Update or Insert) protocol mapped to the composite key (domain_id, email):

1. Insert (New Employee): If the email address does not exist within the organization's directory, a new member record is inserted into team_members. The email is immediately added to the OTP authorization whitelist, enabling instant login.
2. Update (Existing Employee): If the email address is already present in the directory, existing attributes are updated with the values supplied in the CSV.
3. Preserving Empty Attributes: If a field is left empty for an existing employee, the existing stored value in the database is retained rather than overwritten with an empty string.
4. Adoption Continuity: Updating an employee via CSV does not reset their adoption status (e.g., if their status is Copied, updating their job title preserves their status).

Atomic Database Transactions & Error Handling

To ensure consistent database state, all CSV ingestion operations are executed under strict transactional controls:

• Atomic Transactions (BEGIN TRANSACTION): The entire file is processed inside an atomic transaction. If a fatal structural failure occurs, the transaction rolls back cleanly, preventing partial directory corruption.
• Row-Level Parsing & Skipping: If individual rows contain syntax errors (such as malformed email addresses missing an @ symbol or invalid characters), the system logs the exact row number in the import summary, skips that row, and continues processing all valid rows.
• Import Audit Summary: Upon completion, the interface displays a real-time audit modal summarizing:
  • Total Rows Processed
  • New Members Added
  • Existing Profiles Updated
  • Skipped / Invalid Rows (with row-by-row reason)

Sample CSV File Structure

Vertical Column Schema Breakdown:

Standard Roster Columns:
  - email        : Corporate email address (required)
  - name         : Full employee name
  - template_id  : Template ID (blank = default)
  - job_title    : Corporate title
  - phone        : Direct telephone or extension
  - department   : Team or division name
  - linkedin_url : Delegated profile URL

Example Plaintext CSV:

email,name,template_id,job_title,phone,department
[email protected],Alex Morgan,,VP Product,+1-555-0192,Product
[email protected],Beatriz Gomez,3,CS Lead,+34-912-345,Support
[email protected],David Kim,,Sec Engineer,+1-555-0193,Security
[email protected],Sara Chen,,Architect,+1-555-0194,Product

Steps to Download and Import:

1. Navigate to Team (/team) in the admin navigation bar.
2. Click the CSV Import tab.
3. Click Download Sample CSV to receive a CSV file automatically tailored with all active directory fields from your templates.
4. Populate your company data and save as UTF-8 CSV.
5. Drag and drop the file into the upload zone and click Process Ingestion.