Sync Client V2

Der Sync Client kann verwendet werden, um alle Aktualisierungen von Kontakten in eine SQL-Datenbank oder an einen Webservice zu übertragen.

Aktivierung

Um den Sync Client zu verwenden, aktivieren Sie den entsprechenden Connector in den Kampagneneinstellungen.
Nach erfolgreicher Aktivierung wird Ihnen ein Token unterhalb des Connectors angezeigt – dieses Token wird zum Verwenden des Clients benötigt.
Das Token ist nur für den Benutzer sichtbar, der den Connector aktiviert hat.

Wie man den dbsync2-Token erhält

Installation

Neueste Version des Binaries herunterladen

Quellcode herunterladen und kompilieren

Git installieren:

sudo apt-get install git

Google Go installieren:

sudo apt-get install golang-go

Stellen Sie für die nächsten Schritte sicher, dass die Umgebungsvariable GOPATH gesetzt ist.
Eine Anleitung zum Setzen der GOPATH-Variable finden Sie hier.

Repository klonen:

go get bitbucket.org/modima/dbsync2

Alle Abhängigkeiten installieren:

cd $GOPATH/src/bitbucket.org/modima/dbsync && godep restore

Quellcode kompilieren

  • Zielplattform Linux:
    cd $GOPATH/src/bitbucket.org/modima/dbsync2/ && go build
  • Zielplattform Windows:
    cd $GOPATH/src/bitbucket.org/modima/dbsync2/ && GOOS=windows GOARCH=amd64 go build -o dbsync2.exe
  • Zielplattform Mac:
    cd $GOPATH/src/bitbucket.org/modima/dbsync2/ && GOOS=darwin GOARCH=amd64 go build -o dbsync2_mac

Docker Compose Bereitstellung

Für Anwender, die eine containerisierte Bereitstellung bevorzugen, wird eine vorkonfigurierte docker-compose.yml bereitgestellt.
Diese Datei unterstützt alle Modi (PostgreSQL, MySQL/MariaDB, SQL Server und Webhook), sodass Sie dbsync2 ohne Anpassung des Quellcodes ausführen können – es genügt, eine einzelne .env-Datei zu aktualisieren.

Voraussetzungen

Konfiguration

Erstellen Sie eine .env-Datei im selben Verzeichnis wie Ihre docker-compose.yml mit folgendem Inhalt (passen Sie die Werte nach Bedarf an):

# Kampagneneinstellungen
CAMPAIGN_ID=my_campaign_id
CAMPAIGN_TOKEN=my_campaign_token

# PostgreSQL-Einstellungen
POSTGRES_DB=mydb
POSTGRES_USER=myuser
POSTGRES_PASSWORD=mypassword

# MySQL-Einstellungen
MYSQL_DB=mydb
MYSQL_USER=myuser
MYSQL_PASSWORD=mypassword
MYSQL_ROOT_PASSWORD=myrootpassword

# SQL Server-Einstellungen
SA_PASSWORD=YourStrong!Passw0rd
SQLSERVER_DB=mydb

# Webhook-Einstellungen
WEBHOOK_URL=https://example.com/api/transactions/

docker-compose.yml

Nachfolgend ein Beispiel für eine docker-compose.yml-Datei, die unser Docker-Hub-Image (dialfire/dbsync2:latest) verwendet und alle Verbindungsdaten aus der .env-Datei liest:

version: "3.8"

