# Accounting Run - Run Guide (Abacus)

> Source: [Accounting Run - Run Guide (Notion)](https://www.notion.so/20d97177520f80bfaf4ef78308483261)  
> Last updated in Notion: October 2025  
> Status: In progress

This is the step-by-step operational guide for executing an accounting run in the **Abacus** system (the new platform). For the legacy workflow, see [Legacy Workflow](legacy-workflow.md).

## Resources

- [Accounting Run (Tech Overview)](https://www.notion.so/c9ecc13c18cb4362962ce54853992580)
- [Whimsical: accounting_run_calculate](https://whimsical.com/accounting-run-calculate-9eUCj5dC1R9DGSCYvL94dg)
- [DAGs repo](https://github.com/theorchard/ows-royalties-workflows)

## Prerequisites

Before starting, confirm:

1. **Finance has delivered the sales data.** Check `#accounting-calc` — the Sales Processing team posts when files are ready.
2. **Exchange rates have been uploaded** for the statement period. If unsure, ask in `#accounting-calc`.
3. **You know the statement period ID.** This is used as the batch_id. Find it in Abacus UI → Statement Periods, or query: `SELECT * FROM statement_period ORDER BY statement_period_id DESC LIMIT 5;`

## Step 1: Ingest a Sales File

1. Go to the [`ows-abacus-event-create-ingest-sales-event`](https://scheduler.theorchard.io/job/ows-abacus-event-create-ingest-sales-event/) pipeline
2. Click **Build with Parameters**
3. Choose **Environment** (e.g., QA)
4. Choose **Sales Type**: `distro` (distribution) or `nr` (neighbouring rights)
5. Insert **Batch ID** — must be a unique integer; the statement period ID is commonly used (e.g., `317`)
   - The ingest job skips already-ingested batches to prevent duplicates
6. Click **Build**
7. Wait for completion (~20 minutes per 100M rows). Monitor in Airflow DAG: `sales_ingest`
   - **Success:** All Airflow tasks show green. Verify with the staging query below.
   - **Failure:** Check the failed task's logs in Airflow. See [Troubleshooting](troubleshooting.md).

## Step 2: Go to the Accounting Period

1. Open Abacus (e.g., [QA](https://abacus.qaorch.com/accounting-periods))
2. Navigate to **Accounting Periods**
3. Open a period if needed (only one can be open per contract type)
4. Click the relevant accounting period

## Step 3: Add Sales Data to Accounting Period

> **If redoing a run:** You must either use a different file name or delete the old S3 data first.

Each sub-step must complete before the next button becomes active in the UI. If a step fails, see [Troubleshooting](troubleshooting.md).

1. Insert a **File Display Name** (e.g., "May 2025 Distro Sales")
2. Click **Get Eligible Sales** — wait for DAG `sales_get_eligible` (a few minutes)
3. Click **Mark All Sales Delivered**
4. Click **Approve All Sales** — wait for DAG `sales_approve` (a few minutes)
5. Click **Prep Mech Deductions** — wait for DAG `accounting_period_mechanicals` (a few minutes)

## Step 4: Execute the Run Controllers

Run controllers are listed on the accounting period detail page. They are named groupings of contracts (e.g., "Altafonte", "KNR"). Run them **one at a time**:

1. Clear any E2E run controllers if present (from CI/test pipelines — see [Removing E2E Run Controllers](#removing-e2e-run-controllers))
2. Find your controller in the list
3. Click **Create** — triggers DAG `accounting_run_calculate`. Duration varies by data volume (minutes to hours). Monitor in [Airflow UI](#viewing-a-dag).
   - **Success:** Status changes to "Complete" and the run summary appears.
   - **Failure:** Status stays "Running" or shows an error. See [Troubleshooting](troubleshooting.md#accounting-run-stuck-in-running-status).
4. Review the run summary with stakeholders
5. Click **Approve** — wait for status to say "Approved"
6. **Repeat** for each remaining run controller

## Step 5: Update the Unified Sales Table

1. Go to [`dbt-accounting-scheduler`](https://scheduler.theorchard.io/job/dbt-accounting-scheduler/)
2. Click **Build with Parameters**
3. Disable all checkmarks
4. Enable **RUN_ON_QA** (or RUN_ON_PROD)
5. In **SELECT_MODELS**, add `abacus_fact_sales_unified_dbt`
6. In **EXCLUDE_MODELS**, remove `abacus_fact_sales_unified_dbt`
7. Click **Build** and wait for completion

Verify with:

```sql
-- Verify contracts in the unified sales table for a specific run controller
-- NOTE: ORCHARD_APP_REPORTING_V2.PROD_* tables are replicated from prod.
-- For QA validation, this cross-environment join is intentional.
SELECT COUNT(DISTINCT ac.contract_id)
FROM ORCHARD_APP_REPORTING_V2.PROD_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.ACCOUNT_CONTRACT AS ac
    INNER JOIN ORCHARD_APP_REPORTING_V2.PROD_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.RUN_CONTROLLER_CONTRACT AS rcc
        ON rcc.contract_id = ac.contract_id
    INNER JOIN ORCHARD_APP_REPORTING_V2.PROD_ROYALTY_ACCOUNTING_ROYALTY_ACCOUNTING.RUN_CONTROLLER AS rc
        ON rcc.run_controller_id = rc.run_controller_id
    INNER JOIN ROYALTY_ACCOUNTING.<ENV>.ABACUS_FACT_SALES_UNIFIED_DBT AS fs
        ON ac.contract_id = fs.contract_id
WHERE fs.STATEMENT_PERIOD_ID = <statement_period_id>
    AND rc.run_controller_name = '<controller_name>';
```

## Useful Queries

### Sales Distro Staging

```sql
SELECT COUNT(*)
FROM ROYALTY_ACCOUNTING.<ENV>.STMT_DB_SALES_DISTRO_STAGING
WHERE BATCH_ID = '<batch_id>';
```

### Sales File Metadata

```sql
-- MySQL (royalty_accounting)
SELECT * FROM sales_file WHERE accounting_period_id = <period_id>;

-- Snowflake
SELECT *
FROM orchard_app_reporting_v2.<ENV>_royalty_accounting_royalty_accounting.sales_file
WHERE file_name = '<your file display name>';
```

## Mitigations

### "Get Eligible Sales" Before Ingest Completes

See [Troubleshooting: Get Eligible Sales before ingest](troubleshooting.md#get-eligible-sales-triggered-before-ingest-completes).

## Appendix

### Opening an Accounting Period

1. Click **New Accounting Period**
2. Choose contract type (Distribution or Performer Neighboring Rights)
3. Insert a unique period name
4. Click **Create**

### Closing Accounting Periods

1. Go to [`abacus-run-e2e-tests`](https://pipeline.theorchard.io/job/abacus-run-e2e-tests/) pipeline
2. Select action **Close Open Periods**
3. Click **Build**

### Removing E2E Run Controllers

E2E controllers may be left over from CI/demo pipelines. Verify they're not in use first.

1. Go to [`abacus-run-e2e-tests`](https://pipeline.theorchard.io/job/abacus-run-e2e-tests/) pipeline
2. Select action **Clear runcontrollers**
3. Click **Build**

### Refreshing QA / Dev / UAT

See [Environment Refresh](environment-refresh.md).

### Viewing a DAG

1. Go to [AWS Managed Apache Airflow](https://us-east-1.console.aws.amazon.com/mwaa/home?region=us-east-1#environments)
2. Click `[env]-abacus-airflow`
3. Open the **Airflow UI** link
4. Find and click the relevant DAG (e.g., `accounting_run_calculate`)
5. Monitor task completion