Using Camunda 8 JavaScript SDK for Node.js in an AWS Lambda Function

Recently, Camunda introduced official support for the Camunda 8 JavaScript SDK for Node.js. Almost immediately, we began fielding questions asking what could be done using the SDK.

While you can do quite a lot with the SDK, one question from the community was the inspiration for this blog post:

Can I use it in an AWS Lambda function to start a process in Camunda SaaS?

I initially thought, “Sure, why not?” But of course having an actual example would be ideal for proving it does actually work. So let’s get started building a running demo!

Note: If you don’t already have an active account, you can can sign up to try Camunda Platform 8 for free and follow along.

Getting the Camunda 8 JavaScript SDK library into AWS

To be able to use libraries in an AWS Lambda function, you need to create a layer and upload a zip file of the library into the layer. First create a zip file of the SDK. Be sure to install Node.js along with npm.

Create a folder somewhere on your drive, like your user directory: /Users/you/blog_example.

Open a terminal window and cd to /Users/you/blog_example.

Make another directory in your blog_example folder called nodejs (it must be nodejs):

mkdir nodejs

Change directory to nodejs and create a new project using init. You can take all of the defaults:

npm init

Next, use npm to install the Camunda 8 JavaScript SDK for Node.js into this project:

npm i @camunda8/sdk

If you need to use a newer version of the SDK later on, you can create a new version of the layer in Layers.

Your blog_example folder should now look something like this:

Now you need to zip up the contents. Change directory to blog_example and zip up the contents of the nodejs folder.

cd ..
zip -r camunda8sdk.zip nodejs/*

This creates a zip file called camunda8sdk.zip, and it should contain everything you’ve just created and installed. You’ll upload this to AWS in the next section.

Create a layer in AWS and upload the SDK

Take the following steps to create a layer with the Camunda 8 SDK libraries.

First, log in to your AWS console and navigate to the Lambda function console and then to Layers. Click Create layer.

In the next screen, provide an arbitrary name, such as Camunda8SDK, and upload the zip file we created earlier. Select Node.js 20.x as a compatible runtime. Click Create to create the layer.

Next, you need to generate API credentials in Camunda SaaS and set those values in AWS.

Create Camunda 8 API credentials and use them in AWS

To access Camunda SaaS securely, you need to generate API credentials. If you already have a set of credentials, you can skip this section and go on to the next section where the credentials are used.

To create credentials, use the following steps (if you need help with these steps, refer to the documentation listed after each step):

Log into your Camunda SaaS console (Help).

If you haven’t created a Camunda cluster, do so now (Creating a cluster).

Navigate to the API tab in your cluster and create credentials (Creating credentials).

• Be sure to note the generated Client Secret, as it will only be shown upon initial creation.
• You can select all scopes to access all Camunda components.
• You can also download the credentials, including the secret, for later referral.
• Download the credentials as Env Vars, as it will contain necessary URLs along with the credentials.

Using Camunda SaaS credentials in AWS

Once you’ve generated credentials, you can use them in AWS. Go back to AWS and bring up the Lambda function console.

In the Lambda console, select Functions and click Create function.

In the next screen, provide a name for the function, such as Camunda8SDKExample, and leave the defaults for Author from scratch, Node.js 20.x runtime, and x86_64 architecture.

Click Create function.

Click the hyperlink in the list of functions to open the newly created function. In the next screen, click Configuration and then Edit to add environmental variables.

Add the following environmental variables. HOME is a folder where the generated authorization token is stored.

CAMUNDA_OAUTH_URL: https://login.cloud.camunda.io/oauth/token
ZEEBE_ADDRESS: your Zeebe address from client credentials

ZEEBE_CLIENT_ID: your Zeebe Client ID from client credentials

ZEEBE_CLIENT_SECRET: your Zeebe Client Secret from client credentials
HOME: /tmp

Your screen should look something like this:

You may need to update the timeout of your function. The default is 3 seconds, which may not be long enough. In the Configuration tab, go to General Configuration and click Edit to access the timeout configuration.

In the Edit basic settings page, update Timeout to 10 seconds.

You still need to add the layer to the Lambda function code to be able to use it. Click the Code tab in the function.

Next, scroll down in the Code tab until you see the Layers section. Click Add a layer.

Add the Camunda 8 SDK layer you created earlier. Be sure to select Custom layers to see it. There should only be one version of this layer available.

Add code and test it

You may need to rename the file extension of the code; it may default to index.mjs (ECMAScript). You’ll want to rename it to index.js (normal JavaScript).

It’s now the moment of truth—time to add some code and test it!

Copy and paste this sample code into the code section. Be sure to update the process ID to something available in your cluster. You may have to create a sample process and deploy it to your cluster:

const { Camunda8 } = require('@camunda8/sdk');

exports.handler = async (event) => {

    const c8 = new Camunda8();

    const zeebe = c8.getZeebeGrpcApiClient();

    const p = await zeebe.createProcessInstance({

            bpmnProcessId: 'Your process id here',

            variables: {

                hello: "World",

            },

        });

    return p;

};

Be sure to deploy your code:

Click Test and use an empty JSON for your test event for now. You can add a populated JSON object later and extract its contents to pass as variables to a process instance.

Save your test event and then invoke a test:

And voila! Check Operate for a started process instance.

As a further exercise, you can pass in a JSON object and extract its contents for variables. Here is the code snippet (be sure to deploy the updated code):

const { Camunda8 } = require('@camunda8/sdk');

exports.handler = async (event) => {

    var evt = JSON.stringify(event);

    var parsedEvt = JSON.parse(evt);

    var value = parsedEvt.foo;

    const c8 = new Camunda8();

    const zeebe = c8.getZeebeGrpcApiClient();

    const p = await zeebe.createProcessInstance({

            bpmnProcessId: 'Your process id',

            variables: {

                "foo": value,

            },

        });

    return p;

};

And the updated test event:

And the result upon invocation:

Congratulations! You can now use the Camunda 8 JavaScript SDK for Node.js to interact with Camunda SaaS from Lambda functions in AWS!

And remember, you can always sign up to try Camunda 8 for free.