Skip to main content

API Reference

This reference documents the public APIs for integrating Azure Logic Apps UX components into your applications.

Designer Package​

Installation​

npm install @microsoft/logic-apps-designer

Basic Usage​

import { DesignerProvider, Designer } from '@microsoft/logic-apps-designer';

function App() {
  return (
    <DesignerProvider options={designerOptions}>
      <Designer />
    </DesignerProvider>
  );
}

Core Components​

<DesignerProvider>​

The main provider component that supplies context and services to the designer.

interface DesignerProviderProps {
  options: {
    services: ServiceOptions;
    workflowSpec?: WorkflowSpec;
    initialState?: InitialState;
    isDarkMode?: boolean;
    language?: string;
    features?: FeatureOptions;
  };
  children: React.ReactNode;
}

<Designer>​

The workflow designer canvas component.

interface DesignerProps {
  backgroundProps?: BackgroundProps;
  panelLocation?: PanelLocation;
  customPanelLocations?: CustomPanelLocations;
  displayRuntimeInfo?: boolean;
}

Runtime Connection Selection (Designer V2, Standard)​

Designer V2 supports expressions in a Standard ServiceProvider action's inputs.serviceProviderConfiguration.connectionName. The Change connection > Use expression editor is enabled by default for supported actions; no host option is required. Managed API connections, Consumption workflows, and triggers do not expose expression authoring. Imported expressions are preserved when their context does not support authoring. Designer V1 is unchanged and does not offer this editor.

The connection panel places Select existing, Create new, and (when supported) Use expression tabs below the action name. Switching tabs preserves the expression draft until it is applied or the panel is closed. Saved expressions use token presentation in the connection editor. Action details show only Connection selected at runtime, with Change connection to view or edit the expression. The Connections panel groups runtime-selected actions under their connector, in a Connection selected at runtime block. Select an action to edit its expression, or use Reassign to move the block's actions to an existing or new connection together. Expression authoring remains per-action. The expression tab lists existing connection keys for the current connector as case-sensitive examples; this reference list does not select a connection.

Expression editing is per action, not bulk connection reassignment. The token picker does not insert implicit loops. For per-item selection within an existing loop, enter an explicit expression such as @items('For_each')?['connectionName'].

An expression such as @parameters('connectionName') must resolve at runtime to an existing, case-sensitive key in connections.json, for the action's service provider. Display names are not connection keys. The Designer does not create connections at runtime or change their credentials.

The optional Design-time connection supplies resource browsing and schema discovery while editing. This selection is session-only and is not serialized as a runtime fallback. Without a design-time connection, enter parameter values manually; connection-dependent browsing is unavailable. Existing values are preserved. A schema discovered using one connection does not guarantee the same schema for every runtime target.

Hosts must keep connection keys stable and preserve connections that may be selected dynamically, even if no action references them statically. For multi-tenant workflows, map authorized tenant context to permitted connection keys rather than accepting an arbitrary caller-supplied key as authorization.

Workflow Extraction Progress (Designer V2, Standard)​

The optional workflowExtractionService host boundary supports an attempt-scoped callback on WorkflowExtractionRequest. Existing hosts do not need to implement it:

type WorkflowExtractionHostStep = 'validating-child' | 'creating-child' | 'saving-source';
interface WorkflowExtractionProgress {
  step: WorkflowExtractionHostStep;
  status: 'in-progress' | 'completed';
}
// Additional optional field on WorkflowExtractionRequest:
// onProgress?: (progress: WorkflowExtractionProgress) => void;

request.onProgress?.({ step: 'saving-source', status: 'in-progress' });
// After the durable source write has been confirmed:
request.onProgress?.({ step: 'saving-source', status: 'completed' });

Emit notifications at real validation, child creation/readiness, and durable source save checkpoints. For hosts that publish children, creating-child/completed must wait for publication and callable-child readiness, not merely file creation. Protect persistence from observer exceptions using the host's sanitized operational logging. Do not retain callbacks or share them across operations or retries.

The designer owns isolated preparation/hydration and live source application. The reusable ProgressStepper from @microsoft/designer-ui presents three connected milestones: Prepare workflows (hydration and validation), Create child workflow (persistence and host readiness), and Update parent workflow (durable source save, live application, and required finalization). Unstarted milestones have no status message. In-progress, success, and error states are controlled by real checkpoints; errors show the host's contextual recovery message at the affected milestone.

