User Login

Overview

User Logins represent the user accounts that access Finale. Each login belongs to a person who uses the system, with authentication credentials, permission settings, and activity tracking. User management ensures that only authorized people can access sensitive business data and that their actions are tracked for accountability.

Each user login has authentication information - typically a username and password, though the system can support other authentication methods through integration. The authentication layer controls who can log into Finale, forming the first line of security for your business data.

Permission assignments control what each user can do once logged in. Users can be assigned roles that grant permission to modify certain records (like orders or products) or perform certain operations (like posting invoices or voiding payments). This granular permission control ensures users can do their jobs without accessing functions outside their responsibility.

User logins track activity for accountability. When a user creates a shipment, modifies an order, or adjusts inventory, their user login is recorded on the transaction. This creates an audit trail showing who did what and when. This accountability is essential for fraud prevention, error investigation, and operational analysis.

User settings and preferences can be stored per login. Display preferences, default warehouses, favorite reports, and other personalization settings make Finale more efficient for each user. These preferences are tied to the login, so users get their customized experience regardless of which device they use.

Active and inactive status controls whether a user can log in. When an employee leaves the company, their user login is inactivated rather than deleted. This preserves the historical record of their transactions while preventing further access. The inactive user's name still appears on old transactions, maintaining data integrity.

Integration users are special user logins used by automated integrations. When a Shopify integration creates orders, those orders are attributed to the integration's user login. This distinguishes automated actions from human actions in the audit trail. Integration users typically have specific permissions limited to what the integration needs to do, following the principle of least privilege for security.

GraphQL API

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

Query Name: userLoginViewConnection

Available Features:

Cursor-based pagination (first/last/after/before)
3 filter options

Query Examples

Basic Query

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

