The AI Assisted Shift Import Tool lets you turn a messy schedule — a spreadsheet, a photo, a PDF — into clean Shift records inside Salesforce. The tool reads the file with AI, pulls out the rows it finds, lets you review and correct them in a grid, and then writes them to Salesforce in one go.

This page is split into two halves:

End-User Guide — for the person actually importing shifts each week.
Implementation Guide — for the consultant configuring the tool for a client (keys, templates, permissions, moving setup between orgs).

What the tool does

Clients send their schedules in every format imaginable: Excel files with merged cells and coloured headers, photos of printed rotas pinned to a wall, scanned PDFs, CSVs from legacy systems. Typing those into Salesforce by hand is slow and error-prone.

The AI Assisted Shift Import Tool does the typing for you:

You upload the file.
The AI reads it and pulls out one row per Shift.
You review what it found in a spreadsheet-style grid, fix anything wrong, then click Start Import.
Salesforce gets the Shift records.

The tool runs inside Salesforce as the page RecordImporter (also available as a Lightning component).

End-User Guide

Before you start

You will need:

Access to the AI Assisted Shift Import Tool page in Salesforce (your administrator grants this).
The schedule file from the client.
The Account in Salesforce that the schedule belongs to (e.g. the client / site owner).
A Template (also called an Instruction Set) configured for that client's schedule format. If one does not exist yet, ask your implementation consultant to create it before you continue.

The tool is a 4-step wizard. You can move forwards and backwards using the Back / Next buttons at the bottom, or by clicking the numbered steps at the top.

Step 1 — Upload your file and pick the Account

Drag the schedule file onto the upload area, or click to browse for it.
You can upload more than one file at a time — they will all be processed together.
Choose the target Account from the picker on the same screen. This tells the tool which client's Sites, Roles, and other lookup records to match against later.

Accepted file formats: Excel (.xlsx, .xls), CSV, PNG, JPG, JPEG, GIF, WEBP, PDF.

Recommendation: wherever possible use Excel or CSV. The tool can read the row and column structure directly, which gives you the most accurate result and also lets you click a row in the review grid to see the source cell highlighted. Images and PDFs work, but accuracy drops and the source-highlight feature is not available.

When the file is loaded, click Next.

Step 2 — Pick a Template

A Template is a saved instruction set that tells the AI:

What columns to extract (e.g. Date, Site, Role, Start time, End time, Notes).
What each column means in Salesforce (which field, which object to look up against).
How to read the file (instructions in plain English the AI follows).

Pick the Template that matches the client and the file format. If you cannot see a suitable Template, stop and ask your implementation consultant — running with the wrong Template will produce bad data.

Click Next to move on.

Step 3 — Let the AI process the file

The tool runs the file through the AI pipeline. You will see a progress card for each agent:

Generalist — does the first pass: reads the whole file and writes out every row it can find.
Auditor(s) — one or more follow-up agents that check the Generalist's work, correct mistakes, fill gaps, and tighten up the result.

Each card shows running → done, plus a running token count. If an agent fails, you will see an error and a Retry button — usually retrying once is enough. If it fails twice, go back and check the file or the Template.

Once every card says done, click Proceed to Review.

Step 4 — Review & Import

This is the most important step. Do not skip it.

The grid shows every row the AI extracted. Treat the AI's output as a draft, not as final data.

What you will see

Confidence column (first column): a coloured badge per row.
- Green — the AI is very confident in the row.
- Yellow — the AI is fairly confident.
- Red — the AI is unsure. Read this row carefully.
Source File column (only when you uploaded more than one file): tells you which file the row came from.
One column per field in your Template (Date, Site, Role, etc.). Editable like a spreadsheet.
Status column (last): empty until you click Start Import; afterwards it shows a green badge with the new Salesforce record ID for each successful row, or a red badge with the error message for any row that failed.

Things you can do

