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.

Overview

The deleteObjectsByProperties method allows you to delete entities from the Teamwork Graph based on specific property criteria. This is useful for removing entities that match certain conditions rather than knowing their exact external IDs.

Method signature

1
2
deleteObjectsByProperties(request: DeleteObjectsByPropertiesRequest): Promise<DeleteObjectsByPropertiesResponse>

Parameter: request

Type: DeleteObjectsByPropertiesRequest
Required: Yes
Description: The properties object containing criteria for object deletion.

1
2
// DeleteObjectsByPropertiesRequest object:
{
  properties: Record<string, string>;
  objectType: string;
  connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
}

Usage examples

Basic property-based deletion

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  properties: { environment: 'staging' },
  objectType: 'atlassian:document',
  connectionId: 'connection-id-123'
};
const response = await graph.deleteObjectsByProperties(request);
if (response.success) {
  console.log('Deletion completed successfully');
} else {
  console.error('Error deleting entities:', response.error);
}

For EAP, deleteObjectsByProperties supports only 1 key-value pair as shown in the above example.

Handling deletion response

1
2
const request = {
  properties: { environment: 'staging' },
  objectType: 'atlassian:document',
  connectionId: 'connection-id-123'
};
const response = await graph.deleteObjectsByProperties(request);
if (response.success) {
  console.log('All matching entities deleted successfully');
} else {
  console.error('Deletion failed:', response.error);
  if (response.originalError) {
    console.error('Original error:', response.originalError);
  }
}

Request limits

Only one property per request.

Request validation

The method validates the following:

Must be an object: The request must be a valid object.
Only contains one property: The property object must only contain one property criteria for deletion.

Error handling

Error message	Description
`properties must be an object`	The request is not an object.
`properties object cannot be empty`	The properties object is empty.
`Property-based deletion failed`	The overall operation failed.

Response

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

1
2
// DeleteObjectsByPropertiesResponse
{
  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 responses that ensure compile-time validation:

1
2
import { types } from '@forge/teamwork-graph';

// Type-safe request creation
const request: types.DeleteObjectsByPropertiesRequest = {
  properties: { environment: 'staging' },
  objectType: 'atlassian:document',
  connectionId: 'connection-id-123'
};

const response = await graph.deleteObjectsByProperties(request);
if (response.success) {
  // TypeScript knows success is true here
  console.log('All matching entities deleted 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 must be a valid object with string key-value pairs
response.success is always a boolean
response.error and response.originalError are properly typed when present
Compile-time validation prevents type mismatches