Snowflake (Sincronización de datos)

Prisma Campaigns puede integrarse con Snowflake para que las instituciones financieras que mantienen sus datos centrales en un data warehouse de Snowflake puedan sincronizarlos directamente, sin necesidad de desplegar un agente, una capa de middleware ni un servidor SFTP.

Descripción general

Dos procedimientos almacenados de Snowpark Python invocan el API REST de DataSync de Prisma Campaigns: SEND_TO_PRISMA envía una tabla de Snowflake hacia un data sync de importación, y GET_FROM_PRISMA descarga la última exportación hacia una tabla de Snowflake. Usted configura el lado de Snowflake; su representante de Prisma Campaigns configura el esquema de clientes y los mapeos de columnas, y luego le entrega el ID de data sync y el API token que cada procedimiento necesita.

Complete los pasos siguientes con su equipo de Snowflake / ingeniería de datos. En paralelo, coordine con su representante de Prisma Campaigns para que los data syncs y las credenciales estén listos antes de probar los procedimientos.

Configurar el acceso de red en Snowflake

Snowflake bloquea todo el acceso de red externo de forma predeterminada, por lo que los procedimientos almacenados no podrán comunicarse con Prisma Campaigns hasta que usted cree una regla de red y una integración de acceso externo. Esto requiere el rol ACCOUNTADMIN (o un rol al que se le haya otorgado CREATE INTEGRATION).

1. Cree una regla de red que permita el tráfico de salida hacia su instancia de Prisma Campaigns, reemplazando el dominio a continuación por el suyo. Puede incluir más de un host, por ejemplo un sandbox y una instancia de producción:

   USE ROLE ACCOUNTADMIN;
   
   CREATE OR REPLACE NETWORK RULE PRISMACUSTOMERS.PUBLIC.PRISMA_NETWORK_RULE
     MODE = EGRESS
     TYPE = HOST_PORT
     VALUE_LIST = ('yourinstitution.prismacampaigns.com:443');
   

2. Cree una integración de acceso externo llamada HTTP_EXT_INT. Ambos procedimientos almacenados hacen referencia a este nombre exacto en su cláusula EXTERNAL_ACCESS_INTEGRATIONS, por lo que si utiliza un nombre distinto deberá actualizar la definición de los procedimientos en consecuencia:

   CREATE OR REPLACE EXTERNAL ACCESS INTEGRATION HTTP_EXT_INT
     ALLOWED_NETWORK_RULES = (PRISMACUSTOMERS.PUBLIC.PRISMA_NETWORK_RULE)
     ENABLED = TRUE;
   
   GRANT USAGE ON INTEGRATION HTTP_EXT_INT TO ROLE DATA_ENGINEER;
   

Crear los procedimientos almacenados

1. Otorgue al rol que realizará el despliegue el permiso para crear procedimientos en la base de datos y el esquema de destino. Los ejemplos de esta guía utilizan PRISMACUSTOMERS.PUBLIC:

   GRANT USAGE ON DATABASE PRISMACUSTOMERS TO ROLE DATA_ENGINEER;
   GRANT USAGE, CREATE PROCEDURE ON SCHEMA PRISMACUSTOMERS.PUBLIC TO ROLE DATA_ENGINEER;
   

2. Antes de crear los procedimientos, confirme que su cuenta haya aceptado los términos de Anaconda en Admin → Billing & Terms → Anaconda. Los procedimientos se ejecutan sobre Python 3.9 con los paquetes snowflake-snowpark-python, requests y pandas del canal de Anaconda de Snowflake.

3. Solicite a su representante de Prisma Campaigns las sentencias CREATE OR REPLACE PROCEDURE de SEND_TO_PRISMA y GET_FROM_PRISMA, y ejecútelas sobre esa base de datos y ese esquema.

