getObjectIndexStatusByExternalId

The getObjectIndexStatusByExternalId method checks whether a specific object is present in the search index using its external ID and object type. The method is available in @forge/teamwork-graph 5.1.0 and later.

Method signature

1
2
3
4
getObjectIndexStatusByExternalId(
  request: GetObjectIndexStatusByExternalIdRequest
): Promise<GetObjectIndexStatusByExternalIdResponse>

Parameter: request

• Type: GetObjectIndexStatusByExternalIdRequest
• Required: Yes
• Description: The object type, external ID, and connector connection identifier to check. Pass the connection identifier supplied to your connector unchanged. It has the format <dataSourceId>:<connectionId>.

1
2
3
4
5
6
{
  objectType: string;  // The object type declared by the connector, for example, 'atlassian:document'
  externalId: string;  // The external identifier used when the object was ingested
  connectionId: string; // The composite connector connection identifier
}

Usage example

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
import { graph } from '@forge/teamwork-graph';

const response = await graph.getObjectIndexStatusByExternalId({
  objectType: 'atlassian:document',
  externalId: 'document-123',
  connectionId: 'data-source:connection-123'
});

if (!response.success) {
  console.error('Index status check failed:', response.error);
} else {
  switch (response.status) {
    case 'INDEXED':
      console.log('The object is present in the search index.');
      break;
    case 'NOT_INDEXED':
      console.log('The object was not present when it was checked.');
      break;
    case 'UNKNOWN':
      console.log('The index status could not be determined.');
      break;
    case 'UNSUPPORTED_ENTITY':
      console.log('This object type does not support index status checks.');
      break;
  }
}

Request validation

The method validates the following fields:

• objectType required: objectType must not be empty or contain only whitespace.
• externalId required: externalId must not be empty or contain only whitespace.
• connectionId required: connectionId must not be empty or contain only whitespace.

Validation errors are thrown before an API request is made. They are not returned as a success: false response.

Index status values

All four status values are successful API responses with success: true. The status field is the only indexability result. The response does not include an indexed boolean. Do not infer the status from message or lastIndexedModifiedDate.

Response

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

When the request succeeds, the response has the following shape:

1
2
3
4
5
6
7
8
9
10
11
{
  success: true;
  objectType: string;
  externalId: string;
  entityId: string;
  status: 'INDEXED' | 'NOT_INDEXED' | 'UNKNOWN' | 'UNSUPPORTED_ENTITY';
  checkedAt: string;
  lastIndexedModifiedDate?: string;
  message?: string;
}

• checkedAt is the time of the index status observation, formatted as an ISO 8601 string.
• entityId is the identifier used for the index lookup. For this operation, it normally matches externalId.
• lastIndexedModifiedDate, when present for an indexed object, is the source modification timestamp stored on the indexed object, formatted as an ISO 8601 string. It is not the time when the object was written to the index.
• message, when present, provides more information about the result, particularly for UNKNOWN and UNSUPPORTED_ENTITY statuses.

When the request fails, the response has the following shape:

1
2
3
4
5
6
{
  success: false;
  error: string;
  originalError?: unknown;
}

Caching and retries

This method performs one check and does not retry or poll automatically. Before retrying a NOT_INDEXED or UNKNOWN result, or a failed request, wait at least 60 seconds and use bounded retries. Results may be cached, and a cached response retains the original checkedAt value.

Treat UNKNOWN as an inconclusive result, not as NOT_INDEXED. Checking again will not change an UNSUPPORTED_ENTITY result unless the app configuration or supported object types change.

Error handling

Type safety

The SDK provides type-safe request and response objects:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
import { graph, types } from '@forge/teamwork-graph';

const request: types.GetObjectIndexStatusByExternalIdRequest = {
  objectType: 'atlassian:document',
  externalId: 'document-123',
  connectionId: 'data-source:connection-123'
};

const response = await graph.getObjectIndexStatusByExternalId(request);

if (response.success && response.status === 'INDEXED') {
  console.log('Checked at:', response.checkedAt);
  console.log('Source modified at:', response.lastIndexedModifiedDate);
}

The response is a discriminated union. When success is true, the index status fields are available. When success is false, error is available instead.