> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firstwork.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Integrations

> Build custom integrations with the App Integration framework and external APIs

## Overview

Beyond built-in integrations, Firstwork provides an **App Integration** framework that enables you to connect with any external system. This framework supports custom authentication, data mapping, and action execution through a configurable interface.

## App Integration Framework

### App Integrations

An **App Integration** represents a connection to an external service:

| Configuration  | Description                         |
| -------------- | ----------------------------------- |
| Name           | Integration identifier              |
| Base URL       | External service API base URL       |
| Authentication | Auth method (API key, OAuth, Basic) |
| Headers        | Default HTTP headers                |
| Rate Limits    | Request rate limiting configuration |

### App Integration Actions

**App Integration Actions** are automation actions that call external APIs:

| Configuration    | Description                     |
| ---------------- | ------------------------------- |
| Endpoint         | API endpoint path               |
| Method           | HTTP method                     |
| Request Body     | Payload template with variables |
| Response Mapping | How to process the response     |
| Error Handling   | Behavior on failure             |

## Custom Objects

**Custom Objects** allow you to define custom data structures:

* Create custom entity types with custom fields
* Store data from external integrations
* Reference custom objects in compliance rules
* Use custom object data in automation templates

## RPA (Robotic Process Automation)

For integrations that don't have APIs, Firstwork provides **RPA capabilities**:

### RPA Components

| Component                  | Description                                  |
| -------------------------- | -------------------------------------------- |
| **RPA Job**                | A defined automation task                    |
| **RPA Instructions**       | Step-by-step browser automation instructions |
| **RPA Execution**          | Record of an RPA run                         |
| **Input/Output Variables** | Data passed to and from RPA jobs             |

### How RPA Works

```mermaid theme={null}
graph LR
    A[Automation Triggers RPA] --> B[Browser Session Created]
    B --> C[Instructions Executed]
    C --> D[Data Extracted]
    D --> E[Output Mapped to Firstwork]
```

### Use Cases

* Fill forms on external government websites
* Extract data from legacy systems
* Automate repetitive manual tasks
* Bridge systems without APIs

## Data Sync Framework

The **Data Sync** framework provides structured data synchronization:

| Component         | Description                                       |
| ----------------- | ------------------------------------------------- |
| **Data Sync**     | Sync configuration (source, destination, mapping) |
| **Data Sync Run** | Individual sync execution record                  |
| **Field Mapping** | How fields map between systems                    |
| **Schedule**      | Automatic sync schedule                           |

### Sync Capabilities

* Bidirectional data synchronization
* Incremental and full sync modes
* Conflict detection and resolution
* Audit trail of all sync operations
* Error handling with automatic retry

## Chat Integration (Dixa)

Firstwork integrates with **Dixa** for customer support chat:

* Sync conversation history
* Link chat interactions to applications
* Trigger automations from chat events
* Access chat data in compliance rules

## Building Custom Integrations

### Define the integration

Create an App Integration with the external service's API details.

### Create actions

Define App Integration Actions for each API call you need to make.

### Map data

Configure how Firstwork data maps to the external API's request format.

### Process responses

Define how API responses should be processed and stored in Firstwork.

### Connect to automations

Use the App Integration Action in your automations to trigger the integration.