Completed milestones remain visible. Older hosts without notifications do not produce fictional intermediate progress; an overall completed transaction confirms all three milestones. child-created and source-saved alone do not establish child readiness; only explicit child completion or an overall completed result does. source-saved confirms durable source persistence but does not imply successful live application. Parent-update success waits for onApplied and successful transaction finalization. Cleanup failures remain an error even after live application, preserving the existing terminal/reload behavior.

persistenceDescription remains concise host-provided submission copy. Contextual partial-result and error messages retain host-specific recovery instructions. Empty failure or partial-result messages use a localized fallback without changing durability, retry, or terminal recovery semantics. The progress footer follows the complete input/output bindings accordion and adds dialog-specific vertical breathing room while the preview/bindings scroll. The completion banner follows the stepper, above the action row. Available child navigation stays in that row next to Close (or the existing retry/cancel actions for partial results), with an accessible new-tab description. Long recovery details have a bounded keyboard-scrollable progress region, separate from the actions; short viewports allow whole-dialog scrolling so Close remains reachable. The child navigation action opens a new tab without replacing the source editor.

ProgressStepper (Designer UI)​

ProgressStepper is a controlled, informational ordered list, not wizard navigation. Steps have stable IDs and labels, and accept an omitted status, in-progress, success, or error. Error steps require contextual error text. The component has no workflow, persistence, or timing logic; callers own state and announcements are derived from those controlled steps. It uses Fluent tokens and becomes vertical in narrow containers.

import { ProgressStepper, type ProgressStepperStep } from '@microsoft/designer-ui';

const steps: ProgressStepperStep[] = [
  { id: 'prepare', label: 'Prepare workflows', status: 'success' },
  { id: 'create', label: 'Create child workflow', status: 'error', error: 'Child readiness could not be confirmed.' },
  { id: 'update', label: 'Update parent workflow' },
];

<ProgressStepper aria-label="Extraction progress" steps={steps} />;

Service Configuration​

The designer requires several services to be configured:

interface ServiceOptions {
  // Required Services
  connectionService: IConnectionService;
  operationManifestService: IOperationManifestService;
  searchService: ISearchService;
  oAuthService: IOAuthService;
  workflowService: IWorkflowService;
  
  // Optional Services
  connectorService?: IConnectorService;
  gatewayService?: IGatewayService;
  loggerService?: ILoggerService;
  runService?: IRunService;
  apimService?: IApimService;
  functionService?: IFunctionService;
  appService?: IAppService;
  tenantService?: ITenantService;
  customCodeService?: ICustomCodeService;
  hostService?: IHostService;
  workspaceService?: IWorkspaceService;
  userService?: IUserService;
  templateService?: ITemplateService;
}

Hooks​

Workflow State Hooks​

// Check if workflow has unsaved changes
const isDirty = useIsWorkflowDirty();

// Get node display name
const displayName = useNodeDisplayName(nodeId);

// Get node metadata
const metadata = useNodeMetadata(nodeId);

// Check initialization status
const nodesInitialized = useNodesInitialized();

Connection Hooks​

// Get connection mapping
const connectionMapping = useConnectionMapping();

// Get connection references
const connectionRefs = useConnectionRefs();

// Check if operation is missing connection
const isMissingConnection = useIsOperationMissingConnection(nodeId);

Validation Hooks​

// Get all settings validation errors
const settingsErrors = useAllSettingsValidationErrors();

// Get all connection errors
const connectionErrors = useAllConnectionErrors();

History Hooks​

// Check undo/redo availability
const canUndo = useCanUndo();
const canRedo = useCanRedo();

Actions​

Workflow Actions​

// Serialize current workflow
const serializedWorkflow = await serializeWorkflow(store.getState());

// Discard all changes
dispatch(discardAllChanges());

// Set workflow dirty state
dispatch(setIsWorkflowDirty(true));

// Focus on a node
dispatch(setFocusNode(nodeId));

Panel Actions​

// Open a panel for a node
dispatch(openPanel(nodeId, panelType));

// Clear panel
dispatch(clearPanel());

// Collapse panel
dispatch(collapsePanel());

// Change panel node
dispatch(changePanelNode(nodeId));

State Management​

// Reset workflow state
dispatch(resetWorkflowState());

// Reset nodes load status
dispatch(resetNodesLoadStatus());

// Reset designer dirty state
dispatch(resetDesignerDirtyState());

Utility Functions​

Parameter Utilities​

// Validate parameter
const validation = validateParameter(parameter, value);

// Convert parameter value to string
const stringValue = parameterValueToString(parameter, value);

// Load parameter value from string
const value = loadParameterValueFromString(parameter, stringValue);

Token Utilities​

// Get output token sections
const sections = getOutputTokenSections(operation);

// Get expression token sections
const expressions = getExpressionTokenSections();

