API Reference
Start typing to search…

Connection Relation

Connection Relation

Overview

Connection Relations track the integration status between Finale records and external systems like marketplaces, shipping platforms, and accounting software. They record which external system a record is connected to, what the external identifier is, whether synchronization is up to date, and any errors that have occurred during sync operations.

Every integrated record can have multiple connection relations, one for each external system it's connected to. A sales order might have a connection relation to Shopify (showing the Shopify order ID), another to ShipStation (showing the ShipStation order number), and another to QuickBooks (showing the QuickBooks invoice number). This multi-connection capability supports complex integration scenarios where data flows between multiple systems.

The sync status indicates whether the record is in sync with the external system. Statuses like "synced", "pending sync", "sync error", or "excluded from sync" show the current state. This visibility helps operations teams understand integration health and troubleshoot issues. When a sync fails, the status changes immediately, alerting users to investigate.

Error tracking captures what went wrong when synchronization fails. The error details field stores the specific error message from the external system. The error date shows when the problem occurred. This information is essential for troubleshooting - you can see that an order failed to sync to Shopify at 3:45 PM with a specific error about missing address information, giving you exactly what you need to fix it.

Error resolution tracking shows when errors are fixed. When you correct the data and successfully resync, the error resolution date is set. This creates a complete timeline of the problem and its resolution. Historical error data helps identify recurring issues that might need integration improvements or process changes.

Document numbers from external systems are stored in connection relations. When an order syncs to an accounting system and gets an invoice number, that number is stored here. When a shipment syncs to a carrier and gets a tracking number, that's captured too. These external identifiers support cross-system reconciliation and customer service operations.

The GraphQL API exposes connection relations on most major collections. When querying orders, shipments, or invoices, you can include connection relations to see integration status. This lets you build custom interfaces showing sync status or diagnostic tools identifying integration problems. The relations support filtering, so you can query "all orders with sync errors" or "all shipments not yet synced to ShipStation."

GraphQL API

The connectionRelation collection provides access to connectionRelation data via the GraphQL API. All queries use the Relay connection specification with cursor-based pagination.

Query Name: connectionRelationViewConnection

Available Features:

  • Cursor-based pagination (first/last/after/before)

Query Examples

Basic Query

The connectionRelation collection is accessed via the connectionRelationViewConnection query, which returns a Relay-style connection with pagination support.

query {
  connectionRelationViewConnection(first: 10) {
    edges {
      node {
        documentNumbers
        errorDates
        errorDetails
        errorResolutionDates
        syncStatuses
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

# First page
query {
  connectionRelationViewConnection(first: 50) {
    edges {
      node { documentNumbers }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

# Subsequent pages
query {
  connectionRelationViewConnection(first: 50, after: "cursor-from-previous-page") {
    edges {
      node { documentNumbers }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Fields

This collection has 5 fields:

  • 4 simple fields
  • 1 enum fields (with predefined values)
  • 0 parameterized fields (accept query options)

Note on Field Formatting: All scalar fields support the formatter argument to control output format. Available options: "html", "none", "abbreviated", "blank-zero". Some fields have a default formatter (shown below). See the Formatting guide for details.

Note on Sorting: Field sortability may vary depending on the UI context and query parameters used. Some parameter options explicitly disable sorting (marked with ⚠️ not sortable).

Simple Fields

These fields return values directly without additional options.

documentNumbers

The document numbers or names assigned to synced records in QuickBooks Online. This field displays the QuickBooks document identifiers (such as invoice numbers, bill numbers, or journal entry names) that correspond to records synced from Finale.

When a single record is synced to one QuickBooks connection, the field shows a simple document number (e.g., "I547-1"). When a record is synced to multiple QuickBooks connections, the field displays connection-prefixed entries separated by semicolons (e.g., "QuickBooks Online C: I545-1, I545-2; QuickBooks Online B: I545-2"), where each connection name precedes its associated document numbers.

The field can represent various QuickBooks document types including invoices, bills, purchase orders, journal entries, and master records (customers or vendors). When formatted as HTML, document numbers appear as clickable links that open the corresponding record directly in QuickBooks Online. If a record has not been synced to QuickBooks, this field is empty.

Label: QuickBooks Online names
Sortable: No
Default Formatter: html

Example Query:

{
  connectionRelation(connectionRelationUrl: "example-url") {
    documentNumbers    # Uses default formatter: html
    documentNumbersRaw: documentNumbers(formatter: "none")  # Get raw value
  }
}

errorDates

The date when the most recent sync error occurred for this connection relation. This field tracks when synchronization attempts to external accounting systems (like QuickBooks Online) failed for a particular transaction or document. The field displays the error start date from the lastSyncError object, representing when an error was first detected during a sync operation. When multiple connections exist for the same document, the field can display multiple error dates prefixed by the connection name (e.g., "QuickBooks Online C: 7/22/2022"). The field returns an empty string when no active errors exist, either because the document has never encountered a sync error or because previous errors have been resolved. This field is commonly used alongside errorDetails and errorResolutionDates to track the lifecycle of synchronization issues and help users identify when problems began.

Label: Latest error date
Sortable: No

errorDetails

Displays detailed error messages or skip reasons for documents that failed to sync or were excluded from syncing with external accounting systems like QuickBooks Online. When a document encounters a sync error that has not been resolved (no error end date), this field shows the specific error message from the lastSyncError.errorDetail property. If no active error exists but the document was intentionally excluded, it displays the skipReason instead.

The field supports HTML formatting to create links to help documentation when specific error types (errorMetaType) are detected. Common error scenarios include unmapped accounts, missing products, inactive entities, items not found in the external system, documents that cannot be updated because they are posted, and various validation failures. The error detail text is automatically capitalized and formatted for display, with special handling to separate prefixes from the main error message.

When multiple connections exist for the same document, the field can show connection-specific errors in the format "Connection Name: error message". Empty values indicate the document has no sync errors and is not excluded from syncing.

Label: Sync status details
Sortable: No
Default Formatter: html

Example Query:

{
  connectionRelation(connectionRelationUrl: "example-url") {
    errorDetails    # Uses default formatter: html
    errorDetailsRaw: errorDetails(formatter: "none")  # Get raw value
  }
}

errorResolutionDates

The date and time when a sync error was resolved. When a transaction that previously failed to sync successfully syncs to the external system (such as QuickBooks Online), the system records this timestamp to indicate when the error was cleared. An empty value indicates that the error is still unresolved or that no error has occurred. This field pairs with errorDates to show the full lifecycle of sync errors, allowing users to track how long errors persisted before being resolved.

Label: Error resolution dates
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

syncStatuses

Indicates the synchronization status of a transaction or record with external systems such as QuickBooks Online. When multiple integrations are configured, this field displays the sync status for each connection separately (e.g., "QuickBooks Online C: Synced; QuickBooks Online B: Excluded from syncing"). Possible statuses include: "Not synced" (not yet pushed to the external system), "Synced" (successfully synchronized), "Partially synced" (some but not all data synced), "Excluded from syncing" (intentionally skipped), "Has error" (sync failed with an error), and "Invalid" (record cannot be synced due to validation issues). The field may be empty when no integrations are configured or when the record has not been processed for syncing.

Label: Sync status
Sortable: No

Possible Values:

  • ##crStatusNotPushed - Not synced
  • ##crStatusPushed - Synced
  • ##crStatusPartiallySynced - Partially synced
  • ##crStatusSkipped - Excluded from syncing
  • ##crStatusError - Has error
  • ##crStatusInvalid - Invalid

Relations

No relations available.

Filters

No filters available.