Skip to main content

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 stay

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​

MethodKindParametersResultDeclared errorsREST endpoint
DeployUpdate-1instancenonenoneADAPTER_CONFIGURATION_DEPLOY_FAILED (parameter message)POST {tenant}/v1/Adapter/deployUpdate?adapterRtEntityId=
ReconcileServiceAccount-1instancenoneServiceAccountReconcileResultSERVICE_ACCOUNT_RECONCILE_FAILEDPOST {tenant}/v1/Adapter/{adapterRtId}/serviceAccount/reconcile
RotateServiceAccountSecret-1instancenoneServiceAccountSecretRotationResultSERVICE_ACCOUNT_ROTATION_FAILEDPOST {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.

MethodKindParametersResultDeclared errorsREST endpoint
Wake-1instancenonenoneWORKLOAD_WAKE_FAILED (parameter message)POST {tenant}/v1/Adapter/{workloadRtId}/wake
SetChartVersion-1 (4.18.0)instancechartVersion (optional; SemVer, empty or absent = newest chart of the configured repository)noneWORKLOAD_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​

MethodKindParametersResultDeclared errorsREST endpoint
RefreshMirrors-1staticnoneAdapterPoolMirrorSyncResultnonePOST {tenant}/v1/AdapterPool/mirrors/refresh
PublishMirrors-1staticnoneAdapterPoolMirrorSyncResultnonePOST {tenant}/v1/AdapterPool/mirrors/publish
GrantLease-1instanceborrowerTenantId, adapterRtId, executionId (optional), ttlSeconds (optional, 1-3600)AdapterPoolLeaseResultnonePOST {tenant}/v1/AdapterPool/{adapterPoolRtId}/lease
CancelQueuedExecution-1instanceexecutionIdnoneEXECUTION_ALREADY_LEASED, QUEUED_EXECUTION_NOT_FOUNDDELETE {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)​

MethodKindParametersResultDeclared errorsREST endpoint
Deploy-1instanceadapterRtId (optional, default: the assigned adapter), pipelineDefinition (optional, sensitive)nonePIPELINE_ADAPTER_NOT_ASSIGNED, PIPELINE_DEPLOY_REJECTED, PIPELINE_DEPLOY_FAILED (parameter message)POST {tenant}/v1/Pipeline/deploy?adapterRtEntityId=&pipelineRtEntityId=
Execute-1instanceinput (optional, sensitive), isDryRun (optional)PipelineExecutionStartResult (executionId, startedAt)PIPELINE_EXECUTION_START_FAILED (parameter message)POST {tenant}/v1/Pipeline/execute?pipelineRtId=&isDryRun=
SetDebugging-1instanceenabledPipelineDebugResult (enabled, appliedToRunningAdapter)PIPELINE_DEBUG_CHANGE_FAILED (parameter message)PATCH {tenant}/v1/Pipeline/{pipelineRtId}/debug
MoveToAdapter-1instancetargetAdapterRtId, 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)​

MethodKindParametersResultDeclared errorsREST endpoint
Deploy-1instancenonenoneDATA_FLOW_DEPLOY_FAILED (parameter message)POST {tenant}/v1/DataFlow/deploy?dataFlowRtId=
Undeploy-1instancenonenoneDATA_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​

MethodTimeoutIdempotent
Adapter.DeployUpdate-190 syes
DeployableWorkload.Wake-190 s (the wake budget is 60 s)yes
Adapter.ReconcileServiceAccount-160 syes
Adapter.RotateServiceAccountSecret-160 sno
AdapterPool.RefreshMirrors-1120 syes
AdapterPool.PublishMirrors-1120 syes
AdapterPool.GrantLease-130 sno
AdapterPool.CancelQueuedExecution-115 sno
Pipeline.Deploy-1200 s (one wake of 60 s plus one push of 120 s)yes
Pipeline.Execute-130 s (until the execution has started)no
Pipeline.SetDebugging-1300 s (it re-pushes the data flow)yes
Pipeline.MoveToAdapter-1200 s (with redeploy)yes
DataFlow.Deploy-1300 syes
DataFlow.Undeploy-1300 syes
DeployableWorkload.SetChartVersion-115 syes

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 scope octo_api that 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 gets METHOD_FORBIDDEN before the target is read. A token of another tenant is refused (METHOD_FORBIDDEN, reason tenant-not-allowed).
  • Service account roles: ReconcileServiceAccount materialises the declared roles of the account only when the caller also holds UserManagement, as the REST endpoint does; otherwise the result says roleChangesSkipped: true.
  • No secret in a result: RotateServiceAccountSecret writes the new secret into the ServiceAccountConfiguration and 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 answers SERVICE_ACCOUNT_ROTATION_FAILED; the previous secret stays in effect.
  • Sensitive parameters: Pipeline.Deploy.pipelineDefinition (a definition can carry credentials) and Pipeline.Execute.input are declared sensitive: 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's PipelineExecution and stays there after the run, as with REST.
  • Failure messages: the message of 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.