Introduction

Event Driven Functions allow you to run a custom code whenever events are happening in the Mambu application. In custom code you can perform actions like calling Mambu APIs or even any other external APIs.

Event Driven Functions integrates with Mambu Streaming API and supports all events types which are supported by the Streaming API: Event Triggers for Notifications - Notifications Different to Streaming APIs, Event Driven Functions do not require any additional infrastructure to process the events and allows you to concentrate on developing custom business logic rather than hosting your own application.

The guide bellow will walk you through the main Event Driven Functions concepts and commands.

Workflow to set up Event Driven functions

In order to setup Event Driven function, you need to:

• Create an event streaming notification template for the target event via admin UI.
• Generate a sample function using Mambu CLI and then implement the custom business logic.
• Create secrets necessary for your functions.
• Build and deploy the function.
• Create a function Subscription for the target event.
• Monitor your function to verify that events are being processed as expected.

Create event streaming notification templates

Event streaming notification template defines conditions when the event will be triggered as well as the payload which will be sent to the function. Please follow “Creating event streaming notification templates” section in the Streaming API documentation.

Note down the topic name which will be automatically generated when creating the template.

Create the project scaffolding for Event Driven Dunction

The Mambu Functions CLI allows you to easily create all the files you need to start working on your new Event Driven Function with the command:

mambu functions generate --functionDirectory=./your-function --functionName=your-function --template=STREAMING_EVENTS

The command will generate a sample typescript project containing Event Driven Function for the following sample use case: applying a fee for each withdrawal on the deposits account. This can be further extended to other use cases. Please refer to the README file in the function directory for more details how to setup this specific example.

Main project files and directories:

• README.md - documentation how to configure and deploy the example project
• mambu-function.json - function’s manifest file. Specifies target file, function name, language etc.
• package.json - typescript project settings and depencies
• src/* - directory containing all function typescript source files
• test/* - directory containing function unit tests
• src/function.ts - typescript file with the main method which will be invoked by Mambu

After building the project, all function’s files and dependencies will be bundled to dist/bundle.js file. You should never modify this file directly since all the changes will be overwritten during next build.

For more details how to modify this project to suit your business needs, please check Development guidelines section below.

Building and deploying event-driven functions

Event Driven Function can be built and deployed the same way as any other Mambu Function. Please follow the general guide here.

Subscriptions

Similar to Streaming APIs, a Subscription is required for a function to start receiving the events. Subscription is effectively a mapping between a function and an event.

As soon as Subscription is created, Mambu application will start invoking your function when the target event happens and the conditions in the template are met. Each time your function is invoked, it will receive a batch of the events, rather than a single event. Batching behavior can be controlled, see Create Subscriptions and Update Subscriptions.

Create Subscription

To create the Subscription for Mambu Functions, run the command:

mambu functions create-subscription --functionName=your-function --subscriptionName=subscription-name --event=events-name

It might take up a few seconds for Subscription to be created.

Get Subscription details and status

To check the configuration and the status of the Subscription, run the command:

mambu functions get-subscription --functionName your-function --subscriptionName subscription-name

List Subscriptions

To see the Subscription(s) that you have already created for the function, run the command:

mambu functions list-subscriptions --functionName your-function

Update Subscription

To update a Subscription that you have already created to Mambu Functions, run the command:

mambu functions update-subscription --functionName your-function --subscriptionName subscription-name --batchSize <value> --batchWindow <value>

Delete Subscription

To delete a Subscription that you have already deployed to Mambu Functions, run the command:

mambu functions delete-subscription --functionName your-function --subscriptionName subscription-name

After subscription is deleted, there is still a limited amount of time when you can recreate the subscription with the same name and it will pick up events starting from the point when the previous subscription was stopped/deleted.

Disable Subscription

To temporarily stop a Subscription, run the command:

mambu functions disable-subscription --functionName your-function --subscriptionName subscription-name

When subscription is stopped, Mambu application will not be sending the events to your function, but all the events will still be queued and sent to the function as soon as the Subscription is reenabled.

Enable Subscription

To enable a stopped Subscription, run the command:

mambu functions enable-subscription --functionName your-function --subscriptionName subscription-name

When Subscription is reenabled, Mambu application will start sending all events, including those which happened while the Subscription was disabled, assuming they did not expire.

Secrets

For most use cases your function will need to have access to secret values like API tokens or passwords. Mambu Functions capability provides a mechanism to securely store your secrets and retrieve them in your function.

In addition, you can also store environment specific parameters as secrets (e.g. Mambu API url). That way you won’t need to change your code at all when deploying to different environments (sandbox, production).

Secrets you create are not linked to a specific function and can be reused in multiple functions.

Create Secret

To create a Secrets, run the command:

mambu functions create-secret --name secret-name --value secret-value

List Secrets

To see the Secrets that you have already created, run the command:

mambu functions list-secrets

The command will only return secret names and some additional metadata, but not the secret values. For security reasons, it’s not possible to retrieve secret values via CLI or API. Secret values can only be retrieved from inside your function.

Update Secret

To update a Secret that you have already created, run the command:

mambu functions update-secret --name secret-name --value secret-value

Previous value will be overwritten.

Delete Secret

To delete a Secrets that you have already created, run the command:

mambu functions delete-secret --name secret-name

Retrieving Secret in your function

In order to retrieve a secret in your function, a

context.getSecret()

function can be used. context is a second parameter of you handler function. E.g.

export default async function handle(events: StreamingEvent[], context: Context): Promise<void> {
    const secretValue = (await context.getSecret('secret-name')).value
}

context.getSecret() returns a promise with a Secret object. Secret contains two fields:

1. name: string - secret name
2. value: string - secret value

Retries and Error handling

Event Driven Functions come with a built in retry mechanism.

When your event driven function starts throwing an exception, the following error handling strategy is applied:

1. The whole batch of events will be retried multiple times. A random delay will be added between retries.
2. If error rate remains high for a longer period of time, the Subscription of the function will be automatically stopped.
3. An outbound Salesforce case will be created to notify you about a stopped Subscription. Mambu champions will be added to the case as main contacts.

After Subscription is stopped, you need to identify the underlying issue, resolve it and reenable the Subscription using enable-subscription cli command. In order to identify the issue, please check function logs. More details about logging can be found in Retrieving Function logs section.