Create your first Serverless workflow with Durable functions
Tags: serverless, tutorial, javascript, azure
Published: 2019-06-03 18:54:11

---
title: Create your first Serverless workflow with Durable functions
published: true
description: Describing how we can manage an async Serverless workflow with Durable functions
tags: serverless, tutorial, javascript, azure
cover_image: https://thepracticaldev.s3.amazonaws.com/i/fm48o0xxo7pp18rrf4io.jpg
---
Follow me on [Twitter](https://twitter.com/chris_noring), happy to take your suggestions on topics or improvements /Chris

> Durable Functions are an extension of Azure Functions that lets you write stateful functions in a serverless environment. Durable functions manages `state`, `checkpoints`, and `restarts` for you.

What does that even mean you ask?

It means you can have long-running functions like *really* long running functions. It also has a state which means it remembers where it is, like a workflow.

> Ok?

How about this. Imagine you have a situation where
you need to manage something by dividing it up in different checkpoints. Each checkpoint is one step closer for it to be considered *handled*. More concretely imagine a game for example where you need to load a bunch of different resources and only when everything is loaded and ready are you able to play the game.

> Oh, ok, so it's like a workflow framework

Yea exactly, it enables you to specify how something should be executed through a flow. There are even different architectural patterns that is recommended for different flows.

> Sounds like that could be expensive, is it?

No not really, the payment model is very close to the one Azure Functions use, only pay for when the functions/ workflow is actually executing.

> Sounds great, tell me more

In this article we will cover:
- **What are Durable functions**, let's talk through what it is and what the central concepts are
- **How it works**, we will explain a little bit of how it works
Resources, we will give out some resources so you can delve further in 
- **Lab**, we will code through an example so you see the major concepts in use and what happens when

## Concepts and high-level explanation
There are some concepts we need to know about when dealing with durable functions. All concepts play a role that together enables us to run our durable function. 

- **Orchestrator function**, this is a function where we define the workflow, we set up what should happen in the workflow, what activities to carry out and what happens when it's done
- **Activity function**, Activity functions are the basic *unit of work* in a durable function orchestration. Activity functions are the functions and tasks that are orchestrated in the process. You can have as many activity functions you want. Make sure to give them descriptive names that represent steps in your flow
- **Client functions**, Client functions are the triggered functions that create new instances of an orchestration. Client functions are the *entry point* for creating an instance of a Durable Functions orchestration

> Ok, I think I got but can you maybe explain it a bit more? 

Sure, the best way to explain it is through a realistic example and an image. So let's talk about *order processing*. In *order processing* we imagine we have the following tasks to carry out:

- **Checking** the inventory, 
- **Charging** the customer,  
- **Creating** a shipment

Given that we know how an order is processed let's show you that image so you get a feeling for the workflow:

![](https://thepracticaldev.s3.amazonaws.com/i/yv14fujavcff87q9rq0w.png)

Ok, above we see how a client function is being invoked. In the case of an order being created, this typically is an HTTP endpoint we hit from an application. Next thing to happen is that the client function starts an instance of an orchestration. This means we will get an `instance id`, our unique reference to that specific flow. Next thing to happen is that we try to carry out everything inside of the orchestration like `checking the inventory`, `charging the customer` and `creating a shipment`. 


### How it works
Let's talk a bit more of how this technically works. The thing with the orchestration is that what it orchestrates usually is asynchronous which means we don't know exactly when something finishes. To avoid that you pay running costs for it durable functions powers down and saves the state.

When an orchestration function is given more work to do (for example, a response message is received or a durable timer expires), the orchestrator wakes up and re-executes the entire function from the start to rebuild the local state.

> wait, re-running everything?

No worries, during the replay, if the code tries to call a function (or do any other async work), the Durable Task Framework consults the execution history of the current orchestration. If it finds that the activity function has already executed and yielded a result, it replays that function's result and the orchestrator code continues to run. 

> Oh ok, that sounds better

Replay continues until the function code is finished or until it has scheduled new async work

## Resources
- [Free account Azure account](https://azure.microsoft.com/en-gb/free/?wt.mc_id=devto-blog-chnoring) You will need to sign up on Azure to use Durable Functions
- [Creating your first durable function with JavaScript](https://docs.microsoft.com/en-us/azure/azure-functions/durable/quickstart-js-vscode?wt.mc_id=devto-blog-chnoring) Quickstart that takes you through creating a durable function
- [Durable functions concepts](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-concepts?wt.mc_id=devto-blog-chnoring) Read more here on concepts and patterns and how to implement said patterns.
- [Orchestrator function constraints](https://docs.microsoft.com/en-us/azure/azure-functions/durable/durable-functions-checkpointing-and-replay#orchestrator-code-constraints?wt.mc_id=devto-blog-chnoring) Constraints you need to be aware of.

## Lab - simple activity flow

We believe the best way to learn is to build something with it. So how do we do it? Well, it's quite simple. Using VS Code we can install a plugin making this process really easy.

![](https://thepracticaldev.s3.amazonaws.com/i/z6twu7tn3q3yyvejy6ug.png)

### Creating our project

Open up the command palette or type `COMMAND + SHIFT + P`.

Then we select the following, to create a new project

![](https://thepracticaldev.s3.amazonaws.com/i/07e3b91mhymqih0kd51z.png)

This is followed by us selecting a language, let's take `javascript`. Then we are faced with this list of choices:

![](https://thepracticaldev.s3.amazonaws.com/i/ohrjmvtyir344luhu4tq.png)

As you can see above we have highlighted three options, cause those are the ones we are going to be using throughout this lab. We need an entry point `Durable Functions HTTP Start` so let's select that first:

![](https://thepracticaldev.s3.amazonaws.com/i/jd1fs7ygct5x6yg7hdyz.png)

Next up let's create our orchestrator function os again hit `COMMAND + SHIFT + P` and select `Azure Functions: Create Function` and select `Durable Functions Orchestrator`, let's give it the name `Orchestrator`. 

Upon doing so you will be asked to select a storage account: 

![](https://thepracticaldev.s3.amazonaws.com/i/avyj4jd7ul7eh28tcq81.png)

You will need to select `Subscription`, `Storage account` and `Resource group`. The reason for this is that when you save the state of your function it needs to be saved somewhere for later recovery.

We're almost there, just one more thing to create `Activity function`. We can create that as well with `COMMAND+SHIFT+P` and `Azure Functions: Create Function` and `Durable functions activity`, let's give it the name `Hello` when it asks us for a name.

If you followed along it should look like this:

![](https://thepracticaldev.s3.amazonaws.com/i/m2kb428g903i79r3hab0.png)

### Explaining the artifacts
Ok, so we created three different artifacts, an *orchestrator* function, a *HTTP start/client function* and an *activity function*. How does this all work? 

Well, it all starts with `HttpStart` function that kicks everything off. Then said function kicks off the `Orchestrator` that in turn starts the `Activity functions` specified in the orchestrator. Sounds a bit theoretical but let's dive into each of these artifacts and see what happens in the code.

#### HttpStart
As mentioned above, this is the function that starts it all. Let's have a look at its source code and discuss what's happening:

```js
// 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);
};
```

Above we can see that we get a reference to a `client` by calling `getClient` on a durable functions instance `df` that we import from the library `durable-functions`. 
Next up our `client` instance calls `startNew` which produces an `instanceId`. The `instanceId` is a reference or *handler* to this specific function invocation. It doesn't matter so much for this demo but the for the second one we will use that information. 
The last thing to happen is that we create an HTTP response. 

Let's have a look at `function.json`, our config file where we set up inputs and outputs for our function:

HttpStart/function.json

```json
{
  "bindings": [
    {
      "authLevel": "function",
      "name": "req",
      "type": "httpTrigger",
      "direction": "in",
      "route": "orchestrators/{functionName}",
      "methods": [
        "post",
        "get"
      ]
    },
    {
      "name": "$return",
      "type": "http",
      "direction": "out"
    },
    {
      "name": "starter",
      "type": "orchestrationClient",
      "direction": "in"
    }
  ]
}
```

We have two pieces of interesting information. The first is that we have a `httpTrigger`, i.e we can reach this function through an HTTP call, specifically through a route called `orchestrators/{functionName}`. The other piece of interesting information is the last entry with type `orchestrationClient`. This one enables us to get a `client` reference in our code, without it we wouldn't be able to. So remember to include this config if you need a client instance.

#### Orchestrator

Let's look at the Orchestrator next. This is where all the interesting things are happening, this is where we set up our flow, what function to be called when and why. Let's look at the code:

```js
// Orchestrator/index.js

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

module.exports = df.orchestrator(function* (context) {
    const outputs = [];

    // Replace "Hello" with the name of your Durable Activity Function.
    outputs.push(yield context.df.callActivity("Hello", "Tokyo"));
    outputs.push(yield context.df.callActivity("Hello", "Seattle"));
    outputs.push(yield context.df.callActivity("Hello", "London"));

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

The first thing we see that we have a method `orchestrator` that takes a generator function. What are generators? They are a very similar concept to `async/await` and allows you to carry out asynchronous code in a synchronous-looking way. You recognize them by them having the `*` as part of the function declaration like so:

```js
function*() {}
```

and also that the keyword `yield` is used. `yield` is used in the same way as an `await` and means we should stay here and wait in the code until our asynchronous operation has concluded.

So what does that mean for our code above? Let's look more closely:

```js
 outputs.push(yield context.df.callActivity("Hello", "Tokyo"));
```

Here we can see that we are calling `context.df.callActivity()` with the args `Hello` and `Tokyo` with the keyword `yield`. This simply means we are invoking an activity function `Hello` with the argument `Tokyo`. We can see that there are two more calls to `callActivity()` that won't be carried out until our activity function has concluded. 

#### Hello
Next up we have an activity function. This is where we carry out all the heavy lifting. Looking at the `index.js` for the `Hello` directory we see the following code:

```js
// Hello/index.js

module.exports = async function (context) {
    return `Hello ${context.bindings.name}!`;
};
```

We see that it returns straight away but it could definitely be a long-running activity. The point is whether it runs in a millisecond or takes some time, it doesn't matter, the orchestration function still have to wait for it to conclude.

### Debugging

You may think you understand everything up to this point but it really clicks when you see a debugging flow happening. So that's what we are going to be doing next, we are going to start up our durable function from VS Code and you will be able to see how the breakpoints hit and when.

One of the first things we need to do is to install the `durable-functions` NPM library that we keep referring to, so let's do that:

```
npm install durable-functions
```

Now we are ready to debug so let's hit the debug button.

We should be getting something like this printed in the terminal

![](https://thepracticaldev.s3.amazonaws.com/i/v6g5rkpkskgp3v12tayv.png)

Next thing we need to do is to kick everything off by hitting our client function route as indicated above `orchestrators/{functionName}`. Because we only have one such function called `Orchestrator` we need to start the whole thing by calling the following URL in the browser:

```
http://localhost:7071/api/orchestrators/Orchestrator
```

The first thing to happen is our `HttpStart` function and its `index.js` being hit like so:

![](https://thepracticaldev.s3.amazonaws.com/i/93zojxsk69kct56i2qum.png)

We let the debugger advance:

![](https://thepracticaldev.s3.amazonaws.com/i/ex54yfi4o7tyey4b1xwg.png)

Above we see how the `Orchestrator` and its `index.js` is being hit. 

Next up we advance to the next breakpoint and we see that our activity function `Hello` and its `index.js` is being hit next. 

![](https://thepracticaldev.s3.amazonaws.com/i/vgvgi1lwlww6mhbidlm8.png)

We advanced the breakpoint and we find ourselves being back in the orchestration function:

![](https://thepracticaldev.s3.amazonaws.com/i/47nty0r9iz8b609fzcil.png)

This will lead to the `activity` function being hit again, this time with the argument `Seattle`, like so:

![](https://thepracticaldev.s3.amazonaws.com/i/r2qo8squak483rokwuet.png)

As you can see it will keep going like this between activity function and orchestrator until orchestrator is done. 

Let's advance through all the breakpoints. 

We end up coming to a page like this which is the HTTP response from the method called `HttpStart`

![](https://thepracticaldev.s3.amazonaws.com/i/z2w5665kgu0lwdd9jacp.png)

What's interesting for us to know at this point is what did we end up producing? The answer lies in the URL called `statusQueryGetUri`. Let's follow that link:

![](https://thepracticaldev.s3.amazonaws.com/i/1o37k5qdllc93kmvku9j.png)

As you can see above the response from our `Orchestration` function is an array consisting of the responses from all activity functions, like so:

```json
"output": [
  "Hello Tokyo!",
  "Hello Seattle!",
  "Hello London"
]
```

It ended up that way because of the way we constructed the code, we wrote this:

```js
outputs.push(yield context.df.callActivity("Hello", "Tokyo"));
outputs.push(yield context.df.callActivity("Hello", "Seattle"));
outputs.push(yield context.df.callActivity("Hello", "London"));

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

## Summary

There is so much more to learn about Durable Functions but I can already hear some of you snore at this point which is why we will save topics such as Application Patterns and implementation of a pattern `Fan-out/fan-in` for the next part. 

So I hope you are excited about that one.

### Acknowledgements
I wouldn't be writing this if it wasn't for your guidance in how Durable Functions work. You both are amazing human beings.

So go give them a follow, they really know their stuff on Serverless

- Anthony Chu
[dev.to](https://dev.to/anthony), 
[twitter](https://twitter.com/nthonyChu) 
- Jeremy Likness
[dev.to](https://dev.to/jeremylikness)
[twitter](https://twitter.com/jeremylikness)