• Home
  • Features
  • Pricing
  • Docs
  • Announcements
  • Sign In

smartsheet / smartsheet-java-sdk / #69

09 Oct 2026 07:01AM UTC coverage: 60.094% (+0.4%) from 59.734%
#69

push

github

web-flow
Merge pull request #195 from jhinkey-smartsheet/jim.hinkey/document-checking-children-type

Describe the items of the TokenPaginatedResult returned by  getWorkspaceChildren and getFolderChildren

4626 of 7698 relevant lines covered (60.09%)

0.6 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

62.5
/src/main/java/com/smartsheet/api/internal/UserResourcesImpl.java
1
/*
2
 * Copyright (C) 2025 Smartsheet
3
 *
4
 * Licensed under the Apache License, Version 2.0 (the "License");
5
 * you may not use this file except in compliance with the License.
6
 * You may obtain a copy of the License at
7
 *
8
 *      http://www.apache.org/licenses/LICENSE-2.0
9
 *
10
 * Unless required by applicable law or agreed to in writing, software
11
 * distributed under the License is distributed on an "AS IS" BASIS,
12
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13
 * See the License for the specific language governing permissions and
14
 * limitations under the License.
15
 */
16

17
package com.smartsheet.api.internal;
18

19
import com.smartsheet.api.AuthorizationException;
20
import com.smartsheet.api.InvalidRequestException;
21
import com.smartsheet.api.ResourceNotFoundException;
22
import com.smartsheet.api.ServiceUnavailableException;
23
import com.smartsheet.api.SmartsheetException;
24
import com.smartsheet.api.UserResources;
25
import com.smartsheet.api.internal.http.HttpEntity;
26
import com.smartsheet.api.internal.http.HttpMethod;
27
import com.smartsheet.api.internal.http.HttpRequest;
28
import com.smartsheet.api.internal.http.HttpResponse;
29
import com.smartsheet.api.internal.util.QueryUtil;
30
import com.smartsheet.api.internal.util.Util;
31
import com.smartsheet.api.models.AlternateEmail;
32
import com.smartsheet.api.models.DeleteUserParameters;
33
import com.smartsheet.api.models.PagedResult;
34
import com.smartsheet.api.models.PaginationParameters;
35
import com.smartsheet.api.models.Result;
36
import com.smartsheet.api.models.Sheet;
37
import com.smartsheet.api.models.TokenPaginatedResult;
38
import com.smartsheet.api.models.User;
39
import com.smartsheet.api.models.UserPlan;
40
import com.smartsheet.api.models.UserProfile;
41
import com.smartsheet.api.models.enums.ListUserInclusion;
42
import com.smartsheet.api.models.enums.SeatType;
43
import com.smartsheet.api.models.enums.UpgradeSeatType;
44
import com.smartsheet.api.models.enums.DowngradeSeatType;
45
import com.smartsheet.api.models.enums.UserInclusion;
46
import com.smartsheet.api.models.enums.UserPlanInclusion;
47

48
import java.io.File;
49
import java.io.FileInputStream;
50
import java.io.FileNotFoundException;
51
import java.io.InputStream;
52
import java.net.URLEncoder;
53
import java.nio.charset.StandardCharsets;
54
import java.text.SimpleDateFormat;
55
import java.util.Date;
56
import java.util.EnumSet;
57
import java.util.HashMap;
58
import java.util.List;
59
import java.util.Map;
60
import java.util.Set;
61
import java.util.Collections;
62

63
/**
64
 * This is the implementation of the UserResources.
65
 * <p>
66
 * Thread Safety: This class is thread safe because it is immutable and its base class is thread safe.
67
 */
