Communication Methods
Since System.Communication 4.17.0 the operations on adapters, workloads and adapter pools, and since 4.18.0 the
operations on pipelines, data flows and the workload chart version, that the Communication Controller offers over its REST API
are also declared as CK methods. A caller finds
them in the tenant schema as typed mutations and the Communication
Controller handles them (handler: service). The effect is the one of the REST endpoint: the handler calls the same services.
The REST endpoints of the Communication Controller are unchanged and carry no deprecation header yet. Studio, octo-cli and the
MCP server switch to the methods in a later step; only then are the endpoints marked deprecated.
Adapter
| Method | Kind | Parameters | Result | Declared errors | REST endpoint |
|---|---|---|---|---|---|
DeployUpdate-1 | instance | none | none | ADAPTER_CONFIGURATION_DEPLOY_FAILED (parameter message) | POST {tenant}/v1/Adapter/deployUpdate?adapterRtEntityId= |
ReconcileServiceAccount-1 | instance | none | ServiceAccountReconcileResult | SERVICE_ACCOUNT_RECONCILE_FAILED | POST {tenant}/v1/Adapter/{adapterRtId}/serviceAccount/reconcile |
RotateServiceAccountSecret-1 | instance | none | ServiceAccountSecretRotationResult | SERVICE_ACCOUNT_ROTATION_FAILED | POST {tenant}/v1/Adapter/{adapterRtId}/serviceAccount/rotateSecret |
Workload (adapter, application, adapter pool)
Wake is declared on the abstract base type DeployableWorkload, so every adapter, application and adapter pool has it, as the
REST endpoint accepts any workload.
| Method | Kind | Parameters | Result | Declared errors | REST endpoint |
|---|---|---|---|---|---|
Wake-1 | instance | none | none | WORKLOAD_WAKE_FAILED (parameter message) | POST {tenant}/v1/Adapter/{workloadRtId}/wake |
SetChartVersion-1 (4.18.0) | instance | chartVersion (optional; SemVer, empty or absent = newest chart of the configured repository) | none | WORKLOAD_CHART_VERSION_UPDATE_FAILED (METHOD_VALIDATION_FAILED for an invalid version) | PATCH {tenant}/v1/Workload/{workloadRtId}/chart-version |
SetChartVersion does not deploy; deploy the workload afterwards, as with the REST endpoint.
Adapter pool
| Method | Kind | Parameters | Result | Declared errors | REST endpoint |
|---|---|---|---|---|---|
RefreshMirrors-1 | static | none | AdapterPoolMirrorSyncResult | none | POST {tenant}/v1/AdapterPool/mirrors/refresh |
PublishMirrors-1 | static | none | AdapterPoolMirrorSyncResult | none | POST {tenant}/v1/AdapterPool/mirrors/publish |
GrantLease-1 | instance | borrowerTenantId, adapterRtId, executionId (optional), ttlSeconds (optional, 1-3600) | AdapterPoolLeaseResult | none | POST {tenant}/v1/AdapterPool/{adapterPoolRtId}/lease |
CancelQueuedExecution-1 | instance | executionId | none | EXECUTION_ALREADY_LEASED, QUEUED_EXECUTION_NOT_FOUND | DELETE {tenant}/v1/AdapterPool/{adapterPoolRtId}/queue/{executionId} |
RefreshMirrors works for the calling tenant as the borrower, PublishMirrors for the calling tenant as the lender; both
are static, they need no pool. GrantLease is a test and diagnostic surface like its REST endpoint: production leases come from
the scheduler. A lease that cannot be granted is a normal result with granted: false and a statusMessage, not an error.
CancelQueuedExecution cancels a queue entry, never a running pipeline.
Pipeline (4.18.0)
| Method | Kind | Parameters | Result | Declared errors | REST endpoint |
|---|---|---|---|---|---|
Deploy-1 | instance | adapterRtId (optional, default: the assigned adapter), pipelineDefinition (optional, sensitive) | none | PIPELINE_ADAPTER_NOT_ASSIGNED, PIPELINE_DEPLOY_REJECTED, PIPELINE_DEPLOY_FAILED (parameter message) | POST {tenant}/v1/Pipeline/deploy?adapterRtEntityId=&pipelineRtEntityId= |
Execute-1 | instance | input (optional, sensitive), isDryRun (optional) | PipelineExecutionStartResult (executionId, startedAt) | PIPELINE_EXECUTION_START_FAILED (parameter message) | POST {tenant}/v1/Pipeline/execute?pipelineRtId=&isDryRun= |
SetDebugging-1 | instance | enabled | PipelineDebugResult (enabled, appliedToRunningAdapter) | PIPELINE_DEBUG_CHANGE_FAILED (parameter message) | PATCH {tenant}/v1/Pipeline/{pipelineRtId}/debug |
MoveToAdapter-1 | instance | targetAdapterRtId, redeploy (optional) | PipelineMoveResult (oldAdapterRtId, newAdapterRtId, warning) | PIPELINE_MOVE_FAILED (parameter message) | PATCH {tenant}/v1/Pipeline/move-to-adapter |
Deploy without adapterRtId deploys to the adapter the pipeline is assigned to; pipelineDefinition replaces the stored
definition first, like the REST request body. Execute starts the execution and returns its id without waiting for the end; the
caller is passed to a FromExecutePipelineCommand pipeline as with REST. MoveToAdapter moves one pipeline (the REST endpoint
takes a list; call the method once per pipeline). A failed redeploy after the move does not roll the move back: the result carries
a warning. Unlike REST, redeploy: true also deploys when the pipeline already points at the target adapter, so a retried call
still deploys.
Data flow (4.18.0)
| Method | Kind | Parameters | Result | Declared errors | REST endpoint |
|---|---|---|---|---|---|
Deploy-1 | instance | none | none | DATA_FLOW_DEPLOY_FAILED (parameter message) | POST {tenant}/v1/DataFlow/deploy?dataFlowRtId= |
Undeploy-1 | instance | none | none | DATA_FLOW_UNDEPLOY_FAILED (parameter message) | POST {tenant}/v1/DataFlow/undeploy?dataFlowRtId= |
What stays a REST endpoint
The tenant-level endpoints of the Communication Controller are no operations on an entity and get no method: enable and
disable switch the communication capability of the tenant on and off (they install or remove the model itself), GET/PUT lifecycle is tenant configuration, validate-expression checks an expression without any entity, and encrypt-value is
deprecated (store secret overrides in ValueOverride.SecretValue) and takes a secret.
Contract of every method
| Method | Timeout | Idempotent |
|---|---|---|
Adapter.DeployUpdate-1 | 90 s | yes |
DeployableWorkload.Wake-1 | 90 s (the wake budget is 60 s) | yes |
Adapter.ReconcileServiceAccount-1 | 60 s | yes |
Adapter.RotateServiceAccountSecret-1 | 60 s | no |
AdapterPool.RefreshMirrors-1 | 120 s | yes |
AdapterPool.PublishMirrors-1 | 120 s | yes |
AdapterPool.GrantLease-1 | 30 s | no |
AdapterPool.CancelQueuedExecution-1 | 15 s | no |
Pipeline.Deploy-1 | 200 s (one wake of 60 s plus one push of 120 s) | yes |
Pipeline.Execute-1 | 30 s (until the execution has started) | no |
Pipeline.SetDebugging-1 | 300 s (it re-pushes the data flow) | yes |
Pipeline.MoveToAdapter-1 | 200 s (with redeploy) | yes |
DataFlow.Deploy-1 | 300 s | yes |
DataFlow.Undeploy-1 | 300 s | yes |
DeployableWorkload.SetChartVersion-1 | 15 s | yes |
All methods answer synchronously. A data flow that spans several adapters wakes and pushes them one after the other, so
DataFlow.Deploy, DataFlow.Undeploy and Pipeline.SetDebugging use the maximum timeout of 300 s; they will become
asynchronous operations in a later version.
A non-idempotent method can be repeated safely with the same idempotency key: the second call returns the first result instead of rotating the secret or granting a lease again.
- Roles: every method declares the role
CommunicationManagement, plus the scopeocto_apithat every method call needs. The REST endpoints ask only for the scope; a method without roles would admit administrators only, so the methods name the role that the Studio's integration section and every pipeline service account carry. A caller without the role getsMETHOD_FORBIDDENbefore the target is read. A token of another tenant is refused (METHOD_FORBIDDEN, reasontenant-not-allowed). - Service account roles:
ReconcileServiceAccountmaterialises the declared roles of the account only when the caller also holdsUserManagement, as the REST endpoint does; otherwise the result saysroleChangesSkipped: true. - No secret in a result:
RotateServiceAccountSecretwrites the new secret into theServiceAccountConfigurationand into the identity client. The result names the client, says whether the pipelines must be redeployed (requiresPipelineRedeploy) and carries a message, never the secret, like the REST endpoint. A failed rotation answersSERVICE_ACCOUNT_ROTATION_FAILED; the previous secret stays in effect. - Sensitive parameters:
Pipeline.Deploy.pipelineDefinition(a definition can carry credentials) andPipeline.Execute.inputare declaredsensitive: they never appear in a log, the audit or a trace. A failure message that would quote them (or the caller token) answers***in their place. The input of an execution on a Leased adapter (not a dry run) is stored in the tenant'sPipelineExecutionand stays there after the run, as with REST. - Failure messages: the
messageof a pipeline or data flow error carries the controller's own failure text (the one REST answers, e.g. the adapter's validation errors). An unexpected failure answers only the error code; its details stay in the service log. - Data access: the instance methods use the default
dataAccess(Write): the caller needs a write grant on the target record. - Versioning: the methods and their result records are additive, minor versions (
4.17.0,4.18.0). They change no attribute access; the configuration credentials stay writable through the generic API in 4.x.
Example
mutation {
runtime {
systemCommunicationAdapters {
rotateServiceAccountSecret(rtId: "65f0c0ffee65f0c0ffee65f0") {
invocationId
result { clientId requiresPipelineRedeploy message }
}
}
}
}
Deploying a pipeline to the adapter it is assigned to:
mutation {
runtime {
systemCommunicationPipelines {
deploy(rtId: "65f0c0ffee65f0c0ffee65f1") {
invocationId
}
}
}
}
Operations
The Communication Controller hosts the handlers with the method host of the platform: one shared queue per method, so every
replica serves calls. It validates the forwarded caller token with the authority of its own HTTP API, as the
pipeline method handlers do. Methods:Communication:Enabled=false
(OCTO_METHODS__COMMUNICATION__ENABLED) switches the handlers off; the REST endpoints keep working and a method call answers
METHOD_HANDLER_NOT_AVAILABLE. The handlers are validated at startup against the System.Communication model of the system
tenant; a system tenant without the model fails the startup with a message that names the method.