User Guide

Welcome to the Intacct API Usage application. This guide covers all features and how to use them effectively.

Overview

This application monitors and reports on Sage Intacct API usage across multiple companies/instances. It connects to the Intacct API to retrieve usage data, stores it locally, and provides reporting and email notification capabilities.

Key Features

Scheduled Runs - Automate data collection on intervals, daily, weekly, or monthly
Flexible Filtering - Define custom filters to segment data by company prefix or pattern
Email Notifications - Send reports via SMTP or Microsoft Graph to multiple recipients
Multiple Report Types - Detailed, Summary, and Exception reports in CSV or Excel format
Company Management - Search, filter, and skip specific companies
Proxy Support - Configure HTTP/HTTPS proxy for all outbound connections

Getting Started

Follow these steps to set up the application:

1. Configure API Credentials

Go to Configuration and enter your Intacct API credentials:

Sender ID - Your Web Services sender ID
Sender Password - Your Web Services sender password
User ID - An Intacct user with API access
User Password - The user's password

Click Save Credentials to store them securely. Credentials are validated before saving.

2. Configure Proxy (Optional)

If your network requires a proxy for outbound connections, configure it in Configuration > Proxy Configuration:

Enter the proxy URL (e.g., http://proxy.example.com:8080)
Add username/password if authentication is required
Use the toggle to enable/disable the proxy without removing the configuration

3. Load Company List

In Configuration, load your company list:

Enter the API URL that provides your company data
Add an API Token if authentication is required
Click Load to fetch companies from the API

You can also manually add companies using the Manage button.

4. Configure Filters (Optional)

Set up filters in Configuration to segment your data:

Each filter has a Name and a Prefix
Companies matching the prefix will be grouped under that filter
Example: Filter "UK Companies" with prefix "UK_" matches UK_Company1, UK_Company2, etc.

5. Create a Schedule

Go to the Schedules tab and create a schedule to automatically fetch data and send reports.

Schedules Tab

Set up automated data collection on a recurring schedule.

Creating a Schedule

Enter a Schedule Name to identify this schedule
Select a Schedule Type:
- One-off - Run once at a specific date and time, then automatically disabled
- Weekly - Run on selected days at a specific time
- Monthly - Run on a specific day of the month
- Custom (cron) - Advanced scheduling using cron expressions
Configure the timing options for your chosen type
Select a Query Filter (All Filters or a specific filter)
Enable one or more Email Configurations to send reports to multiple recipients
Choose Report Attachments to include in the email
Optionally enable Full Refresh to clear data before each run
Click Save Schedule

Data Fetch Modes

Mode	Description
Incremental (default)	Fetches only new data since the last run. For each company, finds the last date fetched, clears that day's data, and re-fetches from that date forward. Efficient for daily runs.
Full Refresh	Clears all existing data for the selected filter before fetching. Use when you need to start fresh or suspect data inconsistencies.
Reports Only	Skips data fetching entirely and sends reports using existing data. Useful when you want to re-send reports without querying Intacct again.

Multiple Email Recipients

Schedules support sending reports to multiple email configurations simultaneously. Toggle on each configuration you want to receive the report. This is useful for:

Sending to different teams or departments
Distributing reports to external stakeholders via different providers
Maintaining backup notification channels

Schedule Options

Option	Description
Report Start Date	Only include data from this date onwards in reports.
Complete Months Only	Exclude the current (incomplete) month from reports.
Reports Only	Skip data fetch and send reports from existing data. Useful for re-sending reports.
Full Refresh	Clear existing data for the filter before fetching new data. Disabled when Reports Only is active.

Managing Schedules

Edit - Modify an existing schedule's settings (disabled when schedule is enabled)
Enable/Disable - Toggle whether a schedule runs automatically
Delete - Remove a schedule permanently (disabled when schedule is enabled)
Stop - Halt a currently running scheduled job

Note: When saving a new or updated schedule, you'll receive a reminder to enable it using the toggle switch. Schedules are created in a disabled state by default.

Schedule Status

Success - Last run completed successfully
Running - Currently executing
Error - Last run encountered an error
Stopped - Last run was manually stopped
Disabled - Schedule is not active
Pending - Never run yet

Reports Tab

View and download reports, send email reports, and analyze API usage data.

Downloads Section

Download reports in CSV or Excel format:

Filter - Select "All Filters" or a specific filter to include in the download
Format - Choose CSV or XLSX (Excel) format
Detailed - Every API usage record with full details
Summary - Aggregated totals by company and filter
Exceptions - Companies that had errors or returned no data

Send Reports

Email reports to one or more notification configurations:

Select a Filter to limit the report data (or leave as All Filters)
Choose Report Attachments to include
Optionally set a Date Range to filter the data
Toggle on the Email Configurations you want to send to
Click Send Reports

Error Summary

Review companies that encountered errors during data fetch:

Grouped by error description
Click on a row to see the list of affected companies
Use this to identify companies to add to the exceptions list

Usage Chart

Visualize API usage trends over time:

Line chart showing total API usage by month
Stacked view by filter when multiple filters exist
Date range filter to focus on specific periods

Filter Breakdown

See record counts and company counts per filter in a summary table.

Report Types

Report	Contents
Detailed	Every API usage record with company ID, Sage Account Number, partner, transaction count, and timestamps.
Summary	Aggregated view by company showing company ID, Sage Account Number, total transactions and record counts.
Exceptions	Companies that failed to authenticate, returned errors, or had no data. Includes company ID, Sage Account Number, error numbers and descriptions.

Configuration

Manage credentials, companies, filters, and proxy settings.

API Credentials

Your Intacct Web Services credentials for API access:

Sender ID/Password - Web Services sender credentials (obtained from Intacct)
User ID/Password - An Intacct user account with appropriate permissions

Credentials are encrypted and stored securely. The encryption key is set via the ENCRYPTION_KEY environment variable.

Proxy Configuration

Configure an HTTP/HTTPS proxy for all outbound connections (Intacct API, Companies API, email):

Proxy URL - Full URL including port (e.g., http://proxy.example.com:8080)
Username/Password - Optional authentication credentials
Enable/Disable Toggle - Quickly enable or disable the proxy without removing the configuration

When a proxy is configured and enabled, all outbound HTTP/HTTPS requests will be routed through it.

Companies / Instances

Manage the list of companies to query:

Enter the API URL that returns company data
The API must return a JSON object with a companies array:
```
{ "companies": ["COMPANY001", "COMPANY002", ...] }
```
If authentication is required, enter the API Token (sent as Bearer token)
Click Load to fetch companies from the API
Scheduled jobs automatically load fresh company data before each run

Company Management

Manage - Opens the Manage Companies/Instances modal where you can:
- Add individual companies
- Search/filter the company list using the search box
- Skip companies (add to exceptions)
- Remove companies from the list
Exceptions - View and manage companies that are excluded from processing
Clear All - Remove all companies and data

Skipping Companies

In the Manage Companies dialog:

Click Skip to temporarily exclude a company from data fetching
Click Unskip to include it again
Skipped companies remain in the list but are not queried
Skipped companies are also excluded from exception reports

Query Filters

Define filters to segment companies by prefix:

Filter Name - A descriptive name (e.g., "UK Companies")
Prefix - The company ID prefix to match (e.g., "UK_")

Companies not matching any filter are grouped under "Other".

Adding Filters

Click + Add Filter
Enter a name and prefix
Click Save Filters

Notifications

Configure email settings for sending reports.

Supported Providers

Provider	Use Case
SMTP	Standard email servers, Gmail, Office 365 SMTP, etc.
Microsoft Graph	Microsoft 365 using Azure AD app registration (OAuth)

SMTP Configuration

Field	Description
SMTP Host	Mail server hostname (e.g., smtp.office365.com)
Port	Server port (587 for STARTTLS, 465 for SSL, 25 for none)
Security	STARTTLS (recommended), SSL/TLS, or None
Username	SMTP authentication username (usually your email)
Password	SMTP authentication password or app password
From Name	Display name for sent emails
From Address	Sender email address

Microsoft Graph Configuration

Field	Description
Tenant ID	Azure AD tenant ID (GUID)
Client ID	Azure AD app registration client ID
Client Secret	Azure AD app registration client secret
From Address	Microsoft 365 mailbox to send from

Note: The Azure AD app needs the Mail.Send application permission.

Recipients

To - Primary recipients (comma-separated)
CC - Carbon copy recipients
BCC - Blind carbon copy recipients

Saving and Testing

When you click Save Configuration or Save, the application automatically:

Sends a test email to verify your settings work correctly
If the test succeeds, saves the configuration
If the test fails, displays the error without saving

This ensures all saved configurations are known to work. A loading spinner indicates when testing is in progress.

Save As New

When editing an existing configuration, you can use Save As New to create a copy with a new name. Note that you must enter a new password/client secret when creating a new configuration from an existing one.

Logs

View application logs for troubleshooting and monitoring.

Log Levels

INFO - Normal operational messages
WARN - Warning conditions that may need attention
ERROR - Error conditions that prevented an operation

Features

Auto-refresh - Logs update automatically
Filter by Level - Show only specific log levels
Search - Find specific log entries
Download - Export logs for analysis

Understanding Job Logs

During scheduled runs, you'll see log entries like:

Running query: ExcelConnect (INCREMENTAL) - Starting a filter with incremental mode
Mode: INCREMENTAL (top-up from last date) - Confirms incremental mode
[CompanyName] Top-up from 2026-02-10 - Company fetching from its last date
[CompanyName] Cleared 5 records from 2026-02-10 onward - Records cleared for re-fetch
[CompanyName] Initial fetch (no existing data) - First-time fetch for a company

Troubleshooting

Common Issues

"No credentials configured"

Solution: Go to Configuration and enter your Intacct API credentials, then click Save Credentials.

"No companies loaded"

Solution: Load companies from the API or manually add companies via the Manage button in Configuration.

Authentication errors for specific companies

Possible causes:

The company ID is incorrect
The user doesn't have access to that company
The company has been deactivated

Solution: Check the Exceptions report for details. Consider adding problematic companies to the exceptions list.

Emails not sending

Check:

SMTP credentials are correct
Firewall allows outbound SMTP connections
If using a proxy, ensure it's configured correctly
For Microsoft Graph, verify the app has Mail.Send permission

Solution: Use the Test button in Notifications to verify the configuration.

Scheduled jobs not running