Connector configuration

Triggers

Triggers define which resource events activate the connector. Each trigger specifies:

Supported resources

The following resource types can activate a trigger.

Supported events

The following events can activate a trigger.

A single trigger can match multiple resources and events. For example, a trigger with "resources": ["asset"], "events": ["create", "update"] fires on both asset creation and update.

Ordering connectors with dependsOn

When one connector’s work must complete before another connector runs, use dependsOn on the downstream trigger. This orders connector execution within the same lifecycle context — the set of work that a single upstream event triggers.

"triggers": [
  {
    "description": "Publish to catalog after quality analysis completes",
    "resources": ["asset"],
    "events": ["derivationComplete"],
    "dependsOn": ["<quality-analysis-connector-id>"],
    "steps": [{ ... }]
  }
]

dependsOn takes a list of connector IDs. SDMA evaluates the status of each listed connector within the current lifecycle before dispatching:

Rules:

For most compositions, you do not need dependsOn. Connectors compose naturally through the asset record. One connector produces a derived file or updates metadata, and another connector triggers on that lifecycle event. Use dependsOn only when you need explicit ordering within the same lifecycle context that the asset record alone does not provide.

Output routing

When a step completes — whether a REST call, a Lambda invocation, or a Deadline Cloud job — you can route the results back into the asset record. Use an output block to do this. Output routing is how connectors write results back to SDMA as governed metadata, derived files, or both.

Output routing works uniformly across all step types. The same output block works on REST steps, Lambda steps, and Deadline Cloud jobs. For Deadline Cloud, place the output block inside the deadlineJob configuration on the trigger (see Create and transform content with AWS Deadline Cloud). The vocabulary is identical regardless of which step type produced the result.

The output block supports the following routing targets:

Routing metadata with fieldMappings

The metadataAttributes target uses fieldMappings to control which response fields to write and where to write them. Each mapping has a source (a field in the step response) and a target (an SDMA metadata path). Use :type suffixes on targets to store values as typed metadata (see Type coercion).

"output": {
  "metadataAttributes": {
    "fieldMappings": [
      { "source": "overallScore", "target": "asset.metadataAttributes.qualityScore:number" },
      { "source": "classification", "target": "asset.metadataAttributes.classification" },
      { "source": "processedAt", "target": "asset.metadataAttributes.lastProcessed:date" }
    ]
  }
}

Mappings with asset. targets write to asset-level metadata. Mappings with file. targets write to file-level metadata on the triggering file. An optional filter on metadataAttributes narrows which files' attributes the connector processes.

Combining metadata and derived files

A single output block can route to multiple targets. This is the canonical pattern when a step produces both summary metadata (for search and display) and detailed output files (for downstream processing or review).

"output": {
  "metadataAttributes": {
    "fieldMappings": [
      { "source": "score", "target": "asset.metadataAttributes.qualityScore:number" },
      { "source": "status", "target": "asset.metadataAttributes.analysisStatus" }
    ]
  },
  "derivedFiles": [
    { "filter": { "fileExtensionFilter": ".json" } },
    { "filter": { "fileExtensionFilter": ".glb" }, "preview": true }
  ]
}

In this example, the step writes quality scores into asset metadata and ingests .json detail files and .glb preview files as derived files. The preview: true flag marks matched files as preview content in the Spatial Data Portal.

Any trigger that declares an output block makes the connector asset-content-scoped, which means you must approve it through the template authorization chain.

Field mappings

Field mappings transform resource metadata into the format expected by the external system. Each mapping specifies a source field from the resource metadata and a target field name for the output.

"fieldMappings": [
  { "source": "project.projectId", "target": "projectId" },
  { "source": "asset.assetName", "target": "name" },
  { "source": "geoJson:asset.geoLocation", "target": "bbox" }
]

Source field prefixes

Source fields must use a resource prefix or a special prefix:

Array iteration

Field mappings support iterating over arrays using the [*] syntax. For example, to map each file in an asset:

{ "source": "asset.files[*].path", "target": "assets[${file.path}].title" }

This creates one output entry per file, using the file path as the key.

You can define field mappings at the connector level as a default and override them per step when different events require different output shapes.

Payload fields

For publish connectors, the payload.fields array selects which mapped field names to include in the output. If you omit it, the connector includes all mapped fields. This gives you explicit control over what data the connector sends to the external system.

