Disclaimer

While fully functional, this feature is still experimental.

Its behavior, limitations, and available functionality may change as it evolves. As with any experimental feature, bugs may occur. We intend to keep this feature as part of the software long term, but until it matures, changes to its design, capabilities, and constraints should be expected.

This feature requires advanced technical skills in software development, system integration, and related technical domains. Eramba does not provide support for developing or troubleshooting custom automation code. If your code does not compile or behave as expected, this falls outside the scope of basic support.

For assistance of this nature, dedicated consulting services are required. You can contact support@eramba.org for more information on availability and billing.

Introduction

Automations in eramba allow users to run custom PHP code directly within eramba. The code is provided by the user and can include Composer dependencies. Automations give full control over what runs and when, without predefined workflows or fixed integrations.

Automations can run on a schedule (for example, daily) or in response to user-defined scenarios, such as when an item is created, edited, or when a specific attribute changes.

They are mainly used for integrating eramba with external systems, but can also execute any programmatic task, including validations, custom processing, or advanced use cases like using an LLM to review policies for spelling or consistency issues.

Typical Scenarios

This chapter shows practical ways to use automations:

Automatically test internal controls by connecting to AWS and verifying that storage volumes are encrypted
Automatically review policies and procedures for spelling or formatting issues using an LLM
Regularly sync Jira projects with eramba Projects (one-way or bi-directional)
Pull assets from a CMDB and keep them synchronized in eramba
Create or update tickets in an ITSM tool when risks, incidents, or control failures are detected in eramba
Push compliance or risk status from eramba into BI or reporting platforms for centralized dashboards
Run a custom risk calculation after a Risk is saved, using parameters from eramba and external systems
Parse online assessment responses and automatically create Third Party Risks

Supported Versions

Automations run on both on-premise and cloud deployments and are available Enterprise only.

Each Enterprise installation is limited to a maximum of five automation scripts across all modules. To protect system stability, automations are subject to enforced limits on execution time, network usage, and file storage.

Scope

Automations are available only in selected modules. Support will be expanded to additional modules over time, with the long-term goal of covering all modules.

You can verify whether automations are enabled for a module by opening the module and checking the Common Features menu. If Automation is listed, the module supports automations.

Templates

We host a repository of automation examples grouped by vendor (AWS, etc.) in this GitHub repository: https://github.com/eramba/automation

If you need assistance creating custom automations, contact support@eramba.org. We provide these services.

Theory

The following is a detailed list of key concepts you need to understand in order to manage automations:

Automation is based on custom code you write in PHP (latest stable version)
Your code must be composed of two things, a single file script and a JSON based composer
On every execution, eramba will first update your composer instructions and then execute the code
Your code will be executed in two ways:
- Event based (when an notification is triggered your code will be triggered).
- Regularly (every hour or day depending what you prefer)
When a notification triggers an automation, the automation can access the affected item’s attributes (such as ID, name, and other fields) through macros, which can be used directly in the PHP code. For example, if an Internal Control / Audit item (and audit) triggers a notification that today is the due date, the automation will be able to access that "audit" item attributes.
Automations can write data to the filesystem, but only to a single, predefined file name assigned to each automation.
This file can be accessed by automations across different modules.
File size is subject to a maximum size limit.
This mechanism can be used to share data between automations, for example by maintaining a company roster file that multiple automations use for account reviews.
Automation secrets can be stored under System / Settings and referenced by automation scripts, avoiding hardcoded credentials or tokens.
Automation scripts can be tested before being enabled for production use.
Each automation has a unique hash generated from its content, allowing script changes to be tracked over time.
Every automation execution generates logs, capturing both STDOUT and STDERR output.
Automations run inside a dedicated, hardened container.
Only outgoing TCP connections on ports 80 and 443 are allowed, subject to bandwidth limits.
The number of concurrent TCP connections from the container is limited to prevent flooding or denial-of-service scenarios.

Coding

Code Editor

When you create an automation, Eramba displays a code editor. The editor is composed of the following elements:

