Selbst gehostete Exchange-Integration

Die Exchange-Synchronisierungs-App wird als Docker-Image bereitgestellt. In den folgenden Abschnitten wird erläutert, wie Sie das Gerät konfigurieren und bereitstellen.

Konfiguration

Da die Exchange-Synchronisierungs-App beim Start eine JSON-Konfigurationsdatei benötigen muss, wird in diesem Abschnitt der Inhalt der Datei erläutert. Anweisungen dazu, wie Sie die Konfigurationsdatei für die Exchange-Synchronisierungs-App verfügbar machen, finden Sie im Abschnitt Bereitstellung .

OAuth 2.0

Wenn Sie den Authentifizierungstyp OAuth 2.0 verwenden, können Sie die Graph-API oder die EWS-API verwenden. Beide ermöglichen Ihnen die Authentifizierung mit dem geheimen Clientschlüssel oder dem Clientzertifikat.

Der verwendete Flow für die Tokengewährung ist der Flow für die Client-Anmeldeinformationen.

Graph-API mit geheimem Clientschlüssel

{
  "microsoft_api": "graph",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_secret": "<client_secret>",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

Graph-API mit Clientzertifikat

{
  "microsoft_api": "graph",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_credential_private_key": "<private_key>",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

EWS-API mit geheimem Clientschlüssel

{
  "ews_endpoint": "https://outlook.office365.com/EWS/Exchange.asmx",
  "auth_type": "oauth2",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_secret": "<client_secret>",
  "access_type": "impersonation",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

EWS-API mit Clientzertifikat

{
  "ews_endpoint": "https://outlook.office365.com/EWS/Exchange.asmx",
  "auth_type": "oauth2",
  "auth_oauth_authority": "https://login.microsoftonline.com/<tenant_id>/",
  "auth_oauth_client_id": "<client_id>",
  "auth_oauth_client_credential_private_key": "<private_key>",
  "auth_oauth_client_credential_thumbprint": "<thumbprint>",
  "access_type": "impersonation",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

NTLM

Wenn Sie die NTLM-Authentifizierung verwenden, kann sie nur mit EWS-API verwendet werden.

{
  "host": "https://exchange-server.example.com",
  "port": 443,
  "auth_type": "ntlm",
  "auth_user": "[e-mail]",
  "access_type": "delegate",
  "mailboxes": {
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    },
    "[e-mail]": {
      "bucket": {
        "owner": "project-name",
        "name": "bucket-name"
      },
      "start_from": "bucket",
      "start_timestamp": "2020-01-01T00:00:00+00:00"
    }
  }
}

Ersetzen Sie zunächst die Dummy-Werte in host, port und auth_user durch ihre echten Werte und ändern Sie bei Bedarf access_type . Eine Beschreibung dieser Parameter und ihrer zulässigen Werte finden Sie in der Konfigurationsreferenz.

Geben Sie dann das Dienstbenutzerkennwort für die Exchange-Synchronisierungs-App als REINFER_EWS_AUTH_PASS -Umgebungsvariable an. Weitere Informationen finden Sie im Abschnitt Bereitstellung .

Im Folgenden finden Sie eine vollständige Liste der Umgebungsvariablen, die Sie zum Überschreiben von Werten in der Konfiguration festlegen können:

Name	BESCHREIBUNG
REINFER_EWS_AUTH_USER	Exchange-Serverbenutzer
REINFER_EWS_AUTH_PASS	Kennwort für Exchange-Server
REINFER_EWS_ACCESS_TYPE	Zugriffstyp: „Delegieren“ oder „Identitätswechsel“
REINFER_EWS_HOST	Exchange-Serverhost
REINFER_EWS_PORT	Exchange-Serverport

Postfachkonfiguration

Sie können ein oder mehrere Postfächer in Ihrer Konfiguration angeben. Für jedes Postfach müssen Sie die Postfachadresse angeben und die folgenden Parameter angeben:

Name	BESCHREIBUNG
bucket.owner	Projekt des Buckets, in dem das Postfach synchronisiert werden soll.
bucket.name	Name des Buckets, in dem das Postfach synchronisiert werden soll.
start_from	Ob ab dem letzten synchronisierten Zeitpunkt („bucket“) gestartet oder die letzte synchronisierte Zeit ignoriert und immer bei start_timestamp gestartet werden soll („config“). Sollte für normalen Betrieb auf „bucket“ festgelegt werden, beim Debuggen kann jedoch in einigen Fällen „config“ nützlich sein.
start_timestamp	Zeitstempel, ab dem die Synchronisierung der E-Mails gestartet werden soll. Wird diese Option nicht festgelegt, werden alle E-Mails synchronisiert.

Die Konfiguration verwendet die Standardwerte für eine Reihe von Einstellungen wie Abrufhäufigkeit oder Batchgröße. Informationen zur weiteren Anpassung Ihrer Konfiguration finden Sie in der Konfigurationsreferenz.

Buckets

Die Exchange-Integration synchronisiert rohe E-Mail-Daten mit Communications Mining™-Buckets. Wie andere Communications Mining-Ressourcen wird in einem Projekt ein Bucket erstellt, mit dem Sie den Zugriff auf den Bucket steuern können.

Hinweis:

Um aus einem Bucket zu lesen, in ein Bucket hochzuladen oder Buckets zu verwalten, müssen Sie die entsprechenden Berechtigungen im Projekt zugewiesen haben, in dem sich der Bucket befindet.

Bereitstellung

Sie können die Exchange-Synchronisierungs-App entweder mit Kubernetes oder mit Docker bereitstellen.

Die Bereitstellung mit Kubernetes ermöglicht es Ihnen, mehrere Instanzen der Exchange Sync App auszuführen, wobei jede Instanz eine Teilmenge der zu synchronisierenden Postfächer verarbeitet.

Mit Kubernetes

Die Verwendung von Kubernetes ist eine gängige Methode zum Ausführen und Verwalten von Containeranwendungen. In diesem Abschnitt wird erläutert, wie Sie die Exchange Sync App mithilfe von Kubernetes bereitstellen.

Anforderungen

• grundlegende Kubernetes-Kenntnisse. Um mit Kubernetes zu beginnen, finden Sie unter In Kubernetes bereitstellen.
• kubectl installiert haben.

kind: StatefulSet
metadata:
  name: uipath-exchange-sync-app
  labels:
    app: uipath-exchange-sync-app
spec:
  podManagementPolicy: Parallel
  replicas: 1
  selector:
    matchLabels:
      app: uipath-exchange-sync-app
  serviceName: uipath-exchange-sync-app
  template:
    metadata:
      labels:
        app: uipath-exchange-sync-app
      name: uipath-exchange-sync-app
    spec:
      containers:
        - args:
            - "uipath-exchange-sync-app"
            - "--bind"
            - "0.0.0.0:8000"
            - "--reinfer-api-endpoint"
            - "https://cloud.uipath.com/<org>/<tenant>/reinfer_/api/"
            - "--shard-name"
            - "$(POD_NAME)"
            # This value should match `spec.replicas` above
            - "--total-shards"
            - "1"
          env:
            - name: REINFER_EWS_CONFIG
              value: "/mnt/config/example_exchange_sync_config"
            - name: REINFER_API_TOKEN
              valueFrom:
                secretKeyRef:
                  key: reinfer-api-token
                  name: reinfer-credentials
            # Only needed when using EWS API
            - name: REINFER_EWS_AUTH_PASS
              valueFrom:
                secretKeyRef:
                  key: ews-auth-pass
                  name: reinfer-credentials
            - name: POD_NAME
              valueFrom:
                fieldRef:
                  fieldPath: metadata.name
          image: "your.private.registry.com/reinfer/ews:TAG"
          name: uipath-exchange-sync-app
          resources:
            requests:
              cpu: 0.05
              memory: 128Mi
          volumeMounts:
            - mountPath: /mnt/config
              name: config-vol
      volumes:
        - configMap:
            name: exchange-sync-config
            items:
              - key: example_exchange_sync_config
                path: example_exchange_sync_config
          name: config-vol

Bevor Sie die Exchange-Synchronisierungs-App mit dieser YAML-Datei bereitstellen können, müssen Sie einige zusätzliche Schritte durchführen:

1. Ersetzen Sie cloud.uipath.com/<org>/<tenant>/reinfer_ durch Ihren Mandanten-API-Endpunkt.
2. Erstellen Sie die Geheimnisse wie folgt:

   kubectl create secret generic reinfer-credentials \
     --from-literal=reinfer-api-token=<REINFER_TOKEN> \
     --from-literal=ews-auth-pass=<MSEXCHANGE_PASSWORD>
   

   Hinweis:

   • Um zu vermeiden, dass Anmeldeinformationen als Klartext in unserer YAML-Datei gespeichert werden, werden die Umgebungsvariablen REINFER_TOKEN und REINFER_EWS_AUTH_PASS mit Kubernetes-Geheimnissen aufgefüllt.
   • Das Geheimnis ews-auth-pass wird nur benötigt, wenn die EWS-API verwendet wird.
3. Um die Gerätekonfiguration aus einer lokalen Datei zu laden, hängen Sie diese Datei in den Pod ein, indem Sie die Daten in einer Kubernetes ConfigMap speichern und die ConfigMap als Volume einbinden.
4. Erstellen Sie die ConfigMap wie folgt:

   kubectl create configmap exchange-sync-config \
     --from-file=example_exchange_sync_config=your-exchange-sync-config.json
   

   Hinweis:

   Als Alternative zum lokalen Speichern der Konfigurationsdatei können Sie sie in Communications Mining hochladen und von der Exchange-Synchronisierungs-App über die Communications Mining-API abrufen lassen. Dies wird bei der Speicherkonfiguration in Communications Mining beschrieben. Wenn sowohl lokale als auch Remote-Konfigurationsdateien angegeben sind, verwendet das Gerät die lokale Konfigurationsdatei.

Sie können jetzt Ihren StatefulSet erstellen und überprüfen, ob alles über Folgendes läuft:

kubectl apply -f uipath-exchange-sync.yaml
kubectl get sts

Mit Docker

Alternativ können Sie die Exchange-Synchronisierungs-App in Docker ausführen. Der folgende Befehl startet das Gerät mit denselben Parametern, die im Abschnitt Kubernetes verwendet werden:

EWS_CONFIG_DIR="location_of_your_self-hosted_appliance_config_directory"
REINFER_API_TOKEN="YOUR API TOKEN"
TAG=latest

sudo docker run \
  -v $EWS_CONFIG_DIR:/mnt/config \
  --env REINFER_EWS_CONFIG=/mnt/config/config.json \
  --env REINFER_API_TOKEN=$REINFER_API_TOKEN \
  eu.gcr.io/reinfer-gcr/ews:$TAG reinfer-ews \
  --reinfer-api-endpoint https://cloud.uipath.com/YourOrganizationName/TenantName/reinfer_/api \
  &> ews_$(date -Iseconds).log

• Ersetzen Sie cloud.uipath.com/<org>/<tenant>/reinfer_ durch Ihren Mandanten-API-Endpunkt.
• Ersetzen Sie your_exchange_sync_config.json durch den Namen Ihrer JSON-Datei zur Exchange Sync App-Konfiguration.

Die Exchange Sync App wird kontinuierlich ausgeführt und synchronisiert E-Mails mit der Communications Mining-Plattform. Wenn Sie sie anhalten und erneut starten, wird der zuletzt gespeicherte Bucket-Synchronisierungsstatus übernommen.

Mit Docker (lokaler Speicher)

Die Exchange Sync-App kann extrahierte E-Mails lokal speichern, anstatt sie über Folgendes in die Communications Mining™-Plattform zu schieben:

EWS_LOCAL_DIR=
CONFIG_OWNER=
CONFIG_KEY=
TAG=

sudo docker run \
  -v $EWS_LOCAL_DIR:/mnt/ews \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --local-files-prefix /mnt/ews \
  --remote-config-owner $CONFIG_OWNER --remote-config-key $CONFIG_KEY \
  &> ews_$(date -Iseconds).log

Überblick

• Die Exchange Sync App erwartet, die Konfiguration in $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json zu finden. Alternativ können Sie den Pfad zur Konfiguration angeben, indem Sie die Umgebungsvariable $REINFER_EWS_CONFIG festlegen, wie im vorherigen Beispiel gezeigt.
• Die Exchange-Synchronisierungs-App speichert den Synchronisierungsstatus unter $EWS_LOCAL_DIR/state. Wenn Sie sie anhalten und erneut starten, wird der zuletzt gespeicherte Synchronisierungsstatus wieder aufgenommen.
• Die Exchange Sync App speichert Daten in $EWS_LOCAL_DIR/data.

Mit Docker (Azure Blob Storage)

Die Exchange Sync-App kann extrahierte E-Mails in Azure Blob Storage speichern, anstatt sie über Folgendes in die Communications Mining™-Plattform zu schieben:

EWS_CONFIG_DIR=
AZ_STORAGE_ACCOUNT_NAME=
AZ_CONTAINER_NAME=
TAG=

sudo docker run \
  -v $EWS_CONFIG_DIR:/mnt/config \
  --env REINFER_EWS_CONFIG=/mnt/config/your_exchange_sync_config.json \
  eu.gcr.io/reinfer-gcr/ews:$TAG \
  --private-file-prefix az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME \
  &> ews_$(date -Iseconds).log

Überblick

• Sie müssen den Pfad zur Konfiguration angeben, indem Sie die Umgebungsvariable $REINFER_EWS_CONFIG festlegen.
• Die Exchange-Synchronisierungs-App authentifiziert sich bei Azure Blob Storage mithilfe einer der DefaultAzureCredential-Methoden. Stellen Sie sicher, dass Sie eine für Sie geeignete Methode verwenden. Stellen Sie unabhängig von der verwendeten Methode sicher, dass Sie der Exchange Sync-App die Rolle Storage Blob Data Contributor gewähren.
• Die Exchange-Synchronisierungs-App speichert den Synchronisierungsstatus unter az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. Wenn Sie sie anhalten und erneut starten, wird der zuletzt gespeicherte Synchronisierungsstatus wieder aufgenommen.
• Die Exchange Sync App speichert Daten in az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/data.

Speicherkonfiguration in Communications Mining

Anstatt dem Gerät eine lokale Konfigurationsdatei zur Verfügung zu stellen, wie Sie es getan haben, wenn Sie dem Bereitstellungsleitfaden für die Exchange-Synchronisierung gefolgt sind , können Sie stattdessen die Konfigurationsdatei in Communications Mining™ verwalten.

Hinweis:

Wenn sowohl lokale als auch Remote-Konfigurationsdateien angegeben sind, verwendet das Gerät standardmäßig die lokale Konfigurationsdatei.

Laden Sie zuerst Ihre JSON-Konfigurationsdatei in Communications Mining hoch:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'file=@your_exchange_sync_config.json' \
  -XPUT https://cloud.uipath.com/<org>/<tenant>/reinfer_/api/v1/appliance-configs/<project-name>/<config-name>

So zeigen Sie die aktuelle Konfiguration an:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -XGET https://cloud.uipath.com/<org>/<tenant>/reinfer_/api/v1/appliance-configs/<project-name>/<config-name>

Legen Sie dann in der Kubernetes-YAML-Datei den Parameter --remote-config-owner auf den Projektnamen und den Parameter --remote-config-key auf den Konfigurationsnamen fest.

Referenz (Reference)

Anwendungsparameter

Die folgende Tabelle enthält eine Liste der verfügbaren Anwendungsparameter. Weitere Informationen zum Ausführen der Exchange-Synchronisierungs-App finden Sie im Abschnitt Bereitstellung .

Parameter	Beschreibung
--reinfer-api-endpoint	Endpunkt zum Herstellen einer Verbindung mit der Refer-API. Sich gegenseitig ausschließen mit --local-files-prefix .
--local-files-prefix	Pfad zum Speichern synchronisierter E-Mails und Bucket-Synchronisierungsstatus. Sich gegenseitig ausschließen mit --reinfer-api-endpoint und REINFER_API_TOKEN .
--remote-config-owner	Projekt, das die Remote-Konfigurationsdatei der Exchange-Synchronisierung besitzt.
--remote-config-key	Name der Remote-Konfigurationsdatei der Exchange-Synchronisierung .
--debug-level	Debug-Ebene, auf welcher: 0 bedeutet kein Debuggen. 1 bedeutet Dienst-Debug. 2 bedeutet vollständiges Debuggen. Der Standardwert ist 1.
--shard-name	Shard-Name, der uipath-exchange-sync-app-N ist, aus dem die Shard-Nummer extrahiert werden soll. Wenn Sie in Kubernetes ausgeführt werden, können Sie dies auf den Pod-Namen festlegen.
--total-shards	Die Gesamtanzahl der Instanzen im Gerätecluster. Bei der Ausführung in Kubernetes muss der Parameter auf den gleichen Wert wie die Anzahl der Instanzen im StatefulSet festgelegt werden.
--restart-on-unrecoverable-errors	Wenn diese Option aktiviert ist, führen nicht behebbare Fehler dazu, dass der gesamte Dienst neu gestartet wird, ohne abzustürzen.

Konfigurationsparameter

Die folgende Tabelle enthält eine Liste der verfügbaren Konfigurationsparameter. Weitere Informationen zum Schreiben der Exchange Sync-App-Konfigurationsdatei finden Sie im Abschnitt Konfiguration .

Name	Beschreibung
host	Wird nur mit EWS-API verwendet. Exchange-Server-Host. Kann durch die Umgebungsvariable REINFER_EWS_HOST überschrieben werden.
port	Wird nur mit EWS-API verwendet. Exchange-Serverport. Der Standardwert ist 80. Sie können dies mit der Umgebungsvariablen REINFER_EWS_PORT überschreiben.
auth_type	Wird nur mit EWS-API verwendet. Nur ntlm ist zulässig.
auth_user	Wird nur mit EWS-API verwendet. Exchange-Serverbenutzer. Sie können dies mit der Umgebungsvariablen REINFER_EWS_AUTH_USER überschreiben.
auth_password	Wird nur mit EWS-API verwendet. Kennwort des Exchange-Servers. Sie können dies mit der Umgebungsvariablen REINFER_EWS_AUTH_PASS überschreiben.
access_type	Wird nur mit EWS-API verwendet. Der Zugriffstyp kann delegate oder impersonation sein. Der Standardwert ist delegate. Sie können dies mit der Umgebungsvariablen REINFER_EWS_ACCESS_TYPE überschreiben.
ews_ssl_verify	Wird nur mit EWS-API verwendet. Wenn sie auf false festgelegt wird, werden keine Zertifikate überprüft. Der Standardwert ist true.
poll_frequency	Die Wartezeit zwischen Batches in Sekunden. Der Standardwert ist 15.
poll_message_sleep	Die Wartezeit zwischen einzelnen E-Mails in einem Batch in Sekunden. Der Standardwert ist 0.1.
max_concurrent_uploads	Anzahl der gleichzeitigen Uploads in Communications Mining zwischen 0 und 32. Der Standardwert ist 8.
emails_per_folder	Maximale Anzahl der E-Mails, die aus jedem Ordner pro Batch abgerufen werden sollen, zwischen 1 und 100.000. Der Standardwert ist 2520. Diese Einstellung ermöglicht es der Exchange Sync App, bei einem sehr großen Ordner alle Ordner gleichmäßig zu verbessern.
reinfer_batch_size	Wie viele E-Mails pro Batch abgerufen werden sollen, zwischen 1 und 1000. Der Standardwert ist 80.
mailboxes	Liste der abzurufenden Postfächer. Weitere Informationen zum Konfigurieren der Postfächer finden Sie im Abschnitt Konfiguration .
audit_email	Wenn Sie das Gerät mit einer Remote-Konfiguration konfiguriert haben, sendet Communications Mining eine E-Mail an diese Adresse, wenn die Konfiguration aktualisiert wird. Der Standardwert ist None.
ews_ssl_ciphers	Wird nur mit der EWS-API verwendet. Lassen Sie die Exchange-Synchronisierungs-App bestimmte Verschlüsselungen verwenden. Die Verschlüsselungen müssen eine Zeichenfolge im OpenSSL-Verschlüsselungslistenformat sein. Der Standardwert ist None.