Migrating from Another ITSM

Scope

A migration is judged by what the team can find on day one. This guide keeps the operator-facing import workflow and removes private platform detail.

How to move a tenant’s history — tickets with their timelines, knowledge, CIs and relationships, users/groups, attachments — into Beacon using the migration import console (Manage → Integrations → Migration imports).

Overview

Every import is a two-step operation:

1. Stage (dry run). Upload the export. Beacon parses it, maps the source’s statuses/priorities/types onto its own vocabulary, resolves people against the Portal directory, and shows a reconciliation report. Nothing is written to live data at this step.

2. Commit. After you’ve read the report, commit. The commit is idempotent: re-running the same (or an overlapping) export later skips what’s already imported — it never duplicates tickets, notes, articles, CIs, or attachments.

You can discard a staged import at any time; staged rows are kept for lineage but nothing is written.

Getting Started

Prerequisites

• The admin.migration.manage permission (Beacon Administrator has it).

• The Portal directory mirror synced for the tenant (Manage → Directory) — it is how migrated users are matched, by email.

• Exports from the source system (see per-entity sections below).

• For ticket imports: the target organization decided.

Recommended order

Run imports in this order so references resolve:

1. Users — builds the source-user → Portal-identity map.
2. Groups — creates assignment groups, records memberships.
3. CIs, then CI relationships.
4. Tickets (+ journal/conversations companion file).
5. Attachments (needs tickets imported first).
6. Knowledge articles (independent; any time).

Skipping the users import is allowed — tickets then resolve requesters by the email embedded in the export (Freshservice) or import them as not emails).

Preparing exports

Freshservice

Import kind	File
Tickets	the ticket CSV export (include at least Ticket ID and Subject; add Status/Priority/Type/Requester Email/Created Time for fidelity)

Attachments (both sources)

Build a ZIP whose paths are <source ticket id>/<original filename> 2 GiB expanded, 200 MB per file.

Running an import (step-by-step)

1. Manage → Integrations → Migration imports. The import history table pages 25 at a time (10/25/50/100, remembered per session) with a “Showing X-Y of Z” count, so a tenant with a long migration history is never silently truncated.

2. Pick the source system and what the file contains; choose the target organization for tickets; attach the export (+ companion file where applicable); Stage dry run.

3. Read the report: - Ready / invalid — invalid records list exactly why (missing ids, unmapped statuses). They will not be imported.

• Would create / update / skip — the projection against what’s already been imported.

• Identity resolution — how many people matched a Portal user and Unresolved people import as email/name snapshots flagged Unverified identity; Beacon never guesses a near-match.

• Unmapped source values — e.g. a custom Freshservice status. Fix at the source (re-export with standard values) or accept that those records stay out.

4. Open two or three records before you commit. The report is a tally; opening a record shows you both sides of the mapping — the source record exactly as it was exported, next to the Beacon-shaped preview of what the commit will create. Pick a plain one and an awkward one (a record with issues listed, a ticket with a long journal). This is the last point at which a wrong status or priority mapping is cheap to fix: after commit these are live rows in your practice tables.

driving the API directly.

5. Commit import (type ). Watch the outcome counts; any per-record errors are listed with their reason.

6. Spot-check: open a migrated ticket — the timeline should read like it happened in the source system (original timestamps, public replies vs internal notes), with one “Imported from …” provenance event and the original reference under the ticket’s migration details.

Post-migration steps

• Unresolved users. After the people join Portal (invite/SSO), re-run the users import — unresolved map rows upgrade in place. Tickets already imported keep their snapshots; new imports resolve fully.

• Group memberships. Beacon records each migrated membership and its resolution state, but does not add members to assignment groups automatically: group membership is keyed by Portal subject, which only exists once a person has signed in. Add members in Manage → Groups as people onboard.

• Knowledge visibility. Everything imports as internal. Review and set articles to portal deliberately.

• CI review queue. Ambiguous CI matches (a migrated CI that looks like an existing one) sit in CMDB → Review queue — resolve merge/new-CI there, then re-run the CI import to settle the skipped records.

• Attachment scanning. Migrated files enter the normal scan pipeline (pending until the sweep clears them).

Go-live validation

Before declaring a migration done, validate against the real export, not the documented schema alone: this feature was built against ServiceNow’s and Freshservice’s public API/export documentation, and tenant instances vary (custom statuses, custom columns). Stage the customer’s actual export, read the unmapped-values section of the report, and settle every unmapped value before committing. Zero invalid records is the go-live bar for tickets.

Permissions Reference

Permission	Grants