services:
  #############################
  # PostgreSQL Beispiel
  #############################
  postgres:
    image: postgres:16
    container_name: postgres_sync
    restart: unless-stopped
    environment:
      POSTGRES_DB: ${POSTGRES_DB:-mydb}
      POSTGRES_USER: ${POSTGRES_USER:-myuser}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mypassword}
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    ports:
      - "5432:5432"

  dbsync2_postgres:
    image: dialfire/dbsync2:latest
    container_name: dbsync2_postgres
    restart: unless-stopped
    depends_on:
      - postgres
    environment:
      CAMPAIGN_ID: ${CAMPAIGN_ID}
      CAMPAIGN_TOKEN: ${CAMPAIGN_TOKEN}
      POSTGRES_USER: ${POSTGRES_USER:-myuser}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:-mypassword}
      POSTGRES_DB: ${POSTGRES_DB:-mydb}
    command: >
      dbsync2 --a db_sync --c ${CAMPAIGN_ID} --ct ${CAMPAIGN_TOKEN} --url postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@postgres:5432/${POSTGRES_DB}?sslmode=disable

  #############################
  # MySQL/MariaDB Beispiel
  #############################
  mysql:
    image: mysql:8
    container_name: mysql_sync
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: ${MYSQL_DB:-mydb}
      MYSQL_USER: ${MYSQL_USER:-myuser}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-mypassword}
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD:-rootpassword}
    volumes:
      - ./data/mysql:/var/lib/mysql
    ports:
      - "3306:3306"

  dbsync2_mysql:
    image: dialfire/dbsync2:latest
    container_name: dbsync2_mysql
    restart: unless-stopped
    depends_on:
      - mysql
    environment:
      CAMPAIGN_ID: ${CAMPAIGN_ID}
      CAMPAIGN_TOKEN: ${CAMPAIGN_TOKEN}
      MYSQL_USER: ${MYSQL_USER:-myuser}
      MYSQL_PASSWORD: ${MYSQL_PASSWORD:-mypassword}
      MYSQL_DB: ${MYSQL_DB:-mydb}
    command: >
      dbsync2 --a db_sync --c ${CAMPAIGN_ID} --ct ${CAMPAIGN_TOKEN} --url mysql://${MYSQL_USER}:${MYSQL_PASSWORD}@mysql:3306/${MYSQL_DB}?useSSL=false

  #############################
  # SQL Server Beispiel
  #############################
  sqlserver:
    image: mcr.microsoft.com/mssql/server:2019-latest
    container_name: sqlserver_sync
    restart: unless-stopped
    environment:
      SA_PASSWORD: ${SA_PASSWORD:-YourStrong!Passw0rd}
      ACCEPT_EULA: "Y"
      MSSQL_PID: "Developer"
    ports:
      - "1433:1433"

  dbsync2_sqlserver:
    image: dialfire/dbsync2:latest
    container_name: dbsync2_sqlserver
    restart: unless-stopped
    depends_on:
      - sqlserver
    environment:
      CAMPAIGN_ID: ${CAMPAIGN_ID}
      CAMPAIGN_TOKEN: ${CAMPAIGN_TOKEN}
      SA_PASSWORD: ${SA_PASSWORD:-YourStrong!Passw0rd}
      SQLSERVER_DB: ${SQLSERVER_DB:-mydb}
    command: >
      dbsync2 --a db_sync --c ${CAMPAIGN_ID} --ct ${CAMPAIGN_TOKEN} --url sqlserver://sa:${SA_PASSWORD}@sqlserver:1433/${SQLSERVER_DB}

  #############################
  # Webhook Beispiel
  #############################
  dbsync2_webhook:
    image: dialfire/dbsync2:latest
    container_name: dbsync2_webhook
    restart: unless-stopped
    environment:
      CAMPAIGN_ID: ${CAMPAIGN_ID}
      CAMPAIGN_TOKEN: ${CAMPAIGN_TOKEN}
      WEBHOOK_URL: ${WEBHOOK_URL:-https://example.com/api/transactions/}
    command: >
      dbsync2 --a webhook --c ${CAMPAIGN_ID} --ct ${CAMPAIGN_TOKEN} --url ${WEBHOOK_URL}

networks:
  default: {}

Ausführen mit Docker Compose

Nachdem Ihre .env-Datei und die docker-compose.yml konfiguriert sind, führen Sie folgenden Befehl aus:

docker-compose up -d

Docker Compose lädt das vorkonfigurierte dialfire/dbsync2:latest-Image und startet alle Dienste gemäß Ihrer Konfiguration.

Funktionsweise

Alle Aktualisierungen der Kontakte werden jede Minute geladen und anschließend direkt an den konfigurierten Webservice oder die SQL-Datenbank übertragen (siehe Nutzung).

Nutzung

SQL-Datenbank

Der Client unterstützt die folgenden Datenbanksysteme:

  • MySQL / MariaDB
  • PostgreSQL
  • Microsoft SQL Server

Stellen Sie vor der Verwendung sicher, dass die entsprechende Datenbank bereits existiert. Der Client erstellt dann in dieser Datenbank die folgenden Tabellen:

  • contacts
    Enthält alle $-Felder sowie die ersten 100 benutzerdefinierten Felder der Kampagne.
  • transactions
    Enthält alle Transaktionen und den Fremdschlüssel contact_id, der auf den entsprechenden Kontakt verweist.
  • connections
    Enthält alle Verbindungen zu den Transaktionen, mit dem Fremdschlüssel transaction_id.
  • recordings
    Enthält alle Anrufaufzeichnungen, die mit Verbindungen verknüpft sind (Fremdschlüssel connection_id).
  • inbound_calls
    Enthält alle eingehenden Anrufe mit dem Fremdschlüssel contact_id.

Datenbank Tabellenstruktur

Datenbank-Verbindungs-URL Schema

MySQL / MariaDB:

mysql://username:password@localhost:3306/database?useSSL=false

PostgreSQL:

postgres://username:password@localhost:5432/database?sslmode=disable

Microsoft SQL Server:

sqlserver://username:password@localhost:1433/instance/database

Beispiel

Übertragen Sie alle Transaktionen ab dem 01. Februar 2018 in der Kampagne MY_CAMPAIGN auf eine lokal laufende Microsoft SQL Server-Instanz. Dabei sollen nur Aktualisierungen, die mit den Präfixen 'fc_' oder 'qc_' beginnen und von einem Benutzer durchgeführt wurden, übernommen werden:

dbsync2 --a db_sync --fm hi_updates_only --fp 'fc_,qc_' --c MY_CAMPAIGN_ID --ct MY_CAMPAIGN_TOKEN --s 2018-02-01 --url sqlserver://my_user:my_password@localhost:1433/my_database

Webservice

Alternativ können Transaktionen an einen Webservice weitergeleitet werden.
Der Webservice muss POST-Anfragen akzeptieren und bei erfolgreichem Empfang der Daten einen Statuscode zwischen 200 und 299 zurückgeben (ansonsten wird die Übertragung bis zu 10-mal wiederholt).

Die Nutzlast wird im JSON-Format gesendet:

{
    "contact": ...,      
    "transaction": ...,  
    "state": ...
}
  • contact: Enthält die Kontaktdaten.
  • transaction: Enthält die entsprechende Transaktion.
  • state:
    • new für eine neue Transaktion
    • updated wenn eine Transaktion aktualisiert wird (z. B. wenn Verbindungsdaten hinzugefügt werden).

Beispiel

Leiten Sie alle zukünftigen Transaktionen in der Kampagne MY_CAMPAIGN an einen Webservice weiter:

./dbsync2 --a webhook --c MY_CAMPAIGN_ID --ct MY_CAMPAIGN_TOKEN --url 'https://example.com/api/transactions/'

(Fehler-)Protokoll

  • Alle Fehlermeldungen werden direkt in der Konsole (stdout) ausgegeben.
  • Alle Logmeldungen werden geschrieben in:
    /var/log/dbsync/{MY_CAMPAIGN_ID}_{MODE}_{TIMESTAMP}.log
  • Falls das Verzeichnis /var/log/ nicht beschreibbar ist, erscheinen die Logs unter:
    $HOME/.dbsync/logs/{MY_CAMPAIGN_ID}_{MODE}_{TIMESTAMP}.log

Befehlszeilenoptionen

Eine Übersicht aller Optionen erhalten Sie, indem Sie folgenden Befehl ausführen:

dbsync2 --help