@memberjunction/actions-bizapps-accounting

Accounting system integration actions for MemberJunction. This package provides a standardized, multi-provider interface for interacting with external accounting systems through the MemberJunction Actions framework. It currently supports QuickBooks Online and Microsoft Dynamics 365 Business Central, with a pluggable architecture for adding additional providers.

This package is part of the BizApps Actions family within the broader MemberJunction Actions Framework. See those parent documents for general action design principles and BizApps-level patterns.

Architecture

The package follows a three-tier class hierarchy -- a domain base class, provider-specific base classes, and individual action implementations. Each provider encapsulates its own API interaction patterns (QBO query language for QuickBooks, OData for Business Central) while sharing credential management and validation logic.

graph TD
    subgraph Framework["MemberJunction Actions Framework"]
        BA["BaseAction<br/>@memberjunction/actions"]
    end

    subgraph Domain["Domain Layer"]
        BAA["BaseAccountingAction<br/>Credential management<br/>Validation helpers<br/>Currency/date formatting"]
    end

    subgraph Providers["Provider Layer"]
        QB["QuickBooksBaseAction<br/>QBO query language<br/>OAuth + Realm ID<br/>Sandbox/production URLs"]
        BC["BusinessCentralBaseAction<br/>OData query builder<br/>Tenant/environment routing<br/>Filter expression helpers"]
    end

    subgraph QBActions["QuickBooks Online Actions"]
        QGL["GetQuickBooksGLCodesAction"]
        QTX["GetQuickBooksTransactionsAction"]
        QAB["GetQuickBooksAccountBalancesAction"]
        QJE["CreateQuickBooksJournalEntryAction"]
    end

    subgraph BCActions["Business Central Actions"]
        BGL["GetBusinessCentralGLAccountsAction"]
        BGLE["GetBusinessCentralGeneralLedgerEntriesAction"]
        BCU["GetBusinessCentralCustomersAction"]
        BSI["GetBusinessCentralSalesInvoicesAction"]
    end

    BA --> BAA
    BAA --> QB
    BAA --> BC
    QB --> QGL
    QB --> QTX
    QB --> QAB
    QB --> QJE
    BC --> BGL
    BC --> BGLE
    BC --> BCU
    BC --> BSI

    style Framework fill:#64748b,stroke:#475569,color:#fff
    style Domain fill:#7c5295,stroke:#563a6b,color:#fff
    style Providers fill:#2d6a9f,stroke:#1a4971,color:#fff
    style QBActions fill:#2d8659,stroke:#1a5c3a,color:#fff
    style BCActions fill:#b8762f,stroke:#8a5722,color:#fff

Credential Flow

All actions resolve credentials through a two-stage lookup. Environment variables take priority over database records, keeping secrets out of the database while allowing non-sensitive configuration (realm ID, environment name) to remain there.

sequenceDiagram
    participant Action as Accounting Action
    participant BAA as BaseAccountingAction
    participant Env as Environment Variables
    participant DB as CompanyIntegration Entity

    Action->>BAA: getOAuthTokens(integration)
    BAA->>Env: Check BIZAPPS_{PROVIDER}_{COMPANY_ID}_ACCESS_TOKEN
    alt Token found in env
        Env-->>BAA: Return access token + refresh token
    else Not in env
        BAA->>DB: Read AccessToken from CompanyIntegration
        alt Token valid
            DB-->>BAA: Return access token
        else Token expired or missing
            BAA-->>Action: Throw authentication error
        end
    end
    BAA-->>Action: Return { accessToken, refreshToken }

    style Action fill:#2d8659,stroke:#1a5c3a,color:#fff
    style BAA fill:#7c5295,stroke:#563a6b,color:#fff
    style Env fill:#2d6a9f,stroke:#1a4971,color:#fff
    style DB fill:#b8762f,stroke:#8a5722,color:#fff

Installation

npm install @memberjunction/actions-bizapps-accounting

This package requires peer dependencies from the MemberJunction ecosystem. In an MJ monorepo workspace, these are resolved automatically.

Setup