4. Otorgue permiso de ejecución al rol que utilizará la sincronización:

   GRANT USAGE ON PROCEDURE PRISMACUSTOMERS.PUBLIC.SEND_TO_PRISMA(
     VARCHAR, VARCHAR, NUMBER, VARCHAR, VARCHAR, VARCHAR) TO ROLE MARKETING_OPS;
   
   GRANT USAGE ON PROCEDURE PRISMACUSTOMERS.PUBLIC.GET_FROM_PRISMA(
     VARCHAR, VARCHAR, NUMBER, VARCHAR, VARCHAR, VARCHAR) TO ROLE MARKETING_OPS;
   

Tenga en cuenta lo siguiente al otorgar los accesos:

• Ambos procedimientos se ejecutan con EXECUTE AS OWNER, por lo que el rol propietario necesita SELECT sobre cualquier tabla que se pase a SEND_TO_PRISMA, y CREATE TABLE / INSERT sobre el esquema en el que escribe GET_FROM_PRISMA. Quienes invocan el procedimiento solo necesitan USAGE sobre el procedimiento en sí.
• Quien invoque el procedimiento también necesita USAGE sobre un warehouse activo. La serialización a CSV ocurre dentro del sandbox de Python, por lo que un warehouse XS es suficiente para archivos de tamaño típico.

Los procedimientos de referencia reciben el API token como un argumento en texto plano, por lo que puede quedar visible en el historial de consultas. Para un entorno de producción, almacene el token como un SECRET de Snowflake o encapsule las llamadas en procedimientos por data sync que incluyan las credenciales, otorgando acceso únicamente a esos procedimientos. Como mínimo, restrinja quién puede ver el historial de consultas de los roles que ejecutan estas llamadas.

Preparar las tablas de staging

Prisma espera una tabla a nivel de cliente o miembro con los datos de perfil y las señales (flags) y, si además sincroniza productos, una tabla independiente a nivel de cuenta. Dado que SEND_TO_PRISMA serializa los datos con pandas.to_csv (delimitado por comas, con fila de encabezado, sin índice), construya sus vistas de staging con estas reglas:

• Nombre las columnas igual que los campos de Prisma (por ejemplo, MemberNumber, FirstName), o solicite a su representante de Prisma que las mapee explícitamente.
• Incluya primero el identificador único del cliente o miembro (MemberNumber o equivalente) en todos los archivos.
• Convierta las fechas a cadenas YYYY-MM-DD, por ejemplo TO_VARCHAR(dob, 'YYYY-MM-DD'). Evite columnas DATE / TIMESTAMP sin convertir.
• Utilice 1 / 0 para las señales (flags), no TRUE / FALSE.
• Elimine las barras verticales (|) de los campos de texto de la tabla de cuentas: REPLACE(descr, '|', '/').
• Trate los NULL con cuidado — se serializan como cadenas vacías, lo cual es aceptable para campos recomendados, pero no para los obligatorios.
• Mantenga los archivos dentro de los límites de importación de Prisma (se recomiendan 100 MB y 100.000 filas como máximo). Particione las bases más grandes y cargue los datos en lotes.

Tabla de clientes o miembros

Cree una vista con una fila por cliente o miembro:

CREATE OR REPLACE VIEW MEMBERS_STAGING AS
SELECT
    member_number                                 AS "MemberNumber",       -- obligatorio, clave única
    first_name                                    AS "FirstName",
    last_name                                     AS "LastName",
    email                                          AS "Email",
    cell_phone                                     AS "CellPhone",
    TO_VARCHAR(date_of_birth,'YYYY-MM-DD')         AS "DateOfBirth",
    city                                           AS "City",
    state                                          AS "State",
    zip                                            AS "Zip",
    TO_VARCHAR(membership_open_dt,'YYYY-MM-DD')    AS "MembershipOpenDate",
    IFF(dormant, 1, 0)                             AS "DormantFlag",
    IFF(deceased, 1, 0)                            AS "DeceasedFlag",
    IFF(opt_out, 1, 0)                             AS "OptOutFlag",
    IFF(has_checking, 1, 0)                        AS "Has_Checking",
    IFF(has_savings, 1, 0)                         AS "Has_Savings",
    IFF(has_auto_loan, 1, 0)                       AS "Has_AutoLoan",
    IFF(has_credit_card, 1, 0)                     AS "CreditCardFlag"
