deleteObjectsByExternalId

The deleteObjectsByExternalId method allows you to bulk delete multiple entities from the Teamwork Graph using their external IDs and object type. This is useful for removing entities in batches when you know their external identifiers.

Method Signature

1
2
deleteObjectsByExternalId(request: DeleteObjectsByExternalIdRequest): Promise<DeleteObjectsByExternalIdResponse>

Parameter: request

• Type: DeleteObjectsByExternalIdRequest
• Required: Yes
• Description: The bulk deletion request containing object type and external IDs.

1
2
// DeleteObjectsByExternalIdRequest object:
{
  objectType: string;    // objectType: The type of object to delete (e.g., 'atlassian:document', 'atlassian:message')
  externalIds: string[]; // externalIds: Array of external identifiers of entities to delete
}

Usage examples

Basic bulk deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  objectType: 'atlassian:document',
  externalIds: ['pipelines/123/builds/456', 'pipelines/123/builds/789']
};
const response = await graph.deleteObjectsByExternalId(request);
if (response.success) {
  console.log('Deletion success');
} else {
  console.error('Error deleting entities:', response.error);
}

Deleting different object types

1
2
// Delete document entities
const documentRequest = {
  objectType: 'atlassian:document',
  externalIds: ['api-doc-1', 'api-doc-2', 'api-doc-3']
};
const documentResponse = await graph.deleteObjectsByExternalId(documentRequest);
// Delete message entities
const messageRequest = {
  objectType: 'atlassian:message',
  externalIds: ['msg-1', 'msg-2', 'msg-3']
};
const messageResponse = await graph.deleteObjectsByExternalId(messageRequest);

Handling deletion results

1
2
const request = {
  objectType: 'atlassian:document',
  externalIds: ['doc-1', 'doc-2', 'doc-3', 'doc-4']
};
const response = await graph.deleteObjectsByExternalId(request);
if (response.success) {
  console.log('All objects deleted successfully');
} else {
  console.error('Deletion failed:', response.error);
  if (response.originalError) {
    console.error('Original error:', response.originalError);
  }
}

Request limits

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

Request validation

The method validates the following:

• objectType required: The objectType field must be a non-empty string.
• 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 external IDs per request.

Error handling

Response

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

1
2
// DeleteObjectsByExternalIdResponse
{
  success: boolean;           // Indicates if the overall operation was successful
  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.DeleteObjectsByExternalIdRequest = {
  objectType: 'atlassian:document',
  externalIds: ['doc-1', 'doc-2', 'doc-3']
};

// TypeScript will enforce the correct structure
const response = await graph.deleteObjectsByExternalId(request);

// Type-safe response handling
if (response.success) {
  // TypeScript knows success is true here
  console.log('Deletion completed successfully');
} 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.objectType must be a string
• request.externalIds must be a string array
• response.success is always a boolean
• response.error and response.originalError are properly typed when present
• Compile-time validation prevents type mismatches