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.

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​