getObjectByExternalId

The getObjectByExternalId method allows you to retrieve a specific object from the Teamwork Graph using its external ID and object type. This is useful for fetching individual entities when you know their external identifier.

Method signature

1
2
getObjectByExternalId(request: GetObjectByExternalIdRequest): Promise<GetObjectByExternalIdResponse>

Parameter: request

• Type: GetObjectByExternalIdRequest
• Required: Yes
• Description: The request containing the object type and external ID.

1
2
{
  objectType: string; // objectType: The type of object to retrieve (e.g., 'atlassian:document', 'atlassian:message')
  externalId: string; // externalId: The external identifier of the object
  connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
}

Usage examples

Basic object retrieval

1
2
import { graph } from '@forge/teamwork-graph';
const request = {
  objectType: 'atlassian:document',
  externalId: 'pipelines/123/builds/456',
  connectionId: 'connection-id-123'
};
const response = await graph.getObjectByExternalId(request);
if (response.success) {
  console.log('Object found:', response.object);
} else {
  console.error('Error retrieving object:', response.error);
}
/

Retrieving different object types

1
2
// Retrieve a document object
const documentRequest = {
  objectType: 'atlassian:document',
  externalId: 'api-doc-456',
  connectionId: 'connection-id-123'
};
const documentResponse = await graph.getObjectByExternalId(documentRequest);
// Retrieve a message object
const messageRequest = {
  objectType: 'atlassian:message',
  externalId: 'msg-789',
  connectionId: 'connection-id-123'
};
const messageResponse = await graph.getObjectByExternalId(messageRequest);

Request limits

Only one externalId per request.

Request validation

The method validates the following:

• objectType required: The objectType field must be a non-empty string.
• externalId required: The externalId field must be a non-empty string.
• Only contains one externalId: The request only contains one externalId.

Error handling

Response

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

1
2
{
  success: boolean;           // Indicates if the operation was successful
  object?: Object;           // The retrieved object (if found)
  error?: string;            // 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.GetObjectByExternalIdRequest = {
  objectType: 'atlassian:document',
  externalId: 'pipelines/123/builds/456',
  connectionId: 'connection-id-123'
};

// Type-safe response handling
const response = await graph.getObjectByExternalId(request);
if (response.success && response.object) {
  // TypeScript knows object exists here
  const object = response.object;
  // Access object properties safely with proper typing
  
  // The object is typed as the union of all possible object types
  // TypeScript will enforce the correct structure based on the object type
  if ('atlassian:document' in object) {
    // TypeScript knows this is a DocumentObject
    const document = object['atlassian:document'];
    console.log('Document ID:', object.id); // ID is on the root object
    console.log('Document Display Name:', object.displayName);
    console.log('Document Category:', document.type.category);
    console.log('Document MIME Type:', document.type.mimeType);
    console.log('Document Size (bytes):', document.byteSize);
  } else if ('atlassian:message' in object) {
    // TypeScript knows this is a MessageObject
    const message = object['atlassian:message'];
    console.log('Message ID:', object.id); // ID is on the root object
    console.log('Message Description:', object.description);
    console.log('Message Hidden:', message.hidden);
    console.log('Message Pinned:', message.isPinned);
    console.log('Message Attachments Count:', message.attachments?.length || 0);
  }
}

The type system ensures:

• request.objectType and request.externalId must be strings
• response.object is properly typed as Object (union of all object types) when success is true
• The Object union type includes all supported object types like DocumentObject, MessageObject, BranchObject, etc.
• You can safely check object types using the in operator and access type-specific properties
• Compile-time validation prevents type mismatches