# Messaging Sync Subscription Manager Setup

This guide explains how to set up the **Acrobits Subscription Manager** as a systemd service on your local infrastructure.

## Purpose

To enable message history synchronization from **NetSapiens** to **Acrobits Linkup Messaging**, the script creates and maintains SIP domain-level event subscriptions.

- **Security:** By running this locally, your NetSapiens super-user credentials never leave your premises.
- **Transparency:** You have full visibility into the code running on your infrastructure. You also maintain complete control over which domains are monitored and which are excluded using the domain filtering configuration.
- **Reliability:** While running the script once establishes subscriptions, using the system service approach ensures that broken subscriptions are repaired and new domains are automatically added to the sync every hour.
- **Troubleshooting:** The script automatically generates a health report regarding your current subscriptions and sends it to Acrobits. This gives the Acrobits team the visibility they need to assist you quickly if synchronization issues arise.

## Prerequisites

Before you begin, ensure you have the following credentials and information available:

1. **NetSapiens API host:** The base URL of your NetSapiens API (e.g., `https://api.yourdomain.com`).
2. **NetSapiens Super-User Credentials:** A username and password with super-user level access to your NetSapiens instance.
3. **NetSapiens Client ID:** The API Client ID configured in your NetSapiens portal.
4. **NetSapiens Client Secret:** The corresponding API Client Secret for your Client ID.
5. **Acrobits Callback Password:** A unique password provided by your Acrobits representative to authorize the reporting and synchronization requests.
6. **Cloud ID:** Your Cloud ID identifier, provided by your Acrobits representative.

## Step 1: Directory & Script Preparation

We recommend using the `/opt/` directory for self-contained scripts.

1. **Create the application directory:**

    ```bash
    sudo mkdir -p /opt/acrobits-sync
    ```

2. **Install the script:** Contact your Acrobits representative to obtain the latest version of `subscription_manager.py`. Place it into `/opt/acrobits-sync/`.

3. **Set permissions:**

    ```bash
    sudo chown -R root:root /opt/acrobits-sync
    sudo chmod 700 /opt/acrobits-sync/subscription_manager.py
    ```

## Step 2: Configure Environment Variables

Create a file named `config.env` in the same directory to store your credentials.

1. **Create the file:**

    ```bash
    sudo nano /opt/acrobits-sync/config.env
    ```

2. **Paste and update the following template:**

    ```bash
    # NetSapiens API base URL (with scheme, e.g., https://my-api.ns.net)
    NS_API_HOST=your_api_host

    # NetSapiens Client API secrets
    NS_CLIENT_ID=your_client_id
    NS_CLIENT_SECRET=your_client_secret

    # NetSapiens Super-User Credentials
    NS_USERNAME=your_username
    NS_PASSWORD=your_password

    # Acrobits Messaging Endpoint
    CALLBACK_HOST=https://api-us.messaging.acrobits.cz

    # Provided by your Acrobits representative
    CALLBACK_PASSWORD=your_callback_password

    # Cloud ID identifier
    CLOUD_ID=your_cloud_id

    # --- Editable Testing Domain ---
    # Use this to select precisely which domain should be subscribed for
    # testing with the editable version of your Cloud ID.
    EDITABLE_VERSION_DOMAIN=

    # --- Domain Filtering ---
    # Use these to select precisely which domains should be subscribed.
    # Note: ALLOWED_DOMAINS and DISALLOWED_DOMAINS cannot be used at the same time.

    # Comma-separated list (e.g., "domain1.com,domain2.com")
    ALLOWED_DOMAINS=""
    DISALLOWED_DOMAINS=""
    ```

3. **Secure the configuration:**

    ```bash
    sudo chmod 600 /opt/acrobits-sync/config.env
    ```

## Step 3: Create the systemd Service

This unit defines the execution logic for the script.

1. **Create the file:**

    ```bash
    sudo nano /etc/systemd/system/acrobits-sync.service
    ```

2. **Content:**

    ```ini
    [Unit]
    Description=Acrobits Linkup Messaging Subscription Manager
    After=network.target

    [Service]
    Type=oneshot
    User=root
    WorkingDirectory=/opt/acrobits-sync
    EnvironmentFile=/opt/acrobits-sync/config.env
    ExecStart=/usr/bin/python3 /opt/acrobits-sync/subscription_manager.py
    ```

## Step 4: Create the systemd Timer

This unit handles the hourly schedule.

1. **Create the file:**

    ```bash
    sudo nano /etc/systemd/system/acrobits-sync.timer
    ```

2. **Content:**

    ```ini
    [Unit]
    Description=Run Acrobits Subscription Manager hourly

    [Timer]
    OnCalendar=hourly
    RandomizedDelaySec=300
    Persistent=true

    [Install]
    WantedBy=timers.target
    ```

## Step 5: Activation & Monitoring

1. **Enable and start the timer:**

    ```bash
    sudo systemctl daemon-reload
    sudo systemctl enable --now acrobits-sync.timer
    ```

2. **Manual Test:** Run the service immediately to verify the configuration.

    ```bash
    sudo systemctl start acrobits-sync.service
    ```

3. **Check Logs:** Confirm success via the system journal.

    ```bash
    journalctl -u acrobits-sync.service
    ```