Create an Azure Synapse package¶

An Azure Synapse package triggers a pipeline in a Synapse Analytics workspace, so a Synapse pipeline becomes one step in an orchestration flow rather than something scheduled separately inside Synapse.

Before you start¶

• An Azure App Registration data provider in the workspace
• The principal needs to enumerate resource groups in the subscription — without that the chain stops before the workspace, since resource group is a required, selection-only field
• The principal needs a Synapse Artifact User role (or higher) in the Synapse workspace

The selection chain¶

Five fields, each loading the next:

Data provider → subscription → resource group → Synapse workspace → pipeline

The field help text says what each one is for:

The Azure subscription that contains the Synapse workspace.

The resource group (within the subscription) that contains the Synapse workspace.

The Synapse Analytics workspace that hosts the pipeline. Pick a resource group first to load its workspaces.

The Synapse pipeline to trigger. Loaded from the workspace — the data provider needs Synapse access (Synapse Artifact User) to list pipelines.

Each of the fetched lists has a refresh button, for when something was created in Azure after the page loaded.

Steps¶

1. Create the package¶

Orchestration → Packages → Create, then Azure Synapse from the Azure area.

The editor opens with the chain collapsed to its first field — everything below stays disabled until the one above it is set.

2. Choose the data provider¶

The Azure App Registration data provider whose service principal authenticates against Azure.

3. Choose the subscription¶

Subscriptions are fetched with the provider's service principal.

4. Choose the resource group, then the workspace, then the pipeline¶

Each list loads from the selection above it. If the pipeline list is empty while the workspace is listed, the Synapse role is missing — see the admonition above.

5. Save¶

The package saves as a Draft. Publish it to make it runnable on a schedule.

Choosing what belongs in Synapse and what belongs here¶

The same division as Azure Data Factory: keep inside one pipeline the activities that share a failure boundary, and split into separate packages the steps you want to retry, schedule or monitor independently.

The practical test is what you want to see in an execution log at 7am. One package per pipeline tells you which pipeline failed; one package for a chain of five tells you only that something did.

Best practices¶

Grant both permissions when you set up the provider, not when the pipeline list turns out empty. Azure RBAC for the workspace, Synapse Artifact User inside Synapse.

Set a timeout that reflects the pipeline's real runtime.

Name the package for the outcome, not for the pipeline's name in Synapse — the pipeline is already recorded on the Definition tab.

Rotate the client secret deliberately. Credentials are read from the data provider at run time, so one rotation covers every package that uses it — and one expiry breaks all of them at once.

Troubleshooting¶

The resource group list is empty. The service principal cannot enumerate resource groups. Grant it subscription-level Reader or Microsoft.Resources/subscriptions/resourceGroups/read. Because the field is selection-only, an empty list means the package cannot be completed at all.

The workspace list is empty but the resource group is listed. No Synapse workspace in that resource group, or the principal has no Azure role on it.

The pipeline list is empty but the workspace is listed. The Synapse role is missing. Add the principal in Synapse Studio as Synapse Artifact User.

A pipeline created after the page loaded is not listed. Use the refresh button beside the field.

"The selected … no longer exists in Azure. Please select another." Something the package referenced was deleted or renamed. Re-pick from the refreshed list.

Reference¶

Fields¶

Validation: Please select a data provider, Please select a Synapse workspace, Please select a pipeline.

Related¶

• Packages overview
• Create an Azure Data Factory package — the same trigger-a-pipeline shape, with one fewer permission system