Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,10 @@ public enum ErrorMessage {
"Invalid device name.",
"Device name must be a non-blank string of at most 255 characters."),

ERROR_CODE_INVALID_PATCH_REQUEST("60103",
"Invalid device update request.",
"At least one of 'deviceName' or 'status' must be provided."),

ERROR_CODE_ERROR_LISTING_DEVICES("65101",
"Unable to list devices.",
"Server encountered an error while listing devices."),
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ public Response getDevice(@ApiParam(value = "UUID of the registered device",requ
@ApiResponse(code = 403, message = "Forbidden", response = Void.class),
@ApiResponse(code = 500, message = "Server Error", response = Error.class)
})
public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maximum number of records to return.", defaultValue="30") @DefaultValue("30") @QueryParam("limit") Integer limit, @Valid @Min(0)@ApiParam(value = "Number of records to skip for pagination.", defaultValue="0") @DefaultValue("0") @QueryParam("offset") Integer offset, @Valid@ApiParam(value = "Filter devices by the ID of the user who registered them. Returns devices of any status. Pagination applies as usual.") @QueryParam("userId") String userId) {
public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maximum number of records to return.", defaultValue="30") @DefaultValue("30") @QueryParam("limit") Integer limit, @Valid @Min(0)@ApiParam(value = "Number of records to skip for pagination.", defaultValue="0") @DefaultValue("0") @QueryParam("offset") Integer offset, @Valid@ApiParam(value = "Filter devices by the ID of the user who registered them. Returns devices of any status. Pagination applies as usual. In an organization, a shared user gets the devices it inherits from its resident organization.") @QueryParam("userId") String userId) {

