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

Error message	Description
`{field} is required`	A required field is missing from the request.
`updateSequenceNumber must be a non-negative number`	The updateSequenceNumber is negative or invalid.
`Failed to delete relationship: Bad Request - {details}`	The API request failed with a bad request error.

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

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