What are you looking for?

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

Learn how to use the Camunda 8 JavaScript SDK for Node.js in an AWS Lambda function to interact with Camunda SaaS.
  • Blog
  • >
  • 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.

      Sidebar showing Layers menu selected and Create Layer button

      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.
      Screen for selecting credentials format, with Env Vars tab selected

      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.

      Sidebar showing Functions selected and Create function button highlighted

      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.

      Create function window with Author from scratch radio button selected

      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.

      Function overview screen for Camunda8SDKExample

      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:

      Screen showing details for encrypted environment variables

      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.

      Camunda3SDKExample function with general configuration details

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

      Basic settings options showing 128MB for Memory, 512MB for Ephemeral storage, and 10 sec for time out

      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.

      The Code tab for the Camunda8SDKExample function overview, showing the code source and Test button

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

      Layers Info page with the Add a layer button

      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.

      The Choose a Layer page with the Custom layers radio button selected

      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).

      Menu showing the option to Rename the index.mjs folder

      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:

      The Code Source Info tab showing a notice that says Changes not deployed

      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.

      Configure Test Event screen with the Create new event radio button selected

      Save your test event and then invoke a test:

      The Code Source Info page with Test button

      And voila! Check Operate for a started process instance.

      Process instance for Lambda Test

      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:

      The Configure test event page with the Edit saved event radio button selected

      And the result upon invocation:

      Menu showing name and value variables for Lambda Test

      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.

      Start the discussion at forum.camunda.io

      Try All Features of Camunda

      Related Content

      At CamundaCon 2024 Berlin, MetaOps discussed how they used data-driven insights to transform operational oversight for the UK General Register Office.
      Tim Stawowski spoke at CamundaCon 2024 Berlin about how Wergarantie uses Camunda Optimize to measure process and business KPIs.
      Get all the latest updates and recaps of what's happening in this live blog of CamundaCon New York 2024, Day 2.