Five9 Data Ingestion

On a schedule, it runs a Five9 report, parses the result, converts the fields to their proper types, and writes each record into a data store you can query, build dashboards on, or even run workflows against. Most common use case is to pull call logs and agent state details; it also handles contacts, lists, voicemails, and others.

This package comes with four main pieces:

• five9-report-ingestor : the workflow that runs the report, parses it, maps the fields, and writes the records.
• five9-report-ingestor-field-mapper : a helper workflow that turns raw Five9 report rows into clean, typed records. You can edit this if you want to change how data is shaped.
• five9_data_ingestion_settings : a table of defaults for each Five9 data source, so picking a data source is usually all you specify; the report name, folder, and target table come from here.
• a scheduler trigger : runs the ingestor on a schedule. You are free to modify it, or copy it, to ingest more data sources (one trigger per data source you want).

Get it running

1. Connect Five9

When you install the package, you will be asked to pick a Five9 connection. Choose an existing one, or create a new one named five9. That is the only setup the install needs.

The Five9 user behind that connection needs the Admin and Reporting roles, with the "User can use administrator services" box checked. Use a dedicated user for this, separate from the one you log into the Five9 UI with.

2. Tell it what to ingest

The package ships with a starter scheduler trigger. Open it and set how often it should run (every 15 minutes, hourly, nightly, whatever fits) and which data you want. To pull call logs every 15 minutes, that is all you need: call logs are the default.

3. Done

On each run the workflow pulls the report, maps the fields, and upserts the records into a data store table named five9_<data source> (call logs land in five9_call_log, agent state in five9_agent_state, and so on). Records are saved by a stable key, so overlapping runs safely update existing rows instead of creating duplicates.

Ingesting more Five9 data

You are not limited to call logs. Add a scheduler trigger for each kind of Five9 data you care about, each on its own schedule. For example: call logs every 15 minutes, agent state hourly, contacts once a night. Every trigger runs the same ingestor; you just tell it which data source to pull.

On a trigger you pick a data source by its name. These work out of the box:

call_log (the default), agent_state, contact, dnc, dnis, list, voicemails, worksheet, digital_channel, visual_ivr.

The sources acd_queue, call_segment, call_recording, ivr, list_rollup, contact_rollup, and peaks require a custom report created in Five9 and saved in a shared folder the API user can access. See the next section.

The Five9 report folder and report name each of these data sources maps to lives in the five9_data_ingestion_settings table that ships with the package. Open it to see the exact mapping, change a default, or add a new data source of your own. That table is the source of truth, so there is nothing to keep in sync by hand.

Each trigger can also set a lookback window: how far back each run pulls, in hours. Keep it in line with how often the trigger runs; a schedule every hour with a 1 to 2 hour lookback is a good default. A single Five9 report returns at most 500,000 rows, so for high-volume data avoid very long lookbacks.

Pulling custom data and extra fields

Want fields that the standard reports do not include, or a data source not listed above?

1. Build a report in Five9. Create a report (a tabular report is usually the right choice), add whatever columns you want, and save it to a folder your integration user can access.
2. Point a trigger at it. Set the report folder, report name, and the data store table where the records should land. The ingestor will run it just like the built-in ones.
3. (Optional) shape the data. By default your new fields come in as raw text. If you want them cleaned up (numbers as numbers, dates as dates, a custom record key, dropping columns you do not need), edit the five9-report-ingestor-field-mapper workflow. Every data source already has its own branch there. Open the branch for the data source you are working with and adjust how its fields are converted to match the columns in your report.

That is the whole system: one ingestor, one mapper you can extend, and one scheduler trigger per data source you want to pull.

FAQ

Want to limit how much data you pull?

Filter on the Five9 side rather than pulling everything and trimming afterward. Build a custom report in Five9 with the filter you want, then point a scheduler trigger at it instead of the default report.

For example, say you only want your support team's calls. In Five9, create a Call Log report filtered to that team and save it as Support Team Call Logs in a folder named Custom Integrations. Then, in that trigger's initial data, set:

• reportFolder : Custom Integrations
• reportName : Support Team Call Logs

Leave dataSource as call_log so the field mapper still knows how to shape the rows; your filtered report has the same columns as a standard call log. Set dataStoreName too if you want these records in their own table. Five9 does the filtering, and each run stays comfortably under its per-report row limit.

Timestamps look like the wrong timezone?

Five9 writes report times as wall-clock in the report's configured timezone, with no offset attached. Set sourceTimezone in package settings or the trigger input to match the report source timezone; this is separate from the schedule timezone. It defaults to Pacific (America/Los_Angeles).

Need implementation help?

We are happy to help. Email the support contact listed on the package and we will work with you on your requirements.

Live agent and ACD skill snapshots

Version 1.2.0 adds two shared current-state workflows:

• five9-current-agent-state-projection applies agent.current_state.snapshot and agent.current_state.changed events to five9_current_agent_state.
• five9-current-queue-status-projection applies queue.current_status.snapshot events to five9_current_queue_status, keeping one record per ACD skill and retaining the provider metrics.

The package includes all three event triggers and both empty current-state table declarations. It ships no live agent or queue records. Dashboard layouts and analytics source definitions are supplied by the consuming dashboard pack.

Bind the package's five9 connection to the customer's Five9 connection and enable Supervisor Events on that connection for live snapshots. Confirm that the integration is receiving events before enabling the event triggers. The snapshot triggers include projection-health targets for current agents (30 seconds) and current queues (15 minutes).

All package triggers start disabled, including the report schedule. Complete connection and report setup, then enable only the schedules and event streams the customer needs. Publisher copies remain disabled. Publishing this version does not upgrade or enable any existing installation.

Package settings (1.2.1)

Open the installed package's Settings → Five9 report defaults to edit report defaults by data source key. This release includes 17 starter records. You can add records for additional mapper branches; deletion is disabled to keep starter defaults available.

• Five9 report folder and Five9 report name are required, exact names from Five9. The integration user must have access to the folder.
• Destination data store table is optional and falls back to five9_<dataSource>. Changing it does not move existing records; update dependent dashboards and workflows if you change the destination.
• Report source timezone is optional. You should not generally need to change this, as Five9 reports source data is usually hardcoded to America/Los_Angeles. Blank or omitted uses America/Los_Angeles; an override must be an IANA timezone. This controls timestamp parsing, not dashboard display time.

Values supplied by a trigger override these settings. Schedules and lookback windows are configured on triggers. The record key selects the data source; stored dataSource and custom metadata are preserved without exposing ineffective controls.

The new list_rollup, contact_rollup, and peaks records are custom-report starters. Their suggested names are List Details Rollup, Count of Contact Records by Year, and Call and Ports Peaks, respectively, in Shared Reports. Create those reports in Five9 or change the settings to match your actual report names and folders before enabling ingestion. Their columns must match the corresponding mapper branch. The package does not create Five9 reports.

All triggers remain disabled until setup is complete. This release publishes the settings contract and seed defaults; it does not upgrade existing installations.