1. Create Integration Records

Register each accounting system as an Integration entity in the MemberJunction database.

QuickBooks Online:

INSERT INTO Integration (Name, Description, NavigationBaseURL, ClassName)
VALUES ('QuickBooks Online', 'QuickBooks Online Accounting Integration',
        'https://quickbooks.api.intuit.com', 'QuickBooksIntegration');

Business Central:

INSERT INTO Integration (Name, Description, NavigationBaseURL, ClassName)
VALUES ('Microsoft Dynamics 365 Business Central',
        'Business Central Accounting Integration',
        '', 'BusinessCentralIntegration');

2. Configure CompanyIntegration

Link each MJ Company to its accounting system integration.

QuickBooks Online:

INSERT INTO CompanyIntegration (CompanyID, IntegrationID, ExternalSystemID,
                               CustomAttribute1, IsActive)
VALUES (@CompanyID, @QuickBooksIntegrationID, @RealmID, 'production', 1);
-- ExternalSystemID = QuickBooks Realm ID
-- CustomAttribute1 = 'production' or 'sandbox'

Business Central:

INSERT INTO CompanyIntegration (CompanyID, IntegrationID, ExternalSystemID,
                               CustomAttribute1, IsActive)
VALUES (@CompanyID, @BCIntegrationID, @BCCompanyID, 'production', 1);
-- ExternalSystemID = Business Central company ID (GUID)
-- CustomAttribute1 = environment name (production, sandbox, or custom)

3. Set Environment Variables

QuickBooks Online:

BIZAPPS_QUICKBOOKS_ONLINE_{COMPANY_ID}_ACCESS_TOKEN=your_access_token
BIZAPPS_QUICKBOOKS_ONLINE_{COMPANY_ID}_REFRESH_TOKEN=your_refresh_token
BIZAPPS_QUICKBOOKS_ONLINE_{COMPANY_ID}_REALM_ID=your_realm_id  # Optional if stored in DB

Business Central:

BIZAPPS_BUSINESS_CENTRAL_{COMPANY_ID}_ACCESS_TOKEN=your_access_token
BIZAPPS_BUSINESS_CENTRAL_{COMPANY_ID}_REFRESH_TOKEN=your_refresh_token
BIZAPPS_BUSINESS_CENTRAL_{COMPANY_ID}_TENANT_ID=your_tenant_id

Credential Priority

The system checks for credentials in this order:

1. Environment variables (recommended for security)
2. Database (CompanyIntegration entity fields -- for backward compatibility)

Available Actions

QuickBooks Online

| Action | Description | Type | |--------|-------------|------| | GetQuickBooksGLCodesAction | Retrieve Chart of Accounts | Read | | GetQuickBooksTransactionsAction | Query transactions across multiple types | Read | | GetQuickBooksAccountBalancesAction | Trial balance / account balances | Read | | CreateQuickBooksJournalEntryAction | Create a balanced journal entry | Write |

Microsoft Dynamics 365 Business Central

| Action | Description | Type | |--------|-------------|------| | GetBusinessCentralGLAccountsAction | Retrieve Chart of Accounts | Read | | GetBusinessCentralGeneralLedgerEntriesAction | Query general ledger entries | Read | | GetBusinessCentralCustomersAction | Retrieve customers with search/filter | Read | | GetBusinessCentralSalesInvoicesAction | Query sales invoices | Read |

Usage Examples

Retrieve GL Codes from QuickBooks

import { ActionEngineServer } from '@memberjunction/actions';

const engine = ActionEngineServer.Instance;
const result = await engine.RunAction({
    ActionName: 'GetQuickBooksGLCodesAction',
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'your-company-id' },
        { Name: 'IncludeInactive', Type: 'Input', Value: false },
        { Name: 'AccountTypes', Type: 'Input', Value: 'Bank,Expense,Income' }
    ],
    ContextUser: contextUser
});

if (result.Success) {
    const glCodes = result.Params?.find(p => p.Name === 'GLCodes')?.Value;
    const totalCount = result.Params?.find(p => p.Name === 'TotalCount')?.Value;
    console.log(`Retrieved ${totalCount} GL codes`);
}