"payload": {
  "format": "json",
  "fields": ["projectId", "assetId", "name"]
}

Variable substitution

Many configuration fields support ${variable} substitution using resource metadata values. You can use variable substitution in:

Examples:

Type coercion

When you need to store a value as a specific metadata type, append a :type suffix to the target path or to an expression inside ${…​}:

Supported type suffixes: string, number, boolean, date, stringList, numberList.

Example:

{
  "source": "response.survey_date",
  "target": "asset.metadataAttributes.surveyDate:date"
}

{
  "source": "${response.site_codes:numberList}",
  "target": "asset.metadataAttributes.siteCodes:numberList"
}

Without a type suffix, SDMA stores values as strings. Use type coercion when the external system returns values that you want to search or filter as numbers, dates, booleans, or lists in SDMA

Intermediate state with $temp variables

In multi-step triggers, steps often need to pass values to subsequent steps — for example, capturing an ID from a creation response and using it in a follow-up request. The $temp.* namespace provides this intermediate state.

Use responseFieldMapping on a step to capture response values into $temp.* variables:

"steps": [
  {
    "description": "Create external record",
    "method": "POST",
    "path": "/api/records",
    "body": { "name": "${asset.assetName}" },
    "responseFieldMapping": [
      { "source": "id", "target": "$temp.recordId" },
      { "source": "status", "target": "$temp.status" }
    ]
  },
  {
    "description": "Upload file content to the new record",
    "method": "PUT",
    "path": "/api/records/${$temp.recordId}/content",
    "bodyFromFile": { "contentType": "application/octet-stream" }
  }
]

$temp.* variables apply only to a single trigger execution. SDMA does not share them across triggers or across connectors. Each trigger invocation starts with an empty $temp namespace.

$temp.* variables work anywhere that ${variable} substitution is supported: step paths, query parameters, body templates, and field mapping sources.

Security configuration

Connectors authenticate with external systems using a securityConfig block. SDMA supports the following authentication types:

IAM role naming

IAM roles used by connectors must follow a naming convention:

SDMA validates the role name prefix and tests role assumption when you create the connector. If the role cannot be assumed, connector creation fails with a validation error.

Examples

The following examples show different authentication configurations.

IAM role assumption:

"securityConfig": {
  "type": "AssumeRole",
  "assumeRoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/SpatialDataManagementContentPublisher-MyRole"
}

API key in a header:

"securityConfig": {
  "type": "ApiKey",
  "apiKeyLocation": "header",
  "headerName": "X-API-Key",
  "secretArn": "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:<SECRET_NAME>",
  "assumeRoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/SpatialDataManagementContentPublisher-MyRole"
}

Token-based authentication (OAuth 2.0):

"securityConfig": {
  "type": "TokenAuth",
  "tokenEndpoint": "https://auth.example.com/oauth/token",
  "tokenMethod": "POST",
  "headerName": "Authorization",
  "tokenPrefix": "Bearer",
  "tokenResponseField": "access_token",
  "tokenRequestBody": {
    "grant_type": "client_credentials"
  },
  "secretArn": "arn:aws:secretsmanager:<REGION>:<ACCOUNT_ID>:secret:<SECRET_NAME>",
  "assumeRoleArn": "arn:aws:iam::<ACCOUNT_ID>:role/SpatialDataManagementContentPublisher-MyRole"
}

Connected resources

Some connectors need to associate a project with an external resource — for example, a STAC collection or an external project identifier. The optional resources block in the connector configuration defines how SDMA discovers, validates, and displays these external resources.

Each resource type (project, asset, file) can define three sub-configurations:

Discovery configuration

The following example shows how to configure resource discovery.

"resources": {
  "project": {
    "discover": {
      "description": "List external resources",
      "method": "GET",
      "path": "/api/resources",
      "type": "rest",
      "responseListField": "items",
      "labelField": "name",
      "valueField": "id",
      "fieldMappings": [
        { "source": "id", "target": "external_id" }
      ],
      "pagination": {
        "type": "offset",
        "offsetParam": "offset",
        "limitParam": "limit",
        "pageSize": 100,
        "maxPages": 10
      }
    }
  }
}

Validation configuration

The following example shows how to configure resource validation.

