Integración de Exchange autohospedado

La aplicación Exchange Sync se entrega como una imagen de Docker. Las siguientes secciones explican cómo configurar e implementar el dispositivo.

Configuración

Dado que la aplicación Exchange Sync requiere la presencia de un archivo de configuración JSON al inicio, esta sección explica el contenido del archivo. Consulta la sección Implementación para obtener instrucciones sobre cómo hacer que el archivo de configuración esté disponible para la aplicación Exchange Sync.

OAuth 2.0

Si utilizas el tipo de autenticación OAuth 2.0, puedes utilizar la API de Graph o la API de EWS. Ambos te permiten autenticarte con el secreto del cliente o con el certificado del cliente.

El flujo de concesión de tokens utilizado es el flujo de credenciales de cliente.

API Graph con secreto de cliente

{
  "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"
    }
  }
}

API Graph con certificado de cliente

{
  "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"
    }
  }
}

API de EWS con secreto de cliente

{
  "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"
    }
  }
}

API de EWS con certificado de cliente

{
  "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

Si utilizas la autenticación NTLM, solo se puede utilizar con la API de EWS.

{
  "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"
    }
  }
}

Primero, reemplaza los valores ficticios en host, port y auth_user con sus valores reales, y cambia access_type si es necesario. Para obtener una descripción de estos parámetros y sus valores permitidos, consulta la referencia de configuración.

A continuación, proporciona la contraseña de usuario del servicio a la aplicación Exchange Sync como una variable de entorno REINFER_EWS_AUTH_PASS . Para obtener más información, consulta la sección Implementación .

La lista completa de variables de entorno que puedes establecer para anular valores en la configuración es la siguiente:

Nombre	Descripción
REINFER_EWS_AUTH_USER	Usuario del servidor de Exchange
REINFER_EWS_AUTH_PASS	Contraseña del servidor de Exchange
REINFER_EWS_ACCESS_TYPE	Tipo de acceso: "delegado" o "suplantación"
REINFER_EWS_HOST	Host del servidor de Exchange
REINFER_EWS_PORT	Puerto del servidor de Exchange

Configuración del buzón

Puedes especificar uno o más buzones en tu configuración. Para cada buzón, debes proporcionar la dirección del buzón y especificar los siguientes parámetros:

Nombre	Descripción
bucket.owner	Proyecto del depósito en el que se debe sincronizar el buzón.
bucket.name	Nombre del depósito en el que se debe sincronizar el buzón.
start_from	Si se debe comenzar desde la última hora sincronizada ("depósito") o ignorar la última hora sincronizada y comenzar siempre desde start_timestamp ("config"). Debe establecerse en "depósito" para el funcionamiento normal, pero "config" puede ser útil en algunos casos al depurar.
start_timestamp	Marca de tiempo desde la que iniciar la sincronización del correo electrónico. Si no se establece, se sincronizarán todos los correos electrónicos.

La configuración utiliza los valores predeterminados para una serie de ajustes, como la frecuencia de sondeo o el tamaño del lote. Para personalizar aún más tu configuración, consulta la referencia de configuración.

Depósitos

La integración de Exchange sincroniza los datos de correo electrónico sin procesar en depósitos de Communications Mining™. Al igual que otros recursos de Communications Mining, se crea un depósito en un proyecto, lo que te permite controlar el acceso al depósito.

Nota: para leer desde un depósito, cargar en un depósito o gestionar depósitos, debes tener asignados los permisos respectivos en el proyecto en el que se encuentra el depósito.

Implementación

Puedes implementar la aplicación Exchange Sync con Kubernetes o con Docker.

La implementación con Kubernetes te permite ejecutar varias instancias de la aplicación Exchange Sync, y cada instancia gestiona un subconjunto de buzones de correo que se sincronizarán.

Con Kubernetes

El uso de Kubernetes es una forma popular de ejecutar y gestionar aplicaciones en contenedores. Esta sección explica cómo implementar la aplicación Exchange Sync utilizando Kubernetes.

Requisitos

• Conocimientos básicos de Kubernetes. Para empezar a utilizar Kubernetes, consulta Implementar en Kubernetes.
• tener kubectl instalado.

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://<mydomain>.reinfer.io/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

Antes de poder implementar la aplicación Exchange Sync utilizando este archivo YAML, hay algunos pasos adicionales que debes realizar:

