Operation Invocation and Delegation#
This walkthrough invokes the delegated-operation example synchronously and asynchronously. The example adds 5 and 3 and returns an output variable named sum with value 8.
The upstream example uses the AAS Environment, which exposes the same Submodel Repository operation endpoints and delegation behavior. The standalone Submodel Repository uses the same operation invocation implementation.
Note
The BaSyx Delegated Operations Example contains the Compose stack, delegated service, model fixtures, and requests for synchronous and asynchronous invocation in full-metadata and ValueOnly form.
Modeled Operation Versus Invocation#
An AAS Operation Submodel Element models input, output, and in-output variables. Storing that element does not install or execute application code. An invocation is executable only when the Operation has an invocationDelegation qualifier whose string value is the HTTP or HTTPS endpoint that implements the behavior.
The Repository loads the stored Operation, forwards the request’s input and in-output variables to the delegation endpoint, validates the delegated response, and returns an OperationResult. Treat the modeled contract, the Repository invocation API, and the delegated implementation as three distinct concerns.
Delegated invocation supports both the normal OperationRequest and OperationResult representation and the value-only representation. Use /invoke/$value for synchronous value-only invocation, /invoke-async/$value for asynchronous value-only invocation, and /operation-results/{handleId}/$value to retrieve the completed value-only result. Both normal and value-only asynchronous invocation requests require a non-empty clientTimeoutDuration. A missing or empty value produces 400 Bad Request.
Delegation Prerequisite and Trusted Destinations#
The example defines AddNumbersSync and AddNumbersAsync with qualifiers such as:
{
"type": "invocationDelegation",
"valueType": "xs:string",
"value": "http://delegated-operation-service:8080/delegate/add/sync"
}
Set SMREPO_DELEGATION_TRUSTED_HOSTS to the delegated endpoint’s hostname and port and, for DNS names, every resolved IP address and port that BaSyx may connect to. The example uses:
SMREPO_DELEGATION_TRUSTED_HOSTS=delegated-operation-service:8080,172.28.0.10:8080
If the service name, port, or Compose network address changes, update the qualifier and allowlist together.
Delegated Response Size#
Delegated Operation responses are limited by general.delegatedOperationResponseMaxSizeBytes or GENERAL_DELEGATEDOPERATIONRESPONSEMAXSIZEBYTES. The default is 1 MiB (1048576 bytes) and applies to synchronous and asynchronous delegation. Increase the limit only when required by the expected result size because delegated responses are buffered in memory.
Start the Example#
Clone the BaSyx Go repository and select the source tag that matches the BaSyx images you intend to run:
git clone https://github.com/eclipse-basyx/basyx-go-components
cd basyx-go-components
git checkout RELEASE_TAG
cd examples/BaSyxDelegatedOperationsExample
Replace RELEASE_TAG with the source tag of the latest stable BaSyx Go release. The example’s Compose file uses SNAPSHOT. Save the following as compose.release.yml to use the latest stable images:
services:
aas_environment:
image: eclipsebasyx/aasenvironment-go:latest
basyx_configuration:
image: eclipsebasyx/basyxconfigurationservice-go:latest
Start the database, Configuration Service, AAS Environment, delegated service, and data initializer. The AAS Web UI is optional and is not started:
docker compose -f docker-compose.yml -f compose.release.yml up -d --build \
db basyx_configuration aas_environment delegated-operation-service data-init
docker compose -f docker-compose.yml -f compose.release.yml logs data-init
docker compose -f docker-compose.yml -f compose.release.yml ps -a data-init
Wait for Delegated operations example data initialized and an exit code of 0. The fixture is now available through http://localhost:8090. It loads:
Submodel ID
https://example.com/ids/sm/delegated-operations;encoded path value
aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvc20vZGVsZWdhdGVkLW9wZXJhdGlvbnM;Operations
AddNumbersSyncandAddNumbersAsync;request body
data/invoke-request-add-5-and-3.json.
When substituting a different Submodel identifier, encode its UTF-8 bytes with Base64URL for the request path. The example uses the unpadded form. BaSyx Go accepts valid padded and unpadded Base64URL values. See Using the Submodel Repository for the identifier-encoding guidance. The example directory in the selected checkout contains the Submodel fixture, invocation request, and delegated service used below.
Synchronous Invocation#
Invoke the synchronous fixture through /invoke:
curl --fail-with-body --silent --show-error \
--request POST \
'http://localhost:8090/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvc20vZGVsZWdhdGVkLW9wZXJhdGlvbnM/submodel-elements/AddNumbersSync/invoke' \
--header 'Content-Type: application/json' \
--data @data/invoke-request-add-5-and-3.json
Expect 200 OK. The OperationResult has executionState: "Completed", success: true, and one output argument: the sum Property has value "8". This demonstrates 5 + 3 = 8 through synchronous invocation.
Asynchronous Invocation and Result Retrieval#
Submit the same input through /invoke-async. Keep automatic redirect following disabled so that the intermediate status and result locations remain visible; in particular, do not add curl’s --location (-L) option.
curl --include --request POST \
'http://localhost:8090/submodels/aHR0cHM6Ly9leGFtcGxlLmNvbS9pZHMvc20vZGVsZWdhdGVkLW9wZXJhdGlvbnM/submodel-elements/AddNumbersAsync/invoke-async' \
--header 'Content-Type: application/json' \
--data @data/invoke-request-add-5-and-3.json
Expect 202 Accepted with a Location header. Copy that returned location rather than constructing a handle URL, resolve it against http://localhost:8090 if it is relative, and request it without redirect following:
curl --include 'http://localhost:8090/<returned operation-status path>'
While work is pending, status returns 200 OK with executionState Running; repeat the same request. When complete, status returns 302 Found with another Location header pointing to the corresponding /operation-results/ resource. Copy and fetch that returned result location explicitly:
curl --include 'http://localhost:8090/<returned operation-results path>'
Expect 200 OK. The completed OperationResult again has executionState: "Completed", success: true, and output sum equal to "8".
Asynchronous operation handles are retained for 15 minutes by default. Configure SMREPO_DELEGATION_ASYNC_TTL if clients need a different retention period. Retrieve the status and result before the handle expires.
If the Repository’s concurrent asynchronous delegation capacity is exhausted, a new asynchronous invocation returns 429 Too Many Requests. Retry after an active invocation completes.
These are operation-specific resources. Do not apply Registry bulk assumptions about 204 results, consuming a result on retrieval, or bulk retention to delegated-operation results. See Asynchronous API Operations for a comparison with other asynchronous BaSyx APIs.
Failure Diagnosis#
If the delegated endpoint returns an error status, synchronous invocation returns 502 Bad Gateway with an AAS Result object ({"messages":[...]}). The message identifies the endpoint’s status code. Its response body is not exposed. This also applies to /invoke/$value.
When an asynchronous invocation fails, both result routes, including $value, return 200 OK with an OperationResult whose success is false. executionState is Timeout when clientTimeoutDuration ran out and Failed for every other error. messages describe the error, for example SMREPO-INVOKEOP-DELEGATEDSTATUS delegated operation endpoint returned HTTP 500. Check executionState, not the HTTP status, to detect a failed asynchronous invocation.
Symptom |
Check |
|---|---|
Invocation is not implemented |
Confirm the addressed element is an |
Target is reported as untrusted |
Ensure |
Delegated call fails or times out |
Check the delegated service logs, container network reachability, and qualifier URL. For asynchronous calls, verify the required |
|
Use the exact returned location and the same caller identity. Verify the handle belongs to the same Submodel identifier and Operation path and has not expired. |
Status appears to skip the pending state |
Fast work can complete before the first poll. A direct |
Result reports delegated failure |
Read |