Function chaining in Durable Functions - Hello sequence sample

• Complete the quickstart article
• Clone or download the samples project from GitHub

• Complete the quickstart article
• Clone or download the samples project from GitHub

• Complete the quickstart article
• Clone or download the samples project from GitHub

        [FunctionName("E1_HelloSequence")]
        public static async Task<List<string>> Run(
            [OrchestrationTrigger] IDurableOrchestrationContext context)
        {
            var outputs = new List<string>();

            outputs.Add(await context.CallActivityAsync<string>("E1_SayHello", "Tokyo"));
            outputs.Add(await context.CallActivityAsync<string>("E1_SayHello", "Seattle"));
            outputs.Add(await context.CallActivityAsync<string>("E1_SayHello_DirectInput", "London"));

            // returns ["Hello Tokyo!", "Hello Seattle!", "Hello London!"]
            return outputs;
        }

All C# orchestration functions must have a parameter of type DurableOrchestrationContext, which exists in the Microsoft.Azure.WebJobs.Extensions.DurableTask assembly. This context object lets you call other activity functions and pass input parameters using its CallActivityAsync method.

The code calls E1_SayHello three times in sequence with different parameter values. The return value of each call is added to the outputs list, which is returned at the end of the function.

function.json

If you use Visual Studio Code or the Azure portal for development, here's the content of the function.json file for the orchestrator function. Most orchestrator function.json files look almost exactly like this.

{
  "bindings": [
    {
      "name": "context",
      "type": "orchestrationTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

The important thing is the orchestrationTrigger binding type. All orchestrator functions must use this trigger type.

index.js

Here is the orchestrator function:

const df = require("durable-functions");

module.exports = df.orchestrator(function* (context) {
    context.log("Starting chain sample");
    const output = [];
    output.push(yield context.df.callActivity("E1_SayHello", "Tokyo"));
    output.push(yield context.df.callActivity("E1_SayHello", "Seattle"));
    output.push(yield context.df.callActivity("E1_SayHello", "London"));

    return output;
});

All JavaScript orchestration functions must include the durable-functions module. It's a library that enables you to write Durable Functions in JavaScript. There are three significant differences between an orchestrator function and other JavaScript functions:

1. The orchestrator function is a generator function.
2. The function is wrapped in a call to the durable-functions module's orchestrator method (here df).
3. The function must be synchronous. Because the 'orchestrator' method handles the final call to 'context.done', the function should simply 'return'.

The context object contains a df durable orchestration context object that lets you call other activity functions and pass input parameters using its callActivity method. The code calls E1_SayHello three times in sequence with different parameter values, using yield to indicate the execution should wait on the async activity function calls to be returned. The return value of each call is added to the outputs array, which is returned at the end of the function.

const df = require("durable-functions");

const helloActivityName = "sayHello";

df.app.orchestration("helloSequence", function* (context) {
    context.log("Starting chain sample");

    const output = [];
    output.push(yield context.df.callActivity(helloActivityName, "Tokyo"));
    output.push(yield context.df.callActivity(helloActivityName, "Seattle"));
    output.push(yield context.df.callActivity(helloActivityName, "Cairo"));

    return output;
});

All JavaScript orchestration functions must include the durable-functions module. This module enables you to write Durable Functions in JavaScript. To use the V4 node programming model, you need to install the preview v3.x version of durable-functions.

There are two significant differences between an orchestrator function and other JavaScript functions:

1. The orchestrator function is a generator function.
2. The function must be synchronous. The function should simply 'return'.

The context object contains a df durable orchestration context object that lets you call other activity functions and pass input parameters using its callActivity method. The code calls sayHello three times in sequence with different parameter values, using yield to indicate the execution should wait on the async activity function calls to be returned. The return value of each call is added to the outputs array, which is returned at the end of the function.

function.json

If you use Visual Studio Code or the Azure portal for development, here's the content of the function.json file for the orchestrator function. Most orchestrator function.json files look almost exactly like this.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "context",
      "type": "orchestrationTrigger",
      "direction": "in"
    }
  ]
}

The important thing is the orchestrationTrigger binding type. All orchestrator functions must use this trigger type.

__init__.py

Here is the orchestrator function:

import azure.functions as func
import azure.durable_functions as df


def orchestrator_function(context: df.DurableOrchestrationContext):
    result1 = yield context.call_activity('E1_SayHello', "Tokyo")
    result2 = yield context.call_activity('E1_SayHello', "Seattle")
    result3 = yield context.call_activity('E1_SayHello', "London")
    return [result1, result2, result3]

main = df.Orchestrator.create(orchestrator_function)

All Python orchestration functions must include the durable-functions package. It's a library that enables you to write Durable Functions in Python. There are two significant differences between an orchestrator function and other Python functions:

1. The orchestrator function is a generator function.
2. The file should register the orchestrator function as an orchestrator by stating main = df.Orchestrator.create(<orchestrator function name>) at the end of the file. This helps distinguish it from other, helper, functions declared in the file.

The context object lets you call other activity functions and pass input parameters using its call_activity method. The code calls E1_SayHello three times in sequence with different parameter values, using yield to indicate the execution should wait on the async activity function calls to be returned. The return value of each call is returned at the end of the function.

        [FunctionName("E1_SayHello")]
        public static string SayHello([ActivityTrigger] IDurableActivityContext context)
        {
            string name = context.GetInput<string>();
            return $"Hello {name}!";
        }

Activities use the ActivityTrigger attribute. Use the provided IDurableActivityContext to perform activity related actions, such as accessing the input value using GetInput<T>.

The implementation of E1_SayHello is a relatively trivial string formatting operation.