1. Sustituye <mydomain>.reinfer.io por el punto de conexión de la API de tu tenant.
2. Crea los secretos de la siguiente manera:

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

   Nota:

   • Para evitar almacenar las credenciales como texto no cifrado en nuestro archivo YAML, las variables de entorno REINFER_TOKEN y REINFER_EWS_AUTH_PASS se rellenan a partir de los secretos de Kubernetes.
   • El secreto ews-auth-pass solo es necesario cuando se utiliza la API de EWS.
3. Para cargar la configuración del dispositivo desde un archivo local, monta ese archivo en el pod almacenando los datos en un ConfigMap de Kubernetes y montando el ConfigMap como un volumen.
4. Crea el ConfigMap de la siguiente manera:

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

   Nota: como alternativa al almacenamiento local del archivo de configuración, puedes cargarlo en Communications Mining y dejar que la aplicación Exchange Sync lo obtenga a través de la API de Communications Mining. Esto se describe en la configuración del almacén en Communications Mining. Si se especifican los archivos de configuración locales y remotos, el dispositivo utiliza el archivo de configuración local.

Ahora puedes crear tu StatefulSet y comprobar que todo se está ejecutando de la siguiente manera:

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

Con Docker

Como alternativa, puedes ejecutar la aplicación Exchange Sync en Docker. El siguiente comando inicia el dispositivo con los mismos parámetros que se utilizan en la sección Kubernetes :

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

• Sustituye <mydomain>.reinfer.io por el punto de conexión de la API de tu tenant.
• Sustituye your_exchange_sync_config.json por el nombre de tu archivo JSON de configuración de la aplicación de sincronización de Exchange.

La aplicación Exchange Sync se ejecuta continuamente sincronizando correos electrónicos en la plataforma Communications Mining. Si lo detienes y lo vuelves a iniciar, se reanuda desde el último estado de sincronización del depósito almacenado.

Con Docker (almacenamiento local)

La aplicación Exchange Sync puede guardar los correos electrónicos extraídos localmente en lugar de enviarlos a la plataforma Communications Mining™ a través de lo siguiente:

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

Información general

• La aplicación Exchange Sync espera encontrar la configuración en $EWS_LOCAL_DIR/config/$CONFIG_OWNER/$CONFIG_KEY.json. Como alternativa, puedes proporcionar la ruta a la configuración estableciendo la variable de entorno $REINFER_EWS_CONFIG como se muestra en el ejemplo anterior.
• La aplicación Exchange Sync guarda el estado de sincronización en $EWS_LOCAL_DIR/state. Si lo detienes y lo vuelves a iniciar, se reanuda desde el último estado de sincronización almacenado.
• La aplicación Exchange Sync guarda los datos en $EWS_LOCAL_DIR/data.

Con Docker (Azure Blob Storage)

La aplicación Exchange Sync puede guardar los correos electrónicos extraídos en Azure Blob Storage en lugar de enviarlos a la plataforma Communications Mining™ a través de lo siguiente:

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

Información general

• Debes proporcionar la ruta a la configuración estableciendo la variable de entorno $REINFER_EWS_CONFIG .
• La aplicación Exchange Sync se autentica en Azure Blob Storage utilizando uno de los métodos DefaultAzureCredential. Asegúrese de utilizar un método que sea conveniente para usted. Independientemente del método utilizado, asegúrate de otorgar el rol Colaborador de datos de Storage Blob a la aplicación Exchange Sync.
• La aplicación Exchange Sync guarda el estado de sincronización en az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/state. Si lo detienes y lo vuelves a iniciar, se reanuda desde el último estado de sincronización almacenado.
• La aplicación Exchange Sync guarda los datos en az://$AZ_STORAGE_ACCOUNT_NAME/$AZ_CONTAINER_NAME/data.

Almacenar la configuración en Communications Mining

En lugar de proporcionar un archivo de configuración local al dispositivo como hacías si seguías la guía de implementación de la aplicación Exchange Sync, puedes gestionar el archivo de configuración en Communications Mining™. Ten en cuenta que si se especifican los archivos de configuración locales y remotos, el dispositivo utilizará de forma predeterminada el archivo de configuración local.

Primero, sube tu archivo de configuración JSON a Communications Mining:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -H "Content-Type: multipart/form-data" \
  -F 'file=@your_exchange_sync_config.json' \
  -XPUT https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

Para ver la configuración actual:

curl -H "Authorization: Bearer $REINFER_TOKEN" \
  -XGET https://<mydomain>.reinfer.io/api/v1/appliance-configs/<project-name>/<config-name>