FROM core_member_extract;

Incluya siempre los campos de supresión, como OptOutFlag y DeceasedFlag: son los que determinan las exclusiones de campañas.

Tabla de cuentas / productos

Mantenga los productos en una tabla independiente a nivel de cuenta. Prisma ensambla el compuesto AcctInfo durante la importación, por lo que debe enviar columnas individuales en lugar de una cadena delimitada por barras verticales ya armada. Coloque MemberNumber primero como clave del registro:

CREATE OR REPLACE VIEW MEMBER_ACCOUNTS_STAGING AS
SELECT
    member_number                                   AS "MemberNumber",        -- clave del registro
    account_id                                      AS "AccountID",           -- obligatorio
    account_code                                    AS "AccountCode",         -- obligatorio
    REPLACE(account_descr, '|', '/')                AS "AccountDescription",
    account_group                                   AS "AccountGroup",        -- LOAN/DEPOSIT/CARD
    TO_VARCHAR(current_balance, 'FM999999999.00')   AS "CurrentBalance",      -- obligatorio
    TO_VARCHAR(current_rate,    'FM990.00')         AS "CurrentRate",
    TO_VARCHAR(payment_due_dt,  'YYYY-MM-DD')       AS "PaymentDueDate",
    delinquency_days                                AS "DelinquencyDays",
    TO_VARCHAR(account_open_dt, 'YYYY-MM-DD')       AS "AccountOpenDate",     -- obligatorio
    IFF(account_closed, 1, 0)                       AS "AccountClosedFlag",
    TO_VARCHAR(maturity_dt,     'YYYY-MM-DD')       AS "MaturityDate",
    TO_VARCHAR(last_txn_dt,     'YYYY-MM-DD')       AS "LastTransactionDate"
FROM core_account_extract
WHERE account_closed = FALSE OR account_closed_dt >= DATEADD(month, -13, CURRENT_DATE);

• Cargue la tabla de clientes o miembros y la tabla de cuentas mediante dos data syncs de importación independientes. Ambas utilizan MemberNumber como clave y se combinan en el mismo registro.
• Elimine o reemplace las barras verticales en cualquier campo de texto de cuentas antes de la carga.
• Coordine el orden de las columnas y los campos obligatorios con su representante de Prisma para que el mapeo de importación coincida con su vista.

Tabla de destino para exportaciones

GET_FROM_PRISMA crea la tabla de destino en la primera ejecución si todavía no existe, e infiere los tipos de columna a partir del CSV. Revise esos tipos antes de utilizar la tabla en procesos posteriores. Dado que el procedimiento agrega filas en cada llamada, trunque primero el destino o cargue los datos en una tabla sin procesar y combínelos (MERGE) en una tabla curada, utilizando como clave natural, por ejemplo, MemberNumber junto con la campaña y la marca de tiempo del evento.

Obtenga sus credenciales de DataSync

Una vez que sus vistas de staging estén listas:

1. Envíe a su representante de Prisma Campaigns un archivo de muestra pequeño (10 filas o menos, y menos de 1 MB) para la tabla de clientes o miembros y, si corresponde, para la tabla de cuentas.
2. Espere a que configure los data syncs (con la frecuencia establecida en Manual, dado que la propia carga vía API encola el procesamiento) y le envíe, a través de un canal seguro (nunca por correo electrónico en texto plano ni en un documento compartido):
   • Su dominio de Prisma Campaigns, por ejemplo yourinstitution.prismacampaigns.com.
   • Un par de ID de data sync y API token para cada data sync (importación de clientes o miembros, importación de cuentas y exportación, si corresponde).
3. Almacene los tokens según lo descrito en Crear los procedimientos almacenados.

Los tokens se generan por cada data sync, por lo que revocar uno no afecta a los demás.

Probar los procedimientos