Segment Utilities​

// Create literal value segment
const literal = createLiteralValueSegment(value);

// Create token value segment
const token = createTokenValueSegment(tokenData);

// Convert value segments
const converted = ValueSegmentConvertor(segments);

Types​

Workflow Types​

interface Workflow {
  definition: LogicAppsV2.WorkflowDefinition;
  connectionReferences?: ConnectionReferences;
  parameters?: Record<string, WorkflowParameter>;
}

interface ConnectionReference {
  connection: {
    id: string;
  };
  api: {
    id: string;
  };
  connectionName?: string;
  authentication?: Authentication;
}

interface WorkflowParameter {
  name: string;
  type: string;
  value?: any;
  defaultValue?: any;
  metadata?: ParameterMetadata;
}

Custom Code Types​

interface CustomCode {
  id: string;
  name: string;
  type: 'javascript' | 'csharp' | 'typescript';
  content?: string;
}

interface CustomCodeWithData extends CustomCode {
  fileData?: string;
  fileExtension: string;
  fileName: string;
  isModified: boolean;
  isDeleted: boolean;
}

Data Mapper Package​

Installation​

npm install @microsoft/logic-apps-data-mapper-v2

Basic Usage​

import { DataMapperDesigner } from '@microsoft/logic-apps-data-mapper-v2';

function DataMapper() {
  return (
    <DataMapperDesigner
      mapDefinition={mapDefinition}
      sourceSchema={sourceSchema}
      targetSchema={targetSchema}
      dataMapperApiService={apiService}
      options={options}
    />
  );
}

Data Mapper Components​

<DataMapperDesigner>​

The main data mapper designer component.

interface DataMapperDesignerProps {
  mapDefinition?: MapDefinitionEntry;
  sourceSchema: SchemaExtended;
  targetSchema: SchemaExtended;
  dataMapperApiService: IDataMapperApiService;
  options?: DataMapperDesignerOptions;
}

Data Mapper Services​

interface IDataMapperApiService {
  compile(mapDefinition: string, targetSchemaId: string): Promise<string>;
  getAvailableCustomFunctions(): Promise<FunctionData[]>;
  getSchemaTree(schemaId: string): Promise<SchemaExtended>;
  saveDraftStateCall?(mapDefinition: string): Promise<void>;
  saveXsltCall?(xslt: string): Promise<void>;
  testMap?(mapDefinition: string, context: TestMapContext): Promise<TestMapResponse>;
}

Designer UI Package​

Installation​

npm install @microsoft/designer-ui

Common Components​

This package provides stateless UI components used across the designer:

  • Form controls
  • Icons and assets
  • Theme definitions
  • Accessibility utilities

Note: This package must remain stateless - no Redux, no hooks with state.

Shared Package​

Installation​

npm install @microsoft/logic-apps-shared

Utilities​

API Clients​

import { ArmParser } from '@microsoft/logic-apps-shared';

const parser = new ArmParser(armUrl);
const resourceId = parser.getResourceId();

Data Parsers​

import { parseWorkflowDefinition } from '@microsoft/logic-apps-shared';

const parsed = parseWorkflowDefinition(definition);

Localization​

import { getIntl } from '@microsoft/logic-apps-shared';

const intl = getIntl();
const message = intl.formatMessage({ defaultMessage: 'Hello' });

VS Code Extension​

Installation​

The VS Code extension is available in the VS Code Marketplace as "Azure Logic Apps (Standard)".

Extension API​

For extension development:

import { ExtensionApi } from '@microsoft/vscode-extension-logic-apps';

// Activate extension
export async function activate(context: vscode.ExtensionContext): Promise<ExtensionApi> {
  // Extension activation logic
  return api;
}

Migration Guide​

From v1 to v2​

Designer Changes​

// v1
import { Designer } from '@microsoft/designer';

// v2
import { DesignerProvider, Designer } from '@microsoft/logic-apps-designer';

// v2 requires DesignerProvider wrapper

Service Configuration​

// v1
const designer = new Designer({
  services: { /* ... */ }
});

// v2
<DesignerProvider options={{ services: { /* ... */ } }}>
  <Designer />
</DesignerProvider>

Troubleshooting​

Common Issues​

Service Not Configured​

Error: Required service 'connectionService' not provided

Solution: Ensure all required services are configured in ServiceOptions.

State Not Initialized​

Error: Cannot read workflow state before initialization

Solution: Wait for useNodesInitialized() to return true before accessing state.

Token Picker Not Working​

Error: Expression builder context not found

Solution: Ensure component is wrapped in DesignerProvider.

Support​