return delegate.listDevices(limit, offset, userId );
}
Expand All @@ -123,7 +123,7 @@ public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maxim
@Path("/{device-id}")
@Consumes({ "application/json" })
@Produces({ "application/json" })
@ApiOperation(value = "Rename a registered device.", notes = "This API provides the capability to update the display name of a registered device. <b>Scope (Permission) required:</b> ``internal_device_mgt_update`` ", response = DeviceResponse.class, authorizations = {
@ApiOperation(value = "Update a registered device.", notes = "This API provides the capability to rename, activate or deactivate a registered device. At least one of 'deviceName' or 'status' must be provided. <b>Scope (Permission) required:</b> ``internal_device_mgt_update`` ", response = DeviceResponse.class, authorizations = {
@Authorization(value = "BasicAuth"),
@Authorization(value = "OAuth2", scopes = {

Expand All @@ -137,9 +137,9 @@ public Response listDevices( @Valid @Min(1) @Max(100)@ApiParam(value = "Maxim
@ApiResponse(code = 404, message = "Not Found", response = Error.class),
@ApiResponse(code = 500, message = "Server Error", response = Error.class)
})
public Response updateDeviceName(@ApiParam(value = "UUID of the registered device",required=true) @PathParam("device-id") String deviceId, @ApiParam(value = "" ,required=true) @Valid DevicePatchRequest devicePatchRequest) {
public Response updateDevice(@ApiParam(value = "UUID of the registered device",required=true) @PathParam("device-id") String deviceId, @ApiParam(value = "" ,required=true) @Valid DevicePatchRequest devicePatchRequest) {

return delegate.updateDeviceName(deviceId, devicePatchRequest );
return delegate.updateDevice(deviceId, devicePatchRequest );
}

}
Original file line number Diff line number Diff line change
Expand Up @@ -39,5 +39,5 @@ public interface DevicesApiService {

public Response listDevices(Integer limit, Integer offset, String userId);

public Response updateDeviceName(String deviceId, DevicePatchRequest devicePatchRequest);
public Response updateDevice(String deviceId, DevicePatchRequest devicePatchRequest);
}
Original file line number Diff line number Diff line change
Expand Up @@ -24,16 +24,53 @@
import io.swagger.annotations.ApiModelProperty;
import javax.validation.constraints.*;

/**
* Fields to update. At least one of &#39;deviceName&#39; or &#39;status&#39; must be provided.
**/

import io.swagger.annotations.*;
import java.util.Objects;
import javax.validation.Valid;
import javax.xml.bind.annotation.*;

@ApiModel(description = "Fields to update. At least one of 'deviceName' or 'status' must be provided.")
public class DevicePatchRequest {

private String deviceName;

@XmlType(name="StatusEnum")
@XmlEnum(String.class)
public enum StatusEnum {

@XmlEnumValue("ACTIVE") ACTIVE(String.valueOf("ACTIVE")), @XmlEnumValue("INACTIVE") INACTIVE(String.valueOf("INACTIVE"));


private String value;

StatusEnum(String v) {
value = v;
}

public String value() {
return value;
}

@Override
public String toString() {
return String.valueOf(value);
}

public static StatusEnum fromValue(String value) {
for (StatusEnum b : StatusEnum.values()) {
if (b.value.equals(value)) {
return b;
}
}
throw new IllegalArgumentException("Unexpected value '" + value + "'");
}
}

private StatusEnum status;

/**
* The new display name for the device.
**/
Expand All @@ -43,18 +80,35 @@ public DevicePatchRequest deviceName(String deviceName) {
return this;
}

@ApiModelProperty(example = "My Work Phone", required = true, value = "The new display name for the device.")
@ApiModelProperty(example = "My Work Phone", value = "The new display name for the device.")
@JsonProperty("deviceName")
@Valid
@NotNull(message = "Property deviceName cannot be null.")
@Size(min=1,max=255)
@Valid @Size(min=1,max=255)
public String getDeviceName() {
return deviceName;
}
public void setDeviceName(String deviceName) {
this.deviceName = deviceName;
}

/**
* The new status of the device. An inactive device cannot be used for device-based login checks.
**/
public DevicePatchRequest status(StatusEnum status) {

this.status = status;
return this;
}

@ApiModelProperty(example = "INACTIVE", value = "The new status of the device. An inactive device cannot be used for device-based login checks.")
@JsonProperty("status")
@Valid
public StatusEnum getStatus() {
return status;
}
public void setStatus(StatusEnum status) {
this.status = status;
}



@Override
Expand All @@ -67,12 +121,13 @@ public boolean equals(java.lang.Object o) {
return false;
}
DevicePatchRequest devicePatchRequest = (DevicePatchRequest) o;
return Objects.equals(this.deviceName, devicePatchRequest.deviceName);
return Objects.equals(this.deviceName, devicePatchRequest.deviceName) &&
Objects.equals(this.status, devicePatchRequest.status);
}

@Override
public int hashCode() {
return Objects.hash(deviceName);
return Objects.hash(deviceName, status);
}

@Override
Expand All @@ -82,6 +137,7 @@ public String toString() {
sb.append("class DevicePatchRequest {\n");

sb.append(" deviceName: ").append(toIndentedString(deviceName)).append("\n");
sb.append(" status: ").append(toIndentedString(status)).append("\n");
sb.append("}");
return sb.toString();
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,8 @@
import javax.ws.rs.core.Response;

/**
* Core service for Device Management API — handles listing, renaming and deleting devices.
* Core service for Device Management API — handles listing, renaming, activating, deactivating and deleting
* devices.
*/
public class DeviceManagementApiService {

Expand Down Expand Up @@ -208,53 +209,103 @@ public DeviceResponse getDevice(String deviceId) {
String tenantDomain = ContextLoader.getTenantDomainFromContext();
Device device = deviceManagementService.getDeviceById(deviceId, tenantDomain);
if (device == null) {
throw new APIError(Response.Status.NOT_FOUND, new ErrorResponse.Builder()
.withCode(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.code())
.withMessage(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.message())
.withDescription(String.format(
Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.description(), deviceId))
.build(LOG, "Device not found for id: " + deviceId));
throw buildDeviceNotFoundError(deviceId);
}
return DeviceResponseBuilder.buildDeviceResponse(device);
} catch (DeviceMgtException e) {
throw handleException(e, Constants.ErrorMessage.ERROR_CODE_ERROR_RETRIEVING_DEVICE);
}
}

private APIError buildDeviceNotFoundError(String deviceId) {

return new APIError(Response.Status.NOT_FOUND, new ErrorResponse.Builder()
.withCode(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.code())
.withMessage(Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.message())
.withDescription(String.format(
Constants.ErrorMessage.ERROR_CODE_DEVICE_NOT_FOUND.description(), deviceId))
.build(LOG, "Device not found for id: " + deviceId));
}

/**
* Updates the display name of a device.
* Updates a device. Renames the device when a device name is given and activates or deactivates it when a
* status is given. Both can be applied in the same request.
*
* @param deviceId Device UUID.
* @param patchRequest Request body containing the new name.
* @return Updated DeviceResponse.
* @param patchRequest Fields to update.
* @return DeviceResponse reflecting the updated device.
*/
public DeviceResponse updateDeviceName(String deviceId, DevicePatchRequest patchRequest) {
public DeviceResponse updateDevice(String deviceId, DevicePatchRequest patchRequest) {

validateApiEnabled();
validateDeviceName(patchRequest);
validatePatchRequest(patchRequest);

try {
String tenantDomain = ContextLoader.getTenantDomainFromContext();
Device updated = deviceManagementService.updateDeviceName(
deviceId, patchRequest.getDeviceName(), tenantDomain);
return DeviceResponseBuilder.buildDeviceResponse(updated);
Device device = deviceManagementService.getDeviceById(deviceId, tenantDomain);
if (device == null) {
throw buildDeviceNotFoundError(deviceId);
}

if (patchRequest.getDeviceName() != null) {
device = deviceManagementService.updateDeviceName(
deviceId, patchRequest.getDeviceName(), tenantDomain);
}
if (patchRequest.getStatus() != null) {
device = updateDeviceStatus(device, patchRequest.getStatus(), tenantDomain);
Comment thread
DilshanSenarath marked this conversation as resolved.
Resolved
}
return DeviceResponseBuilder.buildDeviceResponse(device);
} catch (DeviceMgtException e) {
throw handleException(e, Constants.ErrorMessage.ERROR_CODE_ERROR_UPDATING_DEVICE);
}
}

private void validateDeviceName(DevicePatchRequest patchRequest) {
/**
* Activates or deactivates the device. Nothing is changed when the device already has the requested status.
*
* @param device Device to update.
* @param status Requested status.
* @param tenantDomain Tenant domain.
* @return Device reflecting the requested status.
* @throws DeviceMgtException If the status update fails.
*/
private Device updateDeviceStatus(Device device, DevicePatchRequest.StatusEnum status, String tenantDomain)
throws DeviceMgtException {

Device.Status requestedStatus = Device.Status.valueOf(status.value());
if (requestedStatus == device.getStatus()) {
if (LOG.isDebugEnabled()) {
LOG.debug("The device: " + device.getId() + " is already " + requestedStatus
+ ". Skipping the status update.");
}
return device;
}
if (requestedStatus == Device.Status.ACTIVE) {
return deviceManagementService.activateDevice(device.getId(), tenantDomain);
}
return deviceManagementService.deactivateDevice(device.getId(), tenantDomain);
}

String deviceName = patchRequest != null ? patchRequest.getDeviceName() : null;
if (StringUtils.isBlank(deviceName) || deviceName.length() > DEVICE_NAME_MAX_LENGTH) {
throw new APIError(Response.Status.BAD_REQUEST, new ErrorResponse.Builder()
.withCode(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME.code())
.withMessage(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME.message())
.withDescription(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME.description())
.build(LOG, "Invalid device name."));
private void validatePatchRequest(DevicePatchRequest patchRequest) {

if (patchRequest == null || (patchRequest.getDeviceName() == null && patchRequest.getStatus() == null)) {
throw buildBadRequestError(Constants.ErrorMessage.ERROR_CODE_INVALID_PATCH_REQUEST);
}
String deviceName = patchRequest.getDeviceName();
if (deviceName != null && (StringUtils.isBlank(deviceName) || deviceName.length() > DEVICE_NAME_MAX_LENGTH)) {
throw buildBadRequestError(Constants.ErrorMessage.ERROR_CODE_INVALID_DEVICE_NAME);
}
}

private APIError buildBadRequestError(Constants.ErrorMessage error) {

return new APIError(Response.Status.BAD_REQUEST, new ErrorResponse.Builder()
.withCode(error.code())
.withMessage(error.message())
.withDescription(error.description())
.build(LOG, error.message()));
}

/**
* Deletes a device by ID.
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -50,9 +50,9 @@ public Response getDevice(String deviceId) {
}

@Override
public Response updateDeviceName(String deviceId, DevicePatchRequest patchRequest) {
public Response updateDevice(String deviceId, DevicePatchRequest patchRequest) {

return Response.ok().entity(service.updateDeviceName(deviceId, patchRequest)).build();
return Response.ok().entity(service.updateDevice(deviceId, patchRequest)).build();
}

@Override
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -127,9 +127,10 @@ paths:
patch:
tags:
- Device Management
summary: Rename a registered device.
operationId: updateDeviceName
description: "This API provides the capability to update the display name of a registered device.\n\n
summary: Update a registered device.
operationId: updateDevice
description: "This API provides the capability to rename, activate or deactivate a registered device.
At least one of 'deviceName' or 'status' must be provided.\n\n
<b>Scope (Permission) required:</b> ``internal_device_mgt_update``\n\n"
parameters:
- name: device-id
Expand Down Expand Up @@ -288,15 +289,21 @@ components:
example: "2026-04-27T10:00:00.000Z"
DevicePatchRequest:
type: object
required:
- deviceName
description: Fields to update. At least one of 'deviceName' or 'status' must be provided.
properties:
deviceName:
type: string
minLength: 1
maxLength: 255
description: The new display name for the device.
example: "My Work Phone"
status:
type: string
enum:
- ACTIVE
- INACTIVE
description: The new status of the device. An inactive device cannot be used for device-based login checks.
example: "INACTIVE"
Error:
type: object
properties:
Expand Down
Loading