Query Transactions from QuickBooks

const result = await engine.RunAction({
    ActionName: 'GetQuickBooksTransactionsAction',
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'your-company-id' },
        { Name: 'TransactionType', Type: 'Input', Value: 'Invoice' },
        { Name: 'StartDate', Type: 'Input', Value: '2025-01-01' },
        { Name: 'EndDate', Type: 'Input', Value: '2025-12-31' },
        { Name: 'MinAmount', Type: 'Input', Value: 1000 },
        { Name: 'MaxResults', Type: 'Input', Value: 50 }
    ],
    ContextUser: contextUser
});

Create a Journal Entry in QuickBooks

const lines = [
    { accountId: '80', debit: 500.00, description: 'Office supplies' },
    { accountId: '35', credit: 500.00, description: 'Cash payment' }
];

const result = await engine.RunAction({
    ActionName: 'CreateQuickBooksJournalEntryAction',
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'your-company-id' },
        { Name: 'Lines', Type: 'Input', Value: JSON.stringify(lines) },
        { Name: 'EntryDate', Type: 'Input', Value: '2025-06-15' },
        { Name: 'PrivateNote', Type: 'Input', Value: 'Monthly office supply purchase' }
    ],
    ContextUser: contextUser
});

if (result.Success) {
    const entryId = result.Params?.find(p => p.Name === 'JournalEntryID')?.Value;
    console.log(`Created journal entry: ${entryId}`);
}

Retrieve Customers from Business Central

const result = await engine.RunAction({
    ActionName: 'GetBusinessCentralCustomersAction',
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'your-company-id' },
        { Name: 'SearchText', Type: 'Input', Value: 'Contoso' },
        { Name: 'OnlyOverdue', Type: 'Input', Value: true },
        { Name: 'SortBy', Type: 'Input', Value: 'balance' },
        { Name: 'MaxResults', Type: 'Input', Value: 25 }
    ],
    ContextUser: contextUser
});

Retrieve Sales Invoices from Business Central

const result = await engine.RunAction({
    ActionName: 'GetBusinessCentralSalesInvoicesAction',
    Params: [
        { Name: 'CompanyID', Type: 'Input', Value: 'your-company-id' },
        { Name: 'Status', Type: 'Input', Value: 'Open' },
        { Name: 'OnlyUnpaid', Type: 'Input', Value: true },
        { Name: 'IncludeLines', Type: 'Input', Value: true },
        { Name: 'MaxResults', Type: 'Input', Value: 100 }
    ],
    ContextUser: contextUser
});

API Reference

Base Classes

BaseAccountingAction

Abstract base class for all accounting actions. Provides shared credential management, validation, and formatting utilities.

| Method | Description | |--------|-------------| | getCompanyIntegration(companyId, contextUser) | Looks up the CompanyIntegration record for the given company and provider | | getCredentialFromEnv(companyId, credentialType) | Reads a credential from environment variables using the BIZAPPS_{PROVIDER}_{ID}_{TYPE} convention | | getOAuthTokens(integration) | Resolves OAuth tokens from env vars first, then database fallback | | getAPIBaseURL(contextUser) | Returns the NavigationBaseURL configured in the Integration entity | | validateAccountNumber(accountNumber) | Basic numeric account number validation | | validateJournalEntryBalance(lines) | Verifies total debits equal total credits within rounding tolerance | | formatCurrency(amount, currencyCode) | Formats a number as localized currency string | | formatAccountingDate(date) | Returns ISO 8601 date string (YYYY-MM-DD) |

QuickBooksBaseAction

Extends BaseAccountingAction for QuickBooks Online. Uses QBO query language for data retrieval and the QBO REST API for mutations.

| Method | Description | |--------|-------------| | makeQBORequest<T>(endpoint, method, body, contextUser) | Authenticated HTTP request to the QBO API | | queryQBO<T>(query, contextUser) | Executes a QBO query language statement | | mapAccountType(qboAccountType) | Maps QBO account types to standard categories (Asset, Liability, Equity, Revenue, Expense) | | parseQBODate(qboDate) / formatQBODate(date) | Date conversion between QBO and JS Date | | getQuickBooksAPIUrl(integration) | Resolves sandbox or production API URL |

