> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yrka.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Import payroll and schedule data into Yrka

> Upload payroll CSV/TSV and schedule ICS/CSV files, map columns, review validation, and commit ready rows. All imports are review-first before data is applied.

The Import Center in Yrka is the review-first intake surface for payroll history, schedule events, resource files, and employee records. Every import follows the same pattern: upload a supported file, map columns to Yrka fields, review validation results, and commit only the rows you have reviewed and approved. Nothing is applied to production records without your explicit commit — imports do not silently mutate data.

<Note>
  XLS/XLSX workbook imports are currently disabled. Convert workbook files to CSV or TSV before uploading. This applies to payroll, schedule, and other import types.
</Note>

***

## Import Center overview

Open **Admin Tools > Imports** to access the Import Center. The main view shows domain import mode tabs and a data-movement queue that surfaces integration sync events, provider handoffs, notification delivery evidence, and failed records alongside your file imports.

### Import modes

| Mode             | What you import                                                                                   |
| ---------------- | ------------------------------------------------------------------------------------------------- |
| **Payroll**      | Historical payroll records, timecard history, pay data                                            |
| **Schedule**     | Schedule events and shift assignments                                                             |
| **Resources**    | Source documents for Resources review and knowledge chat                                          |
| **Employees**    | Employee roster data (available when enabled for your organization)                               |
| **All history**  | Combined view of all import activity, provider sync jobs, webhook replay candidates, and handoffs |
| **Failed**       | Batches and rows that could not commit and need attention                                         |
| **Needs review** | Batches waiting on mapping, validation decisions, or admin action                                 |

***

## Payroll imports

Payroll imports let you bring historical timecard and pay data into Yrka. After import, committed records appear in Timekeeping and Payroll contexts.

### Supported file profiles

* **Generic CSV/TSV** — standard comma- or tab-separated payroll export
* **Foundation Payroll** — Foundation-oriented column layout
* **QuickBooks Time** — QuickBooks Time export format
* **Custom** — configured column mappings saved as a reusable profile

### Importing payroll data

<Steps>
  <Step title="Open Payroll in Imports">
    Go to **Admin Tools > Imports** and select **Payroll**. You need the `payroll.import` permission to upload or commit.
  </Step>

  <Step title="Upload the file">
    Select your CSV or TSV file. Yrka creates an import batch, stores normalized row previews, and auto-detects common column names.
  </Step>

  <Step title="Review detected columns and employee matching">
    The preview shows detected columns alongside Yrka fields, matched employees (matched by employee number, payroll ID, email, or name), duplicate timecard row flags, and any validation warnings. Check each before mapping.
  </Step>

  <Step title="Map source columns">
    Map each source column to the corresponding Yrka field. For common profiles (Foundation, QuickBooks Time), many columns will auto-map. Review auto-mapped columns before committing — do not assume auto-mapping is always correct.
  </Step>

  <Step title="Revalidate">
    After updating mappings, revalidate the batch. Resolve any remaining errors or warnings before proceeding.
  </Step>

  <Step title="Commit ready rows">
    Select **Commit** to apply ready rows only. Committing a payroll batch can:

    * Update employee payroll fields
    * Create missing job catalog rows
    * Insert historical timecards
    * Adjust PTO/VAC balances through the leave ledger
  </Step>

  <Step title="Review the import work item">
    Committing creates an `import_review` admin Inbox work item. Review and resolve it to complete the import audit trail.
  </Step>
</Steps>

<Warning>
  Commit applies ready rows only. Rows with unresolved errors or validation failures are skipped. Review the skipped/error row export to identify records that need correction outside Yrka.
</Warning>

***

## Schedule imports

Schedule imports bring shift and assignment data from external systems into your Yrka schedule calendar.

### Supported file formats

* **ICS** — standard calendar export format (from Google Calendar, Microsoft 365, Apple Calendar, or other calendar tools)
* **CSV** — schedule data in comma-separated format with common schedule column patterns

### Importing schedule data