query {
  userLoginViewConnection(first: 10) {
    edges {
      node {
        accountType
        name
        primaryEmail
        userLoginUrl
      }
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Pagination

Use cursor-based pagination to retrieve large datasets:

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

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

Filtering

Apply filters to narrow results (see Filters section for all available options):

query {
  userLoginViewConnection(
    first: 10
    accountType: ["##finaleStaff"]
  ) {
    edges {
      node { accountType }
    }
  }
}

Summary and Aggregation

This collection supports metrics aggregation through the summary field. You can calculate totals, averages, counts, and other aggregate values across filtered data.

Note: This collection does not support groupBy dimensions. For dimensional analysis, use collections like product, order, or invoice.

For a comprehensive guide to using aggregations, see the Aggregation Concept Guide.

Query Structure

userLoginViewConnection(filters...) {
  summary {
    errorCode
    errorMessage
    metrics {
      # Calculated metrics (see table below)
    }
  }
}

Available Metrics

This collection provides 1 metric that can be aggregated:

Metric	Parameters	Description
`count`	None	Count of items in the result set

Common Parameters:

operator - Aggregation function: sum, mean, min, max
transform - Mathematical transformation: abs
dateRange - Filter to specific date range
facilityUrlList - Filter to specific facilities

Examples

Example 1: Total userLogin Metrics

Calculate aggregate metrics across all userLogin records:

query {
  userLoginViewConnection(first: 1) {
    summary {
      errorCode
      errorMessage
      metrics {
        totalCount: count
      }
    }
  }
}

Expected result structure:

{
  "data": {
    "userLoginViewConnection": {
      "summary": {
        "errorCode": null,
        "errorMessage": null,
        "metrics": {
          "totalCount": [1523]
        }
      }
    }
  }
}

Fields

This collection has 4 fields:

3 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.

`name`

A computed display name for the user that varies based on the account type. For normal Finale users, this returns the userLoginId (username). For external authentication users, it returns the externalAuthIdName if available, or defaults to "Fireworks user" if not set. For Finale staff accounts, it returns "Finale staff", and for API connection accounts it returns "API connection". This field is used throughout the system to display human-readable user names in transaction histories, attribution labels, and audit trails. The value is computed by the formattedUserLogin utility function based on the user's account type and associated metadata.

Label: Name
Sortable: No

`primaryEmail`

The verified email address associated with a user login account. This field is used for password recovery, account notifications, and user invitations. When a new user is added or an email address is changed, the system stores the new address as an unverified email and sends a verification link. Once the user clicks the verification link, the unverified email becomes the primary email. The field can be empty for certain account types like API connections and external authentication users. For regular Finale users, the primary email is required and must be validated before it can be used for authentication purposes.

Label: Primary email
Sortable: No

`userLoginUrl`

The unique identifier (primary key) for a user login record. This URL is automatically generated by the server and serves as a reference to the user throughout the system, appearing in transaction histories, status change records, and audit trails to track which user performed specific actions. The field is commonly used in authorization contexts to identify the current logged-in user and in statusIdHistoryList entries to record which user made status changes or created transactions.

IMPORTANT: Treat URL values as opaque strings supplied by the server. Do not attempt to parse, interpret, or construct URL values manually:

ID values embedded in URLs may differ from entity ID values
The URL structure is an internal implementation detail subject to change
Manually constructing URLs can lead to bugs and system errors
Always use URL values exactly as provided by the API

Label: User Login Url
Sortable: No

Enum Fields

These fields return one of a predefined set of values.

`accountType`

A computed field that categorizes user accounts into distinct types based on their ID ranges and authentication methods. The value is determined by the userLoginType utility function using the following logic: accounts with IDs between 10000-10099 or with Finale staff external authentication are categorized as "Finale staff"; accounts with IDs 10100 and above are "External user" (authenticated through external systems like Fireworks); accounts with IDs starting with "API_KEY_" and no associated party are "API connection"; and all other accounts are "Finale user" (standard internal users). This field is commonly used for filtering and grouping in reports, transaction histories, and general ledger views. It can be filtered in GraphQL queries using values like "##finaleStaff", "##externalAuth", "##apiConnection", and "##normal" to restrict results to specific account types.

Label: Account type
Sortable: No

Possible Values:

##none - null
##finaleStaff - Finale staff
##externalAuth - External user
##apiConnection - API connection
##normal - Finale user

Relations

No relations available.

Filters

accountType

Label: Account type
Type: List|String
Enabled: Yes
Options:
- API connection (##apiConnection)
- External user (##externalAuth)
- Finale staff (##finaleStaff)
- Finale user (##normal)

Filter Type: Predefined options

Get Current Options:

These options may vary by account configuration. To get the current list:

query {
  dataSetMeta(purpose: "uiProduct") {
    dataSets(name: "userLogin") {
      filters {
        name
        optionList {
          value
          label
        }
      }
    }
  }
}

Usage Example:

query {
  userLoginViewConnection(
    first: 10
    accountType: ["##finaleStaff", "##externalAuth"]
  ) {
    edges {
      node {
        name
        accountType
      }
    }
  }
}

search

Label: Not specified
Type: SearchString
Enabled: Yes

Filter Type: Search text

This filter performs a text search across multiple fields.

Usage Example:

query {
  userLoginViewConnection(
    first: 10
    search: "search term"
  ) {
    edges {
      node {
        name
      }
    }
  }
}

searchCustom

Label: Not specified
Type: searchCustomFilter
Enabled: Yes

Filter Type: Advanced search with result expansion

See the Advanced Search guide for complete documentation on how this filter works.

Collection-Specific Examples:

Example 1: Basic search:

query {
  userLoginViewConnection(
    first: 10
    searchCustom: {
      terms: "red widget"
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

Example 2: Include additional fields in search:

# Searches defaults PLUS custom fields
query {
  userLoginViewConnection(
    first: 10
    searchCustom: {
      terms: "acme"
      include: ["customField1", "customField2"]
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

Example 3: Expand results to include related records:

# For each match, also return the related record
query {
  userLoginViewConnection(
    first: 10
    searchCustom: {
      terms: "urgent"
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}

Example 4: Combine include and extend:

# Search in defaults + additional fields, then expand to related records
query {
  userLoginViewConnection(
    first: 10
    searchCustom: {
      terms: "acme corp"
      include: ["customField1"]
      extend: ["relatedRecordUrl"]
    }
  ) {
    edges {
      node {
        name
      }
    }
  }
}