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

![Functions page](https://app.thebcms.com/api/v3/instance/670e90c0cedcf9e4d34d1a23/media/686b9d484111117d7e6f4329/bin2/CleanShot%202025-07-07%20at%2012.11.05%402x.jpg?apiKey=670e90c0cedcf9e4d34d24e6.7e8471eb288ed672495cf4734e877b33042a4d7d63059d938576b8d45d35c166.670e90c0cedcf9e4d34d1a23)

## 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

```JAVASCRIPT

// 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

```JAVASCRIPT

// 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:

```JAVASCRIPT

/*____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:

```BASH

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

```

### API key needs permissions for your function

- Create an API key in the [API Keys](https://thebcms.com/docs/inside-bcms/api-keys.md) section

- Configure function permissions for the API key

- Use the API key to call functions programmatically

### Response format

```JAVASCRIPT

{
  "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:Check "Can call this function" for each function you want the API key to access

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