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
 }

Usage examples

Basic group retrieval

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalId: 'developers'
};
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'
});
if (response.success && response.group) {
  const group = response.group;
  console.log('Group ID:', group.id);
  console.log('External ID:', group.externalId);
  console.log('Display Name:', group.displayName);
  if (group.members) {
    console.log(`Group has ${group.members.length} members:`);
    group.members.forEach(member => {
      console.log(`- ${member.displayName || member.externalId} (${member.type})`);
    });
  }
  if (group.meta) {
    console.log('Created:', group.meta.created);
    console.log('Last Modified:', group.meta.lastModified);
    console.log('Resource Type:', group.meta.resourceType);
  }
}

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 comprehensive group information:

1
2
type Group = {
  id: string;                    // Internal group ID (ARI)
  externalId: string;            // External identifier
  displayName?: string;          // Display name for the group
  members?: GroupMember[];       // Array of group members
  meta?: {                       // Metadata
    resourceType: string;
    created: string;
    lastModified: string;
    location: string;
  };
};

type GroupMember = {
  externalId: string;            // External identifier for the member
  type: string;                  // Type of member (e.g., 'USER')
  updateSequenceNumber?: number; // Sequence number for tracking updates
  displayName?: string;          // Display name for the member
};

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'
};

// 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);
  if (group.members) {
    // TypeScript knows members is an array of GroupMember
    group.members.forEach(member => {
      // member is properly typed as GroupMember
      console.log(`Member: ${member.externalId} (${member.type})`);
    });
  }
}

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, members, and meta are correctly typed
• GroupMember objects have the correct structure with externalId, type, updateSequenceNumber, and displayName
• Compile-time validation prevents type mismatches