Documentation

AWS Lambda

AWS Lambda is the AWS serverless compute service. Polysync uses the official AWS SDK for .NET v4 (AWSSDK.Lambda and AWSSDK.SecurityToken) to list functions, invoke them with a JSON event payload, parse output parameters from the response, and surface a direct link to the AWS Lambda console for monitoring.

Required attributes

  • Region — the AWS region containing the Lambda function (e.g., us-east-1, ap-southeast-2). All Lambda API calls are region-scoped.

Optional platform-level defaults

  • Invocation Type — RequestResponse (synchronous, default), Event (asynchronous fire-and-forget), or DryRun (validation only).
  • Qualifier — a Lambda version number or alias (e.g., PROD, 1). Omit to invoke $LATEST.

Both can be overridden per Polysync Job. Precedence: job override → platform default → RequestResponse (no qualifier).

Authentication methods

  • Web Identity Federation ⭐ (recommended for Polysync SaaS) — Polysync exchanges its Microsoft Entra ID workload identity token for short-lived AWS credentials via sts:AssumeRoleWithWebIdentity. No long-lived secrets stored. Required attributes: Role ARN.
    • In AWS, create an IAM Identity Provider (OIDC) trusting Polysync's Entra ID issuer (https://login.microsoftonline.com/<polysync-tenant-id>/v2.0) with audience sts.amazonaws.com.
    • Create an IAM role whose trust policy allows sts:AssumeRoleWithWebIdentity from that provider with a condition on the Polysync workload identity's sub/oid claim.
  • Access Key — Provide Access Key Id, Secret Access Key, and optionally Session Token. Simplest, but the secret must be rotated and stored in a Secret Vault.
  • Assume Role — Provide a bootstrap Access Key Id and Secret Access Key, plus the Role ARN to assume. The bootstrap user only needs sts:AssumeRole on the target role; the assumed role holds the Lambda permissions.
  • Instance Profile — Uses the host EC2/ECS instance profile. Only viable when Polysync is deployed inside AWS.

IAM permissions checklist

The role / user used to call Lambda must hold (at minimum):

  • lambda:ListFunctions — discover available functions.
  • lambda:GetFunction — read function metadata, including environment variables.
  • lambda:InvokeFunction — invoke functions (scope to specific function ARNs in production).

Plus any IAM permissions the Lambda execution role needs to access downstream AWS services (defined on the Lambda's role, not the Polysync caller).

Job discovery

Polysync calls ListFunctions (paginated via Marker) and imports each Lambda function as a Polysync Job. Because Lambda has no formal event-schema declaration, the function's environment variables are imported as suggested input parameter defaults — they're the closest discoverable surface and typically correspond to keys the function expects in its event payload. Users can add, remove, or rename parameters and assign Direction metadata (Input, Output, InputOutput).

Parameter conventions

  • Input parameters become top-level properties of a JSON event payload built at invocation time. The provider honours each parameter's declared data type (number, boolean, JSON object/array) when serialising. Parameters whose value is already a valid JSON object or array string are embedded as raw JSON, not strings.
  • Output parameters are extracted from the Lambda response Payload when Invocation Type = RequestResponse. The provider parses the response as JSON and updates any parameter whose Direction is Output or Input&Output and whose name matches a top-level property of the response (case-insensitive).
  • For Event (asynchronous) invocations, no response payload is available; output parameters are not populated.

Execution flow

  1. ExecutePipelineAsync resolves the effective invocation type and qualifier, builds the JSON event payload, then calls InvokeAsync(FunctionName, InvocationType, Payload, Qualifier).
  2. The status is determined synchronously from the AWS response:
    • RequestResponse: HTTP 200 + no FunctionError → Success; FunctionError set (Handled / Unhandled) → Failed.
    • Event: HTTP 202 Accepted → Success (queued); anything else → Failed.
    • DryRun: HTTP 204 No Content → Success (permissions and resource validated); otherwise → Failed.
  3. The provider returns a composite RunId of the form {functionName}/{awsRequestId}#{status}. AWS Lambda has no GetInvocation API, so GetPipelineRunStatusAsync decodes the status from the RunId rather than calling AWS again.
  4. CancelPipelineRunAsync returns false — AWS Lambda does not support cancelling an in-flight invocation.

Monitor URL

https://{region}.console.aws.amazon.com/lambda/home?region={region}#/functions/{functionName}?tab=monitoring

This deep-links into the AWS Lambda console for the specific function, showing invocation metrics, recent CloudWatch logs, and configuration. For Event invocations, the monitoring tab is the primary way to confirm execution outcomes.

Troubleshooting

  • AccessDeniedException on InvokeFunction — the caller's IAM principal is missing lambda:InvokeFunction on arn:aws:lambda:{region}:{account}:function:{functionName}.
  • ResourceNotFoundException — confirm the function name (and Qualifier, if any) is correct in the target region.
  • Handled / Unhandled FunctionError — the function returned a runtime error. The response payload (truncated, if small) is surfaced on the Polysync run message. Check CloudWatch Logs for the full stack trace.
  • Web Identity Federation InvalidIdentityToken — check that the IAM Identity Provider's thumbprint matches login.microsoftonline.com, the audience is sts.amazonaws.com, and the role trust policy allows the Polysync workload identity's sub / oid.
  • Output parameters not populated — confirm the invocation type is RequestResponse, the response is a valid JSON object (not a JSON string, number, or array at the root), the parameter's Direction is Output or Input&Output, and the parameter name matches a top-level property name in the response (case-insensitive).
  • Payload too large — Lambda's synchronous invocation payload limit is 6 MB request / 6 MB response. For larger data, write to S3 from the function and pass only references through Polysync parameters.