Skip to main content

Project Organization

James Herring
Updated

A well-organized project is easier to maintain, debug, and hand off to other team members. This article covers practical patterns for structuring your Precision Bridge projects so that migrations remain manageable as they grow in scope.

Procedures and Steps

A procedure is an ordered sequence of steps. A typical migration procedure contains multiple Migrate Records steps that move related entities (users, groups, parent records, child records) in dependency order. Each step targets one source/target table pair, so a project that migrates a dozen entities is usually one or two procedures with many steps — not a dozen separate procedures.

Reserve separate procedures for cases where a clear boundary exists:

  • A distinct migration scope owned by a different team or run on a different schedule.
  • A workflow that needs to be invoked by multiple parents via the Call Procedure step (see Sub-Procedures below).
  • A logically separate task — for example, a one-off data-cleanup procedure that runs before the main migration.

Ordering Steps Within a Procedure

Order steps inside a procedure by data dependency, not by source table. A reliable pattern is:

  1. Identity data — Users, contacts, accounts. These are referenced by most other records.
  2. Reference data — Groups, categories, priorities, configuration items. These provide lookup values for transactional records.
  3. Transactional data — Incidents, requests, changes, problems. These reference both identity and reference data.
  4. Child data — Journal entries, comments, work notes. These attach to transactional records.

This ordering ensures that when a child record references a parent, the parent already exists in the target system and a correlation entry has been written.

Attachments are not a separate step. Attachment migration is a toggle on the Migrate Records step itself (see Advanced Options). Enable it on the step that migrates the parent record — the attachments are downloaded and re-uploaded alongside their owning record.

If you want the step order to be obvious at a glance, give each Migrate Records step a descriptive name (e.g. Migrate Users, Migrate Incidents, Migrate Work Notes). Numeric prefixes are optional — the step list already shows execution order top-to-bottom.

Sub-Procedures

The Call Procedure step lets one procedure invoke another. Use sub-procedures when:

  • A workflow is shared by multiple parents. A sub-procedure that loads lookup data into variables, called at the start of several migrations, removes duplication.
  • A workflow is invoked per-item from an Iterate step. The sub-procedure runs once per iteration with the iteration value passed in as an input variable.
  • A workflow needs to be tested in isolation. Sub-procedures can be executed directly with their own input values, which is harder to do for a sub-section of a parent procedure.

Don't split a procedure just because it has many steps. A long, linear procedure is fine as long as its steps belong together; breaking it into sub-procedures purely on length adds navigation overhead without making anything reusable.

When to Use One Project vs. Multiple Projects

Use a single project when all procedures share the same source and target systems and the data is interrelated. A single project keeps all connections, correlations, and variables in one place.

Split into multiple projects when:

  • You are migrating between different pairs of systems (e.g., ServiceNow-to-ServiceNow and Jira-to-ServiceNow).
  • Different teams own different parts of the migration and need independent control.
  • The migration is large enough that a single project becomes difficult to navigate.
  • You want to version or template parts of the migration independently.

When splitting, document cross-project dependencies clearly. If Project B depends on data migrated by Project A, note that in both projects' descriptions.

Organizing Connections

Name connections so that the system, environment, and role are immediately obvious:

  • Source - ServiceNow Production — production instance used for extraction.
  • Target - ServiceNow Development — development instance used for testing.
  • Target - ServiceNow Production — production instance for final migration.
  • Lookup - CMDB Database — read-only connection for reference lookups.

Prefixing with the role (Source, Target, Lookup) prevents accidental writes to the wrong system. When you are ready to switch from development to production, you only need to update the connection reference in each procedure rather than reconfiguring credentials across dozens of steps.

Using Templates for Reuse

Once a project is working reliably, save it as a template. Templates capture the full project structure including procedures, steps, field mappings, and configuration -- but not credentials or environment-specific settings.

Templates are valuable when:

  • You perform the same type of migration repeatedly for different clients or environments.
  • You want to establish a standard migration pattern that other team members can adopt.
  • You need a starting point for a new project that is similar to an existing one.

When creating a template, clean up any test data, temporary procedures, or one-off workarounds. A template should represent your best practice, not a snapshot of a work-in-progress.

Summary

  • A migration is usually one procedure with many ordered Migrate Records steps — not a separate procedure per entity.
  • Order steps by data dependency: identity, reference, transactional, child. Migrate attachments via the toggle on each Migrate Records step.
  • Use sub-procedures for shared logic or per-item iteration, not as a way to manage long procedures.
  • Keep one project per logical migration; split only when ownership or scope demands it.
  • Name connections with role and environment prefixes.
  • Save proven projects as templates for future reuse.

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk