Skip to content
Merulan

Connect and map a source

Connect a Source, map its fields, and inspect a preview Run before choosing to promote Records.

Use this guide when you need to connect input to Data Pipelines and check the mapping before a write. As a builder, you finish with a saved Pipeline version and a preview Run you can inspect.

Before you start

The Source must have a connection you can use in this Workspace. Confirm the target Entity kind and fields in Company Schema. Decide which field identifies a Record across repeated loads. Use the Console guide for access. The Pipeline model explains identity and write policy.

Choose the input path before mapping. An upload needs a CSV file at run time. An installed Source needs accepted object bindings and current revisions. A connection type shown as unavailable is not an input you can execute.

Connect the input

In the Console's Sources area, create the Source with its name, available connection type, and intended scope. For an upload connection, supply a CSV if you want discovery during creation. Inspect the saved Source and its schema snapshot. For a connected system, use the supported connection test or discovery action. Proceed only when the input fields and scope match the data you intend to load.

Map the fields

From the Source, open Build pipeline. Name the Pipeline and map each input column to the target Entity kind and field. Choose the semantic key and write mode for the intended result. Save the Pipeline, then inspect its version in the builder. Validate the graph and correct diagnostics that name an unknown field, stale target, or invalid mapping before running it.

Preview the Run

In the Pipeline builder, use Dry run for an uploaded CSV or Preview installed sources for accepted Source bindings. Inspect the returned Run, sample, row errors, and bound revisions. A preview stages evidence without promotion. The result is a checked mapping path, not completed Record writes.

For an API dry run, choose a request key before sending it and retain the exact request. Runs and lineage explains replay when the response is uncertain. Installed-source preview rechecks current eligibility. It does not replay a kept request-key result.

Checkpoints

The Source's saved scope must match the intended input. The Pipeline version must name the expected fields, key, and output target. The preview Run must show the input it actually used and the errors it found. A successful save proves the definition was kept. A preview's status, counts, and artifacts provide the separate evidence that the mapping ran.

Success

The Source now feeds a saved Pipeline version with a readable preview Run. Confirm that the preview values match the intended fields and that each row error has a known cause. Keep the Run handle and version for the promotion decision. If the preview staged review candidates, an accepted review and its later write remain separate decisions.

When it fails

The Source or mapping failure determines which part to repair. Use the named field, binding, or revision in the result before repeating the preview.

VALIDATION_FAILED

The request does not fit this Pipeline or its input. Read the detail, correct the named input or mapping, then validate the saved version again.

Select a CSV file first.

The upload path has no file. Select the intended CSV in the builder and run its preview. An installed Source uses the separate preview path.

Recovery

The Source preview can refuse a stale binding, an ineligible object, or a graph that needs repair. Follow the result's recovery: rebind the current revision, choose an eligible object, or accept a corrected graph version. Recheck the preview after that change. If an API response is uncertain, resolve the existing request identity before deciding that another Run is needed.

Next steps