A continuación, en el archivo YAML de Kubernetes, establece el parámetro --remote-config-owner en el nombre del proyecto y el parámetro --remote-config-key en el nombre de la configuración.

Referencia

Parámetros de la aplicación

La siguiente tabla contiene una lista de parámetros de aplicación disponibles. Para obtener más información sobre la ejecución de la aplicación Exchange Sync, consulta la sección Implementación .

Parámetro	Descripción
--reinfer-api-endpoint	Punto final para conectarse a la API Reinferir. Mutuamente excluyente con --local-files-prefix.
--local-files-prefix	Ruta para almacenar los correos electrónicos sincronizados y el estado de sincronización del depósito. Mutuamente excluyente con --reinfer-api-endpoint y REINFER_API_TOKEN.
--remote-config-owner	Proyecto que posee el archivo de configuración de la aplicación Exchange Sync remota.
--remote-config-key	Nombre del archivo de configuración de la aplicación Exchange Sync remota.
--debug-level	Nivel de depuración, donde: 0 significa que no hay depuración. 1 significa depuración del servicio. 2 significa depuración completa. El valor predeterminado es 1.
--shard-name	Nombre del fragmento, que es uipath-exchange-sync-app-N, del que extraer el número del fragmento. Cuando se ejecuta en Kubernetes, puedes establecerlo en el nombre del pod.
--total-shards	El número total de instancias en el clúster de dispositivos. Cuando se ejecuta en Kubernetes, el parámetro debe establecerse en el mismo valor que el número de instancias en StatefulSet.
--restart-on-unrecoverable-errors	Si se habilita, los fallos irrecuperables harán que todo el servicio se reinicie sin bloquearse.

Parámetros de configuración

La siguiente tabla muestra una lista de los parámetros de configuración disponibles. Para obtener más información sobre cómo escribir el archivo de configuración de la aplicación Exchange Sync, consulta la sección Configuración .

Nombre	Descripción
host	Solo se utiliza con la API de EWS. Host del servidor de Exchange. Puede ser anulado por la variable de entorno REINFER_EWS_HOST .
port	Solo se utiliza con la API de EWS. Puerto del servidor de Exchange. El valor predeterminado es 80. Puedes anularlo con la variable de entorno REINFER_EWS_PORT .
auth_type	Solo se utiliza con la API de EWS. Solo se permite ntlm .
auth_user	Solo se utiliza con la API de EWS. Usuario del servidor de Exchange. Puedes anularlo con la variable de entorno REINFER_EWS_AUTH_USER .
auth_password	Solo se utiliza con la API de EWS. Contraseña del servidor de Exchange. Puedes anularlo con la variable de entorno REINFER_EWS_AUTH_PASS .
access_type	Solo se utiliza con la API de EWS. El tipo de acceso puede ser delegate o impersonation. El valor predeterminado es delegate. Puedes anularlo con la variable de entorno REINFER_EWS_ACCESS_TYPE .
ews_ssl_verify	Solo se utiliza con la API de EWS. Si se establece en false, no verificará los certificados. El valor predeterminado es true.
poll_frequency	El tiempo de espera entre lotes, en segundos. El valor predeterminado es 15.
poll_message_sleep	El tiempo de espera entre correos electrónicos individuales en un lote, en segundos. El valor predeterminado es 0.1.
max_concurrent_uploads	Número de cargas simultáneas en Communications Mining, entre 0 y 32. El valor predeterminado es 8.
emails_per_folder	Número máximo de correos electrónicos a recuperar de cada carpeta por lote, entre 1 y 100 000. El valor predeterminado es 2520. Esta configuración permite que la aplicación Exchange Sync progrese en todas las carpetas de manera uniforme en caso de que haya una carpeta muy grande.
reinfer_batch_size	Cuántos correos electrónicos recuperar por lote, entre 1 y 1000. El valor predeterminado es 80.
mailboxes	Lista de buzones de correo a recuperar. Para obtener más detalles sobre cómo configurar los buzones, consulta la sección Configuración .
audit_email	Si ha configurado el dispositivo con una configuración remota, Communications Mining envía un correo electrónico a esta dirección cada vez que se actualiza la configuración. El valor predeterminado es None.
ews_ssl_ciphers	Solo se utiliza con la API de EWS. Hacer que la aplicación Exchange Sync utilice cifrados específicos. Los cifrados deben ser una cadena en el formato de lista de cifrado OpenSSL. El valor predeterminado es None.