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 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
   connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
 }

Usage examples

Basic bulk deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  externalIds: ['developers', 'admins'],
  connectionId: 'connection-id-123'
};
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'],
  connectionId: 'connection-id-123'
};
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

Error message	Description
`externalIds must be an array`	The `externalIds` field is not an array.
`externalIds array cannot be empty`	The `externalIds` array is empty.
`Failed to delete groups by external ID`	The API request failed.

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'],
  connectionId: 'connection-id-123'
};

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