npm package: @mediacockpit/n8n-nodes-mediacockpit
Description: n8n nodes for MediaCockpit DAM and PIM integration
Author: Chris Turchin
Latest version: 0.3.0

# n8n MediaCockpit Integration

A comprehensive n8n node package for integrating with MediaCockpit DAM (Digital Asset Management) and PIM (Product Information Management) systems via REST API.

The REST API is documented at <https://docs.mediacockpit.info/articles/MCDG-A-33227102/REST-API> but only accessible with an elevated login provided by Bertsch apon qualification.

## Features

- **Dual Node Support**: Separate n8n nodes for DAM (Digital Asset Management) and PIM (Product Information Management)
- **Complete CRUD Operations**: Search, List, Get by ID, Update, Delete, Upload, and Download
- **Advanced Search Capabilities**: Simple text search and advanced JSON filter queries
- **File Management**: Upload assets and download with derivative support
- **Flexible Output Control**: Optional build parameters for custom response formatting for search and for individual objects
- **Pagination Support**: Handle large result sets efficiently via paging
- **Session Management**: Automatic login/logout with session handling

## Installation

1. Install the `@mediacockpit/n8n-nodes-mediacockpit` package in your n8n instance in the admin interface via "Install community nodes" option or via the CLI on your server.

   ```bash
   npm install @mediacockpit/n8n-nodes-mediacockpit
   ```

2. Restart your n8n instance to load the new nodes.

3. The MediaCockpit DAM and MediaCockpit PIM nodes will be available in your node palette.

## Configuration

### Credentials Setup

Create MediaCockpit API credentials with:

- **API URL**: Your MediaCockpit server URL (e.g., `my.mediacockpit.co`)
- **Username**: Your MediaCockpit username
- **Password**: Your MediaCockpit password

## MediaCockpit DAM Node

The DAM node handles digital assets like images, videos, documents, and other media files.

### Operations

#### Search Assets

Search for assets using metadata, tags, or content.

**Search Modes:**

- **Simple Search**: Enter a text query to search asset content
- **Advanced Filter**: Use custom JSON filter for complex queries, for more information, see the developer guide or contact Bertsch

**Example Advanced Filter:**

```json
{"criteria": [{"field": "content", "param": "wg21"}]}
```

#### List Assets in Collection

List all assets within a specific folder or collection by ancestry. Any ancestor ID can be used.

**Parameters:**

- **Ancestor ID**: The parent folder/collection ID

#### Get Asset by ID

Retrieve detailed information about a specific asset.

**Parameters:**

- **Asset ID**: The unique identifier of the asset

#### Download Asset

Download asset files with support for derivatives.

**Parameters:**

- **Asset ID**: The asset to download
- **Download Derivative**: Whether to download a derivative instead of the original
- **Derivative Group**: Type of derivative (e.g., "Preview")
- **Derivative Type**: Size/quality (e.g., "large", "medium", "small")

#### Upload Asset

Upload new assets to MediaCockpit from binary field (i.e. generated via AI) or URL

**Parameters:**

- **Folder/Collection ID**: Target destination for the upload
- **File**: Binary data from previous node (e.g., HTTP Request, Read Binary File) or URL

#### Update Asset Attribute

Set / edit attribute for an asset.

**Parameters:**

- **Asset ID**: Target asset
- **Attribute Key**: Attribute to update
- **Text Value**: Simple text value
- **Metadata**: Advanced JSON object for complex attribute data types, see API docs for information.

#### Update Multiple Asset Attributes

Perform multiple attribute updates in a single request with advanced actions.

**Parameters:**
- **Asset ID**: Target asset
- **Multi-Attribute Data**: Array of attribute update objects

**Multi-Attribute Data Format:**
Each object in the array can contain:
- `attribute` (required): Attribute key to update
- `value`: Value to set (string, array, or object)
- `action`: Operation type - "update"/"set" (replace), "append" (add to multivalue), "remove"/"delete" (remove values)
- `create`: Boolean - create enumeration values on demand

**Examples:**

Set a single value:
```json
[{
  "attribute": "AT_TV_SINGLE",
  "value": "a single value"
}]
```

Set multiple values:
```json
[{
  "attribute": "AT_TV_MULTI",
  "value": ["multi value 1", "multi value 2", "multi value 3"]
}]
```