BusinessCentralBaseAction

Extends BaseAccountingAction for Dynamics 365 Business Central. Uses OData v4 for all API interactions.

| Method | Description | |--------|-------------| | makeBCRequest<T>(endpoint, method, body, contextUser) | Authenticated HTTP request to the BC API | | queryBC<T>(resource, filters, select, expand, orderBy, top, contextUser) | Builds and executes an OData query | | buildFilterExpression(field, operator, value) | Generates an OData filter clause | | mapAccountType(bcAccountType) / mapAccountCategory(category) | Maps BC types to standard categories | | parseBCDate(dateString) / formatBCDate(date) | Date conversion between BC and JS Date | | getBusinessCentralAPIUrl(integration, tenantId, environment) | Builds the BC API URL from tenant/environment |

Exported Interfaces

QuickBooks

| Interface | Description | |-----------|-------------| | GLCode | Chart of Accounts entry with id, code, name, type, normal balance, and hierarchy info | | Transaction | Transaction record with type, date, amount, status, entity reference, and line items | | TransactionLine | Individual line within a transaction (amount, account, item, quantity, rate) | | AccountBalance | Account balance snapshot including current balance, sub-account balance, and normal balance side | | JournalEntryLine | Input structure for journal entry creation with accountId, debit/credit, entity references |

Business Central

| Interface | Description | |-----------|-------------| | BCGLAccount | GL account with number, category, balance, debit/credit amounts, and posting info | | BCGeneralLedgerEntry | Ledger entry with posting date, document info, debit/credit amounts, and optional dimensions | | BCDimensionSetLine | Dimension value attached to a GL entry | | BCCustomer | Customer record with contact info, address, balance, overdue amount, and sales totals | | BCAddress | Address structure (street, city, state, country code, postal code) | | BCSalesInvoice | Sales invoice with dates, amounts (excluding/including tax), remaining balance, and optional lines | | BCSalesInvoiceLine | Invoice line item with quantity, unit price, discount, tax, and net amounts |

Action Parameters Reference

Common Parameters (all actions)

| Parameter | Type | Required | Description | |-----------|------|----------|-------------| | CompanyID | string | Yes | MemberJunction Company ID | | FiscalYear | string | No | Fiscal year filter | | AccountingPeriod | string | No | Accounting period filter |

GetQuickBooksGLCodesAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | IncludeInactive | boolean | false | Include inactive accounts | | AccountTypes | string | -- | Comma-separated account types (Bank, Expense, Income, etc.) | | ParentAccountID | string | -- | Filter by parent account |

Output: GLCodes (GLCode[]), TotalCount (number)

GetQuickBooksTransactionsAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | TransactionType | string | -- | Specific type (Invoice, Bill, Payment, JournalEntry, Deposit, Purchase) or omit for all | | StartDate / EndDate | string | -- | Transaction date range (ISO 8601) | | EntityID | string | -- | Filter by customer or vendor ID | | MinAmount / MaxAmount | number | -- | Amount range filter | | MaxResults | number | 100 | Limit results (max 1000) |

Output: Transactions (Transaction[]), TotalCount (number), HasMore (boolean)

GetQuickBooksAccountBalancesAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | AsOfDate | string | today | Balance snapshot date | | AccountTypes | string | -- | Comma-separated account types | | IncludeInactive | boolean | false | Include inactive accounts | | IncludeZeroBalances | boolean | true | Include accounts with zero balance | | SummarizeByType | boolean | false | Return summary grouped by account type |

Output: AccountBalances (AccountBalance[]), TrialBalanceSummary, TypeSummary, TotalAccounts (number)

CreateQuickBooksJournalEntryAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | Lines | JournalEntryLine[] or JSON string | -- | Journal entry lines (required, minimum 2, must balance) | | EntryDate | string | today | Date of the entry | | DocNumber | string | auto | Journal entry number | | PrivateNote | string | -- | Internal memo | | AdjustmentEntry | boolean | false | Mark as adjustment entry |

Output: JournalEntryID (string), DocNumber (string), TotalAmount (number), CreatedDate (string)

GetBusinessCentralGLAccountsAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | IncludeBlocked | boolean | false | Include blocked accounts | | AccountTypes | string | -- | Comma-separated types (Posting, Heading, Total) | | Categories | string | -- | Comma-separated categories (Assets, Liabilities, Equity, Income, Expense) | | MinBalance / MaxBalance | number | -- | Balance range filter | | MaxResults | number | 1000 | Limit results |

Output: GLAccounts (BCGLAccount[]), TotalCount (number), Summary (object)

GetBusinessCentralGeneralLedgerEntriesAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | StartDate / EndDate | string | -- | Posting date range | | AccountNumber | string | -- | Filter by GL account number | | DocumentNumber | string | -- | Filter by document number | | DocumentType | string | -- | Filter by type (Payment, Invoice, etc.) | | MinAmount / MaxAmount | number | -- | Amount range filter | | IncludeDimensions | boolean | false | Include dimension set lines | | MaxResults | number | 500 | Limit results |

Output: GLEntries (BCGeneralLedgerEntry[]), TotalCount (number), Summary (object)

GetBusinessCentralCustomersAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | SearchText | string | -- | Search by name, number, or email | | IncludeBlocked | boolean | false | Include blocked customers | | CustomerType | string | -- | Filter by Company or Person | | MinBalance / MaxBalance | number | -- | Balance range filter | | OnlyOverdue | boolean | false | Only customers with overdue amounts | | SortBy | string | displayName | Sort field (displayName, number, balance, overdueAmount, lastModified) | | MaxResults | number | 100 | Limit results |

Output: Customers (BCCustomer[]), TotalCount (number), Summary (object)

GetBusinessCentralSalesInvoicesAction

| Parameter | Type | Default | Description | |-----------|------|---------|-------------| | CustomerNumber | string | -- | Filter by customer | | Status | string | -- | Filter by status (Draft, Open, Paid, etc.) | | StartDate / EndDate | string | -- | Invoice date range | | DueStartDate / DueEndDate | string | -- | Due date range | | MinAmount / MaxAmount | number | -- | Amount range filter | | OnlyUnpaid | boolean | false | Only invoices with remaining balance | | IncludeLines | boolean | true | Include line item details | | MaxResults | number | 100 | Limit results |

Output: Invoices (BCSalesInvoice[]), TotalCount (number), Summary (object)

Adding New Providers

The package is designed for extensibility. To add support for a new accounting system:

1. Create a provider directory under src/providers/{provider-name}/
2. Create a provider base class extending BaseAccountingAction:

   export abstract class NewProviderBaseAction extends BaseAccountingAction {
       protected accountingProvider = 'New Provider';
       protected integrationName = 'New Provider Full Name';
   
       // Implement provider-specific API methods
       protected async makeProviderRequest<T>(endpoint: string, ...): Promise<T> { ... }
   }

3. Implement individual action classes extending your provider base
4. Export the new actions and interfaces from src/index.ts

Dependencies

| Package | Purpose | |---------|---------| | @memberjunction/actions | BaseAction class and ActionEngineServer | | @memberjunction/actions-base | ActionParam, ActionResultSimple, RunActionParams types | | @memberjunction/core | Metadata, RunView, UserInfo | | @memberjunction/core-entities | CompanyIntegrationEntity, IntegrationEntity | | @memberjunction/global | @RegisterClass decorator |

Related Packages

• @memberjunction/actions -- Actions execution engine
• @memberjunction/actions-base -- Base classes and interfaces
• @memberjunction/actions-bizapps-lms -- LMS integration actions (same BizApps pattern)
• BizApps Overview -- Parent directory with shared patterns

Development

# Build the package
cd packages/Actions/BizApps/Accounting
npm run build

# Watch mode
npm run watch