Click any cell to edit it. Picklists show a dropdown, lookups (e.g. Site, Role) auto-complete from real Salesforce records for the Account you picked in Step 1, dates and times have a proper editor.
Click a confidence badge (Excel/CSV uploads only) to open the original file with the source cells highlighted in yellow. Great for resolving anything that looks wrong.
Red-tinted cells mean the value is not valid (e.g. a Site name that does not exist in Salesforce). Fix these before importing.

Importing

Click Start Import.
The tool first checks that every dropdown / lookup is valid. If anything is invalid, you get a warning and the import is blocked until you fix it.
Valid rows are sent to Salesforce. The Status column fills in row by row.
Successful rows turn green and lock — you cannot edit them again.
Failed rows stay editable and tinted red. Fix the issue, then click Start Import again — only the failed rows get re-sent, so you can never create duplicates.
When every row has succeeded, the Start Import button is replaced with an All records imported badge and the navigation locks. Refresh the page to start a new import.

Tips for a clean import

Use Excel or CSV whenever you can. Photos and PDFs work but are noticeably less accurate.
Don't trust the AI blindly. Always sort by Confidence and read every yellow and red row.
Watch out for dates. Different countries write dates differently (DD/MM vs MM/DD). The Template has a date-format setting — if the dates look wrong, the Template might be set up for the wrong region.
Keep your source file tidy. One sheet of shifts, clear column headers, and no merged cells that span the data area give the best results.
Small batches first. Run 5–10 rows from a new client's file before running the whole thing — it surfaces Template problems cheaply.

Implementation Guide

This section is for the consultant setting up the tool for a client.

One-time setup per org

For each org where you want to use the tool:

Grant the right permission set(s) to the users who will use the tool (see Permissions).
Add the AI key for the provider you intend to use (see below).
Build or import at least one Template (Instruction Set) for each client whose schedules you import.

Adding the AI key (OpenAI / Gemini)

The tool calls either OpenAI or Google Gemini to read the files. It will not work without a key. Each user enters their own key — keys are stored on the user's browser (session storage) and are not shared across users or saved to Salesforce.

Where to get a key

Google Gemini: sign in at Google AI Studio → Get API key. There is a generous free tier.
OpenAI: sign in at OpenAI Platform → API keys → Create new secret key. You will need a paid account and a small amount of credit on the account.

Where to paste it in the tool

Go to Custom Settings
Navigate to Scheduler Settings (b3s__Scheduler__c)
Paste the key into whichever one(s) you plan to use (b3s__Gemini_AI_Key__c or b3s__OpenAI_Key__c).

You can fill in both keys if you want to use OpenAI for some Templates and Gemini for others.

Security note: treat AI keys like passwords. Do not share them in Slack/email; do not commit them to a code repo. Each user should use their own.

Choosing a model

Each Template (and each Auditor inside a Template) specifies which AI model to use. Different models trade off cost vs accuracy vs speed. The dropdown in the Template editor shows the published price and context window next to each model, so you can compare at a glance.

A simple way to think about it:

Goal	Try first	Notes
Cheapest	Gemini 2.5 Flash-Lite, or GPT-5 Nano / GPT-4.1 Nano	Good for very clean spreadsheets with simple headers.
Best balance	Gemini 2.5 Flash, GPT-5 Mini, GPT-4.1 Mini	Sensible default for most clients.
Highest accuracy	Gemini 3.1 Pro Preview, Gemini 2.5 Pro, GPT-5.4, GPT-5 Pro	Use for tricky photos, scanned PDFs, or messy Excel files. Costs more per run.
Reasoning-heavy edge cases	o3, o4-mini, GPT-5.2 Pro	Use when shifts need maths or logic (overlapping shifts, computed end-times, etc.).

Rule of thumb: start with a mid-tier model on the Generalist, and a higher-tier model on the Auditor. The Auditor only sees a smaller payload (the rows the Generalist produced) so a smarter model there is usually worth it.

Provider differences (in plain English)

Google Gemini generally has a much larger context window (1–2 million tokens), which means it can read very large Excel files in a single pass. It also tends to be cheaper.
OpenAI (GPT-5 / GPT-4) is often stronger at understanding handwritten or noisy images and at strict structured output. Slightly more expensive on like-for-like models.