Con los ID de data sync y los tokens en mano, invoque los procedimientos almacenados desde un worksheet:

-- Enviar una tabla de Snowflake a un data sync de importación de Prisma
CALL SEND_TO_PRISMA(
    'MEMBERS_STAGING',                        -- tabla de origen
    'yourinstitution.prismacampaigns.com',    -- dominio de Prisma
    443,                                       -- puerto
    '6908f6f8-8bd0-4b95-9e36-7667d0b21ea6',   -- ID de data sync (provisto por Prisma)
    'api',                                     -- usuario (siempre "api")
    'key-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'    -- API token del data sync (provisto por Prisma)
);

-- Descargar el archivo más reciente de un data sync de exportación de Prisma
CALL GET_FROM_PRISMA(
    'PRISMA_CAMPAIGN_RESULTS',                -- tabla de destino (se crea si no existe)
    'yourinstitution.prismacampaigns.com',
    443,
    '6908f8e9-6843-427a-b33c-109087880239',
    'api',
    'key-yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy'
);

Tenga en cuenta el siguiente comportamiento:

• SEND_TO_PRISMA envía la tabla completa (SELECT *), por lo que su tabla o vista de staging debe contener exactamente las columnas y filas que Prisma debe recibir.
• Una carga exitosa devuelve File queued; el archivo se procesa de forma asíncrona. Confirme que la ejecución finalizó con los APIs de estado descritos en Sincronización de datos (data syncs).
• GET_FROM_PRISMA agrega filas en cada llamada. Para obtener una instantánea limpia, trunque la tabla de destino primero, o cargue los datos en una tabla de staging y combínelos.
• GET_FROM_PRISMA siempre devuelve el archivo de la última ejecución exitosa del data sync de exportación. Si lo invoca dos veces sin que haya una nueva ejecución entre ambas llamadas, importará las mismas filas dos veces.

Programar la sincronización

Una vez que una llamada manual funcione como se espera, encapsúlela en una Task de Snowflake:

CREATE OR REPLACE TASK NIGHTLY_MEMBER_SYNC
  WAREHOUSE = XS_WH
  SCHEDULE = 'USING CRON 0 5 * * * America/New_York'
AS
  CALL SEND_TO_PRISMA('MEMBERS_STAGING', 'yourinstitution.prismacampaigns.com',
                      443, '<datasync-id>', 'api', '<token>');

ALTER TASK NIGHTLY_MEMBER_SYNC RESUME;

Debido a que las importaciones se encolan de forma asíncrona, verifique cada ejecución con los APIs de estado del data sync (misma autenticación Basic Auth). Consulte Sincronización de datos (data syncs) para los endpoints de estado, historial de ejecuciones y descarga.

Resultado esperado

Antes de habilitar las tasks programadas, confirme lo siguiente junto con su representante de Prisma Campaigns:

1. Una carga de muestra pequeña mediante SEND_TO_PRISMA hacia el data sync de importación de clientes o miembros devuelve File queued, y el estado de la ejecución llega a finished.
2. Un cliente o miembro de muestra en Prisma Campaigns muestra los campos de perfil, las señales (flags) y el formato de fechas esperados.
3. Si sincroniza cuentas, una muestra pequeña de cuentas se carga correctamente y las condiciones de segmento que dependen de productos o saldos se resuelven como se espera.
4. Si configuró una exportación, GET_FROM_PRISMA completa la tabla de destino con las columnas y tipos esperados.
5. Una vez que todo funcione correctamente, habilite las tasks programadas de Snowflake.

Solución de problemas

Si las condiciones de segmento sobre productos o cuentas lucen incorrectas después de una importación exitosa, contacte a su representante de Prisma con una muestra de los encabezados y filas cargados: el mapeo y el ensamblado del campo compuesto se configuran del lado de Prisma.

Artículos relacionados

• Sincronización de datos (data syncs)
• Uso de API keys
• Subir datos a Prisma
• Cargar información de clientes desde un archivo .csv