getGroupByExternalId

The getGroupByExternalId method allows you to retrieve a specific group from the Teamwork Graph using its external ID. This is useful for fetching individual groups when you know their external identifier.

Method signature

1
2
getGroupByExternalId(request: GetGroupByExternalIdRequest): Promise<GetGroupByExternalIdResponse>

Parameter: request

• Type: GetGroupByExternalIdRequest
• Required: Yes
• Description: The request containing the external ID

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

Usage examples

Basic group retrieval

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

Accessing group properties

1
2
const response = await graph.getGroupByExternalId({
  externalId: 'developers',
  connectionId: 'connection-id-123'
});
if (response.success && response.group) {
  const group = response.group;
  console.log('Group ID:', group.id);
  console.log('External ID:', group.externalId);
}

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

Response

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

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

Group object structure

The returned Group object contains following group information:

1
2
type Group = {
  id: string;                    // Internal group ID (ARI)
  externalId: string;            // External identifier
  displayName?: string;          // Display name for the group
};

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.GetGroupByExternalIdRequest = {
  externalId: 'developers',
  connectionId: 'connection-id-123'
};

// Type-safe response handling
const response = await graph.getGroupByExternalId(request);
if (response.success && response.group) {
  // TypeScript knows group exists here
  const group = response.group;
  // Access group properties safely with proper typing
  console.log('Group ID:', group.id);
  console.log('External ID:', group.externalId);
}

The type system ensures:

• request.externalId must be a string
• response.group is properly typed as Group when success is true
• Group properties like id, externalId, displayName
• Compile-time validation prevents type mismatches