68
public class UserResourcesImpl extends AbstractResources implements UserResources {
69

70
    private static final String USERS = "users";
71
    private static final String ALTERNATE_EMAILS = "alternateemails";
72
    public static final String PLANS = "/plans/";
73

74
    /**
75
     * Constructor.
76
     * <p>
77
     * Exceptions: - IllegalArgumentException : if any argument is null
78
     *
79
     * @param smartsheet the smartsheet
80
     */
81
    public UserResourcesImpl(SmartsheetImpl smartsheet) {
82
        super(smartsheet);
1 ✔
83
    }
1 ✔
84

85
    /**
86
     * List all users.
87
     * <p>
88
     * It mirrors to the following Smartsheet REST API method: GET /users
89
     *
90
     * @return the list of all users
91
     * @throws IllegalArgumentException    if any argument is null or empty string
92
     * @throws InvalidRequestException     if there is any problem with the REST API request
93
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
94
     * @throws ResourceNotFoundException   if the resource cannot be found
95
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
96
     * @throws SmartsheetException         if there is any other error during the operation
97
     */
98
    public PagedResult<User> listUsers() throws SmartsheetException {
99
        return this.listUsersInternal(null, null, null, null, null, null);
1 ✔
100
    }
101

102
    /**
103
     * List all users.
104
     * <p>
105
     * It mirrors to the following Smartsheet REST API method: GET /users
106
     * <p>
107
     * Exceptions:
108
     *   - InvalidRequestException : if there is any problem with the REST API request
109
     *   - AuthorizationException : if there is any problem with the REST API authorization(access token)
110
     *   - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
111
     *   - SmartsheetRestException : if there is any other REST API related error occurred during the operation
112
     *   - SmartsheetException : if there is any other error occurred during the operation
113
     *
114
     * @param pagination the object containing the pagination query parameters
115
     * @return all users (note that empty list will be returned if there is none)
116
     * @throws SmartsheetException the smartsheet exception
117
     */
118
    public PagedResult<User> listUsers(PaginationParameters pagination) throws SmartsheetException {
119
        return this.listUsersInternal(null, null, null, null, null, pagination);
1 ✔
120
    }
121

122
    /**
123
     * List all users.
124
     * <p>
125
     * It mirrors to the following Smartsheet REST API method: GET /users
126
     * <p>
127
     * Exceptions:
128
     * - InvalidRequestException : if there is any problem with the REST API request
129
     * - AuthorizationException : if there is any problem with the REST API authorization(access token)
130
     * - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
131
     * - SmartsheetRestException : if there is any other REST API related error occurred during the operation
132
     * - SmartsheetException : if there is any other error occurred during the operation
133
     *
134
     * @param email      the list of email addresses
135
     * @param pagination the object containing the pagination query parameters
136
     * @return all users (note that empty list will be returned if there is none)
137
     * @throws SmartsheetException the smartsheet exception
138
     */
139
    public PagedResult<User> listUsers(Set<String> email, PaginationParameters pagination) throws SmartsheetException {
140
        return this.listUsersInternal(email, null, null, null, null, pagination);
1 ✔
141
    }
142

143
    /**
144
     * List all users.
145
     * <p>
146
     * It mirrors to the following Smartsheet REST API method: GET /users
147
     * <p>
148
     * Exceptions:
149
     * - InvalidRequestException : if there is any problem with the REST API request
150
     * - AuthorizationException : if there is any problem with the REST API authorization(access token)
151
     * - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
152
     * - SmartsheetRestException : if there is any other REST API related error occurred during the operation
153
     * - SmartsheetException : if there is any other error occurred during the operation
154
     *
155
     * @param email      the list of email addresses
156
     * @param includes   elements to include in the response
157
     * @param pagination the object containing the pagination query parameters
158
     * @return all users (note that empty list will be returned if there is none)
159
     * @throws SmartsheetException the smartsheet exception
160
     */
161
    public PagedResult<User> listUsers(Set<String> email, EnumSet<ListUserInclusion> includes,
162
                                       PaginationParameters pagination) throws SmartsheetException {
163
        return this.listUsersInternal(email, includes, null, null, null, pagination);
1 ✔
164
    }
165

166
    /**
167
     * List all users with support for Seat Type and Plan ID. If planID or seatType is provided, then the response
168
     * will contain  planId, seatType, seatTypeLastChangedAt, isInternal, otherwise - not
169
     * <p>
170
     * It mirrors to the following Smartsheet REST API method: GET /users
171
     * <p>
172
     * Exceptions:
173
     *   - InvalidRequestException : if there is any problem with the REST API request
174
     *   - AuthorizationException : if there is any problem with the REST API authorization(access token)
175
     *   - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
176
     *   - SmartsheetRestException : if there is any other REST API related error occurred during the operation
177
     *   - SmartsheetException : if there is any other error occurred during the operation
178
     *
179
     * @param email the list of email addresses
180
     * @param pagination the object containing the pagination query parameters
181
     * @param planId filtering all users part of the specific plan
182
     * @param seatType filter users by seat type
183
     * @return all users (note that empty list will be returned if there is none)
184
     * @throws SmartsheetException the smartsheet exception
185
     */
186
    @Override
187
    public PagedResult<User> listUsers(Set<String> email, Long planId,
188
                                       SeatType seatType, PaginationParameters pagination
189
                                       ) throws SmartsheetException {
190
        return this.listUsersInternal(email, null, planId, seatType, null, pagination);
1 ✔
191
    }
192

193
    /**
194
     * List all users with support for Seat Type and Plan ID. If planID or seatType is provided, then the response
195
     * will contain  planId, seatType, seatTypeLastChangedAt, isInternal, otherwise - not
196
     * <p>
197
     * It mirrors to the following Smartsheet REST API method: GET /users
198
     * <p>
199
     * Exceptions:
200
     *   - InvalidRequestException : if there is any problem with the REST API request
201
     *   - AuthorizationException : if there is any problem with the REST API authorization(access token)
202
     *   - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
203
     *   - SmartsheetRestException : if there is any other REST API related error occurred during the operation
204
     *   - SmartsheetException : if there is any other error occurred during the operation
205
     *
206
     * @param email the list of email addresses
207
     * @param pagination the object containing the pagination query parameters
208
     * @param planId filtering all users part of the specific plan
209
     * @param seatType filter users by seat type
210
     * @param displayContributorSeatType if true, returns CONTRIBUTOR instead of VIEWER for eligible users
211
     * @return all users (note that empty list will be returned if there is none)
212
     * @throws SmartsheetException the smartsheet exception
213
     */
214
    @Override
215
    public PagedResult<User> listUsers(Set<String> email, Long planId,
216
                                       SeatType seatType, Boolean displayContributorSeatType,
217
                                       PaginationParameters pagination
218
                                       ) throws SmartsheetException {
219
        return this.listUsersInternal(email, null, planId, seatType, displayContributorSeatType, pagination);
×
220
    }
221

222
    /**
223
     * List all users with support for Seat Type and Plan ID. If planID or seatType is provided, then the response
224
     * will contain  planId, seatType, seatTypeLastChangedAt, isInternal, otherwise - not
225
     * <p>
226
     * It mirrors to the following Smartsheet REST API method: GET /users
227
     * <p>
228
     * Exceptions:
229
     *   - InvalidRequestException : if there is any problem with the REST API request
230
     *   - AuthorizationException : if there is any problem with the REST API authorization(access token)
231
     *   - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
232
     *   - SmartsheetRestException : if there is any other REST API related error occurred during the operation
233
     *   - SmartsheetException : if there is any other error occurred during the operation
234
     *
235
     * @param email the list of email addresses
236
     * @param includes elements to include in the response
237
     * @param pagination the object containing the pagination query parameters
238
     * @param planId filtering all users part of the specific plan
239
     * @param seatType filter users by seat type
240
     * @param displayContributorSeatType if true, returns CONTRIBUTOR instead of VIEWER for eligible users
241
     * @return all users (note that empty list will be returned if there is none)
242
     * @throws SmartsheetException the smartsheet exception
243
     */
244
    private PagedResult<User> listUsersInternal(Set<String> email, EnumSet<ListUserInclusion> includes,
245
                                                Long planId, SeatType seatType, Boolean displayContributorSeatType,
246
                                                PaginationParameters pagination
247
                                                ) throws SmartsheetException {
248
        String path = USERS;
1 ✔
249
        Map<String, Object> parameters = new HashMap<>();
1 ✔
250

251
        if (pagination != null) {
1 ✔
252
            parameters = pagination.toHashMap();
1 ✔
253
        }
254

255
        if (email != null) {
1 ✔
256
            parameters.put("email", QueryUtil.generateCommaSeparatedList(email));
1 ✔
257
        }
258

259
        if (includes != null) {
1 ✔
260
            parameters.put("include", QueryUtil.generateCommaSeparatedList(includes));
1 ✔
261
        }
262

263
        // Seat type support
264
        if (planId != null) {
1 ✔
265
            parameters.put("planId", planId);
1 ✔
266
        }
267

268
        if (seatType != null) {
1 ✔
269
            parameters.put("seatType", seatType);
1 ✔
270
        }
271

272
        if (displayContributorSeatType != null) {
1 ✔
273
            parameters.put("displayContributorSeatType", displayContributorSeatType);
×
274
        }
275

276
        path += QueryUtil.generateUrl(null, parameters);
1 ✔
277
        return this.listResourcesWithWrapper(path, User.class);
1 ✔
278
    }
279

280
    /**
281
     * Add a user to the organization, without sending email.
282
     * <p>
283
     * It mirrors to the following Smartsheet REST API method: POST /users
284
     * <p>
285
     * Exceptions:
286
     * - IllegalArgumentException : if any argument is null
287
     * - InvalidRequestException : if there is any problem with the REST API request
288
     * - AuthorizationException : if there is any problem with the REST API authorization(access token)
289
     * - ResourceNotFoundException : if the resource can not be found
290
     * - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
291
     * - SmartsheetRestException : if there is any other REST API related error occurred during the operation
292
     * - SmartsheetException : if there is any other error occurred during the operation
293
     *
294
     * @param user the user object limited to the following attributes: * admin * email * licensedSheetCreator
295
     * @return the user
296
     * @throws SmartsheetException the smartsheet exception
297
     */
298
    public User addUser(User user) throws SmartsheetException {
299
        return this.createResource(USERS, User.class, user);
1 ✔
300
    }
301

302
    /**
303
     * Add a user to the organization, without sending email.
304
     * <p>
305
     * It mirrors to the following Smartsheet REST API method: POST /users
306
     * <p>
307
     * Exceptions:
308
     * - IllegalArgumentException : if any argument is null
309
     * - InvalidRequestException : if there is any problem with the REST API request
310
     * - AuthorizationException : if there is any problem with the REST API authorization(access token)
311
     * - ResourceNotFoundException : if the resource can not be found
312
     * - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
313
     * - SmartsheetRestException : if there is any other REST API related error occurred during the operation
314
     * - SmartsheetException : if there is any other error occurred during the operation
315
     *
316
     * @param user      the created user
317
     * @param sendEmail whether to send email
318
     * @return the user object limited to the following attributes: * admin * email * licensedSheetCreator
319
     * @throws SmartsheetException the smartsheet exception
320
     */
321
    public User addUser(User user, boolean sendEmail) throws SmartsheetException {
322
        return this.createResource("users?sendEmail=" + sendEmail, User.class, user);
1 ✔
323
    }
324

325
    /**
326
     * Get the current user.
327
     * <p>
328
     * It mirrors to the following Smartsheet REST API method: GET /users/{userId}
329
     *
330
     * @param userId the user id
331
     * @return the user
332
     * @throws IllegalArgumentException    if any argument is null or empty string
333
     * @throws InvalidRequestException     if there is any problem with the REST API request
334
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
335
     * @throws ResourceNotFoundException   if the resource cannot be found
336
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
337
     * @throws SmartsheetException         if there is any other error during the operation
338
     */
339
    public UserProfile getUser(long userId) throws SmartsheetException {
340
        return this.getResource(USERS + "/" + userId, UserProfile.class);
1 ✔
341
    }
342

343
    /**
344
     * Get the current user.
345
     * <p>
346
     * It mirrors to the following Smartsheet REST API method: GET /users/me
347
     * <p>
348
     * Exceptions:
349
     * - InvalidRequestException : if there is any problem with the REST API request
350
     * - AuthorizationException : if there is any problem with the REST API authorization(access token)
351
     * - ResourceNotFoundException : if the resource can not be found
352
     * - ServiceUnavailableException : if the REST API service is not available (possibly due to rate limiting)
353
     * - SmartsheetRestException : if there is any other REST API related error occurred during the operation
354
     * - SmartsheetException : if there is any other error occurred during the operation
355
     *
356
     * @return the resource (note that if there is no such resource, this method will throw ResourceNotFoundException
357
     * rather than returning null).
358
     * @throws SmartsheetException the smartsheet exception
359
     */
360
    public UserProfile getCurrentUser() throws SmartsheetException {
361
        return this.getResource("users/me", UserProfile.class);
1 ✔
362
    }
363

364
    /**
365
     * <p>Get the current user.</p>
366
     *
367
     * <p>It mirrors to the following Smartsheet REST API method: GET /user/me</p>
368
     *
369
     * @param includes used to specify the optional objects to include.
370
     * @return the current user
371
     * @throws IllegalArgumentException    if any argument is null or empty string
372
     * @throws InvalidRequestException     if there is any problem with the REST API request
373
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
374
     * @throws ResourceNotFoundException   if the resource cannot be found
375
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
376
     * @throws SmartsheetException         if there is any other error during the operation
377
     */
378
    public UserProfile getCurrentUser(EnumSet<UserInclusion> includes) throws SmartsheetException {
379
        String path = "users/me";
1 ✔
380

381
        Map<String, Object> parameters = new HashMap<>();
1 ✔
382
        parameters.put("include", QueryUtil.generateCommaSeparatedList(includes));
1 ✔
383

384
        path += QueryUtil.generateUrl(null, parameters);
1 ✔
385
        return this.getResource(path, UserProfile.class);
1 ✔
386
    }
387

388
    /**
389
     * List all organisation sheets.
390
     * <p>
391
     * It mirrors to the following Smartsheet REST API method: GET /users/sheets
392
     *
393
     * @param pagination the object containing the pagination query parameters
394
     * @return the list of all organisation sheets
395
     * @throws IllegalArgumentException    if any argument is null or empty string
396
     * @throws InvalidRequestException     if there is any problem with the REST API request
397
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
398
     * @throws ResourceNotFoundException   if the resource cannot be found
399
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
400
     * @throws SmartsheetException         if there is any other error during the operation
401
     */
402
    public PagedResult<Sheet> listOrgSheets(PaginationParameters pagination, Date modifiedSince) throws SmartsheetException {
403
        String path = "users/sheets";
1 ✔
404

405
        Map<String, Object> parameters = new HashMap<>();
1 ✔
406
        if (pagination != null) {
1 ✔
407
            parameters = pagination.toHashMap();
1 ✔
408
        }
409
        if (modifiedSince != null) {
1 ✔
410
            String isoDate = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ssZ").format(modifiedSince);
×
411
            parameters.put("modifiedSince", isoDate);
×
412
        }
413
        path += QueryUtil.generateUrl(null, parameters);
1 ✔
414
        return this.listResourcesWithWrapper(path, Sheet.class);
1 ✔
415
    }
416

417
    public PagedResult<Sheet> listOrgSheets(PaginationParameters pagination) throws SmartsheetException {
418
        return this.listOrgSheets(pagination, null);
×
419
    }
420

421
    /**
422
     * List all user alternate emails.
423
     * <p>
424
     * It mirrors to the following Smartsheet REST API method: GET /users/{userId}/alternateemails
425
     *
426
     * @param userId     the id of the user
427
     * @param pagination the object containing the pagination query parameters
428
     * @return the list of all user alternate emails
429
     * @throws IllegalArgumentException    if any argument is null or empty string
430
     * @throws InvalidRequestException     if there is any problem with the REST API request
431
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
432
     * @throws ResourceNotFoundException   if the resource cannot be found
433
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
434
     * @throws SmartsheetException         if there is any other error during the operation
435
     */
436
    public PagedResult<AlternateEmail> listAlternateEmails(long userId, PaginationParameters pagination) throws SmartsheetException {
437
        String path = USERS + "/" + userId + "/" + ALTERNATE_EMAILS;
1 ✔
438

439
        if (pagination != null) {
1 ✔
440
            path += pagination.toQueryString();
1 ✔
441
        }
442
        return this.listResourcesWithWrapper(path, AlternateEmail.class);
1 ✔
443
    }
444

445
    /**
446
     * Get alternate email.
447
     * <p>
448
     * It mirrors to the following Smartsheet REST API method: GET /users/{userId}/alternateemails/{alternateEmailId}
449
     *
450
     * @param userId     the id of the user
451
     * @param altEmailId the alternate email id for the alternate email to retrieve.
452
     * @return the resource (note that if there is no such resource, this method will throw
453
     * ResourceNotFoundException rather than returning null).
454
     * @throws IllegalArgumentException    if any argument is null or empty string
455
     * @throws InvalidRequestException     if there is any problem with the REST API request
456
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
457
     * @throws ResourceNotFoundException   if the resource cannot be found
458
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
459
     * @throws SmartsheetException         if there is any other error during the operation
460
     */
461
    public AlternateEmail getAlternateEmail(long userId, long altEmailId) throws SmartsheetException {
462
        return this.getResource(USERS + "/" + userId + "/" + ALTERNATE_EMAILS + "/" + altEmailId, AlternateEmail.class);
1 ✔
463
    }
464

465
    /**
466
     * Add an alternate email.
467
     * <p>
468
     * It mirrors to the following Smartsheet REST API method: POST /users/{userId}/alternateemails
469
     *
470
     * @param userId    the id of the user
471
     * @param altEmails AlternateEmail alternate email address to add.
472
     * @return the resource (note that if there is no such resource, this method will throw
473
     * ResourceNotFoundException rather than returning null).
474
     * @throws IllegalArgumentException    if any argument is null or empty string
475
     * @throws InvalidRequestException     if there is any problem with the REST API request
476
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
477
     * @throws ResourceNotFoundException   if the resource cannot be found
478
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
479
     * @throws SmartsheetException         if there is any other error during the operation
480
     */
481
    public List<AlternateEmail> addAlternateEmail(long userId, List<AlternateEmail> altEmails) throws SmartsheetException {
482
        Util.throwIfNull(altEmails);
1 ✔
483
        if (altEmails.size() == 0) {
1 ✔
484
            return altEmails;
1 ✔
485
        }
486
        return this.postAndReceiveList(USERS + "/" + userId + "/" + ALTERNATE_EMAILS, altEmails, AlternateEmail.class);
1 ✔
487
    }
488

489
    /**
490
     * Delete an alternate email.
491
     * <p>
492
     * It mirrors to the following Smartsheet REST API method: DELETE /users/{userId}/alternateemails/{alternateEmailId}
493
     *
494
     * @param userId     the id of the user
495
     * @param altEmailId the alternate email id for the alternate email to retrieve.
496
     * @throws IllegalArgumentException    if any argument is null or empty string
497
     * @throws InvalidRequestException     if there is any problem with the REST API request
498
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
499
     * @throws ResourceNotFoundException   if the resource cannot be found
500
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
501
     * @throws SmartsheetException         if there is any other error during the operation
502
     */
503
    public void deleteAlternateEmail(long userId, long altEmailId) throws SmartsheetException {
504
        this.deleteResource(USERS + "/" + userId + "/" + ALTERNATE_EMAILS + "/" + altEmailId, AlternateEmail.class);
1 ✔
505
    }
1 ✔
506

507
    /**
508
     * Promote and alternate email to primary.
509
     *
510
     * @param userId     id of the user
511
     * @param altEmailId alternate email id
512
     * @return alternateEmail of the primary
513
     * @throws IllegalArgumentException    if any argument is null or empty string
514
     * @throws InvalidRequestException     if there is any problem with the REST API request
515
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
516
     * @throws ResourceNotFoundException   if the resource cannot be found
517
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
518
     * @throws SmartsheetException         f there is any other error during the operation
519
     */
520
    public AlternateEmail promoteAlternateEmail(long userId, long altEmailId) throws SmartsheetException {
521

522
        HttpRequest request = createHttpRequest(smartsheet.getBaseURI().resolve(
×
523
                USERS + "/" + userId + "/" + ALTERNATE_EMAILS + "/" + altEmailId + "/makeprimary"), HttpMethod.POST);
524

525
        Object obj = null;
×
526
        try {
527
            HttpResponse response = this.smartsheet.getHttpClient().request(request);
×
528
            switch (response.getStatusCode()) {
×
529
                case 200:
530
                    obj = this.smartsheet.getJsonSerializer().deserializeResult(AlternateEmail.class,
×
531
                            response.getEntity().getContent());
×
532
                    break;
×
533
                default:
534
                    handleError(response);
×
535
            }
536
        } finally {
537
            smartsheet.getHttpClient().releaseConnection();
×
538
        }
539

540
        return (AlternateEmail) obj;
×
541
    }
542

543
    /**
544
     * Uploads a profile image for the specified user.
545
     *
546
     * @param userId   id of the user
547
     * @param file     path to the image file
548
     * @param fileType content type of the image file
549
     * @return user
550
     * @throws IllegalArgumentException    if any argument is null or empty string
551
     * @throws InvalidRequestException     if there is any problem with the REST API request
552
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
553
     * @throws ResourceNotFoundException   if the resource cannot be found
554
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
555
     * @throws SmartsheetException         f there is any other error during the operation
556
     */
557
    public User addProfileImage(long userId, String file, String fileType) throws SmartsheetException, FileNotFoundException {
558
        return attachProfileImage(USERS + "/" + userId + "/profileimage", file, fileType);
×
559
    }
560

561
    private User attachProfileImage(String path, String file, String contentType) throws SmartsheetException, FileNotFoundException {
562
        Util.throwIfNull(file);
×
563

564
        if (contentType == null) {
×
565
            contentType = "application/octet-stream";
×
566
        }
567

568
        Map<String, Object> parameters = new HashMap<>();
×
569
        path += QueryUtil.generateUrl(null, parameters);
×
570

571
        HttpRequest request = createHttpRequest(this.smartsheet.getBaseURI().resolve(path), HttpMethod.POST);
×
572
        String attachmentHeaderValue = "attachment; filename=\"" + URLEncoder.encode(file, StandardCharsets.UTF_8) + "\"";
×
573
        request.getHeaders().put("Content-Disposition", attachmentHeaderValue);
×
574

575
        File f = new File(file);
×
576
        InputStream is = new FileInputStream(f);
×
577

578
        HttpEntity entity = new HttpEntity();
×
579
        entity.setContentType(contentType);
×
580
        entity.setContent(is);
×
581
        entity.setContentLength(f.length());
×
582
        request.setEntity(entity);
×
583

584
        User obj = null;
×
585
        try {
586
            HttpResponse response = this.smartsheet.getHttpClient().request(request);
×
587
            switch (response.getStatusCode()) {
×
588
                case 200:
589
                    obj = this.smartsheet.getJsonSerializer().deserializeResult(User.class,
×
590
                            response.getEntity().getContent()).getResult();
×
591
                    break;
×
592
                default:
593
                    handleError(response);
×
594
            }
595
        } finally {
596
            smartsheet.getHttpClient().releaseConnection();
×
597
        }
598

599
        return obj;
×
600
    }
601

602
    /**
603
     * <p>Update a user.</p>
604
     *
605
     * <p>It mirrors to the following Smartsheet REST API method: PUT /user/{id}</p>
606
     *
607
     * @param user the user to update
608
     * @return the updated user
609
     * @throws IllegalArgumentException    if any argument is null or empty string
610
     * @throws InvalidRequestException     if there is any problem with the REST API request
611
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
612
     * @throws ResourceNotFoundException   if the resource cannot be found
613
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
614
     * @throws SmartsheetException         if there is any other error during the operation
615
     */
616
    @Override
617
    public User updateUser(User user) throws SmartsheetException {
618
        return this.updateResource(USERS + "/" + user.getId(), User.class, user);
1 ✔
619
    }
620

621
    /**
622
     * <p>Fetch all user's plans.</p>
623
     *
624
     * <p>It mirrors to the following Smartsheet REST API method: GET /users/{userId}/plans</p>
625
     *
626
     * @param userId the id of the user whose plans to fetch
627
     * @param lastKey lastKey from previous response to get next page of results
628
     * @return UserPlansResponse json response
629
     * @throws IllegalArgumentException    if any argument is null or empty string
630
     * @throws InvalidRequestException     if there is any problem with the REST API request
631
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
632
     * @throws ResourceNotFoundException   if the resource cannot be found
633
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
634
     * @throws SmartsheetException         if there is any other error during the operation
635
     */
636
    @Override
637
    public TokenPaginatedResult<UserPlan> listUserPlans(long userId, String lastKey, Long maxItems) throws SmartsheetException {
638
        return listUserPlans(userId, lastKey, maxItems, null);
1 ✔
639
    }
640

641
    /**
642
     * <p>Fetch all user's plans.</p>
643
     *
644
     * <p>It mirrors to the following Smartsheet REST API method: GET /users/{userId}/plans</p>
645
     *
646
     * @param userId the id of the user whose plans to fetch
647
     * @param lastKey lastKey from previous response to get next page of results
648
     * @param maxItems maximum number of items to return
649
     * @param displayContributorSeatType if true, returns CONTRIBUTOR instead of VIEWER for eligible users
650
     * @return UserPlansResponse json response
651
     * @throws IllegalArgumentException    if any argument is null or empty string
652
     * @throws InvalidRequestException     if there is any problem with the REST API request
653
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
654
     * @throws ResourceNotFoundException   if the resource cannot be found
655
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
656
     * @throws SmartsheetException         if there is any other error during the operation
657
     */
658
    @Override
659
    public TokenPaginatedResult<UserPlan> listUserPlans(
660
            long userId,
661
            String lastKey,
662
            Long maxItems,
663
            Boolean displayContributorSeatType
664
    ) throws SmartsheetException {
665
        return listUserPlans(userId, lastKey, maxItems, displayContributorSeatType, null);
1 ✔
666
    }
667

668
    /**
669
     * <p>Fetch all user's plans.</p>
670
     *
671
     * <p>It mirrors to the following Smartsheet REST API method: GET /users/{userId}/plans</p>
672
     *
673
     * @param userId the id of the user whose plans to fetch
674
     * @param lastKey lastKey from previous response to get next page of results
675
     * @param maxItems maximum number of items to return
676
     * @param displayContributorSeatType if true, returns CONTRIBUTOR instead of VIEWER for eligible users
677
     * @param include elements to include in the response. Specifying
678
     *                {@link UserPlanInclusion#PLAN_NAME} populates {@link UserPlan#getPlanName()}
679
     *                with the name of the organization that owns each plan. Organization names are
680
     *                cached server side for several hours, so a recently renamed organization may
681
     *                briefly report its previous name.
682
     * @return UserPlansResponse json response
683
     * @throws IllegalArgumentException    if any argument is null or empty string
684
     * @throws InvalidRequestException     if there is any problem with the REST API request
685
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
686
     * @throws ResourceNotFoundException   if the resource cannot be found
687
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
688
     * @throws SmartsheetException         if there is any other error during the operation
689
     */
690
    @Override
691
    public TokenPaginatedResult<UserPlan> listUserPlans(
692
            long userId,
693
            String lastKey,
694
            Long maxItems,
695
            Boolean displayContributorSeatType,
696
            EnumSet<UserPlanInclusion> include
697
    ) throws SmartsheetException {
698

699
        String path = USERS + "/" + userId + "/plans";
1 ✔
700
        Map<String, Object> parameters = new HashMap<>();
1 ✔
701

702
        if (lastKey != null) {
1 ✔
703
            parameters.put("lastKey", lastKey);
1 ✔
704
        }
705

706
        if (maxItems != null) {
1 ✔
707
            parameters.put("maxItems", maxItems);
1 ✔
708
        }
709

710
        if (displayContributorSeatType != null) {
1 ✔
711
            parameters.put("displayContributorSeatType", displayContributorSeatType);
×
712
        }
713

714
        if (include != null) {
1 ✔
715
            parameters.put("include", QueryUtil.generateCommaSeparatedList(include));
×
716
        }
717

718
        path += QueryUtil.generateUrl(null, parameters);
1 ✔
719
        return this.listResourcesWithTokenPagination(path, UserPlan.class);
1 ✔
720
    }
721

722
    /**
723
     * <p>Remove's a user from a plan.</p>
724
     *
725
     * <p>It mirrors to the following Smartsheet REST API method: DELETE /2.0/users/{userId}/plans/{planId}</p>
726
     *
727
     * @param userId the id of the user whose plans to fetch
728
     * @param planId the id of the plan from which to remove the user
729
     * @throws IllegalArgumentException    if any argument is null or empty string
730
     * @throws InvalidRequestException     if there is any problem with the REST API request
731
     * @throws AuthorizationException      if there is any problem with  the REST API authorization (access token)
732
     * @throws ResourceNotFoundException   if the resource cannot be found
733
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
734
     * @throws SmartsheetException         if there is any other error during the operation
735
     */
736
    @Override
737
    public void removeUserFromPlan(long userId, long planId) throws SmartsheetException {
738
        deleteResource(USERS + "/" + userId + PLANS + planId, Object.class);
1 ✔
739
    }
1 ✔
740

741
    /**
742
     * <p>Upgrades a user's seat type.</p>
743
     *
744
     * <p>It mirrors to the following Smartsheet REST API method: POST /users/{userId}/plans/{planId}/upgrade</p>
745
     * @param userId the ID of the user to upgrade
746
     * @param planId the ID of the plan to upgrade to
747
     * @param seatType the new seat type for the user
748
     * @throws IllegalArgumentException if any argument is null or empty string
749
     * @throws InvalidRequestException if there is any problem with the REST API request
750
     * @throws AuthorizationException if there is any problem with the REST API authorization
751
     * @throws ResourceNotFoundException if the resource cannot be found
752
     * @throws ServiceUnavailableException if the REST API service is not available
753
     * @throws SmartsheetException if there is any other error during the operation
754
     */
755
    @Override
756
    public void upgradeUser(long userId, long planId, UpgradeSeatType seatType) throws SmartsheetException {
757
        if (seatType != null) {
1 ✔
758
            changeSeatType(seatType.name(), USERS + "/" + userId + PLANS + planId + "/upgrade");
1 ✔
759
            return;
1 ✔
760
        }
761
        changeSeatType(null, USERS + "/" + userId + PLANS + planId + "/upgrade");
×
762
    }
×
763

764
    /**
765
     * <p>Downgrades a user's seat type.</p>
766
     *
767
     * <p>It mirrors to the following Smartsheet REST API method: POST /users/{userId}/plans/{planId}/downgrade</p>
768
     * @param userId the ID of the user to downgrade
769
     * @param planId the ID of the plan to downgrade to
770
     * @param seatType the new seat type for the user
771
     * @throws IllegalArgumentException if any argument is null or empty string
772
     * @throws InvalidRequestException if there is any problem with the REST API request
773
     * @throws AuthorizationException if there is any problem with the REST API authorization
774
     * @throws ResourceNotFoundException if the resource cannot be found
775
     * @throws ServiceUnavailableException if the REST API service is not available
776
     * @throws SmartsheetException if there is any other error during the operation
777
     */
778
    @Override
779
    public void downgradeUser(long userId, long planId, DowngradeSeatType seatType) throws SmartsheetException {
780
        Util.throwIfNull(seatType);
1 ✔
781
        changeSeatType(seatType.name(), USERS + "/" + userId + PLANS + planId + "/downgrade");
1 ✔
782
    }
1 ✔
783

784
    private void changeSeatType(String seatType, String path) throws SmartsheetException {
785
        Map<String, String> body = Collections.emptyMap();
1 ✔
786
        if (seatType != null) {
1 ✔
787
            body = Map.of("seatType", seatType);
1 ✔
788
        }
789
        createResource(path, Result.class, body);
1 ✔
790
    }
1 ✔
791

792
    /**
793
     * <p>Reactivates a user.</p>
794
     *
795
     * <p>Reactivates the user associated with the current Smartsheet plan, restoring the user's access to
796
     * Smartsheet, owned items, and shared items.</p>
797
     *
798
     * <p>Important: You can reactivate the user only if that user has been deactivated for less than thirty (30) days.</p>
799
     *
800
     * <p>It mirrors to the following Smartsheet REST API method: POST /users/{userId}/reactivate</p>
801
     *
802
     * @param userId the id of the user to reactivate
803
     * @throws IllegalArgumentException    if any argument is null or empty string
804
     * @throws InvalidRequestException     if there is any problem with the REST API request (e.g., user email belongs to ISP domain)
805
     * @throws AuthorizationException      if there is any problem with the REST API authorization (access token)
806
     * @throws ResourceNotFoundException   if the resource cannot be found
807
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
808
     * @throws SmartsheetException         if there is any other error during the operation
809
     */
810
    @Override
811
    public void reactivateUser(long userId) throws SmartsheetException {
812
        createResource(USERS + "/" + userId + "/reactivate", Result.class, Collections.emptyMap());
×
813
    }
×
814

815
    /**
816
     * <p>Deactivates a user.</p>
817
     *
818
     * <p>Deactivates the user associated with the current Smartsheet plan, blocking the user from using Smartsheet in any way.
819
     * Deactivating a user does not affect their existing permissions on owned or shared items.</p>
820
     *
821
     * <p>It mirrors to the following Smartsheet REST API method: POST /users/{userId}/deactivate</p>
822
     *
823
     * @param userId the id of the user to deactivate
824
     * @throws IllegalArgumentException    if any argument is null or empty string
825
     * @throws InvalidRequestException     if there is any problem with the REST API request
826
     *                                     (e.g., user email belongs to ISP domain or user is managed by external source)
827
     * @throws AuthorizationException      if there is any problem with the REST API authorization (access token)
828
     * @throws ResourceNotFoundException   if the resource cannot be found
829
     * @throws ServiceUnavailableException if the REST API service is not available (possibly due to rate limiting)
830
     * @throws SmartsheetException         if there is any other error during the operation
831
     */
832
    @Override
833
    public void deactivateUser(long userId) throws SmartsheetException {
834
        createResource(USERS + "/" + userId + "/deactivate", Result.class, Collections.emptyMap());
×
835
    }
×
836

837
    @Override
838
    public void deleteUser(long userId, DeleteUserParameters parameters) throws SmartsheetException {
839
        String path = USERS + "/" + userId;
1 ✔
840

841
        if (parameters != null) {
1 ✔
842
            path += parameters.toQueryString();
1 ✔
843
        }
844

845
        this.deleteResource(path, User.class);
1 ✔
846
    }
1 ✔
847
}
STATUS · Troubleshooting · Open an Issue · Sales · Support · CAREERS · ENTERPRISE · START FREE TRIAL · SCHEDULE DEMO
ANNOUNCEMENTS · TWITTER · TOS & SLA · Supported CI Services · What's a CI service? · Automated Testing

© 2026 Coveralls, Inc