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

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

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