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:

   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:

   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:

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

2. Paste and update the following template:

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

   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:

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

2. Content:

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

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

2. Content:

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

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

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

   sudo systemctl start acrobits-sync.service
   

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

   journalctl -u acrobits-sync.service