"validate": {
  "description": "Verify resource exists",
  "type": "rest",
  "method": "GET",
  "path": "/api/resources/${external_id}",
  "successCriteria": {
    "statusCodes": [200]
  }
}

Display configuration

The following example shows how to configure the display of connected resources in the Spatial Data Portal.

"display": {
  "connectedResourceName": "External resource",
  "displayId": {
    "name": "Resource ID",
    "value": "${external_id}"
  },
  "deepLinkUrl": "https://example.com/resources/${external_id}"
}

Setting up a connector

To create a connector in the Spatial Data Portal:

For integration connectors that combine publish and derive roles, set the direction to bidirectional in the connector configuration.

After creating the connector, associate it with an asset template by adding the connector ID to the template’s permittedConnectorIds list. A connector does nothing until you explicitly approve it on a template. Only approved connectors trigger for assets created under that template. For more on how connectors, templates, and projects relate, see Connectors, templates, and projects.

Connector configuration reference

Every connector configuration is a JSON object with the following top-level structure:

{
  "direction": "publish",
  "connectorType": "RESTApi | S3 | lambda | eventbridge | ...",
  "enabled": true,
  "connectorConfig": {
    "securityConfig": { ... },
    "fieldMappings": [ ... ],
    "triggers": [ ... ]
  }
}

The connectorConfig object contains the connector-specific settings described below.

Security configuration

Every connector requires a securityConfig that tells SDMA how to authenticate with the target service.

Field mappings

Field mappings transform SDMA resource metadata into the structure expected by the target system. Define them at the connector level (shared by all triggers) or at the step level (overrides connector-level mappings).

Each mapping has a source and a target:

"fieldMappings": [
  { "source": "asset.assetName", "target": "properties.title" },
  { "source": "project.projectId", "target": "properties.projectId" },
  { "source": "literal:Feature", "target": "type" },
  { "source": "asset.files[*].size", "target": "files[${file.path}].size" }
]

Supported source types:

Supported target types:

Triggers

Triggers define when and how the connector runs. Each trigger specifies which resources and events activate it, and what steps to execute.

"triggers": [
  {
    "description": "On asset creation, publish metadata to S3.",
    "resources": ["asset"],
    "events": ["create", "onDemand"],
    "stepType": "s3PutObject",
    "steps": [{ ... }]
  }
]

Steps

Each step defines a single action. The step type determines which fields are relevant.

Common step fields:

Failure policy

Connectors support a failure policy that automatically disables the connector when too many failures occur within a time window. Configure this at the connector level:

"failurePolicy": {
  "maxFailures": 5,
  "windowMinutes": 10,
  "onExceeded": "disable"
}

When failures exceed the threshold, SDMA sets the connector status to FAILURE_COUNT_EXCEEDED and disables it. Re-enable the connector manually after resolving the underlying issue.

Error handling

SDMA automatically records connector invocation results. Each invocation tracks:

Steps support per-step error handling by using the onError field:

For multi-step triggers, the sleepTime and retryCount fields on individual steps control retry behavior. Use the successConditions block to define custom success criteria (for example, waiting for a resource to be deleted before proceeding).

In multi-step connectors, error handling interacts with step composition. If a step with onError: fail fails, SDMA marks the entire invocation as failed and does not execute subsequent steps. If a step with onError: record-and-continue fails, SDMA records the error but continues to the next step. The invocation status reflects the overall outcome — SUCCEEDED if all steps completed (even if some recorded errors), FAILED if any fail-mode step failed.

Security model

SDMA enforces multiple layers of security to isolate connector execution and limit the impact of misconfiguration.

Network isolation

Connector step execution runs in isolated AWS Lambda functions within the SDMA deployment account. These functions:

Each connector invocation is an independent, stateless execution. A failure or misconfiguration in one connector does not affect other connectors or the core SDMA service.

IAM role isolation

Every connector authenticates with external services through a dedicated IAM role that you create and control in your own AWS account. SDMA enforces the following constraints:

You control the blast radius of each connector by scoping the IAM role’s permissions. For example, you can restrict an S3 connector role to a single bucket and prefix, preventing the connector from accessing any other resources in your account.

Credential management

For connectors that use API keys, tokens, or basic authentication, you store credentials in AWS Secrets Manager. SDMA retrieves credentials at execution time and does not cache or persist them. The connector’s IAM role must have permission to read the specific secret.