Instead of binding to an IDurableActivityContext, you can bind directly to the type that is passed into the activity function. For example:

        [FunctionName("E1_SayHello_DirectInput")]
        public static string SayHelloDirectInput([ActivityTrigger] string name)
        {
            return $"Hello {name}!";
        }

E1_SayHello/function.json

The function.json file for the activity function E1_SayHello is similar to that of E1_HelloSequence except that it uses an activityTrigger binding type instead of an orchestrationTrigger binding type.

{
  "bindings": [
    {
      "name": "name",
      "type": "activityTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

The implementation of E1_SayHello is a relatively trivial string formatting operation.

E1_SayHello/index.js

module.exports = function (context) {
    context.done(null, `Hello ${context.bindings.name}!`);
};

Unlike the orchestration function, an activity function needs no special setup. The input passed to it by the orchestrator function is located on the context.bindings object under the name of the activityTrigger binding - in this case, context.bindings.name. The binding name can be set as a parameter of the exported function and accessed directly, which is what the sample code does.

The implementation of sayHello is a relatively trivial string formatting operation.

const df = require("durable-functions");

const helloActivityName = "sayHello";

df.app.activity(helloActivityName, {
    handler: function (input) {
        return `Hello ${input}`;
    },
});

Unlike the orchestration function, an activity function needs no special setup. The input passed to it by the orchestrator function is the first argument to the function. The second argument is the invocation context, which is not used in this example.

E1_SayHello/function.json

The function.json file for the activity function E1_SayHello is similar to that of E1_HelloSequence except that it uses an activityTrigger binding type instead of an orchestrationTrigger binding type.

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "name": "name",
      "type": "activityTrigger",
      "direction": "in"
    }
  ]
}

The implementation of E1_SayHello is a relatively trivial string formatting operation.

E1_SayHello/__init__.py

def main(name: str) -> str:
    return f"Hello {name}!"

Unlike the orchestrator function, an activity function needs no special setup. The input passed to it by the orchestrator function is directly accessible as the parameter to the function.

    public static class HttpStart
    {
        [FunctionName("HttpStart")]
        public static async Task<HttpResponseMessage> Run(
            [HttpTrigger(AuthorizationLevel.Function, methods: "post", Route = "orchestrators/{functionName}")] HttpRequestMessage req,
            [DurableClient] IDurableClient starter,
            string functionName,
            ILogger log)
        {
            // Function input comes from the request content.
            object eventData = await req.Content.ReadAsAsync<object>();
            string instanceId = await starter.StartNewAsync(functionName, eventData);

            log.LogInformation($"Started orchestration with ID = '{instanceId}'.");

            return starter.CreateCheckStatusResponse(req, instanceId);
        }
    }

To interact with orchestrators, the function must include a DurableClient input binding. You use the client to start an orchestration. It can also help you return an HTTP response containing URLs for checking the status of the new orchestration.

HttpStart/function.json

{
    "bindings": [
      {
        "authLevel": "anonymous",
        "name": "req",
        "type": "httpTrigger",
        "direction": "in",
        "route": "orchestrators/{functionName}",
        "methods": ["post"]
      },
      {
        "name": "$return",
        "type": "http",
        "direction": "out"
      },
      {
        "name": "starter",
        "type": "orchestrationClient",
        "direction": "in"
      }
    ],
    "disabled": false
  }

To interact with orchestrators, the function must include a durableClient input binding.

HttpStart/index.js

const df = require("durable-functions");

module.exports = async function (context, req) {
    const client = df.getClient(context);
    const instanceId = await client.startNew(req.params.functionName, undefined, req.body);

    context.log(`Started orchestration with ID = '${instanceId}'.`);

    return client.createCheckStatusResponse(context.bindingData.req, instanceId);
};

Use df.getClient to obtain a DurableOrchestrationClient object. You use the client to start an orchestration. It can also help you return an HTTP response containing URLs for checking the status of the new orchestration.

const df = require("durable-functions");
const { app } = require("@azure/functions");

app.http("httpStart", {
    route: "orchestrators/{orchestratorName}",
    extraInputs: [df.input.durableClient()],
    handler: async (request, context) => {
        const client = df.getClient(context);
        const body = await request.json();
        const instanceId = await client.startNew(request.params.orchestratorName, { input: body });

        context.log(`Started orchestration with ID = '${instanceId}'.`);

        return client.createCheckStatusResponse(request, instanceId);
    },
});

To manage and interact with orchestrators, the function needs a durableClient input binding. This binding needs to be specified in the extraInputs argument when registering the function. A durableClient input can be obtained by calling df.input.durableClient().

Use df.getClient to obtain a DurableClient object. You use the client to start an orchestration. It can also help you return an HTTP response containing URLs for checking the status of the new orchestration.

HttpStart/function.json

{
  "scriptFile": "__init__.py",
  "bindings": [
    {
      "authLevel": "anonymous",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{functionName}",
      "methods": [
        "post",
        "get"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "durableClient",
      "direction": "in"
    }
  ]
}

To interact with orchestrators, the function must include a durableClient input binding.

HttpStart/__init__.py

import logging

import azure.functions as func
import azure.durable_functions as df


async def main(req: func.HttpRequest, starter: str) -> func.HttpResponse:
    client = df.DurableOrchestrationClient(starter)
    instance_id = await client.start_new(req.route_params["functionName"], None, None)

    logging.info(f"Started orchestration with ID = '{instance_id}'.")

    return client.create_check_status_response(req, instance_id)

Use the DurableOrchestrationClient constructor to obtain a Durable Functions client. You use the client to start an orchestration. It can also help you return an HTTP response containing URLs for checking the status of the new orchestration.