setObjects

The setObjects method allows you to ingest multiple objects into the Teamwork Graph in a single API call.

Method signature

1
2
setObjects(request: SetObjectsRequest): Promise<BulkObjectResponse>

Parameter: request

• Type: SetObjectsRequest
• Required: Yes
• Description: The bulk ingestion request containing objects.

1
2
 // SetObjectsRequest object:
 {
   objects: Array<Object>; // objects: Array of objects to ingest (maximum 100 objects per request)
   properties?: Record<string, string>; // Max 5 properties to tag the entities with
   connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
 }

Usage examples

Document object (atlassian:document)

1
2
import { types } from '@forge/teamwork-graph';
const document: types.DocumentObject = {
  schemaVersion: '1.0',
  id: 'doc-123',
  updateSequenceNumber: 123,
  displayName: 'API Documentation',
  url: 'https://example.com/doc'
  createdAt: '2024-01-15T10:00:00Z',
  lastUpdatedAt: '2024-01-20T14:30:00Z',
  permissions: [{
    accessControls: [{ principals: [{ type: 'ATLASSIAN_WORKSPACE' }] }]
  }],
  'atlassian:document': {
    type: { category: 'document' },
    content: { mimeType: 'text/plain', text: 'Document content...' }
  }
};

Message object (atlassian:message)

1
2
import { types } from '@forge/teamwork-graph';
const message: types.MessageObject = {
  schemaVersion: '2.0',
  id: 'msg-456',
  updateSequenceNumber: 456,
  description: 'Team update message',
  url: 'https://slack.com/msg/123'
  createdAt: '2024-01-20T15:00:00Z',
  lastUpdatedAt: '2024-01-20T15:00:00Z',
  containerKey: {
    type: 'atlassian:conversation',
    value: { entityId: 'conv-123' }
  },
  permissions: [{
    accessControls: [{ principals: [{ type: 'ATLASSIAN_WORKSPACE' }] }]
  }],
  'atlassian:message': {
    hidden: false,
    isPinned: false
  }
};

Basic bulk ingestion

1
2
import { graph } from '@forge/teamwork-graph';
import { types } from '@forge/teamwork-graph';
const document: types.DocumentObject = {
  // ...common and required properties
  'atlassian:document': {
    type: { category: 'document' },
    content: { mimeType: 'text/plain', text: 'Project documentation...' }
  }
};
const request = {
  objects: [document],
  properties: {
    "pull-id": "12334",
    "timestamp": "12344"
  },
  connectionId: 'connection-id-123'
};
const response = await graph.setObjects(request);

Mixed object types

1
2
const objects = [
  // Document object
  {
    schemaVersion: '1.0',
    id: 'api-doc',
    displayName: 'API Documentation',
    // ... other required fields
    'atlassian:document': {
      type: { category: 'document' },
      content: { mimeType: 'text/plain', text: 'Complete API reference...' }
    }
  },
  // Message object
  {
    schemaVersion: '1.0',
    id: 'team-update',
    description: 'New feature released!',
    // ... other required fields
    'atlassian:message': {
      hidden: false,
      isPinned: false
    }
  }
];
const response = await graph.setObjects({
  objects,
  connectionId: 'connection-id-123'
});

Request limits

• Maximum objects per request: 100
• Minimum objects per request: 1

Request validation

The method validates the following:

• Must be an array: The objects field must be a valid array.
• Cannot be empty: The objects array cannot be empty.
• Maximum limit: Cannot exceed 100 objects per request.

Error handling

Response

The method returns a promise that resolves to a BulkObjectResponse object containing the ingestion results.

1
2
type AcceptedObject = {
  entityType: string;
  entityId: ObjectId;
};

type RejectedObjectKey = {
  entityType: string;
  entityId: ObjectId;
};

type ValidationError = {
  message: string;
  key: string;
};

type RejectedObject = {
  key: RejectedObjectKey;
  errors: ValidationError[];
};

type ValidObject = {
  entityType: string;
  entityId: ObjectId;
};

type BulkObjectResponse = {
  success: boolean;
  results?: {
    accepted?: AcceptedObject[];
    rejected?: RejectedObject[];
    validObjects?: ValidObject[];
  };
  error?: string;
  originalError?: unknown;
};

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 object creation - TypeScript enforces exactly one object type per object
const document: types.DocumentObject = {
  schemaVersion: '1.0',
  id: 'doc-123',
  updateSequenceNumber: 123,
  displayName: 'API Documentation',
  url: 'https://example.com/doc',
  'atlassian:document': {
    type: { category: 'document' },
    content: { mimeType: 'text/plain', text: 'Document content...' }
  }
  // TypeScript error if you try to add 'atlassian:message' here
};

// Type-safe request creation
const request: types.SetObjectsRequest = {
  objects: [document],
  properties: { environment: 'production' },
  connectionId: 'connection-id-123'
};

// Type-safe response handling
const response = await graph.setObjects(request);
if (response.success && response.results) {
  // TypeScript knows results exists here and provides proper typing
  if (response.results.accepted) {
    response.results.accepted.forEach(result => {
      console.log(`Successfully ingested: ${result.entityType}`);
    });
  }
  if (response.results.rejected) {
    response.results.rejected.forEach(result => {
      console.error(`Failed to ingest: ${result.key.entityType}`);
    });
  }
}

The type system ensures:

• Each object must have exactly one object-specific type (e.g., atlassian:document)
• request.objects must be an array of valid Object union types
• response.results has properly typed accepted, rejected, and validObjects arrays
• Compile-time validation prevents mixing incompatible object types