setGroups

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

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