deleteRelationship

The deleteRelationship method allows you to delete a specific relationship between entities in the Teamwork Graph.

Method signature

1
2
deleteRelationship(request: DeleteRelationshipRequest): Promise<DeleteRelationshipResponse>

Parameter: request

• Type: DeleteRelationshipRequest
• Required: Yes
• Description: The delete relationship request containing the relationship to delete.

Request Type: DeleteRelationshipRequest

1
2
{
  from: RelationshipEntity;           // Required - Source entity
  to: RelationshipEntity;             // Required - Target entity
  type: string;                       // Required - Relationship type
  updateSequenceNumber: number;       // Required - Must be >= 0
  connectionId: string;               // Required - Connection identifier
}

Response Type: DeleteRelationshipResponse

1
2
{
  success: boolean;
  error?: string;
  originalError?: unknown;
}

Constraints

• Required fields: from, to, type, updateSequenceNumber, connectionId
• updateSequenceNumber: Must be a non-negative number
• All entity fields (from.type, from.value, to.type, to.value) are required

Usage examples

Delete a relationship

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

const response = await graph.deleteRelationship({
  from: {
    type: 'atlassian:team',
    value: {
      entityId: 'team-id-1'
    }
  },
  to: {
    type: 'issueWorklogId',
    value: {
      issueId: '10001',
      worklogId: '20002'
    }
  },
  type: 'external-team-works-on-worklog',
  updateSequenceNumber: 1,
  connectionId: 'your-connection-id'
});

if (response.success) {
  console.log('Relationship deleted successfully');
  // Response: { success: true }
} else {
  console.error('Error:', response.error);
}

Complete example with error handling

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

async function deleteRelationship(connectionId: string) {
  try {
    const response = await graph.deleteRelationship({
      from: {
        type: 'atlassian:team',
        value: {
          entityId: 'team-id-1'
        }
      },
      to: {
        type: 'issueWorklogId',
        value: {
          issueId: 'PT-1',
          worklogId: '10000'
        }
      },
      type: 'external-team-works-on-worklog',
      updateSequenceNumber: 1,
      connectionId: connectionId
    });

    if (response.success) {
      console.log('Relationship deleted successfully');
      // response = { success: true }
      return response;
    } else {
      console.error('Failed to delete relationship:', response.error);
      throw new Error(response.error);
    }
  } catch (error) {
    console.error('Error deleting relationship:', error);
    throw error;
  }
}

Request validation

The method validates the following:

• Required fields: from, to, type, updateSequenceNumber, connectionId must all be provided
• updateSequenceNumber: Must be a non-negative number (>= 0)
• Entity fields: from.type, from.value, to.type, to.value must all be provided

Error handling

Response

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

Success response

On successful deletion, the API returns HTTP status 202 Accepted and the response contains:

1
2
{
  "success": true
}

Example:

1
2
const response = await graph.deleteRelationship({
  from: {
    type: 'atlassian:team',
    value: { entityId: 'team-id-1' }
  },
  to: {
    type: 'issueWorklogId',
    value: { issueId: '10001', worklogId: '20002' }
  },
  type: 'external-team-works-on-worklog',
  updateSequenceNumber: 1,
  connectionId: 'your-connection-id'
});

// response = { success: true }

Error response

1
2
{
  "success": false,
  "error": "Failed to delete relationship: Bad Request - {details}",
  "originalError": {
    "code": "API_ERROR",
    "details": {
      "status": 400,
      "responseBody": { /* error details */ }
    }
  }
}

TypeScript Types Reference

All types are exported from @forge/teamwork-graph:

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

// Available types:
// - types.DeleteRelationshipRequest
// - types.DeleteRelationshipResponse
// - types.RelationshipEntity
// - types.RelationshipEntityValue

Best Practices

1. Update Sequence Numbers: Always increment updateSequenceNumber when deleting relationships to ensure proper conflict resolution
2. Error Handling: Always check the success field and handle errors appropriately
3. Connection ID: Always provide a valid connectionId for your connector
4. Entity Matching: Ensure the from and to entities exactly match the relationship you want to delete