Replace existing values:
```json
[{
  "attribute": "AT_TV_MULTI",
  "action": "update",
  "value": ["new value 1", "new value 2"]
}]
```

Remove specific values by ID:
```json
[{
  "attribute": "AT_TV_MULTI",
  "action": "remove",
  "value": [4588696, 4588697]
}]
```

Create enumeration values:
```json
[{
  "attribute": "AT_TV_ENUM",
  "create": true,
  "value": ["newValueKey1", "newValueKey2"]
}]
```

#### Delete Asset

Remove an asset from the system.

**Parameters:**

- **Asset ID**: Asset to delete

## MediaCockpit PIM Node

The PIM node handles product information, catalogs, and structured data. 

### Node operations

Except for upload/download, the same operations and details above are also relevant for nodes.

#### Search Nodes

Search for PIM nodes.

**Search Modes:**

- **Simple Search**: Text-based content search
- **Advanced Filter**: Custom JSON filter queries, see above for more information

#### List Nodes in Folder

List all nodes within a specific parent node or collection.

#### Get Node by ID

Retrieve detailed information about a specific PIM node, inlcuding build filter.

#### Update Node Attribute

Modify node attribute.

#### Update Multiple Node Attributes

Perform multiple attribute updates in a single request with advanced actions. Same powerful multi-attribute functionality as DAM nodes, but for PIM nodes. See above for more details.

#### Delete Node

Remove a node from the system.

## Common Features

### Pagination Controls

Available for Search and List operations:

- **Return All Results**: Get all matching items (default: true)
- **Limit**: Maximum number of results when not returning all

### Build Parameter

Available for Search (advanced mode) and Get by ID operations:

- **Build JSON**: Optional parameter to customize output format
- Leave empty for default output
- Use JSON to specify custom build configuration

**Example Build Configuration:**

```json
{
  "attributes": true,
  "relations": false
}
```

### Advanced Filter Examples

**Search by asset type:**

```json
{
  "criteria": [
    {"field": "content", "param": "Stempel"}, 
    {"field": "assetType", "param": "ASSET_TYPE_EPAPER" }
  ]
}
```

**Search by multiple criteria:**

```json
{
  "criteria": [
    {"field": "content", "param": "marketing"},
    {"field": "lifeCycleFlag", "param": "RELEASED"}
  ]
}
```

**Search by date range:**

```json
{
  "criteria": [
  {
    "field": "dateModified",
    "paramList": ["2024-04-24","2026-04-28"],
    "rangeQuery":true,
    "includeParamFrom":true, 
    "includeParamTo":true
  }
  ]
}
```

## Workflow Examples

### Basic Asset Search and Download

1. **MediaCockpit DAM** node → Search Assets (simple mode: "product photos")
2. **MediaCockpit DAM** node → Download Asset (use asset ID from previous step)

### Upload and Organize Assets

1. **HTTP Request** node → Download file from URL
2. **MediaCockpit DAM** node → Upload Asset (to specific collection)
3. **MediaCockpit DAM** node → Update Asset Attribute (add tags, description)

### Batch Processing

1. **MediaCockpit DAM** node → Search Assets (return all: false, limit: 50)
2. **Loop** through results
3. **MediaCockpit DAM** node → Update Asset Attribute (batch update)

## Error Handling

The nodes include comprehensive error handling:

- Authentication errors (login conflicts, invalid credentials)
- API validation errors (invalid JSON, missing parameters)
- Network errors with detailed debugging information
- Graceful handling of empty results

## Development and Debugging

Debug information is available in node outputs:

- `_debug_*` fields provide request URLs, response headers, and processing details
- Enable "Continue on Fail" for batch operations
- Check n8n logs for detailed error messages

## API Reference

This integration uses the MediaCockpit REST API endpoints:

- Authentication: `/mc/rs/login` and `/mc/rs/logout`
- Assets: `/mc/rs/asset`
- Nodes: `/mc/rs/node`
- Download servlet: `/mc/download`

## Requirements

- n8n version 1.0.0 or higher
- MediaCockpit server with REST API access
- Valid MediaCockpit user credentials

## Support

For issues related to:

- **MediaCockpit API**: Contact your MediaCockpit administrator or Bertsch customer success representative
- **Node functionality**: Create an issue in this repository
- **n8n integration**: Refer to [n8n documentation](https://docs.n8n.io)

## License

[MIT](LICENSE.md)