There is no "right" answer — A/B test with the client's real files (see below).

Supported file types

Format	Status	Notes
Excel (.xlsx, .xls)	✅ Recommended	Most accurate; supports source-cell highlighting in the review grid.
CSV	✅ Recommended	Same accuracy as Excel; great for exports from legacy rota systems.
PDF	⚠️ Supported	Works for clean, machine-generated PDFs. Scanned PDFs depend heavily on image quality.
PNG / JPG / JPEG / GIF / WEBP	⚠️ Supported	Use for photos of printed rotas. Lower accuracy; source-highlight feature is not available.

Always push the client towards Excel or CSV if there is any option. The tool can do photos and PDFs, but every extra accuracy point you give the AI by sending it a structured file is a row you don't have to correct by hand.

Building a great Template (Instruction Set)

A Template (stored on the b3s__Import_Instruction_Set__c object — Import Instruction Set in the UI) bundles four things:

Name — a clear, client-specific name. Example: Acme Hospitality — Weekly Rota (Excel).
Generalist configuration — the prompt, provider, model, and date format.
Auditors — an ordered list of follow-up agents.
Field mapping — the list of fields the AI should extract, each mapped to a Salesforce field.

Field mapping

For every field you want extracted, set:

Target Field — the Salesforce API name (e.g. b3s__Shift_Start__c).
Label — what the AI sees (e.g. Shift Start Date/Time).
Description — a hint in plain English. This is one of the highest-leverage things you can tune. "Combine the Date column with the Start Time column. If Start Time is empty, leave this field empty." is the kind of guidance that pays for itself.
Type — text, number, boolean, date, time, datetime, picklist, multipicklist, or reference (lookup).
For lookups (References): the related object, the field to display, and a filter. Use {accountId} in the filter to scope to the Account picked in Step 1. Example: b3s__Account__c = '{accountId}' AND IsActive__c = true.

Writing a good Generalist prompt

The prompt is plain English. It is usually 5–15 short bullets. Cover:

Where the data lives in the file (e.g. "Each row is a shift. Columns A–G are the days of the week.").
How to interpret special markings (e.g. "A cell with 'X' means the person is off — skip those.").
Edge cases you have seen in this client's files (e.g. "If two times are written like '07:00-15:00', split them into Start and End.").
Anything never to do (e.g. "Never invent a Site name. If you cannot read the Site, leave it blank.").

Keep prompts concrete and grounded in the actual file you are working with. Vague prompts ("extract the shifts accurately") perform much worse than specific prompts ("the first column is always the contact's full name").

Date format

Set the date format on the Template (DMY for UK / EU, MDY for US, YMD for ISO). The AI follows this. Getting this wrong is one of the most common causes of off-by-one-month errors.

Tips

Start from a working Template and tweak. Copy an existing client's Template and change the prompt and field mappings — much faster than writing from scratch.
One Template per file format per client. If a client sends a weekly file and an end-of-month adjustment file, those are usually two Templates.
Update the Template, not the file. If the client's format changes, update the Template. Do not ask the client to reformat their file.

Generalist vs. Auditor sub-agents

The tool runs the file through two kinds of agent. Understanding the difference is the key to a reliable setup.

The Generalist

Runs first.
Sees the whole file.
Job: produce a first draft — one row per shift, with every field filled in as best it can.
Should be biased towards completeness (catch every shift) rather than perfection.

The Auditor(s)

Run after the Generalist, in order.
Each Auditor sees both the original file and the current rows produced so far.
Job: check the previous output, correct mistakes, fill in anything missing, enforce the rules in your prompt.
Should be biased towards accuracy and consistency.

You can have as many Auditors as you want. A common, effective setup:

Agent	Role	Suggested model
Generalist	Extract every shift from the file.	Mid-tier (e.g. Gemini 2.5 Flash)
Auditor #1	Verify dates and times are correctly parsed, especially overnight shifts.	Mid-tier or higher
Auditor #2	Verify every Site/Role matches the Account's actual list of Sites/Roles.	Higher-tier reasoning model

