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 field (with predefined values)
• 0 parameterized fields (accept query options)

Simple Fields

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.

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.

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.

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.

Enum Fields

syncStatuses

Indicates the synchronization status of a transaction or record with external systems such as QuickBooks Online. Possible statuses include: "Not synced", "Synced", "Partially synced", "Excluded from syncing", "Has error", and "Invalid".