Skip to main content

Connectors in DSL

Call connectors through the typed ctx.connectors object. Each namespace (sharepoint, dataverse, office365, etc.) exposes PascalCase operation methods with autocomplete:

await ctx.connectors.<namespace>.<Operation>(actionName, params, connectionReferenceName?, authentication?);
  • actionName — the action's unique name, as for every other action
  • params — the operation's parameters, with the names Power Automate uses (dataset, table, entityName, item/Title, ...)
  • connectionReferenceName? — the key of a connection reference in ctx.flow.connectionReferences. It must exist there (DSL016). When omitted, the reference comes from your connection configuration, or a default such as shared_sharepointonline.
  • authentication? — the authentication expression, rarely needed

There is no ctx.sharepoint or ctx.dataverse shorthand — always go through ctx.connectors. Like every action, a connector call needs await and cannot be captured in a variable: read its result with ctx.body('Name') (see Actions).

Parameters​

Power Automate writes nested connector parameters as flat keys joined with /. You can write either form; nested objects are flattened when the flow compiles:

await ctx.connectors.dataverse.CreateRecord('Create_account', {
  entityName: 'accounts',
  item: { name: 'Contoso Ltd', revenue: 5000 },
}, 'shared_commondataserviceforapps');

// compiles to the same parameters as:
await ctx.connectors.dataverse.CreateRecord('Create_account_2', {
  entityName: 'accounts',
  'item/name': 'Contoso Ltd',
  'item/revenue': 5000,
}, 'shared_commondataserviceforapps');

Dataverse​

@Action()
async run(ctx: FlowContext) {
  await ctx.connectors.dataverse.ListRecords('ListAccounts', {
    entityName: 'accounts',
    '$select': 'name,accountnumber',
    '$top': 5,
  });

  await ctx.connectors.dataverse.CreateRecord('CreateAccount', {
    entityName: 'accounts',
    'item/name': 'Sample Account',
  });
}

Typed operations: ListRecords, CreateRecord, UpdateRecord (upsert), UpdateOnlyRecord (update an existing row), DeleteRecord, GetItem ("Get a row"). RetrieveRecord is a typed alias of GetItem (it runs locally and is deployed as GetItem). Other operations (relationships, bound and unbound actions, file and image columns) are called by their operation id through the generic form below. See Dataverse Connector for the full list and their outputs.

A "Get a row" whose row id comes from a lookup column of another action fails when the lookup is empty. The validator notes this as DV_LOOKUP_UNGUARDED: wrap the call in an if on the same value when the lookup is optional.

if (!ctx.empty(ctx.body('Get_order')?.['_customerid_value'])) {
  await ctx.connectors.dataverse.GetItem('Get_customer', {
    entityName: 'accounts',
    recordId: ctx.body('Get_order')?.['_customerid_value'],
  });
}

SharePoint​

@Action()
async run(ctx: FlowContext) {
  await ctx.connectors.sharepoint.GetItems('GetTasks', {
    dataset: 'https://contoso.sharepoint.com/sites/mysite',
    table: '{list-guid}',
    '$filter': "Status eq 'Active'",
    '$top': 100,
  });
}

Typed operations cover list items (GetItems, GetItemById, PostItem, PatchItem, DeleteItem, ...), file items, folders, files, copy and move, and "Send an HTTP request to SharePoint" (HttpRequest). Item fields use the designer's format, so choice, lookup and person columns are written the way the designer writes them:

await ctx.connectors.sharepoint.PostItem('Create_task', {
  dataset: ctx.parameters('SiteUrl'),
  table: ctx.parameters('TasksListId'),
  item: {
    Title: 'Review contract',
    Status: { Value: 'New' },                 // choice column → item/Status/Value
    AssignedTo: { Claims: 'megan@contoso.com' }, // person column → item/AssignedTo/Claims
  },
});

See SharePoint Connector for the operations, output shapes and the field format.

Pagination​

List operations return one page by default. To read more, set a pagination threshold with @runtimeConfig:

/** @runtimeConfig {"paginationPolicy":{"minimumItemCount":2000}} */
await ctx.connectors.sharepoint.GetItems('Get_all_tasks', {
  dataset: ctx.parameters('SiteUrl'),
  table: ctx.parameters('TasksListId'),
});

In a local run, the SharePoint and Dataverse connectors honor it as the cloud does: they follow whole pages until they have at least that many items, and return them as { value }. Above 5,000 the setting needs a premium Power Automate plan (PAGINATION_THRESHOLD).

Other typed connectors​

ctx.connectors also has typed namespaces for office365 (Outlook mail and calendar), office365users, office365groups, teams, wordonline, excelonline, and onedriveforbusiness. These are backed by connector plugins that call Microsoft Graph, so they run locally too. See Microsoft 365 Connectors for their operations, and the CLI reference for the token flags (--graph-token, or a dedicated --word-token / --excel-token / --onedrive-token) and --auth.

Any other connector is reachable through the index signature, with its Power Automate operation id: ctx.connectors['<name>']['<OperationId>'](...). It compiles to the right Logic Apps action, but only the connectors above run locally.

Approvals and other waiting actions​

Some operations wait for a person or an external event: an approval, a Teams card that waits for a response. In Logic Apps JSON they are webhook actions (OpenApiConnectionWebhook), and they need ctx.connectorWebhook:

await ctx.connectorWebhook(
  'Start_and_wait_for_approval',
  'approvals',
  'StartAndWaitForAnApproval',
  {
    approvalType: 'Basic',
    WebhookApprovalCreationInput: {
      title: 'Approve the purchase order',
      assignedTo: 'megan@contoso.com',
    },
  },
  'shared_approvals',
);

Signature: connectorWebhook(actionName, connectorName, operation, params, connectionReferenceName?, authentication?). The arguments are positional; an object with connector/operation/params keys is not recognized.

The typed ctx.connectors.approvals.StartAndWaitForAnApproval(...) compiles to a plain connector action, not a webhook, so use ctx.connectorWebhook for operations that wait.

Approvals do not run locally: a local run records a simulated success with no outcome, so a flow that branches on the approval's response needs a mock (flowforger run --mock <ActionName>=<outputs.json>). See Approvals and Local Testing.

Generic form​

An older, untyped form takes the connector and operation as strings:

/** @deprecated Use ctx.connectors.<name>.<Operation>() instead */
ctx.connector(actionName, connectorName, operation, params, connectionReferenceName?, authentication?);

Connection Config​

When compiling to Logic Apps JSON, connector actions need connection references, either in ctx.flow.connectionReferences or in flowforger.config.json. See Connection Configuration.