Why use Auditors at all?

A single agent trying to do everything tends to drop accuracy when the prompt grows. Splitting the work into focused passes — first find everything, then verify dates, then verify lookups — is much more reliable, even if it uses slightly more tokens overall. Think of it like proof-reading: one pass for content, one pass for grammar, one pass for facts.

Important: every Auditor adds cost and latency. Don't add Auditors "just in case" — add one only when you can describe in one sentence what it is checking that the previous step is missing. When A/B testing a new Instruction Set, you may find that you don't even need to add an Auditor agent.

A/B Testing your Templates

Before you sign off a Template for live use with a client, you must A/B test it. This is not optional — small changes to a prompt or a model can dramatically change the result quality.

Recommended testing process

Pick a representative sample. Get 3–5 real schedule files from the client. Include at least one tricky one (lots of edits, overlapping shifts, photo, etc.).
Hand-build the expected result for one file — write down what the perfect import would look like, row by row. This is your "ground truth".
Create two versions of the Template. Same fields, but vary one thing at a time:
- Different Generalist model (e.g. Gemini Flash vs GPT-4.1 Mini).
- Different number of Auditors (1 vs 2 vs 3).
- Different wording on the prompt.
Run each version on the same file. Compare against your ground truth.
- How many rows did each version extract?
- How many were exactly right?
- How many needed correction?
- What did each cost (the token count is shown in Step 3)?
- Pay extra attention if the AI was successful in extracting date/date time/time data accurately. Was the date parsed/calculated correctly?
Pick a winner, archive the loser, then test the next variable.

Why this matters

The cheapest model is not always best. A cheaper model that produces 30% wrong rows costs more in human review time than an expensive model that produces 2% wrong rows.
More Auditors is not always better. Adding a 3rd Auditor sometimes introduces errors as much as it fixes them. Measure before committing.
Prompts decay. A Template that worked perfectly in January may start failing in June because the client's file format drifted. Re-test quarterly.

Document your tests. Save a note against each Template recording what you tested, what you chose, and why. The next consultant to touch it will thank you.

Permissions

Two layers of permission control who can do what:

1. Salesforce permissions

Users who need to use the tool require:

Visualforce page access for the RecordImporter page.
Object permissions on the target object (currently b3s__Shift__c) — at minimum Read and Create; Edit if they will update existing shifts.
Read access on every object used by lookup fields in the Template (e.g. b3s__Site__c, Contact, Account).
Read access on b3s__Import_Instruction_Set__c so they can see Templates. Only consultants/admins typically need Create / Edit / Delete on this object.
Field-Level Security on every field referenced in the Template — both source fields (lookups) and destination fields (shift fields).

Grant these through a dedicated permission set (e.g. AI Shift Importer User and AI Shift Importer Admin). Avoid using profile-level permissions for this — permission sets are much easier to move between orgs.

Moving Instruction Sets between orgs

Templates are stored as records of the b3s__Import_Instruction_Set__c object in Salesforce. That makes moving them between orgs (e.g. from a sandbox you used to design them, to production) a normal Salesforce data move — no developer help needed.

Fields that make up a Template

Field	What it holds
`Name`	The Template name.
`b3s__Generalist_Config__c`	The Generalist's prompt, provider, model, date format (stored as JSON text).
`b3s__Auditors_Config__c`	The full list of Auditors (stored as JSON text).
`b3s__Field_Mapping_Config__c`	The field mappings (stored as JSON text).

You do not need to understand the JSON inside those fields — just treat them as opaque text and copy them across exactly as-is.

How to export Templates from the source org

In the source org, open Setup → Object Manager → Import Instruction Set.
Click List Views, open a list that shows the records you want to move (or create one).
Use Salesforce native list view export: open the list view, click the export icon (downward arrow), choose CSV.
- Alternatively, run a Report on Import_Instruction_Set__c that returns Name plus the three config fields and export it to CSV.
Open the CSV and confirm all four fields are populated. Save the file.

