# 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/org/620528baca65b6578d29868d/instance/670e90c0cedcf9e4d34d1a23/media/686b9d484111117d7e6f4329/bin2/CleanShot%202025-07-07%20at%2012.11.05%402x.jpg?apiKey=670e90c0cedcf9e4d34d24e7.a2132a1499ac4abf17c3c3183070d09975292fb5fe5c0f15d2d8c9288171554b)

## 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](/docs/inside-bcms/api-keys) 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