<Steps>
  <Step title="Open Schedule in Imports">
    Go to **Admin Tools > Imports** and select **Schedule**. You need the `schedule.import` permission. You can also access schedule import from the Schedule header's Import shortcut.
  </Step>

  <Step title="Upload the file">
    Upload your ICS or CSV file. Yrka creates a schedule import batch, stores row previews, detects common schedule columns, and matches employees by name, email, or employee number.
  </Step>

  <Step title="Review row previews and employee matching">
    Check each row for matched employees, flagged duplicates, and conflicts with existing schedule events. Rows without matched employees cannot be committed until the identifier is corrected.
  </Step>

  <Step title="Select the target calendar">
    Before committing, confirm the **target Schedule calendar** shown on the batch. This is the internal Yrka calendar where committed events will land. Provider calendar names and Yrka schedule calendars are separate — make sure the right one is selected.
  </Step>

  <Step title="Commit ready rows">
    Commit reviewed rows. Each committed row inserts a schedule event and, where employees are matched, creates the corresponding assignment.
  </Step>

  <Step title="Review the schedule import work item">
    Committing creates a `schedule_import_review` admin Inbox work item. Resolve it after confirming the events look correct in Schedule.
  </Step>
</Steps>

<Tip>
  If you use a calendar provider (Google Calendar, Microsoft 365, Apple Calendar ICS) through Integrations, those syncs also stage into the same Schedule import review workflow. Open Imports > Schedule to find and review provider-staged batches alongside manually uploaded files.
</Tip>

***

## Review-first: the import safety model

Every import in Yrka is review-first. This means:

* Uploads create a batch in review state — no data is applied yet
* All imports generate an admin Inbox work item so the review is tracked
* You commit only after inspecting row previews, employee matching, and validation
* Committing applies ready rows only — rows with errors are skipped, not silently applied

This design prevents unreviewed data from entering production records. If an import file has problems, they surface in validation before you commit, not after.

***

## Import history and failed views

Use **All history** to see every import batch, provider sync job, webhook replay candidate, staged source record, payroll handoff, and notification delivery attempt for your organization. Use **Failed** to focus on batches and rows that could not commit.

<Steps>
  <Step title="Find a failed batch">
    Open **Failed** or **All history** and sort or page the table to find the batch. The status column shows whether the batch failed, needs review, was archived, or succeeded.
  </Step>

  <Step title="Review the failure reason">
    Open the batch to see the safe error summary. Common causes include unmatched employee identifiers, unsupported columns, and validation conflicts with existing records.
  </Step>

  <Step title="Export skipped or error rows">
    Export error rows for correction outside Yrka, then re-upload a corrected file. Do not retry a failed batch with the same file if the source data needs correction.
  </Step>

  <Step title="Archive stale batches">
    Archive batches that should leave the active review queue once they are no longer needed. Archived batches remain available as audit evidence.
  </Step>
</Steps>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Employees do not match in the import preview">
    Check the employee identifier columns in your file — employee number, payroll ID, email, and name are the supported matching fields. Correct the identifiers in the source file and re-upload. Do not commit rows with unmatched employees if those employees must receive the imported records.
  </Accordion>

  <Accordion title="Duplicate rows are flagged">
    Compare the flagged rows with existing timecards or schedule events in Yrka. If the source data genuinely duplicates what is already in Yrka, skip or do not commit those rows. If they are different records that should both exist, investigate whether the duplicate flag is from a matching identifier conflict.
  </Accordion>

  <Accordion title="A file type is blocked">
    Convert the file to a supported CSV, TSV, or ICS format. XLS/XLSX workbook imports are currently disabled — do not attempt to upload workbook files.
  </Accordion>

  <Accordion title="Employee invitation emails are not sending after an import">
    Check Resend invite readiness in Integrations. Use the manual invite link fallback from Personnel for affected employees until domain and DNS verification are complete.
  </Accordion>

  <Accordion title="Resources opens source review instead of an upload form">
    Resources import is the source review lane, not a file-row mapping lane. To approve and stage source documents for knowledge chat, work through the source review flow in Resources.
  </Accordion>

  <Accordion title="The Failed view shows nothing but issues are expected">
    Check All history — the batch may have succeeded earlier or may not have started. The Failed view shows only batches and rows that reached a failed or error state, not pending or in-progress batches.
  </Accordion>
</AccordionGroup>