Heads-up: the three config fields are Long Text — they can be thousands of characters long. Excel will display them fine but make sure not to accidentally truncate them when re-saving the CSV. Excel sometimes wraps long text into multiple cells; if that happens, prefer using a plain text editor (Notepad, VS Code) or Google Sheets to inspect the file.

How to import Templates into the target org

Using the Salesforce Data Import Wizard (Setup → Data Import Wizard, or go to the Instruction Template Object Tab and click on "Import"):

Choose Custom Objects → Import Instruction Set.
Choose Add new records (or Add new and update existing records if you are refreshing).
Upload the CSV you exported.
Map the four columns: Name, b3s__Generalist_Config__c, b3s__Auditors_Config__c, b3s__Field_Mapping_Config__c.
Run the import and confirm every row succeeded.
Open the AI Assisted Shift Import Tool in the target org and check that the Templates appear in Step 2.

If the Data Import Wizard truncates the long text fields, use Data Loader instead — it has no row-size limit and handles long text more reliably.

One last check after moving

Lookup filters in the Template reference objects and fields by API name (e.g. b3s__Site__c, b3s__Account__c). After importing into the new org, open each Template, run one test file through it, and confirm the lookup columns resolve correctly. If a field or object has a different API name in the new org, the lookup query will silently return no matches.

Limitations & when not to use the tool

The tool is designed for small to medium ad-hoc imports — typically a weekly or monthly rota for one client. It is not designed for mass data loads.

Practical limits

Up to roughly 100 shifts per run is the sweet spot.
Up to ~500 shifts is doable but the review step gets painful and you will hit a noticeable lag in the grid.
Above 500 shifts — do not use this tool. The AI cost becomes meaningful, the grid becomes slow to navigate, and the chance of human error in the review step rises.
Excel file size: keep under ~2 MB. Larger files (especially with embedded images or many sheets) will either be slow or exceed the AI's context window.
PDF / image size: keep individual files under ~5 MB. Larger files should be downscaled before upload.

When to use something else

Situation	Use this instead
Bulk migration of thousands of historical shifts.	Data Loader (insert/upsert directly to `b3s__Shift__c`).
Clean CSV from another system, no AI extraction needed.	Salesforce Data Import Wizard.
Recurring scheduled imports.	A proper integration (MuleSoft, REST API, ETL tool).
One-time migration from another scheduling system.	Data Loader, with the data prepared in Excel first.

In all of those cases, the AI Assisted Shift Import Tool will work — but you are paying AI cost and human review time for something a direct data load would do faster and cheaper.

Rule of thumb: if a client gives you a clean CSV they exported from another system and it already has Salesforce-style IDs in it, skip this tool entirely. If it's the messy human-formatted file the floor manager prints every Sunday, this tool is exactly the right answer.

Troubleshooting

Symptom	Likely cause	Fix
Pipeline fails immediately with a 401 / 403 from the provider.	Invalid or expired key.	Generate a new key in the provider's console; re-paste.
Pipeline fails with a quota / billing error.	Provider account out of credit (OpenAI) or daily quota exceeded (Gemini free tier).	Top up the provider account or switch to a different model.
Dates are off by one month.	Date format setting on the Template is wrong (DMY vs MDY).	Edit the Template, switch the date format, re-run.
Lookup column is empty / red for every row.	The Template's lookup filter references an object/field that doesn't exist in this org, or no records match.	Open the Template, fix the API names, re-run.
Many rows have low (red) confidence.	The file is hard to read (photo, scan, very busy spreadsheet) or the prompt is too generic.	Tighten the Generalist prompt; try a higher-tier model; ask the client for a cleaner file.
Confidence cell click does nothing.	The file is an image or PDF — source-highlight is Excel/CSV only.	Working as designed.
Some rows imported, some failed.	Salesforce validation rule rejected the failed rows.	Read the red error badge, fix the row, click Start Import again. Only failed rows are re-submitted.
Need to start over.	Refresh the page.	The wizard resets to Step 1.

If something looks broken in a way that isn't covered here, capture the file, the Template name, and a screenshot of the error, and raise it with the team that owns the tool.

AI Assisted Shift Import Tool