NetSapiens Subscription Manager Script Setup

This guide explains the supported deployment models for the NetSapiens Subscription Manager script and provides setup steps for the customer-hosted systemd deployment.

This guide is part of the broader Cloud Softphone Configuration for NetSapiens setup. The NetSapiens Subscription Manager script is required only for Cloud Softphone Linkup Messaging synchronization.

Purpose

To enable bidirectional message synchronization between Cloud Softphone Linkup Messaging and NetSapiens, the script creates and maintains SIP domain-level event subscriptions on the NetSapiens platform.

With the script running, Cloud Softphone Linkup Messaging is synchronized with messaging on your deployed NetSapiens instance. Messages sent in Cloud Softphone are synchronized to NetSapiens, and messages sent or received on the NetSapiens side are synchronized back to Cloud Softphone. The integration also enables SMS through your NetSapiens SMS integration.

• Credential control: In the customer-hosted model, your NetSapiens super-user credentials remain within your infrastructure. In the Acrobits-hosted model, you securely provide the required credentials to Acrobits so Acrobits can operate the script for you.
• 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.

Deployment Options

The NetSapiens Subscription Manager script can run either on customer-managed infrastructure or on Acrobits-managed infrastructure. Both deployment models provide the same messaging synchronization functionality.

Deployment model	When to choose it	Credential handling	Network access
Customer-hosted	Choose this if you want to operate the script inside your own infrastructure and keep NetSapiens super-user credentials within your environment.	NetSapiens super-user credentials are configured locally and are not shared with Acrobits.	The host running the script must be able to reach the primary core hostname and the Acrobits Messaging endpoint. api-us.messaging.acrobits.cz must be able to reach your primary core hostname.
Acrobits-hosted	Choose this if you prefer Acrobits to operate the script for you.	You must securely provide the required NetSapiens super-user credentials and configuration values to Acrobits.	Acrobits infrastructure and api-us.messaging.acrobits.cz must be able to reach your primary core hostname. Make sure all entries tagged App provisioning in the CloudSoftphone services IP allowlist are allowed, and that login.cloudsoftphone.com is accessible.

The setup steps below describe the customer-hosted deployment model. If you prefer Acrobits-hosted deployment, contact your Acrobits representative to arrange secure credential transfer and hosting.

Prerequisites

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

1. Primary core hostname: The NetSapiens primary core hostname, provided in URL form for the script (e.g., https://core1.my.ucaas.tech).
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.

Note

The script does not need to run on the servers hosting the NetSapiens core. It can run from any machine that can reach the primary core hostname and the Acrobits Messaging endpoint. For messaging synchronization, api-us.messaging.acrobits.cz must also be able to reach the primary core hostname.

Customer-Hosted Setup

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: Download the latest version of subscription_manager.py from the official GitHub repository and place it in /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 primary core hostname URL (with scheme, e.g., https://core1.my.ucaas.tech)
   # The variable name NS_API_HOST is retained from earlier versions; do not rename it.
   NS_API_HOST=your_primary_core_hostname_url
   
   # 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=NetSapiens Subscription Manager script for Cloud Softphone Linkup Messaging
   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 NetSapiens Subscription Manager script 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