EAPs are offered to selected users for testing and feedback purposes. We are currently working with a select group of EAP participants to get their apps production-ready and available for publishing on Marketplace.

To use the Connector SDK, you must be part of the Forge connector EAP. If you are interested in joining this EAP, you can express interest through this form.

The getUserByExternalId method allows you to retrieve a specific user from the Teamwork Graph using their external ID. This is useful for fetching individual users when you know their external identifier.

Method signature

1
2
getUserByExternalId(request: GetUserByExternalIdRequest): Promise<GetUserByExternalIdResponse>

Parameter: request

Type: GetUserByExternalIdRequest
Required: Yes
Description: The request containing the external ID.

1
2
// GetUserByExternalIdRequest object:
{
  externalId: string; // externalId: The external identifier of the user
  connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
}

Usage examples

Basic user retrieval

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalId: 'user-123',
  connectionId: 'connection-id-123'
};
const response = await graph.getUserByExternalId(request);
if (response.success) {
  console.log('User found:', response.user);
} else {
  console.error('Error retrieving user:', response.error);
}

Accessing user properties

1
2
const response = await graph.getUserByExternalId({
  externalId: 'user-123',
  connectionId: 'connection-id-123'
});
if (response.success && response.user) {
  const user = response.user;
  console.log('User ID:', user.id);
  console.log('Display Name:', user.displayName);
  console.log('Username:', user.userName);
  console.log('Nickname:', user.nickname);
  if (user.name) {
    console.log('Full Name:', user.name.formatted);
    console.log('First Name:', user.name.givenName);
    console.log('Last Name:', user.name.familyName);
  }
  if (user.emails) {
    const primaryEmail = user.emails.find(email => email.primary);
    console.log('Primary Email:', primaryEmail?.value);
  }
  if (user.extendedProfile) {
    console.log('Job Title:', user.extendedProfile.jobTitle);
    console.log('Department:', user.extendedProfile.department);
    console.log('Organization:', user.extendedProfile.organization);
    console.log('Location:', user.extendedProfile.location);
  }
}

Request limits

Only one externalId per request.

Request validation

The method validates the following:

externalId required: The externalId field must be a non-empty string.
Only contains one externalId: The request only contains one externalId.

Error handling

Error message	Description
`externalId is required`	The `externalId` is missing or empty.
`User not found`	The specified user doesn't exist (API response).
`Failed to get user by external ID`	The API request failed.

Response

The method returns a promise that resolves to a GetUserByExternalIdResponse object.

1
2
// GetUserByExternalIdResponse
{
  success: boolean;           // Indicates if the operation was successful
  user?: User;               // The retrieved user (if found)
  error?: string;            // Error message (if operation failed)
  originalError?: unknown;   // Original error object (if available)
}

User object structure

The returned User object contains comprehensive user information:

1
2
type User = {
  id?: string;                    // Internal user ID (ARI)
  externalId: string;            // External identifier
  userName?: string;             // Username
  name?: UserName;               // Structured name information
  nickname?: string;             // User's nickname
  displayName?: string;          // Display name
  photos?: UserPhoto[];          // User profile photos
  emails?: UserEmail[];          // User email addresses
  extendedProfile?: UserExtendedProfile; // Additional profile information
};

Type safety

The SDK provides type-safe request and response objects that ensure compile-time validation:

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

// Type-safe request creation
const request: types.GetUserByExternalIdRequest = {
  externalId: 'user-123',
  connectionId: 'connection-id-123'
};

// Type-safe response handling
const response = await graph.getUserByExternalId(request);
if (response.success && response.user) {
  // TypeScript knows user exists here and provides proper typing
  const user = response.user;
  // Access user properties safely with full type support
  console.log('User ID:', user.id);
  console.log('Display Name:', user.displayName);
  if (user.emails) {
    // TypeScript knows emails is an array of UserEmail
    const primaryEmail = user.emails.find(email => email.primary);
    console.log('Primary Email:', primaryEmail?.value);
  }
}

The type system ensures:

request.externalId must be a string
response.user is properly typed as User when success is true
All user properties have correct types and optional/required status
Compile-time validation prevents type mismatches