Skip to main content

Nexus feature guide

View Markdown

Nexus is a tool for coordinating asynchronous operations between Temporal and external systems. Service handlers allow Workflows to receive inbound requests through Nexus.

Call a Nexus Operation from a Workflow​

You can start a Nexus operation from a Workflow using ctx.start_nexus_operation(): Enable the experimental feature for the temporalio-sdk dependency to use this API.

rust-sandbox/nexus/feature-guide/src/workflows.rs

use std::time::Duration;

use temporalio_common::protos::coresdk::AsJsonPayloadExt;
use temporalio_macros::{workflow, workflow_methods};
use temporalio_sdk::{
    ApplicationFailure, NexusOperationOptions, WorkflowContext, WorkflowContextView, WorkflowResult,
};

#[workflow]
pub struct GreetingWorkflow {
    pub name: String,
}

#[workflow_methods]
impl GreetingWorkflow {
    #[init]
    fn new(_ctx: &WorkflowContextView, name: String) -> Self {
        Self { name }
    }

    #[run]
    pub async fn run(ctx: &mut WorkflowContext<Self>) -> WorkflowResult<String> {
        let name = ctx.state(|s| s.name.clone());
        let nexus_started = ctx
            .start_nexus_operation(
                NexusOperationOptions::builder()
                    .endpoint("my-endpoint")
                    .service("my-service")
                    .operation("my-operation")
                    .input(name.as_json_payload().map_err(ApplicationFailure::new)?)
                    .start_to_close_timeout(Duration::from_secs(10))
                    .build(),
            )
            .await;

        let nexus_started = match nexus_started {
            Ok(started) => started,
            Err(failure) => return Ok(format!("Nexus start failed: {failure:?}")),
        };
        let nexus_result = nexus_started.result().await;

        println!("Nexus result: {:?}", nexus_result);

        Ok(format!("nexus result: {:?}", nexus_result))
    }
}

Nexus Operation arguments​

  • endpoint - The Nexus Endpoint name. The Endpoint must already exist, or the command fails.
  • service - The service name
  • operation - The operation name
  • input - The input payload (optional)
  • schedule_to_close_timeout - How long the caller waits for the operation to complete
  • schedule_to_start_timeout - How long the caller waits for the handler to start the operation. Requires Temporal Server 1.31.0 or later.
  • start_to_close_timeout - How long an asynchronous operation can run after it starts. Synchronous operations ignore it. Requires Temporal Server 1.31.0 or later.