Skip to main content

Artez Interactive Connector (Technical Reference)

Written by Philippe Trussart

Overview

This connector pulls transaction exports from Artez Interactive’s WebGet service and lands them in your data lake. Each run requests the next export file available for your organization, parses the XML payload, flattens key attributes, and stores several nested sections (e.g., payment, donation, tribute, monthly plan, constituent) as JSON. After a successful load in production, the connector confirms receipt to prevent the same file from being re-delivered.

Authentication & Setup

Required settings:

  • Organization ID (organizationId)

  • Username (userName)

  • Password (password)

  • App Environment (app_env) — when set to production, the connector will acknowledge completed exports

  • XML Version — fixed to xml1_9 in requests

API Endpoints and HTTP Methods

Service endpoint:

  • Base URL: https://secure.e2rm.com/webgetservice/export.asmx

getNextNewExportFile — GET

  • HTTP method: GET

  • URL:
    ​https://secure.e2rm.com/webgetservice/export.asmx/getNextNewExportFile

  • Purpose:
    Pulls the next available export file from Artez Interactive. This is the main data-extraction call; the connector uses it to retrieve a batch of transactions to process into the transactions_v2 table.

  • Parameters (query string):

    • organizationId

    • userName

    • password

    • XMLVersion (e.g., xml1_9)

All parameters are sent as query parameters on the GET request (no request body). The response is XML and is parsed into transactions; if only a single <Transaction> is returned, the connector normalizes it into an array of one transaction before processing.

setExportIsSuccessful — GET

  • HTTP method: GET

  • URL:
    ​https://secure.e2rm.com/webgetservice/export.asmx/setExportIsSuccessful

  • Purpose:
    ​Acknowledges receipt of the export file that was just processed. This tells Artez Interactive that the export has been successfully consumed, so it won’t be returned again on subsequent calls. The connector only calls this method when running in the production environment and only if an exportID was present on the response.

  • Parameters (query string):

    • organizationId

    • userName

    • password

    • exportID (the exportID returned by getNextNewExportFile)

As with the export call, all parameters are sent as query string values on the GET request. No response body is used beyond basic success/failure.

Sync Strategy

Pull-next export workflow

  1. Request the next file using getNextNewExportFile with your credentials and XMLVersion=xml1_9.

  2. Parse the payload. If the export contains a single <Transaction>, it is normalized to a list so it can be processed uniformly.

  3. Write records to the destination.

  4. Acknowledge in production: after processing, if an exportID was returned and app_env=production, call setExportIsSuccessful to confirm receipt. This prevents re-delivery of the same file.

Incrementality & state

  • The source queues exports; each call returns the next file, so incrementality is handled by the service itself.

  • When no file is available, the connector emits a record_count metric of 0 and exits the run. There is no local bookmark because the export acknowledgment is the deduplication mechanism.

Deletes

  • No delete propagation is emitted for these exports. The connector writes only the records present in the returned file(s).

Error handling & parsing

  • Non-200 responses raise a clear failure.

  • XML responses are parsed and, if needed, repaired and re-parsed to tolerate minor formatting issues.

  • The connector logs and surfaces minimal request context to aid troubleshooting.

Primary Keys & Indexes

  • Unique key (per record): transactionid

  • Indexed fields: exportid, transactionid, eventid, locationid, locationtypeid, constituentid
    These are used for identity, merge/upsert efficiency, and common filtering patterns.

Metrics

After each run, the connector emits a per-table record_count metric with the total number of records written. If no export file is available, the count is 0.

Known Limitations & Behavior

  • Single stream: the connector currently exposes only the transactions_v2 stream.

  • No in-run pagination: export files are delivered whole by the service. If multiple transactions are present, each becomes a row.

  • Production acknowledgment: the receipt confirmation is only issued when app_env=production. In non-production environments, files are processed but not acknowledged.

  • Schema stability: the mapped column set is fixed in the connector; if Artez adds new nodes, they will not appear automatically without an update to the mapping.

  • Null semantics: if a mapped path points to a complex object/array (rather than a scalar), the value is written as null. JSON blocks capture the nested detail as a whole.

Request Parameters (for reference)

Each request to the service includes:

  • organizationId, userName, password, and (for the fetch call) XMLVersion=xml1_9.

  • On successful fetch, the response contains attributes like exportID and count; the connector uses exportID for the production acknowledgment call.

Did this answer your question?