Extending BCMS with Functions

Functions in BCMS are serverless code snippets that can be executed on-demand to perform custom logic, data processing, or integrations. They provide a way to extend your BCMS instance with custom functionality without managing infrastructure.

Accessing Functions

  1. Navigate to Settings: Go to your BCMS instance dashboard and click on "Settings" in the left navigation menu.

  2. Functions Section: In the settings menu, click on "Functions" to access the functions management interface.

CleanShot 2025-07-07 at 12.11.05@2x.jpg

Creating a new function

Step 1: Access the create function interface

  • From the Functions list view, click the "Add new function" button (blue button with plus icon)

  • This will open the function creation form

Step 2: Configure basic settings

  • Name: Enter a descriptive name for your function (required)

  • Use clear, descriptive names like "ProcessUserData" or "SendEmailNotification"

  • Names should be unique within your instance

Step 3: Write your function code

The function editor has two main sections:

Imports section

// e.g.
const crypto = require("crypto");
const axios = require("axios");
  • Add any Node.js modules you need to use

  • Only include modules that you previously defined in Dependencies.

Function handler section

// Is run on every function call
// e.g.
console.log(data);
return {
    message: 'Hello ' + mySetupValue,
    randomString: crypto.randomBytes(8).toString('hex'),
};

Key points:

  • The handler code runs every time the function is called

  • You have access to the request object containing the call data

  • Return any data you want to send back to the caller

Step 4: Save your function

  • Click "Add function" to save and create your function

  • The function will be immediately available for use


Editing existing functions

Accessing function editor

  1. From the Functions list, click on any function name or the "Edit" action

  2. This opens the function editor with the current code

Making changes

  • Modify the function name, imports, or handler code as needed

  • Click "Update function" to save changes

  • Changes take effect immediately


Function structure and execution

Code structure

Functions are automatically wrapped in this structure:

/*____IMPORTS_START____*/
// Your imports here
/*____IMPORTS_END____*/

exports.default = async (request) => {

/*____HANDLER_START____*/
// Your handler code here
/*____HANDLER_END____*/

}

Request object

The request parameter contains:

  • body: The data sent with the function call

  • headers: HTTP headers from the request

  • user: User information (if authenticated)

  • apiKey: API key information (if called via API key)

Return values

  • Return any JavaScript object or primitive

  • The return value will be sent back as JSON

  • Example: return { success: true, data: result };


Calling functions

Via API

Functions can be called using the REST API:

curl -X POST \
  "https://your-instance.bcms.cloud/api/v3/org/{orgId}/instance/{instanceId}/fn/{functionId}/call" \
  -H "Authorization: ApiKey {key_id}.{key_secret}" \
  -H "Content-Type: application/json" \
  -d '{"key": "value"}'

API key needs permissions for your function

  • Create an API key in the API Keys section

  • Configure function permissions for the API key

  • Use the API key to call functions programmatically

Response format

{
  "success": true,
  "payload": {
    "message": "Hello World",
    "timestamp": "2024-01-01T00:00:00.000Z"
  }
}

Function permissions and security

API Key permissions

  1. Access API Keys: Go to Settings → API Keys

  2. Edit API Key: Click on any API key to edit its permissions

  3. Function Permissions: In the "Function permissions" section:

    1. Check "Can call this function" for each function you want the API key to access

    2. Only checked functions can be called with that API key

Security features

  • Functions run in isolated environments

  • API keys can be blocked/unblocked

  • Function access is granular per API key


Best practices

Code organization

  • Keep functions focused on a single responsibility

  • Use descriptive function names

  • Add comments for complex logic

  • Handle errors gracefully

Performance

  • Keep functions lightweight and fast

  • Avoid long-running operations

  • Use async/await for external API calls

  • Cache results when appropriate

Security

  • Validate all input data

  • Sanitize user inputs

  • Use environment variables for sensitive data

  • Implement proper error handling

Testing

  • Test functions with various input data

  • Verify error handling scenarios

  • Check response formats


Limitations and considerations

Runtime Environment

  • Functions run in a Node.js environment

  • Limited to available Node.js modules

  • No file system access

  • Memory and execution time limits apply

Rate Limits

  • Functions are subject to rate limiting

Error Handling

  • Always return a response object

  • Use try-catch blocks for external API calls

  • Provide meaningful error messages


Troubleshooting

Common Issues

  1. Function not found: Check function ID and permissions

  2. Import errors: Verify module availability

  3. Timeout errors: Optimize function performance

  4. Permission denied: Check API key permissions

Debugging

  • Check function execution logs

  • Verify API key permissions

  • Test with simple data first

Integration with other BCMS features

Events

  • Functions can be triggered by BCMS events

  • Use for automated workflows

  • Process content changes automatically

Templates

  • Functions can process template data

  • Transform content before display

  • Validate entry data

Media

  • Process uploaded media files

  • Generate thumbnails or metadata

  • Integrate with external media services