A connector can work during setup and fail later because credentials expire, permissions change, or a configured source is removed. Teamwork Graph can reuse your connector's existing validateConnection function after setup to identify these problems and report when the connection recovers.

A periodic health check invokes your existing validateConnection function and verifies only what that function checks. It does not run ingestion, inspect indexed objects, or measure data freshness.

Configure connection validation

Declare validateConnection under datasource.formConfiguration in your graph:connector module. You do not need to declare a separate health-check callback. For a complete manifest and function example, see Build a Teamwork Graph connector.

The typed response and reason-code constants require @forge/teamwork-graph@5.3.0-next.1 or later. Import them from the types export:

1
2
import { types } from '@forge/teamwork-graph';

Return a result or throw an error based on the type of failure:

Result	When to use it	Health treatment
`{ success: true }`	The configured source and required access are available.	The health check passes. A successful check can clear a previous health-check failure.
`success: false` with `INVALID_CREDENTIALS`	Credentials are invalid or expired.	The connection is reported as unhealthy with guidance for the admin.
`success: false` with `INSUFFICIENT_PERMISSIONS`	The connector no longer has the access required for ingestion.	The connection is reported as unhealthy with guidance for the admin.
`success: false` with `INVALID_CONFIGURATION`	A configured source or another setting is invalid.	The connection is reported as unhealthy with guidance for the admin.
Throw an error.	The provider, network, timeout, or rate-limit failure is transient.	Teamwork Graph treats the failure as transient and reports the connection as unhealthy only after repeated failed checks.

Return success: false only for a deterministic problem that an admin can fix. Do not classify a provider response from its HTTP status alone when that status can represent both deterministic and transient failures. For example, some providers use HTTP 403 for both permission errors and rate limits. Inspect the provider's structured error response and throw the transient case.

Make the check representative and safe

The check should make the smallest read-only provider request that verifies the configuration and access needed by ingestion. For example, if ingestion reads a configured folder, verify that the folder exists and that the connector can list its contents. A general provider endpoint may succeed even when the connector cannot read the configured source.

Keep validateConnection:

Read-only: Do not create, update, or delete third-party data.
Idempotent: Repeated calls with the same configuration must be safe.
Inexpensive: Request only the minimum data needed to evaluate the connection.

Never return or log credentials, secrets, configuration values, or raw provider errors.

Cadence and compatibility

When periodic health evaluation is enabled for a connection, Atlassian currently invokes validateConnection approximately every eight hours. Timing can vary, and the interval may change.

Existing validators that complete normally without returning a structured result remain compatible. New and updated connectors should return the typed response. Although reasonCode is optional, provide a recognized reason code when returning success: false so Atlassian Administration can show more specific guidance.

What admins see

When a health check reports an administrator-fixable problem, the connector can appear as unhealthy in Atlassian Administration and admins can be notified. A later successful check clears the health-check failure and can trigger a recovery notification.

App-authored messages are not displayed in the connector UI or health notification emails. Atlassian maps recognized reason codes to standard administrator guidance.