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 setGroups method allows you to bulk create or update groups in the Teamwork Graph in a single API call. This is the recommended approach for bulk group ingestion as it's more efficient than making individual requests for each group.

Method signature

1
2
setGroups(request: BulkGroupsRequest): Promise<BulkGroupsResponse>

Parameter: request

Type: BulkGroupsRequest
Required: Yes
Description: The bulk group ingestion request containing groups.

1
2
 // BulkGroupsRequest object:
 {
   groups: GroupPayload[]; // groups: Array of groups to ingest (maximum 100 groups per request)
   connectionId?: string; // Optional: Connection identifier for multi-connection scenarios
 }

Group payload structure

The GroupPayload type supports group information with optional members:

1
2
type GroupPayload = {
  externalId: string;        // Required: Unique external identifier for the group
  displayName?: string;      // Optional: Display name for the group
  members?: GroupMember[];   // Optional: Array of group members
};

Group member structure

1
2
type GroupMember = {
  externalId: string;              // Required: External identifier for the member
  type: string;                    // Required: Type of member (e.g., 'USER')
  updateSequenceNumber?: number;   // Optional: Sequence number for tracking updates
  displayName?: string;            // Optional: Display name for the member
};

Usage examples

Basic group creation

1
2
import { graph } from '@forge/teamwork-graph';
const group = {
  externalId: 'developers',
  displayName: 'Development Team',
  members: [
    {
      externalId: 'user-123',
      type: 'USER'
    },
    {
      externalId: 'user-456',
      type: 'USER'
    }
  ]
};
const request = {
  groups: [group],
  connectionId: 'connection-id-123'
};
const response = await graph.setGroups(request);

Group without members

1
2
const groupWithoutMembers = {
  externalId: 'admins',
  displayName: 'Administrators'
};
const response = await graph.setGroups({
  groups: [groupWithoutMembers],
  connectionId: 'connection-id-123'
});

Bulk group creation

1
2
const groups = [
  {
    externalId: 'developers',
    displayName: 'Development Team',
    members: [
      { externalId: 'user-1', type: 'USER' },
      { externalId: 'user-2', type: 'USER' }
    ]
  },
  {
    externalId: 'designers',
    displayName: 'Design Team',
    members: [
      { externalId: 'user-3', type: 'USER' },
      { externalId: 'user-4', type: 'USER' }
    ]
  },
  {
    externalId: 'managers',
    displayName: 'Management Team'
  }
];
const response = await graph.setGroups({
  groups,
  connectionId: 'connection-id-123'
});

Handling group creation results

1
2
const response = await graph.setGroups({
  groups,
  connectionId: 'connection-id-123'
});
if (response.success && response.results) {
  response.results.forEach(result => {
    if (result.success) {
      console.log(`Successfully created group: ${result.externalId}`);
    } else {
      console.error(`Failed to create group ${result.externalId}: ${result.error}`);
    }
  });
}

Request Limits

Maximum groups per request: 100
Minimum groups per request: 1

Request validation

The method validates the following:

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

Error handling

Error message	Description
`groups must be an array`	The `groups` field is not an array.
`groups array cannot be empty`	The `groups` array is empty.
`Bulk group ingestion supports maximum 100 groups. Received X`	The number of groups per request has exceeded the maximum limit.

Response

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

1
2
 // BulkGroupsResponse

type BulkGroupsResponse = {
   success: boolean;
   results?: {
     success: Array<{
       externalId: string;
       success: true;
       statusCode: number; // 200-299
     }>;
     failures: Array<{
       externalId: string;
       success: false;
       statusCode: number; // non 200-299
       error: string;
     }>;
   };
   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 group creation
const group: types.GroupPayload = {
  externalId: 'developers',
  displayName: 'Development Team',
  members: [
    {
      externalId: 'user-123',
      type: 'USER'
    } as types.GroupMember
  ]
};

// Type-safe request creation
const request: types.BulkGroupsRequest = {
  groups: [group],
  connectionId: 'connection-id-123'
};

// Type-safe response handling
const response = await graph.setGroups(request);
if (response.success && response.results) {
  // TypeScript knows results exists here and provides proper typing
  response.results.success.forEach(result => {
    // result is properly typed with externalId, success, and statusCode properties
    console.log(`Successfully created group: ${result.externalId}`);
  });
  response.results.failures.forEach(result => {
    // result is properly typed with error information
    console.error(`Failed to create group: ${result.externalId}, Error: ${result.error}`);
  });
}

The type system ensures:

group object has correct GroupPayload structure with proper member types
request.groups must be an array of GroupPayload objects
response.results has properly typed success and failures arrays
Compile-time validation prevents type mismatches