Execution Type: A flag that defines whether the automation is Recurrent or Event Triggered.
Automation Title (mandatory): A descriptive name used to identify the automation.
Timeout: Maximum execution time for the script.This value is hardcoded to 120 seconds.
Composer Instructions: Dependency definitions written in JSON format. Invalid JSON will prevent the automation from running.
PHP Code Editor: The area where the automation logic is implemented using PHP.

Each of these elements must be correctly configured for the automation to execute successfully.

Anything written in this editor is executed by PHP, so the syntax must be valid. If the code contains syntax errors, the Save button will not work and an error will be displayed. PHP validation happens at save, test and exection time.

Editor Tools

There are three key tools you can use when building code:

Macros are primarily used in event-triggered automations. They allow the automation to reference the item that triggered the event. For example, if a control named “Test” triggers the automation, the Title macro will resolve to “Test”.
Actions define what the automation does. They allow you to create and update items, add comments and attachments, and write data to files for permanent storage.
Secrets are used to securely store credentials that can later be accessed by automations.

In the comming chapters we describe how each is used.

Macros

Item Macros are useful for "Even Triggered" automations since these are always asociated to an existing eramba item (Policy, Internal Control/Audit, Exception, etc). The attributes (Title, ID, Etc) of these items can be read using these macros.

Macros are enclosed by % characters. Always wrap macros in quotes; otherwise, PHP will fail to parse the code and a syntax error will occur.

Actions

Actions allow you to interact with items: Add, Edit and Include Comments and attachments.

Actions/Edit

When editing an item you need:

Understand the Key->Value fields for that item (some are editable some not, some are mandatory some are not, etc)
The ID of the item you are trying to Edit, while this is often times coming from a Macro you could have found those IDs by querying eramba with an API call.

When you click Tools / Actions / Edit Item, you are presented with the following:

Item ID Macro and Variable: A macro representing the item ID, along with a PHP variable that already contains this value.
Sample JSON Payload: An example JSON structure using a key → value format, showing how object attributes can be updated.
Built-in Function: editObjectMacro(): A helper function used to modify items in Eramba. This function requires two mandatory parameters: the JSON payload described above and the item ID. Both parameters must be provided for the function to execute correctly.
The edit function updates only the fields explicitly defined in the JSON payload. All other fields in the item remain unchanged. Only fields that are editable can be modified; you can verify which fields are editable by editing the item through the web interface. For example you can not edit the "Planned date" of an existing Internal Control / Audit record using the web-interface, the same applies to this function.
The edit function support custom fields

Actions/Add

When adding an item you need:

Understand the Key->Value fields for that item (some are editable some not, some are mandatory some are not, etc)
You only need to complete mandatory fields, optional fields do not need to be part of the JSON file.
The Add function support custom fields

Comments

Your automation can add text (strings) to an item’s Comments & Attachments section. This function is simple and requires only the item ID (for example, obtained from a macro) and the text you want to add.

Attachments

In the same way that you can add comments, you can also add attachments. Keep the following points in mind:

The attachment function also requires a comment. While this may seem unnecessary, it is mandatory.
If the attachment is a binary file, it must be encoded before being uploaded. Base64 encoding is recommended.
The text inserted on the editor box is a functinoal example on how a binary encoded content can be included as an attachment.

File Write

Some scripts may need to write output to a local file (TRIGGER_STORAGE_HASH). For example, you might maintain an always-up-to-date list of employees when running automation jobs that refresh the roster every hour.

Each automation is assigned a single, dedicated file that it is allowed to write to. This file has a fixed size limit. Any attempt to write to other files or locations will be blocked.

Secrets

Your code will typically connect to external systems, which requires credentials such as endpoints, tokens, and other secrets. These values can be defined under System → Settings → Application Configuration → Secrets.

In your code, use the toolbox option to load the required secrets. Secrets are provided as strings, so they must be enclosed in quotes for PHP execution not to fail.

Test Code

While writing code, you should test it before saving. Click Test to run the automation in test mode.

When testing, a modal window opens where you can optionally select an item from the module where the automation was created.

