mapUsers

The mapUsers method allows you to create mappings between external users and Atlassian account IDs or email addresses. This is essential for linking users from external systems to Atlassian accounts for proper permissions and collaboration.

Method signature

1
2
mapUsers(request: MapUsersRequest): Promise<MapUsersResponse>

Parameter: request

• Type: MapUsersRequest
• Required: Yes
• Description: The user mapping request containing direct mappings.

1
2
 // MapUsersRequest object:
 {
   directMappings: UserMapping[]; // directMappings: Array of user mappings (maximum 100 mappings per request)
 }

User mapping structure

Each mapping must contain either an accountId or email:

1
2
type UserMapping = {
  externalId: string;              // Required: External identifier for the user
  updateSequenceNumber: number;    // Required: Sequence number for tracking updates
  updatedAt: number;               // Required: Timestamp of the update
  accountId?: string;              // Optional: Atlassian account ID (must have either this or email)
  email?: string;   // Optional: External email address (must have either this or accountId)
};

Usage examples

Mapping with account ID

1
2
import { graph } from '@forge/teamwork-graph';
const mappingWithAccountId = {
  externalId: 'user-123',
  accountId: '5dd4fb8db3a9c80fc0a3283b',
  updateSequenceNumber: 1,
  updatedAt: Date.now()
};
const request = {
  directMappings: [mappingWithAccountId]
};
const response = await graph.mapUsers(request);

Mapping with email address

1
2
const mappingWithEmail = {
  externalId: 'user-456',
  email: 'user@my-company.com',
  updateSequenceNumber: 2,
  updatedAt: Date.now()
};
const response = await graph.mapUsers({
  directMappings: [mappingWithEmail]
});

Mixed mappings

1
2
const mappings = [
  {
    externalId: 'user-123',
    accountId: '5dd4fb8db3a9c80fc0a3283b',
    updateSequenceNumber: 1,
    updatedAt: Date.now()
  },
  {
    externalId: 'user-456',
    email: 'user@my-company.com',
    updateSequenceNumber: 2,
    updatedAt: Date.now()
  }
];
const response = await graph.mapUsers({
  directMappings: mappings
});

Handling mapping results

1
2
const response = await graph.mapUsers({
  directMappings: mappings
});
if (response.success && response.results) {
  response.results.forEach(result => {
    if (result.success) {
      console.log(`Successfully mapped user ${result.externalId} to account ${result.accountId}`);
    } else {
      console.error(`Failed to map user ${result.externalId}: ${result.error}`);
    }
  });
}

Request limits

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

Request validation

The method validates the following:

• Must be an array: The directMappings field must be a valid array.
• Cannot be empty: The directMappings array cannot be empty.
• Maximum limit: Cannot exceed 100 mappings per request.
• Each mapping must have externalId: Every mapping must include an externalId.
• Each mapping must have either accountId or email: At least one identifier is required.

Error handling

Response

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

1
2
 // MapUsersResponse
 {
   success: boolean;           // Indicates if the overall operation was successful
   results?: Array<{          // Individual results for each mapping
     externalId: string;      // The external ID that was processed
     accountId?: string;      // The mapped Atlassian account ID (if successful)
     success: boolean;        // Whether this specific mapping was successful
     error?: string;          // Error message for this specific mapping (if failed)
   }>;
   error?: string;            // Overall 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 mapping creation
const mapping: types.UserMapping = {
  externalId: 'user-123',
  accountId: '5dd4fb8db3a9c80fc0a3283b',
  updateSequenceNumber: 1,
  updatedAt: Date.now()
};

// Type-safe request creation
const request: types.MapUsersRequest = {
  directMappings: [mapping]
};

// Type-safe response handling
const response = await graph.mapUsers(request);
if (response.success && response.results) {
  // TypeScript knows results exists here and provides proper typing
  response.results.forEach(result => {
    // result is properly typed with externalId, accountId, success, and error properties
    if (result.success) {
      console.log(`Successfully mapped user: ${result.externalId}`);
    } else {
      console.error(`Failed to map user: ${result.externalId}, Error: ${result.error}`);
    }
  });
}

The type system ensures:

• mapping object has correct structure with required and optional properties
• request.directMappings must be an array of UserMapping objects
• response.results is properly typed when success is true
• Compile-time validation prevents type mismatches