deleteGroupsByExternalId

The deleteGroupsByExternalId method allows you to bulk delete multiple groups from the Teamwork Graph using their external IDs. This is useful for removing groups in batches when you know their external identifiers.

Method signature

1
2
deleteGroupsByExternalId(request: DeleteGroupsByExternalIdRequest): Promise<DeleteGroupsByExternalIdResponse>

Parameter: request

• Type: DeleteGroupsByExternalIdRequest
• Required: Yes
• Description: The bulk deletion request containing external IDs.

1
2
 // DeleteGroupsByExternalIdRequest object:
 {
   externalIds: string[]; // externalIds: Array of external identifiers of groups to delete
 }

Usage examples

Basic bulk deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalIds: ['developers', 'admins']
};
const response = await graph.deleteGroupsByExternalId(request);
if (response.success) {
  console.log('Deletion results:', response.results);
} else {
  console.error('Error deleting groups:', response.error);
}

Handling deletion results

1
2
const request = {
  externalIds: ['developers', 'designers', 'managers', 'qa-team']
};
const response = await graph.deleteGroupsByExternalId(request);
if (response.success && response.results) {
  response.results.forEach(result => {
    // Check status code to determine success (200-299 indicates success)
    if (result.statusCode && result.statusCode >= 200 && result.statusCode < 300) {
      console.log(`Successfully deleted group: ${result.externalId}`);
    } else {
      console.error(`Failed to delete group ${result.externalId}. Status: ${result.statusCode}, Message: ${result.message}`);
    }
  });
}

Request limits

• Maximum external IDs per request: 100
• Minimum external IDs per request: 1

Request validation

The method validates the following:

• externalIds must be an array: The externalIds field must be a valid array.
• externalIds cannot be empty: The externalIds array cannot be empty.
• Maximum limit: Cannot exceed 100 externalIds per request.

Error handling

Response

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

1
2
// GroupDeleteResult
type GroupDeleteResult = {
  externalId: string;        // The external ID that was processed
  statusCode?: number;       // HTTP status code for this specific deletion
  message?: string;          // Message for this specific deletion
};

// DeleteGroupsByExternalIdResponse
{
  success: boolean;           // Indicates if the overall operation was successful
  results?: GroupDeleteResult[]; // Array of results for each requested group
  error?: string;            // Overall error message (if operation failed)
  originalError?: unknown;   // Original error object (if available)
}

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.DeleteGroupsByExternalIdRequest = {
  externalIds: ['developers', 'designers']
};

// Type-safe response handling
const response = await graph.deleteGroupsByExternalId(request);
if (response.success && response.results) {
  // TypeScript knows results exists here and provides proper typing
  response.results.forEach(result => {
    // result is properly typed as GroupDeleteResult
    // Note: GroupDeleteResult uses statusCode to indicate success, not a success property
    if (result.statusCode && result.statusCode >= 200 && result.statusCode < 300) {
      console.log(`Successfully deleted group: ${result.externalId}`);
    } else {
      console.error(`Failed to delete group: ${result.externalId}. Status: ${result.statusCode}, Message: ${result.message}`);
    }
  });
} else {
  // TypeScript knows error exists here
  console.error('Deletion failed:', response.error);
  
  // Safely access originalError if available
  if (response.originalError) {
    console.error('Original error details:', response.originalError);
  }
}

The type system ensures:

• request.externalIds must be a string array
• response.results is properly typed as GroupDeleteResult[] when success is true
• Each result has externalId, statusCode, and message properties (no success property)
• Compile-time validation prevents type mismatches