Selecting an item allows the script to read the item’s ID and perform actions such as editing the item, adding comments, or updating attributes.
Selecting an item is optional because some automations do not depend on a specific object. This is common for Recurrent scripts.

Testing helps validate both PHP syntax and runtime behavior before saving the automation.

Testing will replace your code macros for real values (if you selected a testing item) and execute the PHP code showing you the STDOUT, STDERR and exist CODE.

If you select an item for testing, the Test feature replaces macros with the item’s actual values (strings) and executes the code exactly as it would run in production.

This allows you to verify that:

Macros are resolved correctly
The script can read the item ID and attributes
Actions (edit, comment, etc.) behave as expected (remeber Clicking on test will actually run the code)

If you are building code is good idea to create a few dummy items on the module you can test against. Once your code is working as expected you can delete these items.

Creating Automations

The general process by which you implement automations in Eramba is defined by the following steps:

Scenario Definition

Automations can be applied to an almost unlimited range of scenarios; their usefulness depends largely on your design choices. When defining an automation, consider the following points:

Objective: What are you trying to achieve with this automation?
Scope: Which Eramba modules are affected, and are automations enabled for those modules?
Integrations: What external systems need to be integrated, and do they expose API capabilities? Can you get credentials to connect?
Dependencies: When integrating with external systems, are Composer-ready SDKs available to keep your PHP script clean and maintainable?
Execution model: Should the automation run in response to an event or on a recurring schedule?
Persistence: Do you need to store data permanently in the filesystem, and will other automations within the same section need access to those files?
System changes: Will the automation create or update items within Eramba?
Failure handling: How will administrators be notified if the automation fails, and are notifications properly configured to surface these issues?

Create Automation

The steps to create an automation are as follows:

Go to the module or sub-module where the automation should run.
Create a new automation and complete all required fields. You must decide whether the automation will run in response to an event or execute on a regular schedule (for example, hourly or daily).
Test the automation to ensure it works as expected. This may require creating a “dummy” item in the module to trigger the automation.
Save the automation.
Monitor its execution using the Automation logs (see the chapter below).

Recurrent Automations

When creating an automation, if you set it as a Recurrent Automation, you can define how frequently it will run or place it in a Paused state if it should not execute. Daily executions run at midnight.

Triggered Automations

Triggered automations are executed by notifications. The process to create a triggered automation is as follows:

(Optional) Create a Dynamic Status with the conditions you require on the module where the Automation will run.
Create a Warning Notification on that same module, that triggers either:
- Based on the previously defined Dynamic Status, or
- Using a pre-defined condition built into the notification. You can also trigger automations using Comments & Attachments–type notifications.

In the notification settings, select the Trigger Automation option. You may enable other actions at the same time, such as Email or Webhook.
Select the automation you created in the previous steps.

Logs

Every time a script runs—including test runs—it generates logs that are stored under System → Settings → Application → Logs.

Every time you save an automation, Eramba generates a unique hash based on the code you provided. This hash is recorded on every execution (see Logs), allowing you to track code changes over time.

Logs are also accessible from each automation. When you open the automation modal, a log counter is shown; clicking it redirects you to the corresponding logs section under Settings.

Error Handling

Automation scripts can complete successfully (exit code 0) or fail with an error (exit codes 1, 255, etc.). When an automation that affects an item finishes with an exit code other than 0, a dynamic status associated with that item will be displayed.

In addition, System → Settings → System Health will display a warning if any automation executions fail. You can always review the Automation logs under System → Settings to identify what triggered the issue and understand the cause of the failure.

Example

AWS Volume Encryption

For this example, we want to automate the testing of an Internal Control called “AWS Volume Encryption”. The automation will connect to AWS, pull all volumes that match a certain tag, and review whether encryption is enabled on them or not. Based on this, it will complete the audit record.

All the code for this example will be provided by an LLM, we will not code a single line of code.

Online Assessment Review

This automation will execute right after an Online Assessment has been submitted. The automation will go through the questions and answers and run them through an LLM for an opinion on how risky the supplier is. Based on the LLM judgment, a custom field called “Risk” will be updated.