简柏林 / thingskit · Commits

Commit 339deb1d3ca76730fc10bd2ede9d4cbac3aecb58

Authored by Dima Landiak
2 parents 85b1cd04 96cdae87

Merge branch 'feature/swagger' into feature/swagger-device-profile-data

Inline Side-by-side
Showing 30 changed files with 573 additions and 237 deletions
... ... @@ -46,7 +46,6 @@ import org.thingsboard.server.service.update.UpdateService;
46 46 @RequestMapping("/api/admin")
47 47 public class AdminController extends BaseController {
48 48
49   - public static final String SYS_ADMIN_AUTHORITY_ONLY = " Available for users with System Administrator ('SYS_ADMIN') authority only.";
50 49 @Autowired
51 50 private MailService mailService;
52 51
... ... @@ -63,7 +62,7 @@ public class AdminController extends BaseController {
63 62 private UpdateService updateService;
64 63
65 64 @ApiOperation(value = "Get the Administration Settings object using key (getAdminSettings)",
66   - notes = "Get the Administration Settings object using specified string key. Referencing non-existing key will cause an error." + SYS_ADMIN_AUTHORITY_ONLY)
  65 + notes = "Get the Administration Settings object using specified string key. Referencing non-existing key will cause an error." + SYSTEM_AUTHORITY_PARAGRAPH)
67 66 @PreAuthorize("hasAuthority('SYS_ADMIN')")
68 67 @RequestMapping(value = "/settings/{key}", method = RequestMethod.GET)
69 68 @ResponseBody
... ... @@ -86,7 +85,7 @@ public class AdminController extends BaseController {
86 85 @ApiOperation(value = "Get the Administration Settings object using key (getAdminSettings)",
87 86 notes = "Creates or Updates the Administration Settings. Platform generates random Administration Settings Id during settings creation. " +
88 87 "The Administration Settings Id will be present in the response. Specify the Administration Settings Id when you would like to update the Administration Settings. " +
89   - "Referencing non-existing Administration Settings Id will cause an error." + SYS_ADMIN_AUTHORITY_ONLY)
  88 + "Referencing non-existing Administration Settings Id will cause an error." + SYSTEM_AUTHORITY_PARAGRAPH)
90 89 @PreAuthorize("hasAuthority('SYS_ADMIN')")
91 90 @RequestMapping(value = "/settings", method = RequestMethod.POST)
92 91 @ResponseBody
... ... @@ -109,7 +108,7 @@ public class AdminController extends BaseController {
109 108 }
110 109
111 110 @ApiOperation(value = "Get the Security Settings object",
112   - notes = "Get the Security Settings object that contains password policy, etc." + SYS_ADMIN_AUTHORITY_ONLY)
  111 + notes = "Get the Security Settings object that contains password policy, etc." + SYSTEM_AUTHORITY_PARAGRAPH)
113 112 @PreAuthorize("hasAuthority('SYS_ADMIN')")
114 113 @RequestMapping(value = "/securitySettings", method = RequestMethod.GET)
115 114 @ResponseBody
... ... @@ -123,7 +122,7 @@ public class AdminController extends BaseController {
123 122 }
124 123
125 124 @ApiOperation(value = "Update Security Settings (saveSecuritySettings)",
126   - notes = "Updates the Security Settings object that contains password policy, etc." + SYS_ADMIN_AUTHORITY_ONLY)
  125 + notes = "Updates the Security Settings object that contains password policy, etc." + SYSTEM_AUTHORITY_PARAGRAPH)
127 126 @PreAuthorize("hasAuthority('SYS_ADMIN')")
128 127 @RequestMapping(value = "/securitySettings", method = RequestMethod.POST)
129 128 @ResponseBody
... ... @@ -141,7 +140,7 @@ public class AdminController extends BaseController {
141 140
142 141 @ApiOperation(value = "Send test email (sendTestMail)",
143 142 notes = "Attempts to send test email to the System Administrator User using Mail Settings provided as a parameter. " +
144   - "You may change the 'To' email in the user profile of the System Administrator. " + SYS_ADMIN_AUTHORITY_ONLY)
  143 + "You may change the 'To' email in the user profile of the System Administrator. " + SYSTEM_AUTHORITY_PARAGRAPH)
145 144 @PreAuthorize("hasAuthority('SYS_ADMIN')")
146 145 @RequestMapping(value = "/settings/testMail", method = RequestMethod.POST)
147 146 public void sendTestMail(
... ... @@ -165,7 +164,7 @@ public class AdminController extends BaseController {
165 164
166 165 @ApiOperation(value = "Send test sms (sendTestMail)",
167 166 notes = "Attempts to send test sms to the System Administrator User using SMS Settings and phone number provided as a parameters of the request. "
168   - + SYS_ADMIN_AUTHORITY_ONLY)
  167 + + SYSTEM_AUTHORITY_PARAGRAPH)
169 168 @PreAuthorize("hasAuthority('SYS_ADMIN')")
170 169 @RequestMapping(value = "/settings/testSms", method = RequestMethod.POST)
171 170 public void sendTestSms(
... ... @@ -181,7 +180,7 @@ public class AdminController extends BaseController {
181 180
182 181 @ApiOperation(value = "Check for new Platform Releases (checkUpdates)",
183 182 notes = "Check notifications about new platform releases. "
184   - + SYS_ADMIN_AUTHORITY_ONLY)
  183 + + SYSTEM_AUTHORITY_PARAGRAPH)
185 184 @PreAuthorize("hasAuthority('SYS_ADMIN')")
186 185 @RequestMapping(value = "/updates", method = RequestMethod.GET)
187 186 @ResponseBody
... ...
... ... @@ -88,7 +88,7 @@ public class AlarmController extends BaseController {
88 88
89 89 @ApiOperation(value = "Get Alarm Info (getAlarmInfoById)",
90 90 notes = "Fetch the Alarm Info object based on the provided Alarm Id. " +
91   - ALARM_SECURITY_CHECK + ALARM_INFO_DESCRIPTION, produces = MediaType.APPLICATION_JSON_VALUE)
  91 + ALARM_SECURITY_CHECK + ALARM_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
92 92 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
93 93 @RequestMapping(value = "/alarm/info/{alarmId}", method = RequestMethod.GET)
94 94 @ResponseBody
... ... @@ -111,7 +111,7 @@ public class AlarmController extends BaseController {
111 111 "\n\nPlatform also deduplicate the alarms based on the entity id of originator and alarm 'type'. " +
112 112 "For example, if the user or system component create the alarm with the type 'HighTemperature' for device 'Device A' the new active alarm is created. " +
113 113 "If the user tries to create 'HighTemperature' alarm for the same device again, the previous alarm will be updated (the 'end_ts' will be set to current timestamp). " +
114   - "If the user clears the alarm (see 'Clear Alarm(clearAlarm)'), than new alarm with the same type and same device may be created. "
  114 + "If the user clears the alarm (see 'Clear Alarm(clearAlarm)'), than new alarm with the same type and same device may be created. " + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH
115 115 , produces = MediaType.APPLICATION_JSON_VALUE)
116 116 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
117 117 @RequestMapping(value = "/alarm", method = RequestMethod.POST)
... ... @@ -138,7 +138,7 @@ public class AlarmController extends BaseController {
138 138 }
139 139
140 140 @ApiOperation(value = "Delete Alarm (deleteAlarm)",
141   - notes = "Deletes the Alarm. Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
  141 + notes = "Deletes the Alarm. Referencing non-existing Alarm Id will cause an error." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
142 142 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
143 143 @RequestMapping(value = "/alarm/{alarmId}", method = RequestMethod.DELETE)
144 144 @ResponseBody
... ... @@ -165,7 +165,7 @@ public class AlarmController extends BaseController {
165 165 @ApiOperation(value = "Acknowledge Alarm (ackAlarm)",
166 166 notes = "Acknowledge the Alarm. " +
167 167 "Once acknowledged, the 'ack_ts' field will be set to current timestamp and special rule chain event 'ALARM_ACK' will be generated. " +
168   - "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
  168 + "Referencing non-existing Alarm Id will cause an error." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
169 169 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
170 170 @RequestMapping(value = "/alarm/{alarmId}/ack", method = RequestMethod.POST)
171 171 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -189,7 +189,7 @@ public class AlarmController extends BaseController {
189 189 @ApiOperation(value = "Clear Alarm (clearAlarm)",
190 190 notes = "Clear the Alarm. " +
191 191 "Once cleared, the 'clear_ts' field will be set to current timestamp and special rule chain event 'ALARM_CLEAR' will be generated. " +
192   - "Referencing non-existing Alarm Id will cause an error.", produces = MediaType.APPLICATION_JSON_VALUE)
  192 + "Referencing non-existing Alarm Id will cause an error." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
193 193 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
194 194 @RequestMapping(value = "/alarm/{alarmId}/clear", method = RequestMethod.POST)
195 195 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -212,8 +212,8 @@ public class AlarmController extends BaseController {
212 212
213 213 @ApiOperation(value = "Get Alarms (getAlarms)",
214 214 notes = "Returns a page of alarms for the selected entity. Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error. " +
215   - PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
216   - @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
  215 + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
  216 + @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
217 217 @RequestMapping(value = "/alarm/{entityType}/{entityId}", method = RequestMethod.GET)
218 218 @ResponseBody
219 219 public PageData<AlarmInfo> getAlarms(
... ... @@ -265,7 +265,7 @@ public class AlarmController extends BaseController {
265 265 "If the user has the authority of 'Tenant Administrator', the server returns alarms that belongs to the tenant of current user. " +
266 266 "If the user has the authority of 'Customer User', the server returns alarms that belongs to the customer of current user. " +
267 267 "Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error. " +
268   - PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
  268 + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
269 269 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
270 270 @RequestMapping(value = "/alarms", method = RequestMethod.GET)
271 271 @ResponseBody
... ... @@ -312,7 +312,7 @@ public class AlarmController extends BaseController {
312 312
313 313 @ApiOperation(value = "Get Highest Alarm Severity (getHighestAlarmSeverity)",
314 314 notes = "Search the alarms by originator ('entityType' and entityId') and optional 'status' or 'searchStatus' filters and returns the highest AlarmSeverity(CRITICAL, MAJOR, MINOR, WARNING or INDETERMINATE). " +
315   - "Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error."
  315 + "Specifying both parameters 'searchStatus' and 'status' at the same time will cause an error." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH
316 316 , produces = MediaType.APPLICATION_JSON_VALUE)
317 317 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
318 318 @RequestMapping(value = "/alarm/highestSeverity/{entityType}/{entityId}", method = RequestMethod.GET)
... ...
... ... @@ -80,7 +80,8 @@ public class AssetController extends BaseController {
80 80 @ApiOperation(value = "Get Asset (getAssetById)",
81 81 notes = "Fetch the Asset object based on the provided Asset Id. " +
82 82 "If the user has the authority of 'Tenant Administrator', the server checks that the asset is owned by the same tenant. " +
83   - "If the user has the authority of 'Customer User', the server checks that the asset is assigned to the same customer.", produces = MediaType.APPLICATION_JSON_VALUE)
  83 + "If the user has the authority of 'Customer User', the server checks that the asset is assigned to the same customer." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH
  84 + , produces = MediaType.APPLICATION_JSON_VALUE)
84 85 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
85 86 @RequestMapping(value = "/asset/{assetId}", method = RequestMethod.GET)
86 87 @ResponseBody
... ... @@ -98,7 +99,8 @@ public class AssetController extends BaseController {
98 99 @ApiOperation(value = "Get Asset Info (getAssetInfoById)",
99 100 notes = "Fetch the Asset Info object based on the provided Asset Id. " +
100 101 "If the user has the authority of 'Tenant Administrator', the server checks that the asset is owned by the same tenant. " +
101   - "If the user has the authority of 'Customer User', the server checks that the asset is assigned to the same customer. " + ASSET_INFO_DESCRIPTION, produces = MediaType.APPLICATION_JSON_VALUE)
  102 + "If the user has the authority of 'Customer User', the server checks that the asset is assigned to the same customer. "
  103 + + ASSET_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
102 104 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
103 105 @RequestMapping(value = "/asset/info/{assetId}", method = RequestMethod.GET)
104 106 @ResponseBody
... ... @@ -117,7 +119,7 @@ public class AssetController extends BaseController {
117 119 notes = "Creates or Updates the Asset. When creating asset, platform generates Asset Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address) " +
118 120 "The newly created Asset id will be present in the response. " +
119 121 "Specify existing Asset id to update the asset. " +
120   - "Referencing non-existing Asset Id will cause 'Not Found' error.", produces = MediaType.APPLICATION_JSON_VALUE)
  122 + "Referencing non-existing Asset Id will cause 'Not Found' error." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
121 123 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
122 124 @RequestMapping(value = "/asset", method = RequestMethod.POST)
123 125 @ResponseBody
... ... @@ -158,7 +160,7 @@ public class AssetController extends BaseController {
158 160 }
159 161
160 162 @ApiOperation(value = "Delete asset (deleteAsset)",
161   - notes = "Deletes the asset and all the relations (from and to the asset). Referencing non-existing asset Id will cause an error.")
  163 + notes = "Deletes the asset and all the relations (from and to the asset). Referencing non-existing asset Id will cause an error." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
162 164 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
163 165 @RequestMapping(value = "/asset/{assetId}", method = RequestMethod.DELETE)
164 166 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -187,7 +189,7 @@ public class AssetController extends BaseController {
187 189 }
188 190
189 191 @ApiOperation(value = "Assign asset to customer (assignAssetToCustomer)",
190   - notes = "Creates assignment of the asset to customer. Customer will be able to query asset afterwards.", produces = MediaType.APPLICATION_JSON_VALUE)
  192 + notes = "Creates assignment of the asset to customer. Customer will be able to query asset afterwards." + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
191 193 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
192 194 @RequestMapping(value = "/customer/{customerId}/asset/{assetId}", method = RequestMethod.POST)
193 195 @ResponseBody
... ... @@ -223,7 +225,7 @@ public class AssetController extends BaseController {
223 225 }
224 226
225 227 @ApiOperation(value = "Unassign asset from customer (unassignAssetFromCustomer)",
226   - notes = "Clears assignment of the asset to customer. Customer will not be able to query asset afterwards.", produces = MediaType.APPLICATION_JSON_VALUE)
  228 + notes = "Clears assignment of the asset to customer. Customer will not be able to query asset afterwards." + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
227 229 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
228 230 @RequestMapping(value = "/customer/asset/{assetId}", method = RequestMethod.DELETE)
229 231 @ResponseBody
... ... @@ -261,7 +263,7 @@ public class AssetController extends BaseController {
261 263 @ApiOperation(value = "Make asset publicly available (assignAssetToPublicCustomer)",
262 264 notes = "Asset will be available for non-authorized (not logged-in) users. " +
263 265 "This is useful to create dashboards that you plan to share/embed on a publicly available website. " +
264   - "However, users that are logged-in and belong to different tenant will not be able to access the asset.", produces = MediaType.APPLICATION_JSON_VALUE)
  266 + "However, users that are logged-in and belong to different tenant will not be able to access the asset." + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
265 267 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
266 268 @RequestMapping(value = "/customer/public/asset/{assetId}", method = RequestMethod.POST)
267 269 @ResponseBody
... ... @@ -290,7 +292,7 @@ public class AssetController extends BaseController {
290 292
291 293 @ApiOperation(value = "Get Tenant Assets (getTenantAssets)",
292 294 notes = "Returns a page of assets owned by tenant. " +
293   - PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
  295 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
294 296 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
295 297 @RequestMapping(value = "/tenant/assets", params = {"pageSize", "page"}, method = RequestMethod.GET)
296 298 @ResponseBody
... ... @@ -322,7 +324,7 @@ public class AssetController extends BaseController {
322 324
323 325 @ApiOperation(value = "Get Tenant Asset Infos (getTenantAssetInfos)",
324 326 notes = "Returns a page of assets info objects owned by tenant. " +
325   - PAGE_DATA_PARAMETERS + ASSET_INFO_DESCRIPTION, produces = MediaType.APPLICATION_JSON_VALUE)
  327 + PAGE_DATA_PARAMETERS + ASSET_INFO_DESCRIPTION + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
326 328 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
327 329 @RequestMapping(value = "/tenant/assetInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
328 330 @ResponseBody
... ... @@ -354,7 +356,7 @@ public class AssetController extends BaseController {
354 356
355 357 @ApiOperation(value = "Get Tenant Asset (getTenantAsset)",
356 358 notes = "Requested asset must be owned by tenant that the user belongs to. " +
357   - "Asset name is an unique property of asset. So it can be used to identify the asset.", produces = MediaType.APPLICATION_JSON_VALUE)
  359 + "Asset name is an unique property of asset. So it can be used to identify the asset." + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
358 360 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
359 361 @RequestMapping(value = "/tenant/assets", params = {"assetName"}, method = RequestMethod.GET)
360 362 @ResponseBody
... ...
... ... @@ -60,7 +60,7 @@ public class AuditLogController extends BaseController {
60 60 @ApiOperation(value = "Get audit logs by customer id (getAuditLogsByCustomerId)",
61 61 notes = "Returns a page of audit logs related to the targeted customer entities (devices, assets, etc.), " +
62 62 "and users actions (login, logout, etc.) that belong to this customer. " +
63   - PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
  63 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH,
64 64 produces = MediaType.APPLICATION_JSON_VALUE)
65 65 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
66 66 @RequestMapping(value = "/audit/logs/customer/{customerId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -98,7 +98,7 @@ public class AuditLogController extends BaseController {
98 98 @ApiOperation(value = "Get audit logs by user id (getAuditLogsByUserId)",
99 99 notes = "Returns a page of audit logs related to the actions of targeted user. " +
100 100 "For example, RPC call to a particular device, or alarm acknowledgment for a specific device, etc. " +
101   - PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
  101 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH,
102 102 produces = MediaType.APPLICATION_JSON_VALUE)
103 103 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
104 104 @RequestMapping(value = "/audit/logs/user/{userId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -137,7 +137,7 @@ public class AuditLogController extends BaseController {
137 137 notes = "Returns a page of audit logs related to the actions on the targeted entity. " +
138 138 "Basically, this API call is used to get the full lifecycle of some specific entity. " +
139 139 "For example to see when a device was created, updated, assigned to some customer, or even deleted from the system. " +
140   - PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
  140 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH,
141 141 produces = MediaType.APPLICATION_JSON_VALUE)
142 142 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
143 143 @RequestMapping(value = "/audit/logs/entity/{entityType}/{entityId}", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -177,7 +177,7 @@ public class AuditLogController extends BaseController {
177 177
178 178 @ApiOperation(value = "Get all audit logs (getAuditLogs)",
179 179 notes = "Returns a page of audit logs related to all entities in the scope of the current user's Tenant. " +
180   - PAGE_DATA_PARAMETERS + ADMINISTRATOR_AUTHORITY_ONLY,
  180 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH,
181 181 produces = MediaType.APPLICATION_JSON_VALUE)
182 182 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
183 183 @RequestMapping(value = "/audit/logs", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ...
... ... @@ -181,11 +181,16 @@ public abstract class BaseController {
181 181 public static final String ENTITY_ID_PARAM_DESCRIPTION = "A string value representing the entity id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
182 182 public static final String ENTITY_TYPE_PARAM_DESCRIPTION = "A string value representing the entity type. For example, 'DEVICE'";
183 183 public static final String RULE_CHAIN_ID_PARAM_DESCRIPTION = "A string value representing the rule chain id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  184 + public static final String WIDGET_BUNDLE_ID_PARAM_DESCRIPTION = "A string value representing the widget bundle id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  185 + public static final String WIDGET_TYPE_ID_PARAM_DESCRIPTION = "A string value representing the widget type id. For example, '784f394c-42b6-435a-983c-b7beff2784f9'";
  186 +
184 187
185 188 protected static final String SYSTEM_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'SYS_ADMIN' authority.";
186   - protected static final String SYSTEM_AND_TENANT_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority.";
  189 + protected static final String SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'SYS_ADMIN' or 'TENANT_ADMIN' authority.";
187 190 protected static final String TENANT_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'TENANT_ADMIN' authority.";
188   - protected static final String TENANT_AND_USER_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority.";
  191 + protected static final String TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority.";
  192 + protected static final String CUSTOMER_AUTHORITY_PARAGRAPH = "\n\nAvailable for users with 'CUSTOMER_USER' authority.";
  193 + protected static final String AVAILABLE_FOR_ANY_AUTHORIZED_USER = "\n\nAvailable for any authorized user. ";
189 194
190 195 protected static final String PAGE_SIZE_DESCRIPTION = "Maximum amount of entities in a one page";
191 196 protected static final String PAGE_NUMBER_DESCRIPTION = "Sequence number of page starting from 0";
... ... @@ -196,8 +201,10 @@ public abstract class BaseController {
196 201
197 202 protected static final String ASSET_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the asset name.";
198 203 protected static final String DASHBOARD_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the dashboard title.";
  204 + protected static final String WIDGET_BUNDLE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the widget bundle title.";
199 205 protected static final String RPC_TEXT_SEARCH_DESCRIPTION = "Not implemented. Leave empty.";
200 206 protected static final String DEVICE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the device name.";
  207 + protected static final String USER_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the user email.";
201 208 protected static final String TENANT_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the tenant name.";
202 209 protected static final String TENANT_PROFILE_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the tenant profile name.";
203 210 protected static final String RULE_CHAIN_TEXT_SEARCH_DESCRIPTION = "The case insensitive 'startsWith' filter based on the rule chain name.";
... ... @@ -211,6 +218,7 @@ public abstract class BaseController {
211 218 protected static final String CUSTOMER_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, city";
212 219 protected static final String RPC_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, expirationTime, request, response";
213 220 protected static final String DEVICE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, deviceProfileName, label, customerTitle";
  221 + protected static final String USER_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, firstName, lastName, email";
214 222 protected static final String TENANT_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, email, country, state, city, address, address2, zip, phone, email";
215 223 protected static final String TENANT_PROFILE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, description, isDefault";
216 224 protected static final String TENANT_PROFILE_INFO_SORT_PROPERTY_ALLOWABLE_VALUES = "id, name";
... ... @@ -221,6 +229,7 @@ public abstract class BaseController {
221 229 protected static final String EVENT_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, id";
222 230 protected static final String EDGE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, type, label, customerTitle";
223 231 protected static final String RULE_CHAIN_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, name, root";
  232 + protected static final String WIDGET_BUNDLE_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, title, tenantId";
224 233 protected static final String AUDIT_LOG_SORT_PROPERTY_ALLOWABLE_VALUES = "createdTime, entityType, entityName, userName, actionType, actionStatus";
225 234 protected static final String SORT_ORDER_DESCRIPTION = "Sort order. ASC (ASCENDING) or DESC (DESCENDING)";
226 235 protected static final String SORT_ORDER_ALLOWABLE_VALUES = "ASC, DESC";
... ... @@ -370,8 +379,6 @@ public abstract class BaseController {
370 379 protected static final String RELATION_TYPE_PARAM_DESCRIPTION = "A string value representing relation type between entities. For example, 'Contains', 'Manages'. It can be any string value.";
371 380 protected static final String RELATION_TYPE_GROUP_PARAM_DESCRIPTION = "A string value representing relation type group. For example, 'COMMON'";
372 381
373   - protected static final String ADMINISTRATOR_AUTHORITY_ONLY = "Available for users with 'Tenant Administrator' authority only.";
374   -
375 382 public static final String INCORRECT_TENANT_ID = "Incorrect tenantId ";
376 383 protected static final String DEFAULT_DASHBOARD = "defaultDashboardId";
377 384 protected static final String HOME_DASHBOARD = "homeDashboardId";
... ...
... ... @@ -47,7 +47,7 @@ public class ComponentDescriptorController extends BaseController {
47 47
48 48 @ApiOperation(value = "Get Component Descriptor (getComponentDescriptorByClazz)",
49 49 notes = "Gets the Component Descriptor object using class name from the path parameters. " +
50   - COMPONENT_DESCRIPTOR_DEFINITION)
  50 + COMPONENT_DESCRIPTOR_DEFINITION + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
51 51 @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN')")
52 52 @RequestMapping(value = "/component/{componentDescriptorClazz:.+}", method = RequestMethod.GET)
53 53 @ResponseBody
... ... @@ -64,7 +64,7 @@ public class ComponentDescriptorController extends BaseController {
64 64
65 65 @ApiOperation(value = "Get Component Descriptors (getComponentDescriptorsByType)",
66 66 notes = "Gets the Component Descriptors using rule node type and optional rule chain type request parameters. " +
67   - COMPONENT_DESCRIPTOR_DEFINITION)
  67 + COMPONENT_DESCRIPTOR_DEFINITION + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
68 68 @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN')")
69 69 @RequestMapping(value = "/components/{componentType}", method = RequestMethod.GET)
70 70 @ResponseBody
... ... @@ -83,7 +83,7 @@ public class ComponentDescriptorController extends BaseController {
83 83
84 84 @ApiOperation(value = "Get Component Descriptors (getComponentDescriptorsByTypes)",
85 85 notes = "Gets the Component Descriptors using coma separated list of rule node types and optional rule chain type request parameters. " +
86   - COMPONENT_DESCRIPTOR_DEFINITION)
  86 + COMPONENT_DESCRIPTOR_DEFINITION + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
87 87 @PreAuthorize("hasAnyAuthority('SYS_ADMIN','TENANT_ADMIN')")
88 88 @RequestMapping(value = "/components", params = {"componentTypes"}, method = RequestMethod.GET)
89 89 @ResponseBody
... ...
... ... @@ -57,7 +57,8 @@ public class CustomerController extends BaseController {
57 57 "If the user has the authority of 'Customer User', the server checks that the user belongs to the customer.";
58 58
59 59 @ApiOperation(value = "Get Customer (getCustomerById)",
60   - notes = "Get the Customer object based on the provided Customer Id. " + CUSTOMER_SECURITY_CHECK)
  60 + notes = "Get the Customer object based on the provided Customer Id. "
  61 + + CUSTOMER_SECURITY_CHECK + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
61 62 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
62 63 @RequestMapping(value = "/customer/{customerId}", method = RequestMethod.GET)
63 64 @ResponseBody
... ... @@ -79,7 +80,8 @@ public class CustomerController extends BaseController {
79 80
80 81
81 82 @ApiOperation(value = "Get short Customer info (getShortCustomerInfoById)",
82   - notes = "Get the short customer object that contains only the title and 'isPublic' flag. " + CUSTOMER_SECURITY_CHECK)
  83 + notes = "Get the short customer object that contains only the title and 'isPublic' flag. "
  84 + + CUSTOMER_SECURITY_CHECK + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
83 85 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
84 86 @RequestMapping(value = "/customer/{customerId}/shortInfo", method = RequestMethod.GET)
85 87 @ResponseBody
... ... @@ -101,7 +103,8 @@ public class CustomerController extends BaseController {
101 103 }
102 104
103 105 @ApiOperation(value = "Get Customer Title (getCustomerTitleById)",
104   - notes = "Get the title of the customer. " + CUSTOMER_SECURITY_CHECK)
  106 + notes = "Get the title of the customer. "
  107 + + CUSTOMER_SECURITY_CHECK + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
105 108 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
106 109 @RequestMapping(value = "/customer/{customerId}/title", method = RequestMethod.GET, produces = "application/text")
107 110 @ResponseBody
... ... @@ -122,7 +125,7 @@ public class CustomerController extends BaseController {
122 125 notes = "Creates or Updates the Customer. When creating customer, platform generates Customer Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address) " +
123 126 "The newly created Customer Id will be present in the response. " +
124 127 "Specify existing Customer Id to update the Customer. " +
125   - "Referencing non-existing Customer Id will cause 'Not Found' error.")
  128 + "Referencing non-existing Customer Id will cause 'Not Found' error." + TENANT_AUTHORITY_PARAGRAPH)
126 129 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
127 130 @RequestMapping(value = "/customer", method = RequestMethod.POST)
128 131 @ResponseBody
... ... @@ -153,7 +156,9 @@ public class CustomerController extends BaseController {
153 156 }
154 157
155 158 @ApiOperation(value = "Delete Customer (deleteCustomer)",
156   - notes = "Deletes the Customer and all customer Users. All assigned Dashboards, Assets, Devices, etc. will be unassigned but not deleted. Referencing non-existing Customer Id will cause an error.")
  159 + notes = "Deletes the Customer and all customer Users. " +
  160 + "All assigned Dashboards, Assets, Devices, etc. will be unassigned but not deleted. " +
  161 + "Referencing non-existing Customer Id will cause an error." + TENANT_AUTHORITY_PARAGRAPH)
157 162 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
158 163 @RequestMapping(value = "/customer/{customerId}", method = RequestMethod.DELETE)
159 164 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -187,7 +192,7 @@ public class CustomerController extends BaseController {
187 192
188 193 @ApiOperation(value = "Get Tenant Customers (getCustomers)",
189 194 notes = "Returns a page of customers owned by tenant. " +
190   - PAGE_DATA_PARAMETERS)
  195 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH)
191 196 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
192 197 @RequestMapping(value = "/customers", params = {"pageSize", "page"}, method = RequestMethod.GET)
193 198 @ResponseBody
... ... @@ -212,7 +217,7 @@ public class CustomerController extends BaseController {
212 217 }
213 218
214 219 @ApiOperation(value = "Get Tenant Customer by Customer title (getTenantCustomer)",
215   - notes = "Get the Customer using Customer Title. " + ADMINISTRATOR_AUTHORITY_ONLY)
  220 + notes = "Get the Customer using Customer Title. " + TENANT_AUTHORITY_PARAGRAPH)
216 221 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
217 222 @RequestMapping(value = "/tenant/customers", params = {"customerTitle"}, method = RequestMethod.GET)
218 223 @ResponseBody
... ...
... ... @@ -120,7 +120,7 @@ public class DashboardController extends BaseController {
120 120 }
121 121
122 122 @ApiOperation(value = "Get Dashboard (getDashboardById)",
123   - notes = "Get the dashboard based on 'dashboardId' parameter. " + DASHBOARD_DEFINITION,
  123 + notes = "Get the dashboard based on 'dashboardId' parameter. " + DASHBOARD_DEFINITION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
124 124 produces = MediaType.APPLICATION_JSON_VALUE
125 125 )
126 126 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
... ... @@ -143,7 +143,7 @@ public class DashboardController extends BaseController {
143 143 "The newly created Dashboard id will be present in the response. " +
144 144 "Specify existing Dashboard id to update the dashboard. " +
145 145 "Referencing non-existing dashboard Id will cause 'Not Found' error. " +
146   - "Only users with 'TENANT_ADMIN') authority may create the dashboards.",
  146 + TENANT_AUTHORITY_PARAGRAPH,
147 147 produces = MediaType.APPLICATION_JSON_VALUE,
148 148 consumes = MediaType.APPLICATION_JSON_VALUE)
149 149 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
... ... @@ -177,7 +177,7 @@ public class DashboardController extends BaseController {
177 177 }
178 178
179 179 @ApiOperation(value = "Delete the Dashboard (deleteDashboard)",
180   - notes = "Delete the Dashboard. Only users with 'TENANT_ADMIN') authority may delete the dashboards.")
  180 + notes = "Delete the Dashboard." + TENANT_AUTHORITY_PARAGRAPH)
181 181 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
182 182 @RequestMapping(value = "/dashboard/{dashboardId}", method = RequestMethod.DELETE)
183 183 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -211,7 +211,7 @@ public class DashboardController extends BaseController {
211 211
212 212 @ApiOperation(value = "Assign the Dashboard (assignDashboardToCustomer)",
213 213 notes = "Assign the Dashboard to specified Customer or do nothing if the Dashboard is already assigned to that Customer. " +
214   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may assign the dashboards to customers.",
  214 + "Returns the Dashboard object." + TENANT_AUTHORITY_PARAGRAPH,
215 215 produces = MediaType.APPLICATION_JSON_VALUE)
216 216 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
217 217 @RequestMapping(value = "/customer/{customerId}/dashboard/{dashboardId}", method = RequestMethod.POST)
... ... @@ -251,7 +251,7 @@ public class DashboardController extends BaseController {
251 251
252 252 @ApiOperation(value = "Unassign the Dashboard (unassignDashboardFromCustomer)",
253 253 notes = "Unassign the Dashboard from specified Customer or do nothing if the Dashboard is already assigned to that Customer. " +
254   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may unassign the dashboards from customers.",
  254 + "Returns the Dashboard object." + TENANT_AUTHORITY_PARAGRAPH,
255 255 produces = MediaType.APPLICATION_JSON_VALUE)
256 256 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
257 257 @RequestMapping(value = "/customer/{customerId}/dashboard/{dashboardId}", method = RequestMethod.DELETE)
... ... @@ -290,7 +290,7 @@ public class DashboardController extends BaseController {
290 290
291 291 @ApiOperation(value = "Update the Dashboard Customers (updateDashboardCustomers)",
292 292 notes = "Updates the list of Customers that this Dashboard is assigned to. Removes previous assignments to customers that are not in the provided list. " +
293   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may assign the dashboards to customers.",
  293 + "Returns the Dashboard object. " + TENANT_AUTHORITY_PARAGRAPH,
294 294 produces = MediaType.APPLICATION_JSON_VALUE,
295 295 consumes = MediaType.APPLICATION_JSON_VALUE)
296 296
... ... @@ -365,7 +365,7 @@ public class DashboardController extends BaseController {
365 365
366 366 @ApiOperation(value = "Adds the Dashboard Customers (addDashboardCustomers)",
367 367 notes = "Adds the list of Customers to the existing list of assignments for the Dashboard. Keeps previous assignments to customers that are not in the provided list. " +
368   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may assign the dashboards to customers.",
  368 + "Returns the Dashboard object." + TENANT_AUTHORITY_PARAGRAPH,
369 369 produces = MediaType.APPLICATION_JSON_VALUE,
370 370 consumes = MediaType.APPLICATION_JSON_VALUE)
371 371 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
... ... @@ -417,7 +417,7 @@ public class DashboardController extends BaseController {
417 417
418 418 @ApiOperation(value = "Remove the Dashboard Customers (removeDashboardCustomers)",
419 419 notes = "Removes the list of Customers from the existing list of assignments for the Dashboard. Keeps other assignments to customers that are not in the provided list. " +
420   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may assign the dashboards to customers.",
  420 + "Returns the Dashboard object." + TENANT_AUTHORITY_PARAGRAPH,
421 421 produces = MediaType.APPLICATION_JSON_VALUE,
422 422 consumes = MediaType.APPLICATION_JSON_VALUE)
423 423 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
... ... @@ -473,7 +473,7 @@ public class DashboardController extends BaseController {
473 473 "Be aware that making the dashboard public does not mean that it automatically makes all devices and assets you use in the dashboard to be public." +
474 474 "Use [assign Asset to Public Customer](#!/asset-controller/assignAssetToPublicCustomerUsingPOST) and " +
475 475 "[assign Device to Public Customer](#!/device-controller/assignDeviceToPublicCustomerUsingPOST) for this purpose. " +
476   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may assign the dashboards to customers.",
  476 + "Returns the Dashboard object." + TENANT_AUTHORITY_PARAGRAPH,
477 477 produces = MediaType.APPLICATION_JSON_VALUE)
478 478 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
479 479 @RequestMapping(value = "/customer/public/dashboard/{dashboardId}", method = RequestMethod.POST)
... ... @@ -505,7 +505,7 @@ public class DashboardController extends BaseController {
505 505
506 506 @ApiOperation(value = "Unassign the Dashboard from Public Customer (unassignDashboardFromPublicCustomer)",
507 507 notes = "Unassigns the dashboard from a special, auto-generated 'Public' Customer. Once unassigned, unauthenticated users may no longer browse the dashboard. " +
508   - "Returns the Dashboard object. Only users with 'TENANT_ADMIN') authority may assign the dashboards to customers.",
  508 + "Returns the Dashboard object." + TENANT_AUTHORITY_PARAGRAPH,
509 509 produces = MediaType.APPLICATION_JSON_VALUE)
510 510 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
511 511 @RequestMapping(value = "/customer/public/dashboard/{dashboardId}", method = RequestMethod.DELETE)
... ... @@ -538,7 +538,7 @@ public class DashboardController extends BaseController {
538 538
539 539 @ApiOperation(value = "Get Tenant Dashboards by System Administrator (getTenantDashboards)",
540 540 notes = "Returns a page of dashboard info objects owned by tenant. " + DASHBOARD_INFO_DEFINITION + " " + PAGE_DATA_PARAMETERS +
541   - "Only users with 'SYS_ADMIN' authority may use this method.",
  541 + SYSTEM_AUTHORITY_PARAGRAPH,
542 542 produces = MediaType.APPLICATION_JSON_VALUE)
543 543 @PreAuthorize("hasAuthority('SYS_ADMIN')")
544 544 @RequestMapping(value = "/tenant/{tenantId}/dashboards", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -567,8 +567,8 @@ public class DashboardController extends BaseController {
567 567 }
568 568
569 569 @ApiOperation(value = "Get Tenant Dashboards (getTenantDashboards)",
570   - notes = "Returns a page of dashboard info objects owned by the tenant of a current user. " + DASHBOARD_INFO_DEFINITION + " " + PAGE_DATA_PARAMETERS +
571   - "Only users with 'TENANT_ADMIN' authority may use this method.",
  570 + notes = "Returns a page of dashboard info objects owned by the tenant of a current user. "
  571 + + DASHBOARD_INFO_DEFINITION + " " + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH,
572 572 produces = MediaType.APPLICATION_JSON_VALUE)
573 573 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
574 574 @RequestMapping(value = "/tenant/dashboards", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -600,8 +600,8 @@ public class DashboardController extends BaseController {
600 600 }
601 601
602 602 @ApiOperation(value = "Get Customer Dashboards (getCustomerDashboards)",
603   - notes = "Returns a page of dashboard info objects owned by the specified customer. " + DASHBOARD_INFO_DEFINITION + " " + PAGE_DATA_PARAMETERS +
604   - "Only users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority may use this method.",
  603 + notes = "Returns a page of dashboard info objects owned by the specified customer. "
  604 + + DASHBOARD_INFO_DEFINITION + " " + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
605 605 produces = MediaType.APPLICATION_JSON_VALUE)
606 606 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
607 607 @RequestMapping(value = "/customer/{customerId}/dashboards", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -641,8 +641,7 @@ public class DashboardController extends BaseController {
641 641 notes = "Returns the home dashboard object that is configured as 'homeDashboardId' parameter in the 'additionalInfo' of the User. " +
642 642 "If 'homeDashboardId' parameter is not set on the User level and the User has authority 'CUSTOMER_USER', check the same parameter for the corresponding Customer. " +
643 643 "If 'homeDashboardId' parameter is not set on the User and Customer levels then checks the same parameter for the Tenant that owns the user. "
644   - + DASHBOARD_DEFINITION + " " +
645   - "Only users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority should use this method.",
  644 + + DASHBOARD_DEFINITION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
646 645 produces = MediaType.APPLICATION_JSON_VALUE)
647 646 @PreAuthorize("isAuthenticated()")
648 647 @RequestMapping(value = "/dashboard/home", method = RequestMethod.GET)
... ... @@ -679,7 +678,7 @@ public class DashboardController extends BaseController {
679 678 notes = "Returns the home dashboard info object that is configured as 'homeDashboardId' parameter in the 'additionalInfo' of the User. " +
680 679 "If 'homeDashboardId' parameter is not set on the User level and the User has authority 'CUSTOMER_USER', check the same parameter for the corresponding Customer. " +
681 680 "If 'homeDashboardId' parameter is not set on the User and Customer levels then checks the same parameter for the Tenant that owns the user. " +
682   - "Only users with 'TENANT_ADMIN' or 'CUSTOMER_USER' authority should use this method.",
  681 + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
683 682 produces = MediaType.APPLICATION_JSON_VALUE)
684 683 @PreAuthorize("isAuthenticated()")
685 684 @RequestMapping(value = "/dashboard/home/info", method = RequestMethod.GET)
... ... @@ -714,7 +713,7 @@ public class DashboardController extends BaseController {
714 713
715 714 @ApiOperation(value = "Get Tenant Home Dashboard Info (getTenantHomeDashboardInfo)",
716 715 notes = "Returns the home dashboard info object that is configured as 'homeDashboardId' parameter in the 'additionalInfo' of the corresponding tenant. " +
717   - "Only users with 'TENANT_ADMIN' authority may use this method.",
  716 + TENANT_AUTHORITY_PARAGRAPH,
718 717 produces = MediaType.APPLICATION_JSON_VALUE)
719 718 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
720 719 @RequestMapping(value = "/tenant/dashboard/home/info", method = RequestMethod.GET)
... ... @@ -740,7 +739,7 @@ public class DashboardController extends BaseController {
740 739
741 740 @ApiOperation(value = "Update Tenant Home Dashboard Info (getTenantHomeDashboardInfo)",
742 741 notes = "Update the home dashboard assignment for the current tenant. " +
743   - "Only users with 'TENANT_ADMIN' authority may use this method.",
  742 + TENANT_AUTHORITY_PARAGRAPH,
744 743 produces = MediaType.APPLICATION_JSON_VALUE)
745 744 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
746 745 @RequestMapping(value = "/tenant/dashboard/home/info", method = RequestMethod.POST)
... ... @@ -810,7 +809,8 @@ public class DashboardController extends BaseController {
810 809 EDGE_ASSIGN_ASYNC_FIRST_STEP_DESCRIPTION +
811 810 "Second, remote edge service will receive a copy of assignment dashboard " +
812 811 EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION + ". " +
813   - "Third, once dashboard will be delivered to edge service, it's going to be available for usage on remote edge instance.",
  812 + "Third, once dashboard will be delivered to edge service, it's going to be available for usage on remote edge instance." +
  813 + TENANT_AUTHORITY_PARAGRAPH,
814 814 produces = MediaType.APPLICATION_JSON_VALUE)
815 815 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
816 816 @RequestMapping(value = "/edge/{edgeId}/dashboard/{dashboardId}", method = RequestMethod.POST)
... ... @@ -850,7 +850,8 @@ public class DashboardController extends BaseController {
850 850 EDGE_UNASSIGN_ASYNC_FIRST_STEP_DESCRIPTION +
851 851 "Second, remote edge service will receive an 'unassign' command to remove dashboard " +
852 852 EDGE_UNASSIGN_RECEIVE_STEP_DESCRIPTION + ". " +
853   - "Third, once 'unassign' command will be delivered to edge service, it's going to remove dashboard locally.",
  853 + "Third, once 'unassign' command will be delivered to edge service, it's going to remove dashboard locally." +
  854 + TENANT_AUTHORITY_PARAGRAPH,
854 855 produces = MediaType.APPLICATION_JSON_VALUE)
855 856 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
856 857 @RequestMapping(value = "/edge/{edgeId}/dashboard/{dashboardId}", method = RequestMethod.DELETE)
... ...
... ... @@ -103,8 +103,9 @@ public class DeviceController extends BaseController {
103 103
104 104 @ApiOperation(value = "Get Device (getDeviceById)",
105 105 notes = "Fetch the Device object based on the provided Device Id. " +
106   - "If the user has the authority of 'Tenant Administrator', the server checks that the device is owned by the same tenant. " +
107   - "If the user has the authority of 'Customer User', the server checks that the device is assigned to the same customer.")
  106 + "If the user has the authority of 'TENANT_ADMIN', the server checks that the device is owned by the same tenant. " +
  107 + "If the user has the authority of 'CUSTOMER_USER', the server checks that the device is assigned to the same customer." +
  108 + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
108 109 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
109 110 @RequestMapping(value = "/device/{deviceId}", method = RequestMethod.GET)
110 111 @ResponseBody
... ... @@ -122,7 +123,8 @@ public class DeviceController extends BaseController {
122 123 @ApiOperation(value = "Get Device Info (getDeviceInfoById)",
123 124 notes = "Fetch the Device Info object based on the provided Device Id. " +
124 125 "If the user has the authority of 'Tenant Administrator', the server checks that the device is owned by the same tenant. " +
125   - "If the user has the authority of 'Customer User', the server checks that the device is assigned to the same customer. " + DEVICE_INFO_DESCRIPTION)
  126 + "If the user has the authority of 'Customer User', the server checks that the device is assigned to the same customer. " +
  127 + DEVICE_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
126 128 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
127 129 @RequestMapping(value = "/device/info/{deviceId}", method = RequestMethod.GET)
128 130 @ResponseBody
... ... @@ -139,11 +141,12 @@ public class DeviceController extends BaseController {
139 141
140 142 @ApiOperation(value = "Create Or Update Device (saveDevice)",
141 143 notes = "Create or update the Device. When creating device, platform generates Device Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
142   - "Device credentials are also generated if not provided in the 'accessToken' request parameter. " +
143   - "The newly created device id will be present in the response. " +
144   - "Specify existing Device id to update the device. " +
145   - "Referencing non-existing device Id will cause 'Not Found' error." +
146   - "\n\nDevice name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the device names and non-unique 'label' field for user-friendly visualization purposes.")
  144 + "Device credentials are also generated if not provided in the 'accessToken' request parameter. " +
  145 + "The newly created device id will be present in the response. " +
  146 + "Specify existing Device id to update the device. " +
  147 + "Referencing non-existing device Id will cause 'Not Found' error." +
  148 + "\n\nDevice name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the device names and non-unique 'label' field for user-friendly visualization purposes."
  149 + + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
147 150 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
148 151 @RequestMapping(value = "/device", method = RequestMethod.POST)
149 152 @ResponseBody
... ... @@ -187,7 +190,7 @@ public class DeviceController extends BaseController {
187 190 }
188 191
189 192 @ApiOperation(value = "Delete device (deleteDevice)",
190   - notes = "Deletes the device, it's credentials and all the relations (from and to the device). Referencing non-existing device Id will cause an error.")
  193 + notes = "Deletes the device, it's credentials and all the relations (from and to the device). Referencing non-existing device Id will cause an error." + TENANT_AUTHORITY_PARAGRAPH)
191 194 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
192 195 @RequestMapping(value = "/device/{deviceId}", method = RequestMethod.DELETE)
193 196 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -219,7 +222,7 @@ public class DeviceController extends BaseController {
219 222 }
220 223
221 224 @ApiOperation(value = "Assign device to customer (assignDeviceToCustomer)",
222   - notes = "Creates assignment of the device to customer. Customer will be able to query device afterwards.")
  225 + notes = "Creates assignment of the device to customer. Customer will be able to query device afterwards." + TENANT_AUTHORITY_PARAGRAPH)
223 226 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
224 227 @RequestMapping(value = "/customer/{customerId}/device/{deviceId}", method = RequestMethod.POST)
225 228 @ResponseBody
... ... @@ -255,7 +258,7 @@ public class DeviceController extends BaseController {
255 258 }
256 259
257 260 @ApiOperation(value = "Unassign device from customer (unassignDeviceFromCustomer)",
258   - notes = "Clears assignment of the device to customer. Customer will not be able to query device afterwards.")
  261 + notes = "Clears assignment of the device to customer. Customer will not be able to query device afterwards." + TENANT_AUTHORITY_PARAGRAPH)
259 262 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
260 263 @RequestMapping(value = "/customer/device/{deviceId}", method = RequestMethod.DELETE)
261 264 @ResponseBody
... ... @@ -291,7 +294,7 @@ public class DeviceController extends BaseController {
291 294 @ApiOperation(value = "Make device publicly available (assignDeviceToPublicCustomer)",
292 295 notes = "Device will be available for non-authorized (not logged-in) users. " +
293 296 "This is useful to create dashboards that you plan to share/embed on a publicly available website. " +
294   - "However, users that are logged-in and belong to different tenant will not be able to access the device.")
  297 + "However, users that are logged-in and belong to different tenant will not be able to access the device." + TENANT_AUTHORITY_PARAGRAPH)
295 298 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
296 299 @RequestMapping(value = "/customer/public/device/{deviceId}", method = RequestMethod.POST)
297 300 @ResponseBody
... ... @@ -318,7 +321,7 @@ public class DeviceController extends BaseController {
318 321 }
319 322
320 323 @ApiOperation(value = "Get Device Credentials (getDeviceCredentialsByDeviceId)",
321   - notes = "If during device creation there wasn't specified any credentials, platform generates random 'ACCESS_TOKEN' credentials.")
  324 + notes = "If during device creation there wasn't specified any credentials, platform generates random 'ACCESS_TOKEN' credentials." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
322 325 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
323 326 @RequestMapping(value = "/device/{deviceId}/credentials", method = RequestMethod.GET)
324 327 @ResponseBody
... ... @@ -344,7 +347,7 @@ public class DeviceController extends BaseController {
344 347 @ApiOperation(value = "Update device credentials (updateDeviceCredentials)", notes = "During device creation, platform generates random 'ACCESS_TOKEN' credentials. " +
345 348 "Use this method to update the device credentials. First use 'getDeviceCredentialsByDeviceId' to get the credentials id and value. " +
346 349 "Then use current method to update the credentials type and value. It is not possible to create multiple device credentials for the same device. " +
347   - "The structure of device credentials id and value is simple for the 'ACCESS_TOKEN' but is much more complex for the 'MQTT_BASIC' or 'LWM2M_CREDENTIALS'.")
  350 + "The structure of device credentials id and value is simple for the 'ACCESS_TOKEN' but is much more complex for the 'MQTT_BASIC' or 'LWM2M_CREDENTIALS'." + TENANT_AUTHORITY_PARAGRAPH)
348 351 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
349 352 @RequestMapping(value = "/device/credentials", method = RequestMethod.POST)
350 353 @ResponseBody
... ... @@ -405,7 +408,7 @@ public class DeviceController extends BaseController {
405 408
406 409 @ApiOperation(value = "Get Tenant Device Infos (getTenantDeviceInfos)",
407 410 notes = "Returns a page of devices info objects owned by tenant. " +
408   - PAGE_DATA_PARAMETERS + DEVICE_INFO_DESCRIPTION)
  411 + PAGE_DATA_PARAMETERS + DEVICE_INFO_DESCRIPTION + TENANT_AUTHORITY_PARAGRAPH)
409 412 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
410 413 @RequestMapping(value = "/tenant/deviceInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
411 414 @ResponseBody
... ... @@ -443,7 +446,7 @@ public class DeviceController extends BaseController {
443 446
444 447 @ApiOperation(value = "Get Tenant Device (getTenantDevice)",
445 448 notes = "Requested device must be owned by tenant that the user belongs to. " +
446   - "Device name is an unique property of device. So it can be used to identify the device.")
  449 + "Device name is an unique property of device. So it can be used to identify the device." + TENANT_AUTHORITY_PARAGRAPH)
447 450 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
448 451 @RequestMapping(value = "/tenant/devices", params = {"deviceName"}, method = RequestMethod.GET)
449 452 @ResponseBody
... ... @@ -460,7 +463,7 @@ public class DeviceController extends BaseController {
460 463
461 464 @ApiOperation(value = "Get Customer Devices (getCustomerDevices)",
462 465 notes = "Returns a page of devices objects assigned to customer. " +
463   - PAGE_DATA_PARAMETERS)
  466 + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
464 467 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
465 468 @RequestMapping(value = "/customer/{customerId}/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
466 469 @ResponseBody
... ... @@ -497,7 +500,7 @@ public class DeviceController extends BaseController {
497 500
498 501 @ApiOperation(value = "Get Customer Device Infos (getCustomerDeviceInfos)",
499 502 notes = "Returns a page of devices info objects assigned to customer. " +
500   - PAGE_DATA_PARAMETERS + DEVICE_INFO_DESCRIPTION)
  503 + PAGE_DATA_PARAMETERS + DEVICE_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
501 504 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
502 505 @RequestMapping(value = "/customer/{customerId}/deviceInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
503 506 @ResponseBody
... ... @@ -538,7 +541,7 @@ public class DeviceController extends BaseController {
538 541 }
539 542
540 543 @ApiOperation(value = "Get Devices By Ids (getDevicesByIds)",
541   - notes = "Requested devices must be owned by tenant or assigned to customer which user is performing the request. ")
  544 + notes = "Requested devices must be owned by tenant or assigned to customer which user is performing the request. " + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
542 545 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
543 546 @RequestMapping(value = "/devices", params = {"deviceIds"}, method = RequestMethod.GET)
544 547 @ResponseBody
... ... @@ -569,7 +572,7 @@ public class DeviceController extends BaseController {
569 572 @ApiOperation(value = "Find related devices (findByQuery)",
570 573 notes = "Returns all devices that are related to the specific entity. " +
571 574 "The entity id, relation type, device types, depth of the search, and other query parameters defined using complex 'DeviceSearchQuery' object. " +
572   - "See 'Model' tab of the Parameters for more info.")
  575 + "See 'Model' tab of the Parameters for more info." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
573 576 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
574 577 @RequestMapping(value = "/devices", method = RequestMethod.POST)
575 578 @ResponseBody
... ... @@ -597,7 +600,8 @@ public class DeviceController extends BaseController {
597 600 }
598 601
599 602 @ApiOperation(value = "Get Device Types (getDeviceTypes)",
600   - notes = "Returns a set of unique device profile names based on devices that are either owned by the tenant or assigned to the customer which user is performing the request.")
  603 + notes = "Returns a set of unique device profile names based on devices that are either owned by the tenant or assigned to the customer which user is performing the request."
  604 + + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
601 605 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
602 606 @RequestMapping(value = "/device/types", method = RequestMethod.GET)
603 607 @ResponseBody
... ... @@ -618,7 +622,7 @@ public class DeviceController extends BaseController {
618 622 "Once device is claimed, the customer becomes its owner and customer users may access device data as well as control the device. \n" +
619 623 "In order to enable claiming devices feature a system parameter security.claim.allowClaimingByDefault should be set to true, " +
620 624 "otherwise a server-side claimingAllowed attribute with the value true is obligatory for provisioned devices. \n" +
621   - "See official documentation for more details regarding claiming.")
  625 + "See official documentation for more details regarding claiming." + CUSTOMER_AUTHORITY_PARAGRAPH)
622 626 @PreAuthorize("hasAuthority('CUSTOMER_USER')")
623 627 @RequestMapping(value = "/customer/device/{deviceName}/claim", method = RequestMethod.POST)
624 628 @ResponseBody
... ... @@ -676,7 +680,8 @@ public class DeviceController extends BaseController {
676 680 }
677 681
678 682 @ApiOperation(value = "Reclaim device (reClaimDevice)",
679   - notes = "Reclaiming means the device will be unassigned from the customer and the device will be available for claiming again.")
  683 + notes = "Reclaiming means the device will be unassigned from the customer and the device will be available for claiming again."
  684 + + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
680 685 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
681 686 @RequestMapping(value = "/customer/device/{deviceName}/claim", method = RequestMethod.DELETE)
682 687 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -730,7 +735,7 @@ public class DeviceController extends BaseController {
730 735 }
731 736
732 737 @ApiOperation(value = "Assign device to tenant (assignDeviceToTenant)",
733   - notes = "Creates assignment of the device to tenant. Thereafter tenant will be able to reassign the device to a customer.")
  738 + notes = "Creates assignment of the device to tenant. Thereafter tenant will be able to reassign the device to a customer." + TENANT_AUTHORITY_PARAGRAPH)
734 739 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
735 740 @RequestMapping(value = "/tenant/{tenantId}/device/{deviceId}", method = RequestMethod.POST)
736 741 @ResponseBody
... ... @@ -788,7 +793,7 @@ public class DeviceController extends BaseController {
788 793 EDGE_ASSIGN_ASYNC_FIRST_STEP_DESCRIPTION +
789 794 "Second, remote edge service will receive a copy of assignment device " +
790 795 EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION + ". " +
791   - "Third, once device will be delivered to edge service, it's going to be available for usage on remote edge instance.",
  796 + "Third, once device will be delivered to edge service, it's going to be available for usage on remote edge instance." + TENANT_AUTHORITY_PARAGRAPH,
792 797 produces = MediaType.APPLICATION_JSON_VALUE)
793 798 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
794 799 @RequestMapping(value = "/edge/{edgeId}/device/{deviceId}", method = RequestMethod.POST)
... ... @@ -831,7 +836,7 @@ public class DeviceController extends BaseController {
831 836 EDGE_UNASSIGN_ASYNC_FIRST_STEP_DESCRIPTION +
832 837 "Second, remote edge service will receive an 'unassign' command to remove device " +
833 838 EDGE_UNASSIGN_RECEIVE_STEP_DESCRIPTION + ". " +
834   - "Third, once 'unassign' command will be delivered to edge service, it's going to remove device locally.",
  839 + "Third, once 'unassign' command will be delivered to edge service, it's going to remove device locally." + TENANT_AUTHORITY_PARAGRAPH,
835 840 produces = MediaType.APPLICATION_JSON_VALUE)
836 841 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
837 842 @RequestMapping(value = "/edge/{edgeId}/device/{deviceId}", method = RequestMethod.DELETE)
... ... @@ -871,7 +876,7 @@ public class DeviceController extends BaseController {
871 876
872 877 @ApiOperation(value = "Get devices assigned to edge (getEdgeDevices)",
873 878 notes = "Returns a page of devices assigned to edge. " +
874   - PAGE_DATA_PARAMETERS)
  879 + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
875 880 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
876 881 @RequestMapping(value = "/edge/{edgeId}/devices", params = {"pageSize", "page"}, method = RequestMethod.GET)
877 882 @ResponseBody
... ... @@ -928,7 +933,7 @@ public class DeviceController extends BaseController {
928 933 notes = "The platform gives an ability to load OTA (over-the-air) packages to devices. " +
929 934 "It can be done in two different ways: device scope or device profile scope." +
930 935 "In the response you will find the number of devices with specified device profile, but without previously defined device scope OTA package. " +
931   - "It can be useful when you want to define number of devices that will be affected with future OTA package")
  936 + "It can be useful when you want to define number of devices that will be affected with future OTA package" + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
932 937 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
933 938 @RequestMapping(value = "/devices/count/{otaPackageType}/{deviceProfileId}", method = RequestMethod.GET)
934 939 @ResponseBody
... ... @@ -949,7 +954,7 @@ public class DeviceController extends BaseController {
949 954 }
950 955
951 956 @ApiOperation(value = "Import the bulk of devices (processDevicesBulkImport)",
952   - notes = "There's an ability to import the bulk of devices using the only .csv file.")
  957 + notes = "There's an ability to import the bulk of devices using the only .csv file." + TENANT_AUTHORITY_PARAGRAPH)
953 958 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
954 959 @PostMapping("/device/bulk_import")
955 960 public BulkImportResult<Device> processDevicesBulkImport(@RequestBody BulkImportRequest request) throws Exception {
... ...
... ... @@ -528,7 +528,7 @@ public class DeviceProfileController extends BaseController {
528 528
529 529 @ApiOperation(value = "Get Device Profile Info (getDeviceProfileInfoById)",
530 530 notes = "Fetch the Device Profile Info object based on the provided Device Profile Id. "
531   - + DEVICE_PROFILE_INFO_DESCRIPTION + TENANT_AND_USER_AUTHORITY_PARAGRAPH,
  531 + + DEVICE_PROFILE_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
532 532 produces = "application/json")
533 533 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
534 534 @RequestMapping(value = "/deviceProfileInfo/{deviceProfileId}", method = RequestMethod.GET)
... ... @@ -547,7 +547,7 @@ public class DeviceProfileController extends BaseController {
547 547
548 548 @ApiOperation(value = "Get Default Device Profile (getDefaultDeviceProfileInfo)",
549 549 notes = "Fetch the Default Device Profile Info object. " +
550   - DEVICE_PROFILE_INFO_DESCRIPTION + TENANT_AND_USER_AUTHORITY_PARAGRAPH,
  550 + DEVICE_PROFILE_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
551 551 produces = "application/json")
552 552 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
553 553 @RequestMapping(value = "/deviceProfileInfo/default", method = RequestMethod.GET)
... ... @@ -769,7 +769,7 @@ public class DeviceProfileController extends BaseController {
769 769
770 770 @ApiOperation(value = "Get Device Profiles for transport type (getDeviceProfileInfos)",
771 771 notes = "Returns a page of devices profile info objects owned by tenant. " +
772   - PAGE_DATA_PARAMETERS + DEVICE_PROFILE_INFO_DESCRIPTION + TENANT_AND_USER_AUTHORITY_PARAGRAPH,
  772 + PAGE_DATA_PARAMETERS + DEVICE_PROFILE_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
773 773 produces = "application/json")
774 774 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
775 775 @RequestMapping(value = "/deviceProfileInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ...
... ... @@ -91,7 +91,7 @@ public class EdgeController extends BaseController {
91 91 }
92 92
93 93 @ApiOperation(value = "Get Edge (getEdgeById)",
94   - notes = "Get the Edge object based on the provided Edge Id. " + EDGE_SECURITY_CHECK,
  94 + notes = "Get the Edge object based on the provided Edge Id. " + EDGE_SECURITY_CHECK + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
95 95 produces = MediaType.APPLICATION_JSON_VALUE)
96 96 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
97 97 @RequestMapping(value = "/edge/{edgeId}", method = RequestMethod.GET)
... ... @@ -112,7 +112,7 @@ public class EdgeController extends BaseController {
112 112 }
113 113
114 114 @ApiOperation(value = "Get Edge Info (getEdgeInfoById)",
115   - notes = "Get the Edge Info object based on the provided Edge Id. " + EDGE_SECURITY_CHECK,
  115 + notes = "Get the Edge Info object based on the provided Edge Id. " + EDGE_SECURITY_CHECK + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
116 116 produces = MediaType.APPLICATION_JSON_VALUE)
117 117 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
118 118 @RequestMapping(value = "/edge/info/{edgeId}", method = RequestMethod.GET)
... ... @@ -137,7 +137,8 @@ public class EdgeController extends BaseController {
137 137 "The newly created edge id will be present in the response. " +
138 138 "Specify existing Edge id to update the edge. " +
139 139 "Referencing non-existing Edge Id will cause 'Not Found' error." +
140   - "\n\nEdge name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the edge names and non-unique 'label' field for user-friendly visualization purposes.",
  140 + "\n\nEdge name is unique in the scope of tenant. Use unique identifiers like MAC or IMEI for the edge names and non-unique 'label' field for user-friendly visualization purposes."
  141 + + TENANT_AUTHORITY_PARAGRAPH,
141 142 produces = MediaType.APPLICATION_JSON_VALUE)
142 143 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
143 144 @RequestMapping(value = "/edge", method = RequestMethod.POST)
... ... @@ -187,7 +188,7 @@ public class EdgeController extends BaseController {
187 188 }
188 189
189 190 @ApiOperation(value = "Delete edge (deleteEdge)",
190   - notes = "Deletes the edge. Referencing non-existing edge Id will cause an error.")
  191 + notes = "Deletes the edge. Referencing non-existing edge Id will cause an error."+ TENANT_AUTHORITY_PARAGRAPH)
191 192 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
192 193 @RequestMapping(value = "/edge/{edgeId}", method = RequestMethod.DELETE)
193 194 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -219,7 +220,7 @@ public class EdgeController extends BaseController {
219 220
220 221 @ApiOperation(value = "Get Tenant Edges (getEdges)",
221 222 notes = "Returns a page of edges owned by tenant. " +
222   - PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
  223 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
223 224 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
224 225 @RequestMapping(value = "/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
225 226 @ResponseBody
... ... @@ -243,7 +244,7 @@ public class EdgeController extends BaseController {
243 244 }
244 245
245 246 @ApiOperation(value = "Assign edge to customer (assignEdgeToCustomer)",
246   - notes = "Creates assignment of the edge to customer. Customer will be able to query edge afterwards.",
  247 + notes = "Creates assignment of the edge to customer. Customer will be able to query edge afterwards." + TENANT_AUTHORITY_PARAGRAPH,
247 248 produces = MediaType.APPLICATION_JSON_VALUE)
248 249 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
249 250 @RequestMapping(value = "/customer/{customerId}/edge/{edgeId}", method = RequestMethod.POST)
... ... @@ -283,7 +284,7 @@ public class EdgeController extends BaseController {
283 284 }
284 285
285 286 @ApiOperation(value = "Unassign edge from customer (unassignEdgeFromCustomer)",
286   - notes = "Clears assignment of the edge to customer. Customer will not be able to query edge afterwards.",
  287 + notes = "Clears assignment of the edge to customer. Customer will not be able to query edge afterwards." + TENANT_AUTHORITY_PARAGRAPH,
287 288 produces = MediaType.APPLICATION_JSON_VALUE)
288 289 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
289 290 @RequestMapping(value = "/customer/edge/{edgeId}", method = RequestMethod.DELETE)
... ... @@ -323,7 +324,7 @@ public class EdgeController extends BaseController {
323 324 @ApiOperation(value = "Make edge publicly available (assignEdgeToPublicCustomer)",
324 325 notes = "Edge will be available for non-authorized (not logged-in) users. " +
325 326 "This is useful to create dashboards that you plan to share/embed on a publicly available website. " +
326   - "However, users that are logged-in and belong to different tenant will not be able to access the edge.",
  327 + "However, users that are logged-in and belong to different tenant will not be able to access the edge." + TENANT_AUTHORITY_PARAGRAPH,
327 328 produces = MediaType.APPLICATION_JSON_VALUE)
328 329 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
329 330 @RequestMapping(value = "/customer/public/edge/{edgeId}", method = RequestMethod.POST)
... ... @@ -355,7 +356,7 @@ public class EdgeController extends BaseController {
355 356
356 357 @ApiOperation(value = "Get Tenant Edges (getTenantEdges)",
357 358 notes = "Returns a page of edges owned by tenant. " +
358   - PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
  359 + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
359 360 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
360 361 @RequestMapping(value = "/tenant/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
361 362 @ResponseBody
... ... @@ -387,7 +388,7 @@ public class EdgeController extends BaseController {
387 388
388 389 @ApiOperation(value = "Get Tenant Edge Infos (getTenantEdgeInfos)",
389 390 notes = "Returns a page of edges info objects owned by tenant. " +
390   - PAGE_DATA_PARAMETERS + EDGE_INFO_DESCRIPTION,
  391 + PAGE_DATA_PARAMETERS + EDGE_INFO_DESCRIPTION + TENANT_AUTHORITY_PARAGRAPH,
391 392 produces = MediaType.APPLICATION_JSON_VALUE)
392 393 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
393 394 @RequestMapping(value = "/tenant/edgeInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
... ... @@ -420,7 +421,7 @@ public class EdgeController extends BaseController {
420 421
421 422 @ApiOperation(value = "Get Tenant Edge (getTenantEdge)",
422 423 notes = "Requested edge must be owned by tenant or customer that the user belongs to. " +
423   - "Edge name is an unique property of edge. So it can be used to identify the edge.",
  424 + "Edge name is an unique property of edge. So it can be used to identify the edge." + TENANT_AUTHORITY_PARAGRAPH,
424 425 produces = MediaType.APPLICATION_JSON_VALUE)
425 426 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
426 427 @RequestMapping(value = "/tenant/edges", params = {"edgeName"}, method = RequestMethod.GET)
... ... @@ -437,7 +438,7 @@ public class EdgeController extends BaseController {
437 438
438 439 @ApiOperation(value = "Set root rule chain for provided edge (setRootRuleChain)",
439 440 notes = "Change root rule chain of the edge to the new provided rule chain. \n" +
440   - "This operation will send a notification to update root rule chain on remote edge service.",
  441 + "This operation will send a notification to update root rule chain on remote edge service." + TENANT_AUTHORITY_PARAGRAPH,
441 442 produces = MediaType.APPLICATION_JSON_VALUE)
442 443 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
443 444 @RequestMapping(value = "/edge/{edgeId}/{ruleChainId}/root", method = RequestMethod.POST)
... ... @@ -475,7 +476,7 @@ public class EdgeController extends BaseController {
475 476
476 477 @ApiOperation(value = "Get Customer Edges (getCustomerEdges)",
477 478 notes = "Returns a page of edges objects assigned to customer. " +
478   - PAGE_DATA_PARAMETERS, produces = MediaType.APPLICATION_JSON_VALUE)
  479 + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
479 480 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
480 481 @RequestMapping(value = "/customer/{customerId}/edges", params = {"pageSize", "page"}, method = RequestMethod.GET)
481 482 @ResponseBody
... ... @@ -520,7 +521,7 @@ public class EdgeController extends BaseController {
520 521
521 522 @ApiOperation(value = "Get Customer Edge Infos (getCustomerEdgeInfos)",
522 523 notes = "Returns a page of edges info objects assigned to customer. " +
523   - PAGE_DATA_PARAMETERS + EDGE_INFO_DESCRIPTION, produces = MediaType.APPLICATION_JSON_VALUE)
  524 + PAGE_DATA_PARAMETERS + EDGE_INFO_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH, produces = MediaType.APPLICATION_JSON_VALUE)
524 525 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
525 526 @RequestMapping(value = "/customer/{customerId}/edgeInfos", params = {"pageSize", "page"}, method = RequestMethod.GET)
526 527 @ResponseBody
... ... @@ -564,7 +565,7 @@ public class EdgeController extends BaseController {
564 565 }
565 566
566 567 @ApiOperation(value = "Get Edges By Ids (getEdgesByIds)",
567   - notes = "Requested edges must be owned by tenant or assigned to customer which user is performing the request.",
  568 + notes = "Requested edges must be owned by tenant or assigned to customer which user is performing the request." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
568 569 produces = MediaType.APPLICATION_JSON_VALUE)
569 570 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
570 571 @RequestMapping(value = "/edges", params = {"edgeIds"}, method = RequestMethod.GET)
... ... @@ -602,7 +603,7 @@ public class EdgeController extends BaseController {
602 603 @ApiOperation(value = "Find related edges (findByQuery)",
603 604 notes = "Returns all edges that are related to the specific entity. " +
604 605 "The entity id, relation type, edge types, depth of the search, and other query parameters defined using complex 'EdgeSearchQuery' object. " +
605   - "See 'Model' tab of the Parameters for more info.",
  606 + "See 'Model' tab of the Parameters for more info." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
606 607 produces = MediaType.APPLICATION_JSON_VALUE)
607 608 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
608 609 @RequestMapping(value = "/edges", method = RequestMethod.POST)
... ... @@ -636,7 +637,8 @@ public class EdgeController extends BaseController {
636 637 }
637 638
638 639 @ApiOperation(value = "Get Edge Types (getEdgeTypes)",
639   - notes = "Returns a set of unique edge types based on edges that are either owned by the tenant or assigned to the customer which user is performing the request.",
  640 + notes = "Returns a set of unique edge types based on edges that are either owned by the tenant or assigned to the customer which user is performing the request."
  641 + + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
640 642 produces = MediaType.APPLICATION_JSON_VALUE)
641 643 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
642 644 @RequestMapping(value = "/edge/types", method = RequestMethod.GET)
... ... @@ -654,7 +656,7 @@ public class EdgeController extends BaseController {
654 656
655 657 @ApiOperation(value = "Sync edge (syncEdge)",
656 658 notes = "Starts synchronization process between edge and cloud. \n" +
657   - "All entities that are assigned to particular edge are going to be send to remote edge service.")
  659 + "All entities that are assigned to particular edge are going to be send to remote edge service." + TENANT_AUTHORITY_PARAGRAPH)
658 660 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
659 661 @RequestMapping(value = "/edge/sync/{edgeId}", method = RequestMethod.POST)
660 662 public void syncEdge(@ApiParam(value = EDGE_ID_PARAM_DESCRIPTION, required = true)
... ... @@ -676,7 +678,7 @@ public class EdgeController extends BaseController {
676 678 }
677 679
678 680 @ApiOperation(value = "Find missing rule chains (findMissingToRelatedRuleChains)",
679   - notes = "Returns list of rule chains ids that are not assigned to particular edge, but these rule chains are present in the already assigned rule chains to edge.")
  681 + notes = "Returns list of rule chains ids that are not assigned to particular edge, but these rule chains are present in the already assigned rule chains to edge." + TENANT_AUTHORITY_PARAGRAPH)
680 682 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
681 683 @RequestMapping(value = "/edge/missingToRelatedRuleChains/{edgeId}", method = RequestMethod.GET)
682 684 @ResponseBody
... ... @@ -694,7 +696,7 @@ public class EdgeController extends BaseController {
694 696 }
695 697
696 698 @ApiOperation(value = "Import the bulk of edges (processEdgesBulkImport)",
697   - notes = "There's an ability to import the bulk of edges using the only .csv file.",
  699 + notes = "There's an ability to import the bulk of edges using the only .csv file." + TENANT_AUTHORITY_PARAGRAPH,
698 700 produces = MediaType.APPLICATION_JSON_VALUE)
699 701 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
700 702 @PostMapping("/edge/bulk_import")
... ...
... ... @@ -488,7 +488,7 @@ public class EntityQueryController extends BaseController {
488 488 "\n\n Example mentioned above search all devices which have attribute 'active' set to 'true'. Now let's review available entity filters and key filters syntax:" +
489 489 ENTITY_FILTERS +
490 490 KEY_FILTERS +
491   - TENANT_AND_USER_AUTHORITY_PARAGRAPH;
  491 + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
492 492
493 493 private static final String ENTITY_DATA_QUERY_DESCRIPTION =
494 494 "Allows to run complex queries over platform entities (devices, assets, customers, etc) " +
... ... @@ -571,7 +571,7 @@ public class EntityQueryController extends BaseController {
571 571 "\n\n Example mentioned above search all devices which have attribute 'active' set to 'true'. Now let's review available entity filters and key filters syntax:" +
572 572 ENTITY_FILTERS +
573 573 KEY_FILTERS +
574   - TENANT_AND_USER_AUTHORITY_PARAGRAPH;
  574 + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
575 575
576 576
577 577 private static final String ALARM_DATA_QUERY_DESCRIPTION = "This method description defines how Alarm Data Query extends the Entity Data Query. " +
... ...
... ... @@ -45,7 +45,7 @@ public class OAuth2ConfigTemplateController extends BaseController {
45 45
46 46 private static final String OAUTH2_CLIENT_REGISTRATION_TEMPLATE_DEFINITION = "Client registration template is OAuth2 provider configuration template with default settings for registering new OAuth2 clients";
47 47
48   - @ApiOperation(value = "Create or update OAuth2 client registration template (saveClientRegistrationTemplate)",
  48 + @ApiOperation(value = "Create or update OAuth2 client registration template (saveClientRegistrationTemplate)" + SYSTEM_AUTHORITY_PARAGRAPH,
49 49 notes = OAUTH2_CLIENT_REGISTRATION_TEMPLATE_DEFINITION)
50 50 @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
51 51 @RequestMapping(method = RequestMethod.POST)
... ... @@ -59,7 +59,7 @@ public class OAuth2ConfigTemplateController extends BaseController {
59 59 }
60 60 }
61 61
62   - @ApiOperation(value = "Delete OAuth2 client registration template by id (deleteClientRegistrationTemplate)",
  62 + @ApiOperation(value = "Delete OAuth2 client registration template by id (deleteClientRegistrationTemplate)" + SYSTEM_AUTHORITY_PARAGRAPH,
63 63 notes = OAUTH2_CLIENT_REGISTRATION_TEMPLATE_DEFINITION)
64 64 @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
65 65 @RequestMapping(value = "/{clientRegistrationTemplateId}", method = RequestMethod.DELETE)
... ... @@ -76,7 +76,7 @@ public class OAuth2ConfigTemplateController extends BaseController {
76 76 }
77 77 }
78 78
79   - @ApiOperation(value = "Get the list of all OAuth2 client registration templates (getClientRegistrationTemplates)",
  79 + @ApiOperation(value = "Get the list of all OAuth2 client registration templates (getClientRegistrationTemplates)" + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH,
80 80 notes = OAUTH2_CLIENT_REGISTRATION_TEMPLATE_DEFINITION)
81 81 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
82 82 @RequestMapping(method = RequestMethod.GET, produces = "application/json")
... ...
... ... @@ -88,7 +88,7 @@ public class OAuth2Controller extends BaseController {
88 88 }
89 89 }
90 90
91   - @ApiOperation(value = "Get current OAuth2 settings (getCurrentOAuth2Info)")
  91 + @ApiOperation(value = "Get current OAuth2 settings (getCurrentOAuth2Info)", notes = SYSTEM_AUTHORITY_PARAGRAPH)
92 92 @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
93 93 @RequestMapping(value = "/oauth2/config", method = RequestMethod.GET, produces = "application/json")
94 94 @ResponseBody
... ... @@ -101,7 +101,7 @@ public class OAuth2Controller extends BaseController {
101 101 }
102 102 }
103 103
104   - @ApiOperation(value = "Save OAuth2 settings (saveOAuth2Info)")
  104 + @ApiOperation(value = "Save OAuth2 settings (saveOAuth2Info)", notes = SYSTEM_AUTHORITY_PARAGRAPH)
105 105 @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
106 106 @RequestMapping(value = "/oauth2/config", method = RequestMethod.POST)
107 107 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -118,7 +118,7 @@ public class OAuth2Controller extends BaseController {
118 118 @ApiOperation(value = "Get OAuth2 log in processing URL (getLoginProcessingUrl)", notes = "Returns the URL enclosed in " +
119 119 "double quotes. After successful authentication with OAuth2 provider, it makes a redirect to this path so that the platform can do " +
120 120 "further log in processing. This URL may be configured as 'security.oauth2.loginProcessingUrl' property in yml configuration file, or " +
121   - "as 'SECURITY_OAUTH2_LOGIN_PROCESSING_URL' env variable. By default it is '/login/oauth2/code/'")
  121 + "as 'SECURITY_OAUTH2_LOGIN_PROCESSING_URL' env variable. By default it is '/login/oauth2/code/'" + SYSTEM_AUTHORITY_PARAGRAPH)
122 122 @PreAuthorize("hasAnyAuthority('SYS_ADMIN')")
123 123 @RequestMapping(value = "/oauth2/loginProcessingUrl", method = RequestMethod.GET)
124 124 @ResponseBody
... ...
... ... @@ -40,7 +40,7 @@ import java.util.UUID;
40 40 @Slf4j
41 41 public class RpcV1Controller extends AbstractRpcController {
42 42
43   - @ApiOperation(value = "Send one-way RPC request (handleOneWayDeviceRPCRequest)", notes = "Deprecated. See 'Rpc V 2 Controller' instead.")
  43 + @ApiOperation(value = "Send one-way RPC request (handleOneWayDeviceRPCRequest)", notes = "Deprecated. See 'Rpc V 2 Controller' instead." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
44 44 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
45 45 @RequestMapping(value = "/oneway/{deviceId}", method = RequestMethod.POST)
46 46 @ResponseBody
... ... @@ -52,7 +52,7 @@ public class RpcV1Controller extends AbstractRpcController {
52 52 return handleDeviceRPCRequest(true, new DeviceId(UUID.fromString(deviceIdStr)), requestBody, HttpStatus.REQUEST_TIMEOUT, HttpStatus.CONFLICT);
53 53 }
54 54
55   - @ApiOperation(value = "Send two-way RPC request (handleTwoWayDeviceRPCRequest)", notes = "Deprecated. See 'Rpc V 2 Controller' instead.")
  55 + @ApiOperation(value = "Send two-way RPC request (handleTwoWayDeviceRPCRequest)", notes = "Deprecated. See 'Rpc V 2 Controller' instead." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
56 56 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
57 57 @RequestMapping(value = "/twoway/{deviceId}", method = RequestMethod.POST)
58 58 @ResponseBody
... ...
... ... @@ -91,9 +91,9 @@ public class RpcV2Controller extends AbstractRpcController {
91 91 "In case of persistent RPC, the result of this call is 'rpcId' UUID. In case of lightweight RPC, " +
92 92 "the result of this call is the response from device, or 504 Gateway Timeout if device is offline.";
93 93
94   - private static final String ONE_WAY_RPC_REQUEST_DESCRIPTION = "Sends the one-way remote-procedure call (RPC) request to device. " + RPC_REQUEST_DESCRIPTION + ONE_WAY_RPC_RESULT + TENANT_AND_USER_AUTHORITY_PARAGRAPH;
  94 + private static final String ONE_WAY_RPC_REQUEST_DESCRIPTION = "Sends the one-way remote-procedure call (RPC) request to device. " + RPC_REQUEST_DESCRIPTION + ONE_WAY_RPC_RESULT + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
95 95
96   - private static final String TWO_WAY_RPC_REQUEST_DESCRIPTION = "Sends the two-way remote-procedure call (RPC) request to device. " + RPC_REQUEST_DESCRIPTION + TWO_WAY_RPC_RESULT + TENANT_AND_USER_AUTHORITY_PARAGRAPH;
  96 + private static final String TWO_WAY_RPC_REQUEST_DESCRIPTION = "Sends the two-way remote-procedure call (RPC) request to device. " + RPC_REQUEST_DESCRIPTION + TWO_WAY_RPC_RESULT + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH;
97 97
98 98 @ApiOperation(value = "Send one-way RPC request", notes = ONE_WAY_RPC_REQUEST_DESCRIPTION)
99 99 @ApiResponses(value = {
... ... @@ -131,7 +131,7 @@ public class RpcV2Controller extends AbstractRpcController {
131 131 return handleDeviceRPCRequest(false, new DeviceId(UUID.fromString(deviceIdStr)), requestBody, HttpStatus.GATEWAY_TIMEOUT, HttpStatus.GATEWAY_TIMEOUT);
132 132 }
133 133
134   - @ApiOperation(value = "Get persistent RPC request", notes = "Get information about the status of the RPC call." + TENANT_AND_USER_AUTHORITY_PARAGRAPH)
  134 + @ApiOperation(value = "Get persistent RPC request", notes = "Get information about the status of the RPC call." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
135 135 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
136 136 @RequestMapping(value = "/persistent/{rpcId}", method = RequestMethod.GET)
137 137 @ResponseBody
... ... @@ -147,7 +147,7 @@ public class RpcV2Controller extends AbstractRpcController {
147 147 }
148 148 }
149 149
150   - @ApiOperation(value = "Get persistent RPC requests", notes = "Allows to query RPC calls for specific device using pagination." + TENANT_AND_USER_AUTHORITY_PARAGRAPH)
  150 + @ApiOperation(value = "Get persistent RPC requests", notes = "Allows to query RPC calls for specific device using pagination." + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
151 151 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
152 152 @RequestMapping(value = "/persistent/device/{deviceId}", method = RequestMethod.GET)
153 153 @ResponseBody
... ...
... ... @@ -169,7 +169,7 @@ public class RuleChainController extends BaseController {
169 169 "The newly created Rule Chain Id will be present in the response. " +
170 170 "Specify existing Rule Chain id to update the rule chain. " +
171 171 "Referencing non-existing rule chain Id will cause 'Not Found' error." +
172   - "\n\n" + RULE_CHAIN_DESCRIPTION)
  172 + "\n\n" + RULE_CHAIN_DESCRIPTION + TENANT_AUTHORITY_PARAGRAPH)
173 173 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
174 174 @RequestMapping(value = "/ruleChain", method = RequestMethod.POST)
175 175 @ResponseBody
... ... @@ -327,7 +327,7 @@ public class RuleChainController extends BaseController {
327 327
328 328
329 329 @ApiOperation(value = "Get Rule Chains (getRuleChains)",
330   - notes = "Returns a page of Rule Chains owned by tenant. " + RULE_CHAIN_DESCRIPTION + PAGE_DATA_PARAMETERS)
  330 + notes = "Returns a page of Rule Chains owned by tenant. " + RULE_CHAIN_DESCRIPTION + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH)
331 331 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
332 332 @RequestMapping(value = "/ruleChains", params = {"pageSize", "page"}, method = RequestMethod.GET)
333 333 @ResponseBody
... ... @@ -358,7 +358,8 @@ public class RuleChainController extends BaseController {
358 358 }
359 359
360 360 @ApiOperation(value = "Delete rule chain (deleteRuleChain)",
361   - notes = "Deletes the rule chain. Referencing non-existing rule chain Id will cause an error. Referencing rule chain that is used in the device profiles will cause an error.")
  361 + notes = "Deletes the rule chain. Referencing non-existing rule chain Id will cause an error. " +
  362 + "Referencing rule chain that is used in the device profiles will cause an error." + TENANT_AUTHORITY_PARAGRAPH)
362 363 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
363 364 @RequestMapping(value = "/ruleChain/{ruleChainId}", method = RequestMethod.DELETE)
364 365 @ResponseStatus(value = HttpStatus.OK)
... ... @@ -409,7 +410,7 @@ public class RuleChainController extends BaseController {
409 410
410 411 @ApiOperation(value = "Get latest input message (getLatestRuleNodeDebugInput)",
411 412 notes = "Gets the input message from the debug events for specified Rule Chain Id. " +
412   - "Referencing non-existing rule chain Id will cause an error. ")
  413 + "Referencing non-existing rule chain Id will cause an error. " + TENANT_AUTHORITY_PARAGRAPH)
413 414 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN')")
414 415 @RequestMapping(value = "/ruleNode/{ruleNodeId}/debugIn", method = RequestMethod.GET)
415 416 @ResponseBody
... ... @@ -582,7 +583,7 @@ public class RuleChainController extends BaseController {
582 583 "Second, remote edge service will receive a copy of assignment rule chain " +
583 584 EDGE_ASSIGN_RECEIVE_STEP_DESCRIPTION + ". " +
584 585 "Third, once rule chain will be delivered to edge service, it's going to start processing messages locally. " +
585   - "\n\nOnly rule chain with type 'EDGE' can be assigned to edge.",
  586 + "\n\nOnly rule chain with type 'EDGE' can be assigned to edge." + TENANT_AUTHORITY_PARAGRAPH,
586 587 produces = MediaType.APPLICATION_JSON_VALUE)
587 588 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
588 589 @RequestMapping(value = "/edge/{edgeId}/ruleChain/{ruleChainId}", method = RequestMethod.POST)
... ... @@ -622,7 +623,7 @@ public class RuleChainController extends BaseController {
622 623 EDGE_UNASSIGN_ASYNC_FIRST_STEP_DESCRIPTION +
623 624 "Second, remote edge service will receive an 'unassign' command to remove rule chain " +
624 625 EDGE_UNASSIGN_RECEIVE_STEP_DESCRIPTION + ". " +
625   - "Third, once 'unassign' command will be delivered to edge service, it's going to remove rule chain locally.",
  626 + "Third, once 'unassign' command will be delivered to edge service, it's going to remove rule chain locally." + TENANT_AUTHORITY_PARAGRAPH,
626 627 produces = MediaType.APPLICATION_JSON_VALUE)
627 628 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
628 629 @RequestMapping(value = "/edge/{edgeId}/ruleChain/{ruleChainId}", method = RequestMethod.DELETE)
... ...
... ... @@ -28,10 +28,13 @@ import com.google.gson.JsonParseException;
28 28 import com.google.gson.JsonParser;
29 29 import io.swagger.annotations.ApiOperation;
30 30 import io.swagger.annotations.ApiParam;
  31 +import io.swagger.annotations.ApiResponse;
  32 +import io.swagger.annotations.ApiResponses;
31 33 import lombok.extern.slf4j.Slf4j;
32 34 import org.springframework.beans.factory.annotation.Autowired;
33 35 import org.springframework.beans.factory.annotation.Value;
34 36 import org.springframework.http.HttpStatus;
  37 +import org.springframework.http.MediaType;
35 38 import org.springframework.http.ResponseEntity;
36 39 import org.springframework.security.access.prepost.PreAuthorize;
37 40 import org.springframework.util.StringUtils;
... ... @@ -113,12 +116,43 @@ public class TelemetryController extends BaseController {
113 116 private static final String ATTRIBUTES_KEYS_DESCRIPTION = "A string value representing the comma-separated list of attributes keys. For example, 'active,inactivityAlarmTime'.";
114 117 private static final String ATTRIBUTES_SCOPE_ALLOWED_VALUES = "SERVER_SCOPE, CLIENT_SCOPE, SHARED_SCOPE";
115 118 private static final String ATTRIBUTES_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}'";
116   -
117   - private static final String TELEMETRY_KEYS_DESCRIPTION = "A string value representing the comma-separated list of timeseries keys. If keys are not selected, the result will return all latest timeseries. For example, 'temp,humidity'.";
118   - private static final String TELEMETRY_SCOPE_DESCRIPTION = "Value is not used in the API call implementation";
119   - private static final String TELEMETRY_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}' or '{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}'";
120   -
121   - private static final String STRICT_DATA_TYPES_DESCRIPTION = "A boolean value to specify if values of selected timeseries keys will representing a string (by default) or use strict data type.";
  119 + private static final String ATTRIBUTE_DATA_CLASS_DESCRIPTION = "AttributeData class represents information regarding a particular attribute and includes the next parameters: 'lastUpdatesTs' - a long value representing the timestamp of the last attribute modification in milliseconds. 'key' - attribute key name, and 'value' - attribute value.";
  120 + private static final String GET_ALL_ATTRIBUTES_BASE_DESCRIPTION = "Returns a JSON structure that represents a list of AttributeData class objects for the selected entity based on the specified comma-separated list of attribute key names. " + ATTRIBUTE_DATA_CLASS_DESCRIPTION;
  121 + private static final String GET_ALL_ATTRIBUTES_BY_SCOPE_BASE_DESCRIPTION = "Returns a JSON structure that represents a list of AttributeData class objects for the selected entity based on the attributes scope selected and a comma-separated list of attribute key names. " + ATTRIBUTE_DATA_CLASS_DESCRIPTION;
  122 +
  123 + private static final String TS_DATA_CLASS_DESCRIPTION = "TsData class is a timeseries data point for specific telemetry key that includes 'value' - object value, and 'ts' - a long value representing timestamp in milliseconds for this value. ";
  124 +
  125 + private static final String TELEMETRY_KEYS_BASE_DESCRIPTION = "A string value representing the comma-separated list of telemetry keys.";
  126 + private static final String TELEMETRY_KEYS_DESCRIPTION = TELEMETRY_KEYS_BASE_DESCRIPTION + " If keys are not selected, the result will return all latest timeseries. For example, 'temp,humidity'.";
  127 + private static final String TELEMETRY_SCOPE_DESCRIPTION = "Value is not used in the API call implementation. However, you need to specify whatever value cause scope is a path variable.";
  128 + private static final String TELEMETRY_JSON_REQUEST_DESCRIPTION = "A string value representing the json object. For example, '{\"key\":\"value\"}' or '{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}' or [{\"ts\":1527863043000,\"values\":{\"key1\":\"value1\",\"key2\":\"value2\"}}, {\"ts\":1527863053000,\"values\":{\"key1\":\"value3\",\"key2\":\"value4\"}}]";
  129 +
  130 +
  131 + private static final String STRICT_DATA_TYPES_DESCRIPTION = "A boolean value to specify if values of selected telemetry keys will represent string values(by default) or use strict data type.";
  132 + private static final String INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION = "Referencing a non-existing entity Id or invalid entity type will cause an error. ";
  133 +
  134 + private static final String SAVE_ENTITY_ATTRIBUTES_DESCRIPTION = "Creates or updates the entity attributes based on entity id, entity type, specified attributes scope " +
  135 + "and request payload that represents a JSON object with key-value format of attributes to create or update. " +
  136 + "For example, '{\"temperature\": 26}'. Key is a unique parameter and cannot be overwritten. Only value can be overwritten for the key. ";
  137 + private static final String SAVE_ATTIRIBUTES_STATUS_OK = "Attribute from the request was created or updated. ";
  138 + private static final String INVALID_STRUCTURE_OF_THE_REQUEST = "Invalid structure of the request";
  139 + private static final String SAVE_ATTIRIBUTES_STATUS_BAD_REQUEST = INVALID_STRUCTURE_OF_THE_REQUEST + " or invalid attributes scope provided.";
  140 + private static final String SAVE_ENTITY_ATTRIBUTES_STATUS_OK = "Platform creates an audit log event about entity attributes updates with action type 'ATTRIBUTES_UPDATED', " +
  141 + "and also sends event msg to the rule engine with msg type 'ATTRIBUTES_UPDATED'.";
  142 + private static final String SAVE_ENTITY_ATTRIBUTES_STATUS_UNAUTHORIZED = "User is not authorized to save entity attributes for selected entity. Most likely, User belongs to different Customer or Tenant.";
  143 + private static final String SAVE_ENTITY_ATTRIBUTES_STATUS_INTERNAL_SERVER_ERROR = "The exception was thrown during processing the request. " +
  144 + "Platform creates an audit log event about entity attributes updates with action type 'ATTRIBUTES_UPDATED' that includes an error stacktrace.";
  145 + private static final String SAVE_ENTITY_TIMESERIES_DESCRIPTION = "Creates or updates the entity timeseries based on entity id, entity type " +
  146 + "and request payload that represents a JSON object with key-value or ts-values format. " +
  147 + "For example, '{\"temperature\": 26}' or '{\"ts\":1634712287000,\"values\":{\"temperature\":26, \"humidity\":87}}', " +
  148 + "or JSON array with inner objects inside of ts-values format. " +
  149 + "For example, '[{\"ts\":1634712287000,\"values\":{\"temperature\":26, \"humidity\":87}}, {\"ts\":1634712588000,\"values\":{\"temperature\":25, \"humidity\":88}}]'. " +
  150 + "The scope parameter is not used in the API call implementation but should be specified whatever value because it is used as a path variable. ";
  151 + private static final String SAVE_ENTITY_TIMESERIES_STATUS_OK = "Timeseries from the request was created or updated. " +
  152 + "Platform creates an audit log event about entity timeseries updates with action type 'TIMESERIES_UPDATED'.";
  153 + private static final String SAVE_ENTITY_TIMESERIES_STATUS_UNAUTHORIZED = "User is not authorized to save entity timeseries for selected entity. Most likely, User belongs to different Customer or Tenant.";
  154 + private static final String SAVE_ENTITY_TIMESERIES_STATUS_INTERNAL_SERVER_ERROR = "The exception was thrown during processing the request. " +
  155 + "Platform creates an audit log event about entity timeseries updates with action type 'TIMESERIES_UPDATED' that includes an error stacktrace.";
122 156
123 157 @Autowired
124 158 private TimeseriesService tsService;
... ... @@ -146,7 +180,11 @@ public class TelemetryController extends BaseController {
146 180 }
147 181
148 182 @ApiOperation(value = "Get all attribute keys (getAttributeKeys)",
149   - notes = "Returns key names for the selected entity.")
  183 + notes = "Returns a list of all attribute key names for the selected entity. " +
  184 + "In the case of device entity specified, a response will include merged attribute key names list from each scope: " +
  185 + "SERVER_SCOPE, CLIENT_SCOPE, SHARED_SCOPE. "
  186 + + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  187 + produces = MediaType.APPLICATION_JSON_VALUE)
150 188 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
151 189 @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes", method = RequestMethod.GET)
152 190 @ResponseBody
... ... @@ -156,8 +194,11 @@ public class TelemetryController extends BaseController {
156 194 return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_ATTRIBUTES, entityType, entityIdStr, this::getAttributeKeysCallback);
157 195 }
158 196
159   - @ApiOperation(value = "Get all attributes by scope (getAttributeKeysByScope)",
160   - notes = "Returns key names of specified scope for the selected entity.")
  197 + @ApiOperation(value = "Get all attributes keys by scope (getAttributeKeysByScope)",
  198 + notes = "Returns a list of attribute key names from the specified attributes scope for the selected entity. " +
  199 + "If scope parameter is omitted, Get all attribute keys(getAttributeKeys) API will be called. "
  200 + + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  201 + produces = MediaType.APPLICATION_JSON_VALUE)
161 202 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
162 203 @RequestMapping(value = "/{entityType}/{entityId}/keys/attributes/{scope}", method = RequestMethod.GET)
163 204 @ResponseBody
... ... @@ -170,7 +211,9 @@ public class TelemetryController extends BaseController {
170 211 }
171 212
172 213 @ApiOperation(value = "Get attributes (getAttributes)",
173   - notes = "Returns JSON array of AttributeData objects for the selected entity.")
  214 + notes = GET_ALL_ATTRIBUTES_BASE_DESCRIPTION + " If 'keys' parameter is omitted, AttributeData class objects will be added to the response for all existing keys of the selected entity. " +
  215 + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  216 + produces = MediaType.APPLICATION_JSON_VALUE)
174 217 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
175 218 @RequestMapping(value = "/{entityType}/{entityId}/values/attributes", method = RequestMethod.GET)
176 219 @ResponseBody
... ... @@ -184,7 +227,11 @@ public class TelemetryController extends BaseController {
184 227 }
185 228
186 229 @ApiOperation(value = "Get attributes by scope (getAttributesByScope)",
187   - notes = "Returns JSON array of AttributeData objects for the selected entity.")
  230 + notes = GET_ALL_ATTRIBUTES_BY_SCOPE_BASE_DESCRIPTION + " In case that 'keys' parameter is not selected, " +
  231 + "AttributeData class objects will be added to the response for all existing attribute keys from the " +
  232 + "specified attributes scope of the selected entity. If 'scope' parameter is omitted, " +
  233 + "Get attributes (getAttributes) API will be called. " + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  234 + produces = MediaType.APPLICATION_JSON_VALUE)
188 235 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
189 236 @RequestMapping(value = "/{entityType}/{entityId}/values/attributes/{scope}", method = RequestMethod.GET)
190 237 @ResponseBody
... ... @@ -199,7 +246,9 @@ public class TelemetryController extends BaseController {
199 246 }
200 247
201 248 @ApiOperation(value = "Get timeseries keys (getTimeseriesKeys)",
202   - notes = "Returns latest timeseries keys for selected entity.")
  249 + notes = "Returns a list of all telemetry key names for the selected entity based on entity id and entity type specified. " +
  250 + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  251 + produces = MediaType.APPLICATION_JSON_VALUE)
203 252 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
204 253 @RequestMapping(value = "/{entityType}/{entityId}/keys/timeseries", method = RequestMethod.GET)
205 254 @ResponseBody
... ... @@ -211,7 +260,10 @@ public class TelemetryController extends BaseController {
211 260 }
212 261
213 262 @ApiOperation(value = "Get latest timeseries (getLatestTimeseries)",
214   - notes = "Returns JSON object with mapping latest timeseries keys to JSON arrays of TsData objects for the selected entity.")
  263 + notes = "Returns a JSON structure that represents a Map, where the map key is a telemetry key name " +
  264 + "and map value - is a singleton list of TsData class objects. "
  265 + + TS_DATA_CLASS_DESCRIPTION + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  266 + produces = MediaType.APPLICATION_JSON_VALUE)
215 267 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
216 268 @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET)
217 269 @ResponseBody
... ... @@ -222,30 +274,36 @@ public class TelemetryController extends BaseController {
222 274 @ApiParam(value = STRICT_DATA_TYPES_DESCRIPTION)
223 275 @RequestParam(name = "useStrictDataTypes", required = false, defaultValue = "false") Boolean useStrictDataTypes) throws ThingsboardException {
224 276 SecurityUser user = getCurrentUser();
225   -
226 277 return accessValidator.validateEntityAndCallback(getCurrentUser(), Operation.READ_TELEMETRY, entityType, entityIdStr,
227 278 (result, tenantId, entityId) -> getLatestTimeseriesValuesCallback(result, user, entityId, keysStr, useStrictDataTypes));
228 279 }
229 280
230 281 @ApiOperation(value = "Get timeseries (getTimeseries)",
231   - notes = "Returns JSON object with mapping timeseries keys to JSON arrays of TsData objects based on specified filters for the selected entity.")
  282 + notes = "Returns a JSON structure that represents a Map, where the map key is a telemetry key name " +
  283 + "and map value - is a list of TsData class objects. " + TS_DATA_CLASS_DESCRIPTION +
  284 + "This method allows us to group original data into intervals and aggregate it using one of the aggregation methods or just limit the number of TsData objects to fetch for each key specified. " +
  285 + "See the desription of the request parameters for more details. " +
  286 + "The result can also be sorted in ascending or descending order. "
  287 + + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  288 + produces = MediaType.APPLICATION_JSON_VALUE)
232 289 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
233 290 @RequestMapping(value = "/{entityType}/{entityId}/values/timeseries", method = RequestMethod.GET, params = {"keys", "startTs", "endTs"})
234 291 @ResponseBody
235 292 public DeferredResult<ResponseEntity> getTimeseries(
236 293 @ApiParam(value = ENTITY_TYPE_PARAM_DESCRIPTION) @PathVariable("entityType") String entityType,
237 294 @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION) @PathVariable("entityId") String entityIdStr,
238   - @ApiParam(value = TELEMETRY_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keys,
239   - @ApiParam(value = "A long value representing the start timestamp(milliseconds) of search time range.")
  295 + @ApiParam(value = TELEMETRY_KEYS_BASE_DESCRIPTION) @RequestParam(name = "keys") String keys,
  296 + @ApiParam(value = "A long value representing the start timestamp of search time range in milliseconds.")
240 297 @RequestParam(name = "startTs") Long startTs,
241   - @ApiParam(value = "A long value representing the end timestamp(milliseconds) of search time range.")
  298 + @ApiParam(value = "A long value representing the end timestamp of search time range in milliseconds.")
242 299 @RequestParam(name = "endTs") Long endTs,
243   - @ApiParam(value = "A long value representing the aggregation interval(milliseconds) range.")
  300 + @ApiParam(value = "A long value representing the aggregation interval range in milliseconds.")
244 301 @RequestParam(name = "interval", defaultValue = "0") Long interval,
245   - @ApiParam(value = "An integer value representing max number of selected data points.", defaultValue = "100")
  302 + @ApiParam(value = "An integer value that represents a max number of timeseries data points to fetch." +
  303 + " This parameter is used only in the case if 'agg' parameter is set to 'NONE'.", defaultValue = "100")
246 304 @RequestParam(name = "limit", defaultValue = "100") Integer limit,
247 305 @ApiParam(value = "A string value representing the aggregation function. " +
248   - "If the interval is not specified, 'agg' parameter will be converted to 'NONE' value.",
  306 + "If the interval is not specified, 'agg' parameter will use 'NONE' value.",
249 307 allowableValues = "MIN, MAX, AVG, SUM, COUNT, NONE")
250 308 @RequestParam(name = "agg", defaultValue = "NONE") String aggStr,
251 309 @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
... ... @@ -263,7 +321,21 @@ public class TelemetryController extends BaseController {
263 321 });
264 322 }
265 323
266   - @ApiOperation(value = "Save or update device attributes (saveDeviceAttributes)")
  324 + @ApiOperation(value = "Save or update device attributes (saveDeviceAttributes)",
  325 + notes = "Creates or updates the device attributes based on device id, specified attribute scope, " +
  326 + "and request payload that represents a JSON object with key-value format of attributes to create or update. " +
  327 + "For example, '{\"temperature\": 26}'. Key is a unique parameter and cannot be overwritten. Only value can " +
  328 + "be overwritten for the key. " + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  329 + produces = MediaType.APPLICATION_JSON_VALUE)
  330 + @ApiResponses(value = {
  331 + @ApiResponse(code = 200, message = SAVE_ATTIRIBUTES_STATUS_OK +
  332 + "Platform creates an audit log event about device attributes updates with action type 'ATTRIBUTES_UPDATED', " +
  333 + "and also sends event msg to the rule engine with msg type 'ATTRIBUTES_UPDATED'."),
  334 + @ApiResponse(code = 400, message = SAVE_ATTIRIBUTES_STATUS_BAD_REQUEST),
  335 + @ApiResponse(code = 401, message = "User is not authorized to save device attributes for selected device. Most likely, User belongs to different Customer or Tenant."),
  336 + @ApiResponse(code = 500, message = "The exception was thrown during processing the request. " +
  337 + "Platform creates an audit log event about device attributes updates with action type 'ATTRIBUTES_UPDATED' that includes an error stacktrace."),
  338 + })
267 339 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
268 340 @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.POST)
269 341 @ResponseBody
... ... @@ -275,7 +347,15 @@ public class TelemetryController extends BaseController {
275 347 return saveAttributes(getTenantId(), entityId, scope, request);
276 348 }
277 349
278   - @ApiOperation(value = "Save or update attributes (saveEntityAttributesV1)")
  350 + @ApiOperation(value = "Save or update attributes (saveEntityAttributesV1)",
  351 + notes = SAVE_ENTITY_ATTRIBUTES_DESCRIPTION + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  352 + produces = MediaType.APPLICATION_JSON_VALUE)
  353 + @ApiResponses(value = {
  354 + @ApiResponse(code = 200, message = SAVE_ATTIRIBUTES_STATUS_OK + SAVE_ENTITY_ATTRIBUTES_STATUS_OK),
  355 + @ApiResponse(code = 400, message = SAVE_ATTIRIBUTES_STATUS_BAD_REQUEST),
  356 + @ApiResponse(code = 401, message = SAVE_ENTITY_ATTRIBUTES_STATUS_UNAUTHORIZED),
  357 + @ApiResponse(code = 500, message = SAVE_ENTITY_ATTRIBUTES_STATUS_INTERNAL_SERVER_ERROR),
  358 + })
279 359 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
280 360 @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.POST)
281 361 @ResponseBody
... ... @@ -288,7 +368,15 @@ public class TelemetryController extends BaseController {
288 368 return saveAttributes(getTenantId(), entityId, scope, request);
289 369 }
290 370
291   - @ApiOperation(value = "Save or update attributes (saveEntityAttributesV2)")
  371 + @ApiOperation(value = "Save or update attributes (saveEntityAttributesV2)",
  372 + notes = SAVE_ENTITY_ATTRIBUTES_DESCRIPTION + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  373 + produces = MediaType.APPLICATION_JSON_VALUE)
  374 + @ApiResponses(value = {
  375 + @ApiResponse(code = 200, message = SAVE_ATTIRIBUTES_STATUS_OK + SAVE_ENTITY_ATTRIBUTES_STATUS_OK),
  376 + @ApiResponse(code = 400, message = SAVE_ATTIRIBUTES_STATUS_BAD_REQUEST),
  377 + @ApiResponse(code = 401, message = SAVE_ENTITY_ATTRIBUTES_STATUS_UNAUTHORIZED),
  378 + @ApiResponse(code = 500, message = SAVE_ENTITY_ATTRIBUTES_STATUS_INTERNAL_SERVER_ERROR),
  379 + })
292 380 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
293 381 @RequestMapping(value = "/{entityType}/{entityId}/attributes/{scope}", method = RequestMethod.POST)
294 382 @ResponseBody
... ... @@ -301,7 +389,15 @@ public class TelemetryController extends BaseController {
301 389 return saveAttributes(getTenantId(), entityId, scope, request);
302 390 }
303 391
304   - @ApiOperation(value = "Save or update telemetry (saveEntityTelemetry)")
  392 + @ApiOperation(value = "Save or update telemetry (saveEntityTelemetry)",
  393 + notes = SAVE_ENTITY_TIMESERIES_DESCRIPTION + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  394 + produces = MediaType.APPLICATION_JSON_VALUE)
  395 + @ApiResponses(value = {
  396 + @ApiResponse(code = 200, message = SAVE_ENTITY_TIMESERIES_STATUS_OK),
  397 + @ApiResponse(code = 400, message = INVALID_STRUCTURE_OF_THE_REQUEST),
  398 + @ApiResponse(code = 401, message = SAVE_ENTITY_TIMESERIES_STATUS_UNAUTHORIZED),
  399 + @ApiResponse(code = 500, message = SAVE_ENTITY_TIMESERIES_STATUS_INTERNAL_SERVER_ERROR),
  400 + })
305 401 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
306 402 @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}", method = RequestMethod.POST)
307 403 @ResponseBody
... ... @@ -315,7 +411,15 @@ public class TelemetryController extends BaseController {
315 411 }
316 412
317 413 @ApiOperation(value = "Save or update telemetry with TTL (saveEntityTelemetryWithTTL)",
318   - notes = "The TTL parameter is used to extract the number of days to store the data.")
  414 + notes = SAVE_ENTITY_TIMESERIES_DESCRIPTION + "The ttl parameter used only in case of Cassandra DB use for timeseries data storage. "
  415 + + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  416 + produces = MediaType.APPLICATION_JSON_VALUE)
  417 + @ApiResponses(value = {
  418 + @ApiResponse(code = 200, message = SAVE_ENTITY_TIMESERIES_STATUS_OK),
  419 + @ApiResponse(code = 400, message = INVALID_STRUCTURE_OF_THE_REQUEST),
  420 + @ApiResponse(code = 401, message = SAVE_ENTITY_TIMESERIES_STATUS_UNAUTHORIZED),
  421 + @ApiResponse(code = 500, message = SAVE_ENTITY_TIMESERIES_STATUS_INTERNAL_SERVER_ERROR),
  422 + })
319 423 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
320 424 @RequestMapping(value = "/{entityType}/{entityId}/timeseries/{scope}/{ttl}", method = RequestMethod.POST)
321 425 @ResponseBody
... ... @@ -323,14 +427,25 @@ public class TelemetryController extends BaseController {
323 427 @ApiParam(value = ENTITY_TYPE_PARAM_DESCRIPTION) @PathVariable("entityType") String entityType,
324 428 @ApiParam(value = ENTITY_ID_PARAM_DESCRIPTION) @PathVariable("entityId") String entityIdStr,
325 429 @ApiParam(value = TELEMETRY_SCOPE_DESCRIPTION) @PathVariable("scope") String scope,
326   - @ApiParam(value = "A long value representing TTL(Time to Live) parameter.") @PathVariable("ttl") Long ttl,
  430 + @ApiParam(value = "A long value representing TTL (Time to Live) parameter.") @PathVariable("ttl") Long ttl,
327 431 @ApiParam(value = TELEMETRY_JSON_REQUEST_DESCRIPTION) @RequestBody String requestBody) throws ThingsboardException {
328 432 EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr);
329 433 return saveTelemetry(getTenantId(), entityId, requestBody, ttl);
330 434 }
331 435
332 436 @ApiOperation(value = "Delete entity timeseries (deleteEntityTimeseries)",
333   - notes = "Delete timeseries in the specified time range for selected entity.")
  437 + notes = "Delete timeseries for selected entity based on entity id, entity type, keys " +
  438 + "and removal time range. To delete all data for keys parameter 'deleteAllDataForKeys' should be set to true, " +
  439 + "otherwise, will be deleted data that is in range of the selected time interval. " + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  440 + produces = MediaType.APPLICATION_JSON_VALUE)
  441 + @ApiResponses(value = {
  442 + @ApiResponse(code = 200, message = "Timeseries for the selected keys in the request was removed. " +
  443 + "Platform creates an audit log event about entity timeseries removal with action type 'TIMESERIES_DELETED'."),
  444 + @ApiResponse(code = 400, message = "Platform returns a bad request in case if keys list is empty or start and end timestamp values is empty when deleteAllDataForKeys is set to false."),
  445 + @ApiResponse(code = 401, message = "User is not authorized to delete entity timeseries for selected entity. Most likely, User belongs to different Customer or Tenant."),
  446 + @ApiResponse(code = 500, message = "The exception was thrown during processing the request. " +
  447 + "Platform creates an audit log event about entity timeseries removal with action type 'TIMESERIES_DELETED' that includes an error stacktrace."),
  448 + })
334 449 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
335 450 @RequestMapping(value = "/{entityType}/{entityId}/timeseries/delete", method = RequestMethod.DELETE)
336 451 @ResponseBody
... ... @@ -340,11 +455,11 @@ public class TelemetryController extends BaseController {
340 455 @ApiParam(value = TELEMETRY_KEYS_DESCRIPTION) @RequestParam(name = "keys") String keysStr,
341 456 @ApiParam(value = "A boolean value to specify if should be deleted all data for selected keys or only data that are in the selected time range.")
342 457 @RequestParam(name = "deleteAllDataForKeys", defaultValue = "false") boolean deleteAllDataForKeys,
343   - @ApiParam(value = "A long value representing the start timestamp(milliseconds) of removal time range.")
  458 + @ApiParam(value = "A long value representing the start timestamp of removal time range in milliseconds.")
344 459 @RequestParam(name = "startTs", required = false) Long startTs,
345   - @ApiParam(value = "A long value representing the end timestamp(milliseconds) of removal time range.")
  460 + @ApiParam(value = "A long value representing the end timestamp of removal time range in milliseconds.")
346 461 @RequestParam(name = "endTs", required = false) Long endTs,
347   - @ApiParam(value = "If the parameter is set to true, the latest telemetry will be rewritten if the current latest value was removed, otherwise, the new latest value will not set.")
  462 + @ApiParam(value = "If the parameter is set to true, the latest telemetry will be rewritten in case that current latest value was removed, otherwise, in case that parameter is set to false the new latest value will not set.")
348 463 @RequestParam(name = "rewriteLatestIfDeleted", defaultValue = "false") boolean rewriteLatestIfDeleted) throws ThingsboardException {
349 464 EntityId entityId = EntityIdFactory.getByTypeAndId(entityType, entityIdStr);
350 465 return deleteTimeseries(entityId, keysStr, deleteAllDataForKeys, startTs, endTs, rewriteLatestIfDeleted);
... ... @@ -395,7 +510,17 @@ public class TelemetryController extends BaseController {
395 510 }
396 511
397 512 @ApiOperation(value = "Delete device attributes (deleteEntityAttributes)",
398   - notes = "Delete attributes of specified scope for selected device.")
  513 + notes = "Delete device attributes from the specified attributes scope based on device id and a list of keys to delete. " +
  514 + "Selected keys will be deleted only if there are exist in the specified attribute scope. Referencing a non-existing device Id will cause an error" + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  515 + produces = MediaType.APPLICATION_JSON_VALUE)
  516 + @ApiResponses(value = {
  517 + @ApiResponse(code = 200, message = "Device attributes was removed for the selected keys in the request. " +
  518 + "Platform creates an audit log event about device attributes removal with action type 'ATTRIBUTES_DELETED'."),
  519 + @ApiResponse(code = 400, message = "Platform returns a bad request in case if keys or scope are not specified."),
  520 + @ApiResponse(code = 401, message = "User is not authorized to delete device attributes for selected entity. Most likely, User belongs to different Customer or Tenant."),
  521 + @ApiResponse(code = 500, message = "The exception was thrown during processing the request. " +
  522 + "Platform creates an audit log event about device attributes removal with action type 'ATTRIBUTES_DELETED' that includes an error stacktrace."),
  523 + })
399 524 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
400 525 @RequestMapping(value = "/{deviceId}/{scope}", method = RequestMethod.DELETE)
401 526 @ResponseBody
... ... @@ -408,7 +533,17 @@ public class TelemetryController extends BaseController {
408 533 }
409 534
410 535 @ApiOperation(value = "Delete entity attributes (deleteEntityAttributes)",
411   - notes = "Delete attributes of specified scope for selected entity.")
  536 + notes = "Delete entity attributes from the specified attributes scope based on entity id, entity type and a list of keys to delete. " +
  537 + "Selected keys will be deleted only if there are exist in the specified attribute scope." + INVALID_ENTITY_ID_OR_ENTITY_TYPE_DESCRIPTION + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH,
  538 + produces = MediaType.APPLICATION_JSON_VALUE)
  539 + @ApiResponses(value = {
  540 + @ApiResponse(code = 200, message = "Entity attributes was removed for the selected keys in the request. " +
  541 + "Platform creates an audit log event about entity attributes removal with action type 'ATTRIBUTES_DELETED'."),
  542 + @ApiResponse(code = 400, message = "Platform returns a bad request in case if keys or scope are not specified."),
  543 + @ApiResponse(code = 401, message = "User is not authorized to delete entity attributes for selected entity. Most likely, User belongs to different Customer or Tenant."),
  544 + @ApiResponse(code = 500, message = "The exception was thrown during processing the request. " +
  545 + "Platform creates an audit log event about entity attributes removal with action type 'ATTRIBUTES_DELETED' that includes an error stacktrace."),
  546 + })
412 547 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
413 548 @RequestMapping(value = "/{entityType}/{entityId}/{scope}", method = RequestMethod.DELETE)
414 549 @ResponseBody
... ...
... ... @@ -57,7 +57,7 @@ public class TenantController extends BaseController {
57 57 private TenantService tenantService;
58 58
59 59 @ApiOperation(value = "Get Tenant (getTenantById)",
60   - notes = "Fetch the Tenant object based on the provided Tenant Id. " + SYSTEM_AND_TENANT_AUTHORITY_PARAGRAPH)
  60 + notes = "Fetch the Tenant object based on the provided Tenant Id. " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
61 61 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
62 62 @RequestMapping(value = "/tenant/{tenantId}", method = RequestMethod.GET)
63 63 @ResponseBody
... ... @@ -79,7 +79,7 @@ public class TenantController extends BaseController {
79 79
80 80 @ApiOperation(value = "Get Tenant Info (getTenantInfoById)",
81 81 notes = "Fetch the Tenant Info object based on the provided Tenant Id. " +
82   - TENANT_INFO_DESCRIPTION + SYSTEM_AND_TENANT_AUTHORITY_PARAGRAPH)
  82 + TENANT_INFO_DESCRIPTION + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
83 83 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
84 84 @RequestMapping(value = "/tenant/info/{tenantId}", method = RequestMethod.GET)
85 85 @ResponseBody
... ...
... ... @@ -108,11 +108,6 @@ public class TenantProfileController extends BaseController {
108 108 "Let's review the example of tenant profile data below: " +
109 109 "\n\n" + MARKDOWN_CODE_BLOCK_START +
110 110 "{\n" +
111   - " \"id\": {\n" +
112   - " \"entityType\": \"TENANT_PROFILE\",\n" +
113   - " \"id\": \"0f2978a0-0d46-11eb-ab90-09ceaa526dd8\"\n" +
114   - " },\n" +
115   - " \"createdTime\": 1602588011818,\n" +
116 111 " \"name\": \"Default\",\n" +
117 112 " \"description\": \"Default tenant profile\",\n" +
118 113 " \"isolatedTbCore\": false,\n" +
... ...
... ... @@ -15,9 +15,9 @@
15 15 */
16 16 package org.thingsboard.server.controller;
17 17
18   -import com.fasterxml.jackson.databind.JsonNode;
19   -import com.fasterxml.jackson.databind.ObjectMapper;
20 18 import com.fasterxml.jackson.databind.node.ObjectNode;
  19 +import io.swagger.annotations.ApiOperation;
  20 +import io.swagger.annotations.ApiParam;
21 21 import lombok.Getter;
22 22 import lombok.RequiredArgsConstructor;
23 23 import org.springframework.beans.factory.annotation.Value;
... ... @@ -32,7 +32,6 @@ import org.springframework.web.bind.annotation.RequestParam;
32 32 import org.springframework.web.bind.annotation.ResponseBody;
33 33 import org.springframework.web.bind.annotation.ResponseStatus;
34 34 import org.springframework.web.bind.annotation.RestController;
35   -import org.thingsboard.common.util.JacksonUtil;
36 35 import org.thingsboard.rule.engine.api.MailService;
37 36 import org.thingsboard.server.common.data.EntityType;
38 37 import org.thingsboard.server.common.data.User;
... ... @@ -52,6 +51,7 @@ import org.thingsboard.server.common.data.security.event.UserAuthDataChangedEven
52 51 import org.thingsboard.server.common.data.security.model.JwtToken;
53 52 import org.thingsboard.server.queue.util.TbCoreComponent;
54 53 import org.thingsboard.server.service.security.auth.jwt.RefreshTokenRepository;
  54 +import org.thingsboard.server.service.security.model.JwtTokenPair;
55 55 import org.thingsboard.server.service.security.model.SecurityUser;
56 56 import org.thingsboard.server.service.security.model.UserPrincipal;
57 57 import org.thingsboard.server.service.security.model.token.JwtTokenFactory;
... ... @@ -82,20 +82,27 @@ public class UserController extends BaseController {
82 82 private final SystemSecurityService systemSecurityService;
83 83 private final ApplicationEventPublisher eventPublisher;
84 84
  85 + @ApiOperation(value = "Get User (getUserById)",
  86 + notes = "Fetch the User object based on the provided User Id. " +
  87 + "If the user has the authority of 'SYS_ADMIN', the server does not perform additional checks. " +
  88 + "If the user has the authority of 'TENANT_ADMIN', the server checks that the requested user is owned by the same tenant. " +
  89 + "If the user has the authority of 'CUSTOMER_USER', the server checks that the requested user is owned by the same customer.")
85 90 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
86 91 @RequestMapping(value = "/user/{userId}", method = RequestMethod.GET)
87 92 @ResponseBody
88   - public User getUserById(@PathVariable(USER_ID) String strUserId) throws ThingsboardException {
  93 + public User getUserById(
  94 + @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
  95 + @PathVariable(USER_ID) String strUserId) throws ThingsboardException {
89 96 checkParameter(USER_ID, strUserId);
90 97 try {
91 98 UserId userId = new UserId(toUUID(strUserId));
92 99 User user = checkUserId(userId, Operation.READ);
93   - if(user.getAdditionalInfo().isObject()) {
  100 + if (user.getAdditionalInfo().isObject()) {
94 101 ObjectNode additionalInfo = (ObjectNode) user.getAdditionalInfo();
95 102 processDashboardIdFromAdditionalInfo(additionalInfo, DEFAULT_DASHBOARD);
96 103 processDashboardIdFromAdditionalInfo(additionalInfo, HOME_DASHBOARD);
97 104 UserCredentials userCredentials = userService.findUserCredentialsByUserId(user.getTenantId(), user.getId());
98   - if(userCredentials.isEnabled() && !additionalInfo.has("userCredentialsEnabled")) {
  105 + if (userCredentials.isEnabled() && !additionalInfo.has("userCredentialsEnabled")) {
99 106 additionalInfo.put("userCredentialsEnabled", true);
100 107 }
101 108 }
... ... @@ -105,6 +112,10 @@ public class UserController extends BaseController {
105 112 }
106 113 }
107 114
  115 + @ApiOperation(value = "Check Token Access Enabled (isUserTokenAccessEnabled)",
  116 + notes = "Checks that the system is configured to allow administrators to impersonate themself as other users. " +
  117 + "If the user who performs the request has the authority of 'SYS_ADMIN', it is possible to login as any tenant administrator. " +
  118 + "If the user who performs the request has the authority of 'TENANT_ADMIN', it is possible to login as any customer user. ")
108 119 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
109 120 @RequestMapping(value = "/user/tokenAccessEnabled", method = RequestMethod.GET)
110 121 @ResponseBody
... ... @@ -112,10 +123,16 @@ public class UserController extends BaseController {
112 123 return userTokenAccessEnabled;
113 124 }
114 125
  126 + @ApiOperation(value = "Get User Token (getUserToken)",
  127 + notes = "Returns the token of the User based on the provided User Id. " +
  128 + "If the user who performs the request has the authority of 'SYS_ADMIN', it is possible to get the token of any tenant administrator. " +
  129 + "If the user who performs the request has the authority of 'TENANT_ADMIN', it is possible to get the token of any customer user that belongs to the same tenant. ")
115 130 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
116 131 @RequestMapping(value = "/user/{userId}/token", method = RequestMethod.GET)
117 132 @ResponseBody
118   - public JsonNode getUserToken(@PathVariable(USER_ID) String strUserId) throws ThingsboardException {
  133 + public JwtTokenPair getUserToken(
  134 + @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
  135 + @PathVariable(USER_ID) String strUserId) throws ThingsboardException {
119 136 checkParameter(USER_ID, strUserId);
120 137 try {
121 138 if (!userTokenAccessEnabled) {
... ... @@ -130,22 +147,26 @@ public class UserController extends BaseController {
130 147 SecurityUser securityUser = new SecurityUser(user, credentials.isEnabled(), principal);
131 148 JwtToken accessToken = tokenFactory.createAccessJwtToken(securityUser);
132 149 JwtToken refreshToken = refreshTokenRepository.requestRefreshToken(securityUser);
133   - ObjectMapper objectMapper = new ObjectMapper();
134   - ObjectNode tokenObject = objectMapper.createObjectNode();
135   - tokenObject.put("token", accessToken.getToken());
136   - tokenObject.put("refreshToken", refreshToken.getToken());
137   - return tokenObject;
  150 + return new JwtTokenPair(accessToken.getToken(), refreshToken.getToken());
138 151 } catch (Exception e) {
139 152 throw handleException(e);
140 153 }
141 154 }
142 155
  156 + @ApiOperation(value = "Save Or update User (saveUser)",
  157 + notes = "Create or update the User. When creating user, platform generates User Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
  158 + "The newly created User Id will be present in the response. " +
  159 + "Specify existing User Id to update the device. " +
  160 + "Referencing non-existing User Id will cause 'Not Found' error." +
  161 + "\n\nDevice email is unique for entire platform setup.")
143 162 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
144 163 @RequestMapping(value = "/user", method = RequestMethod.POST)
145 164 @ResponseBody
146   - public User saveUser(@RequestBody User user,
147   - @RequestParam(required = false, defaultValue = "true") boolean sendActivationMail,
148   - HttpServletRequest request) throws ThingsboardException {
  165 + public User saveUser(
  166 + @ApiParam(value = "A JSON value representing the User.", required = true)
  167 + @RequestBody User user,
  168 + @ApiParam(value = "Send activation email (or use activation link)", defaultValue = "true")
  169 + @RequestParam(required = false, defaultValue = "true") boolean sendActivationMail, HttpServletRequest request) throws ThingsboardException {
149 170 try {
150 171
151 172 if (Authority.TENANT_ADMIN.equals(getCurrentUser().getAuthority())) {
... ... @@ -188,10 +209,13 @@ public class UserController extends BaseController {
188 209 }
189 210 }
190 211
  212 + @ApiOperation(value = "Send or re-send the activation email",
  213 + notes = "Force send the activation email to the user. Useful to resend the email if user has accidentally deleted it. " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
191 214 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
192 215 @RequestMapping(value = "/user/sendActivationMail", method = RequestMethod.POST)
193 216 @ResponseStatus(value = HttpStatus.OK)
194 217 public void sendActivationEmail(
  218 + @ApiParam(value = "Email of the user", required = true)
195 219 @RequestParam(value = "email") String email,
196 220 HttpServletRequest request) throws ThingsboardException {
197 221 try {
... ... @@ -214,10 +238,14 @@ public class UserController extends BaseController {
214 238 }
215 239 }
216 240
  241 + @ApiOperation(value = "Get the activation link (getActivationLink)",
  242 + notes = "Get the activation link for the user. " +
  243 + "The base url for activation link is configurable in the general settings of system administrator. " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
217 244 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
218 245 @RequestMapping(value = "/user/{userId}/activationLink", method = RequestMethod.GET, produces = "text/plain")
219 246 @ResponseBody
220 247 public String getActivationLink(
  248 + @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
221 249 @PathVariable(USER_ID) String strUserId,
222 250 HttpServletRequest request) throws ThingsboardException {
223 251 checkParameter(USER_ID, strUserId);
... ... @@ -239,10 +267,15 @@ public class UserController extends BaseController {
239 267 }
240 268 }
241 269
  270 + @ApiOperation(value = "Delete User (deleteUser)",
  271 + notes = "Deletes the User, it's credentials and all the relations (from and to the User). " +
  272 + "Referencing non-existing User Id will cause an error. " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
242 273 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
243 274 @RequestMapping(value = "/user/{userId}", method = RequestMethod.DELETE)
244 275 @ResponseStatus(value = HttpStatus.OK)
245   - public void deleteUser(@PathVariable(USER_ID) String strUserId) throws ThingsboardException {
  276 + public void deleteUser(
  277 + @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
  278 + @PathVariable(USER_ID) String strUserId) throws ThingsboardException {
246 279 checkParameter(USER_ID, strUserId);
247 280 try {
248 281 UserId userId = new UserId(toUUID(strUserId));
... ... @@ -267,14 +300,22 @@ public class UserController extends BaseController {
267 300 }
268 301 }
269 302
  303 + @ApiOperation(value = "Get Users (getUsers)",
  304 + notes = "Returns a page of users owned by tenant or customer. The scope depends on authority of the user that performs the request." +
  305 + PAGE_DATA_PARAMETERS + TENANT_OR_CUSTOMER_AUTHORITY_PARAGRAPH)
270 306 @PreAuthorize("hasAnyAuthority('TENANT_ADMIN', 'CUSTOMER_USER')")
271 307 @RequestMapping(value = "/users", params = {"pageSize", "page"}, method = RequestMethod.GET)
272 308 @ResponseBody
273 309 public PageData<User> getUsers(
  310 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
274 311 @RequestParam int pageSize,
  312 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
275 313 @RequestParam int page,
  314 + @ApiParam(value = USER_TEXT_SEARCH_DESCRIPTION)
276 315 @RequestParam(required = false) String textSearch,
  316 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = USER_SORT_PROPERTY_ALLOWABLE_VALUES)
277 317 @RequestParam(required = false) String sortProperty,
  318 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
278 319 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
279 320 try {
280 321 PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
... ... @@ -289,15 +330,23 @@ public class UserController extends BaseController {
289 330 }
290 331 }
291 332
  333 + @ApiOperation(value = "Get Tenant Users (getTenantAdmins)",
  334 + notes = "Returns a page of users owned by tenant. " + PAGE_DATA_PARAMETERS + SYSTEM_AUTHORITY_PARAGRAPH)
292 335 @PreAuthorize("hasAuthority('SYS_ADMIN')")
293 336 @RequestMapping(value = "/tenant/{tenantId}/users", params = {"pageSize", "page"}, method = RequestMethod.GET)
294 337 @ResponseBody
295 338 public PageData<User> getTenantAdmins(
296   - @PathVariable("tenantId") String strTenantId,
  339 + @ApiParam(value = TENANT_ID_PARAM_DESCRIPTION, required = true)
  340 + @PathVariable(TENANT_ID) String strTenantId,
  341 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
297 342 @RequestParam int pageSize,
  343 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
298 344 @RequestParam int page,
  345 + @ApiParam(value = USER_TEXT_SEARCH_DESCRIPTION)
299 346 @RequestParam(required = false) String textSearch,
  347 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = USER_SORT_PROPERTY_ALLOWABLE_VALUES)
300 348 @RequestParam(required = false) String sortProperty,
  349 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
301 350 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
302 351 checkParameter("tenantId", strTenantId);
303 352 try {
... ... @@ -309,15 +358,23 @@ public class UserController extends BaseController {
309 358 }
310 359 }
311 360
  361 + @ApiOperation(value = "Get Customer Users (getCustomerUsers)",
  362 + notes = "Returns a page of users owned by customer. " + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH)
312 363 @PreAuthorize("hasAuthority('TENANT_ADMIN')")
313 364 @RequestMapping(value = "/customer/{customerId}/users", params = {"pageSize", "page"}, method = RequestMethod.GET)
314 365 @ResponseBody
315 366 public PageData<User> getCustomerUsers(
316   - @PathVariable("customerId") String strCustomerId,
  367 + @ApiParam(value = CUSTOMER_ID_PARAM_DESCRIPTION, required = true)
  368 + @PathVariable(CUSTOMER_ID) String strCustomerId,
  369 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
317 370 @RequestParam int pageSize,
  371 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
318 372 @RequestParam int page,
  373 + @ApiParam(value = USER_TEXT_SEARCH_DESCRIPTION)
319 374 @RequestParam(required = false) String textSearch,
  375 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = USER_SORT_PROPERTY_ALLOWABLE_VALUES)
320 376 @RequestParam(required = false) String sortProperty,
  377 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
321 378 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
322 379 checkParameter("customerId", strCustomerId);
323 380 try {
... ... @@ -331,11 +388,16 @@ public class UserController extends BaseController {
331 388 }
332 389 }
333 390
  391 + @ApiOperation(value = "Enable/Disable User credentials (setUserCredentialsEnabled)",
  392 + notes = "Enables or Disables user credentials. Useful when you would like to block user account without deleting it. " + PAGE_DATA_PARAMETERS + TENANT_AUTHORITY_PARAGRAPH)
334 393 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
335 394 @RequestMapping(value = "/user/{userId}/userCredentialsEnabled", method = RequestMethod.POST)
336 395 @ResponseBody
337   - public void setUserCredentialsEnabled(@PathVariable(USER_ID) String strUserId,
338   - @RequestParam(required = false, defaultValue = "true") boolean userCredentialsEnabled) throws ThingsboardException {
  396 + public void setUserCredentialsEnabled(
  397 + @ApiParam(value = USER_ID_PARAM_DESCRIPTION)
  398 + @PathVariable(USER_ID) String strUserId,
  399 + @ApiParam(value = "Disable (\"true\") or enable (\"false\") the credentials.", defaultValue = "true")
  400 + @RequestParam(required = false, defaultValue = "true") boolean userCredentialsEnabled) throws ThingsboardException {
339 401 checkParameter(USER_ID, strUserId);
340 402 try {
341 403 UserId userId = new UserId(toUUID(strUserId));
... ...
... ... @@ -15,6 +15,8 @@
15 15 */
16 16 package org.thingsboard.server.controller;
17 17
  18 +import io.swagger.annotations.ApiOperation;
  19 +import io.swagger.annotations.ApiParam;
18 20 import lombok.extern.slf4j.Slf4j;
19 21 import org.springframework.http.HttpStatus;
20 22 import org.springframework.security.access.prepost.PreAuthorize;
... ... @@ -48,10 +50,20 @@ import java.util.List;
48 50 @RequestMapping("/api")
49 51 public class WidgetTypeController extends BaseController {
50 52
  53 + private static final String WIDGET_TYPE_DESCRIPTION = "Widget Type represents the template for widget creation. Widget Type and Widget are similar to class and object in OOP theory.";
  54 + private static final String WIDGET_TYPE_DETAILS_DESCRIPTION = "Widget Type Details extend Widget Type and add image and description properties. " +
  55 + "Those properties are useful to edit the Widget Type but they are not required for Dashboard rendering. ";
  56 + private static final String WIDGET_TYPE_INFO_DESCRIPTION = "Widget Type Info is a lightweight object that represents Widget Type but does not contain the heavyweight widget descriptor JSON";
  57 +
  58 +
  59 + @ApiOperation(value = "Get Widget Type Details (getWidgetTypeById)",
  60 + notes = "Get the Widget Type Details based on the provided Widget Type Id. " + WIDGET_TYPE_DETAILS_DESCRIPTION + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
51 61 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
52 62 @RequestMapping(value = "/widgetType/{widgetTypeId}", method = RequestMethod.GET)
53 63 @ResponseBody
54   - public WidgetTypeDetails getWidgetTypeById(@PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
  64 + public WidgetTypeDetails getWidgetTypeById(
  65 + @ApiParam(value = WIDGET_TYPE_ID_PARAM_DESCRIPTION, required = true)
  66 + @PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
55 67 checkParameter("widgetTypeId", strWidgetTypeId);
56 68 try {
57 69 WidgetTypeId widgetTypeId = new WidgetTypeId(toUUID(strWidgetTypeId));
... ... @@ -61,10 +73,21 @@ public class WidgetTypeController extends BaseController {
61 73 }
62 74 }
63 75
  76 + @ApiOperation(value = "Create Or Update Widget Type (saveWidgetType)",
  77 + notes = "Create or update the Widget Type. " + WIDGET_TYPE_DESCRIPTION + " " +
  78 + "When creating the Widget Type, platform generates Widget Type Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
  79 + "The newly created Widget Type Id will be present in the response. " +
  80 + "Specify existing Widget Type id to update the Widget Type. " +
  81 + "Referencing non-existing Widget Type Id will cause 'Not Found' error." +
  82 + "\n\nWidget Type alias is unique in the scope of Widget Bundle. " +
  83 + "Special Tenant Id '13814000-1dd2-11b2-8080-808080808080' is automatically used if the create request is sent by user with 'SYS_ADMIN' authority."
  84 + + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
64 85 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
65 86 @RequestMapping(value = "/widgetType", method = RequestMethod.POST)
66 87 @ResponseBody
67   - public WidgetTypeDetails saveWidgetType(@RequestBody WidgetTypeDetails widgetTypeDetails) throws ThingsboardException {
  88 + public WidgetTypeDetails saveWidgetType(
  89 + @ApiParam(value = "A JSON value representing the Widget Type Details.", required = true)
  90 + @RequestBody WidgetTypeDetails widgetTypeDetails) throws ThingsboardException {
68 91 try {
69 92 if (Authority.SYS_ADMIN.equals(getCurrentUser().getAuthority())) {
70 93 widgetTypeDetails.setTenantId(TenantId.SYS_TENANT_ID);
... ... @@ -84,10 +107,14 @@ public class WidgetTypeController extends BaseController {
84 107 }
85 108 }
86 109
  110 + @ApiOperation(value = "Delete widget type (deleteWidgetType)",
  111 + notes = "Deletes the Widget Type. Referencing non-existing Widget Type Id will cause an error." + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
87 112 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
88 113 @RequestMapping(value = "/widgetType/{widgetTypeId}", method = RequestMethod.DELETE)
89 114 @ResponseStatus(value = HttpStatus.OK)
90   - public void deleteWidgetType(@PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
  115 + public void deleteWidgetType(
  116 + @ApiParam(value = WIDGET_TYPE_ID_PARAM_DESCRIPTION, required = true)
  117 + @PathVariable("widgetTypeId") String strWidgetTypeId) throws ThingsboardException {
91 118 checkParameter("widgetTypeId", strWidgetTypeId);
92 119 try {
93 120 WidgetTypeId widgetTypeId = new WidgetTypeId(toUUID(strWidgetTypeId));
... ... @@ -101,11 +128,15 @@ public class WidgetTypeController extends BaseController {
101 128 }
102 129 }
103 130
  131 + @ApiOperation(value = "Get all Widget types for specified Bundle (getBundleWidgetTypes)",
  132 + notes = "Returns an array of Widget Type objects that belong to specified Widget Bundle." + WIDGET_TYPE_DESCRIPTION + " " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
104 133 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
105 134 @RequestMapping(value = "/widgetTypes", params = {"isSystem", "bundleAlias"}, method = RequestMethod.GET)
106 135 @ResponseBody
107 136 public List<WidgetType> getBundleWidgetTypes(
  137 + @ApiParam(value = "System or Tenant", required = true)
108 138 @RequestParam boolean isSystem,
  139 + @ApiParam(value = "Widget Bundle alias", required = true)
109 140 @RequestParam String bundleAlias) throws ThingsboardException {
110 141 try {
111 142 TenantId tenantId;
... ... @@ -120,11 +151,15 @@ public class WidgetTypeController extends BaseController {
120 151 }
121 152 }
122 153
  154 + @ApiOperation(value = "Get all Widget types details for specified Bundle (getBundleWidgetTypes)",
  155 + notes = "Returns an array of Widget Type Details objects that belong to specified Widget Bundle." + WIDGET_TYPE_DETAILS_DESCRIPTION + " " + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
123 156 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
124 157 @RequestMapping(value = "/widgetTypesDetails", params = {"isSystem", "bundleAlias"}, method = RequestMethod.GET)
125 158 @ResponseBody
126 159 public List<WidgetTypeDetails> getBundleWidgetTypesDetails(
  160 + @ApiParam(value = "System or Tenant", required = true)
127 161 @RequestParam boolean isSystem,
  162 + @ApiParam(value = "Widget Bundle alias", required = true)
128 163 @RequestParam String bundleAlias) throws ThingsboardException {
129 164 try {
130 165 TenantId tenantId;
... ... @@ -139,11 +174,15 @@ public class WidgetTypeController extends BaseController {
139 174 }
140 175 }
141 176
  177 + @ApiOperation(value = "Get Widget Type Info objects (getBundleWidgetTypesInfos)",
  178 + notes = "Get the Widget Type Info objects based on the provided parameters. " + WIDGET_TYPE_INFO_DESCRIPTION + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
142 179 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
143 180 @RequestMapping(value = "/widgetTypesInfos", params = {"isSystem", "bundleAlias"}, method = RequestMethod.GET)
144 181 @ResponseBody
145 182 public List<WidgetTypeInfo> getBundleWidgetTypesInfos(
  183 + @ApiParam(value = "System or Tenant", required = true)
146 184 @RequestParam boolean isSystem,
  185 + @ApiParam(value = "Widget Bundle alias", required = true)
147 186 @RequestParam String bundleAlias) throws ThingsboardException {
148 187 try {
149 188 TenantId tenantId;
... ... @@ -158,12 +197,17 @@ public class WidgetTypeController extends BaseController {
158 197 }
159 198 }
160 199
  200 + @ApiOperation(value = "Get Widget Type (getWidgetType)",
  201 + notes = "Get the Widget Type based on the provided parameters. " + WIDGET_TYPE_DESCRIPTION + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
161 202 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
162 203 @RequestMapping(value = "/widgetType", params = {"isSystem", "bundleAlias", "alias"}, method = RequestMethod.GET)
163 204 @ResponseBody
164 205 public WidgetType getWidgetType(
  206 + @ApiParam(value = "System or Tenant", required = true)
165 207 @RequestParam boolean isSystem,
  208 + @ApiParam(value = "Widget Bundle alias", required = true)
166 209 @RequestParam String bundleAlias,
  210 + @ApiParam(value = "Widget Type alias", required = true)
167 211 @RequestParam String alias) throws ThingsboardException {
168 212 try {
169 213 TenantId tenantId;
... ...
... ... @@ -15,6 +15,8 @@
15 15 */
16 16 package org.thingsboard.server.controller;
17 17
  18 +import io.swagger.annotations.ApiOperation;
  19 +import io.swagger.annotations.ApiParam;
18 20 import org.springframework.http.HttpStatus;
19 21 import org.springframework.security.access.prepost.PreAuthorize;
20 22 import org.springframework.web.bind.annotation.PathVariable;
... ... @@ -44,10 +46,16 @@ import java.util.List;
44 46 @RequestMapping("/api")
45 47 public class WidgetsBundleController extends BaseController {
46 48
  49 + private static final String WIDGET_BUNDLE_DESCRIPTION = "Widget Bundle represents a group(bundle) of widgets. Widgets are grouped into bundle by type or use case. ";
  50 +
  51 + @ApiOperation(value = "Get Widget Bundle (getWidgetsBundleById)",
  52 + notes = "Get the Widget Bundle based on the provided Widget Bundle Id. " + WIDGET_BUNDLE_DESCRIPTION + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
47 53 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
48 54 @RequestMapping(value = "/widgetsBundle/{widgetsBundleId}", method = RequestMethod.GET)
49 55 @ResponseBody
50   - public WidgetsBundle getWidgetsBundleById(@PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
  56 + public WidgetsBundle getWidgetsBundleById(
  57 + @ApiParam(value = WIDGET_BUNDLE_ID_PARAM_DESCRIPTION, required = true)
  58 + @PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
51 59 checkParameter("widgetsBundleId", strWidgetsBundleId);
52 60 try {
53 61 WidgetsBundleId widgetsBundleId = new WidgetsBundleId(toUUID(strWidgetsBundleId));
... ... @@ -57,10 +65,21 @@ public class WidgetsBundleController extends BaseController {
57 65 }
58 66 }
59 67
  68 + @ApiOperation(value = "Create Or Update Widget Bundle (saveWidgetsBundle)",
  69 + notes = "Create or update the Widget Bundle. " + WIDGET_BUNDLE_DESCRIPTION + " " +
  70 + "When creating the bundle, platform generates Widget Bundle Id as [time-based UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier#Version_1_(date-time_and_MAC_address). " +
  71 + "The newly created Widget Bundle Id will be present in the response. " +
  72 + "Specify existing Widget Bundle id to update the Widget Bundle. " +
  73 + "Referencing non-existing Widget Bundle Id will cause 'Not Found' error." +
  74 + "\n\nWidget Bundle alias is unique in the scope of tenant. " +
  75 + "Special Tenant Id '13814000-1dd2-11b2-8080-808080808080' is automatically used if the create bundle request is sent by user with 'SYS_ADMIN' authority."
  76 + + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
60 77 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
61 78 @RequestMapping(value = "/widgetsBundle", method = RequestMethod.POST)
62 79 @ResponseBody
63   - public WidgetsBundle saveWidgetsBundle(@RequestBody WidgetsBundle widgetsBundle) throws ThingsboardException {
  80 + public WidgetsBundle saveWidgetsBundle(
  81 + @ApiParam(value = "A JSON value representing the Widget Bundle.", required = true)
  82 + @RequestBody WidgetsBundle widgetsBundle) throws ThingsboardException {
64 83 try {
65 84 if (Authority.SYS_ADMIN.equals(getCurrentUser().getAuthority())) {
66 85 widgetsBundle.setTenantId(TenantId.SYS_TENANT_ID);
... ... @@ -80,10 +99,14 @@ public class WidgetsBundleController extends BaseController {
80 99 }
81 100 }
82 101
  102 + @ApiOperation(value = "Delete widgets bundle (deleteWidgetsBundle)",
  103 + notes = "Deletes the widget bundle. Referencing non-existing Widget Bundle Id will cause an error." + SYSTEM_OR_TENANT_AUTHORITY_PARAGRAPH)
83 104 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN')")
84 105 @RequestMapping(value = "/widgetsBundle/{widgetsBundleId}", method = RequestMethod.DELETE)
85 106 @ResponseStatus(value = HttpStatus.OK)
86   - public void deleteWidgetsBundle(@PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
  107 + public void deleteWidgetsBundle(
  108 + @ApiParam(value = WIDGET_BUNDLE_ID_PARAM_DESCRIPTION, required = true)
  109 + @PathVariable("widgetsBundleId") String strWidgetsBundleId) throws ThingsboardException {
87 110 checkParameter("widgetsBundleId", strWidgetsBundleId);
88 111 try {
89 112 WidgetsBundleId widgetsBundleId = new WidgetsBundleId(toUUID(strWidgetsBundleId));
... ... @@ -97,14 +120,22 @@ public class WidgetsBundleController extends BaseController {
97 120 }
98 121 }
99 122
  123 + @ApiOperation(value = "Get Widget Bundles (getWidgetsBundles)",
  124 + notes = "Returns a page of Widget Bundle objects available for current user. " + WIDGET_BUNDLE_DESCRIPTION + " " +
  125 + PAGE_DATA_PARAMETERS + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
100 126 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
101 127 @RequestMapping(value = "/widgetsBundles", params = {"pageSize", "page"}, method = RequestMethod.GET)
102 128 @ResponseBody
103 129 public PageData<WidgetsBundle> getWidgetsBundles(
  130 + @ApiParam(value = PAGE_SIZE_DESCRIPTION, required = true)
104 131 @RequestParam int pageSize,
  132 + @ApiParam(value = PAGE_NUMBER_DESCRIPTION, required = true)
105 133 @RequestParam int page,
  134 + @ApiParam(value = WIDGET_BUNDLE_TEXT_SEARCH_DESCRIPTION)
106 135 @RequestParam(required = false) String textSearch,
  136 + @ApiParam(value = SORT_PROPERTY_DESCRIPTION, allowableValues = WIDGET_BUNDLE_SORT_PROPERTY_ALLOWABLE_VALUES)
107 137 @RequestParam(required = false) String sortProperty,
  138 + @ApiParam(value = SORT_ORDER_DESCRIPTION, allowableValues = SORT_ORDER_ALLOWABLE_VALUES)
108 139 @RequestParam(required = false) String sortOrder) throws ThingsboardException {
109 140 try {
110 141 PageLink pageLink = createPageLink(pageSize, page, textSearch, sortProperty, sortOrder);
... ... @@ -119,6 +150,8 @@ public class WidgetsBundleController extends BaseController {
119 150 }
120 151 }
121 152
  153 + @ApiOperation(value = "Get all Widget Bundles (getWidgetsBundles)",
  154 + notes = "Returns an array of Widget Bundle objects that are available for current user." + WIDGET_BUNDLE_DESCRIPTION + " " + AVAILABLE_FOR_ANY_AUTHORIZED_USER)
122 155 @PreAuthorize("hasAnyAuthority('SYS_ADMIN', 'TENANT_ADMIN', 'CUSTOMER_USER')")
123 156 @RequestMapping(value = "/widgetsBundles", method = RequestMethod.GET)
124 157 @ResponseBody
... ...
... ... @@ -15,6 +15,10 @@
15 15 */
16 16 package org.thingsboard.server.service.telemetry;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
  20 +
  21 +@ApiModel
18 22 public class AttributeData implements Comparable<AttributeData>{
19 23
20 24 private final long lastUpdateTs;
... ... @@ -28,14 +32,17 @@ public class AttributeData implements Comparable<AttributeData>{
28 32 this.value = value;
29 33 }
30 34
  35 + @ApiModelProperty(position = 1, value = "Timestamp last updated attribute, in milliseconds", example = "1609459200000", readOnly = true)
31 36 public long getLastUpdateTs() {
32 37 return lastUpdateTs;
33 38 }
34 39
  40 + @ApiModelProperty(position = 2, value = "String representing attribute key", example = "active", readOnly = true)
35 41 public String getKey() {
36 42 return key;
37 43 }
38 44
  45 + @ApiModelProperty(position = 3, value = "Object representing value of attribute key", example = "false", readOnly = true)
39 46 public Object getValue() {
40 47 return value;
41 48 }
... ...
... ... @@ -15,6 +15,10 @@
15 15 */
16 16 package org.thingsboard.server.service.telemetry;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
  20 +
  21 +@ApiModel
18 22 public class TsData implements Comparable<TsData>{
19 23
20 24 private final long ts;
... ... @@ -26,10 +30,12 @@ public class TsData implements Comparable<TsData>{
26 30 this.value = value;
27 31 }
28 32
  33 + @ApiModelProperty(position = 1, value = "Timestamp last updated timeseries, in milliseconds", example = "1609459200000", readOnly = true)
29 34 public long getTs() {
30 35 return ts;
31 36 }
32 37
  38 + @ApiModelProperty(position = 2, value = "Object representing value of timeseries key", example = "20", readOnly = true)
33 39 public Object getValue() {
34 40 return value;
35 41 }
... ...
... ... @@ -15,6 +15,7 @@
15 15 */
16 16 package org.thingsboard.server.common.data.widget;
17 17
  18 +import io.swagger.annotations.ApiModelProperty;
18 19 import lombok.Data;
19 20 import org.thingsboard.server.common.data.BaseData;
20 21 import org.thingsboard.server.common.data.HasTenantId;
... ... @@ -27,12 +28,16 @@ public class BaseWidgetType extends BaseData<WidgetTypeId> implements HasTenantI
27 28
28 29 private static final long serialVersionUID = 8388684344603660756L;
29 30
  31 + @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
30 32 private TenantId tenantId;
31 33 @NoXss
  34 + @ApiModelProperty(position = 4, value = "Reference to widget bundle", readOnly = true)
32 35 private String bundleAlias;
33 36 @NoXss
  37 + @ApiModelProperty(position = 5, value = "Unique alias that is used in dashboards as a reference widget type", readOnly = true)
34 38 private String alias;
35 39 @NoXss
  40 + @ApiModelProperty(position = 6, value = "Widget name used in search and UI", readOnly = true)
36 41 private String name;
37 42
38 43 public BaseWidgetType() {
... ... @@ -50,4 +55,19 @@ public class BaseWidgetType extends BaseData<WidgetTypeId> implements HasTenantI
50 55 this.alias = widgetType.getAlias();
51 56 this.name = widgetType.getName();
52 57 }
  58 +
  59 + @ApiModelProperty(position = 1, value = "JSON object with the Widget Type Id. " +
  60 + "Specify this field to update the Widget Type. " +
  61 + "Referencing non-existing Widget Type Id will cause error. " +
  62 + "Omit this field to create new Widget Type." )
  63 + @Override
  64 + public WidgetTypeId getId() {
  65 + return super.getId();
  66 + }
  67 +
  68 + @ApiModelProperty(position = 2, value = "Timestamp of the Widget Type creation, in milliseconds", example = "1609459200000", readOnly = true)
  69 + @Override
  70 + public long getCreatedTime() {
  71 + return super.getCreatedTime();
  72 + }
53 73 }
... ...
... ... @@ -16,12 +16,14 @@
16 16 package org.thingsboard.server.common.data.widget;
17 17
18 18 import com.fasterxml.jackson.databind.JsonNode;
  19 +import io.swagger.annotations.ApiModelProperty;
19 20 import lombok.Data;
20 21 import org.thingsboard.server.common.data.id.WidgetTypeId;
21 22
22 23 @Data
23 24 public class WidgetType extends BaseWidgetType {
24 25
  26 + @ApiModelProperty(position = 7, value = "Complex JSON object that describes the widget type", readOnly = true)
25 27 private transient JsonNode descriptor;
26 28
27 29 public WidgetType() {
... ...
... ... @@ -16,6 +16,7 @@
16 16 package org.thingsboard.server.common.data.widget;
17 17
18 18 import com.fasterxml.jackson.annotation.JsonPropertyOrder;
  19 +import io.swagger.annotations.ApiModelProperty;
19 20 import lombok.Data;
20 21 import org.thingsboard.server.common.data.id.WidgetTypeId;
21 22 import org.thingsboard.server.common.data.validation.NoXss;
... ... @@ -24,8 +25,10 @@ import org.thingsboard.server.common.data.validation.NoXss;
24 25 @JsonPropertyOrder({ "alias", "name", "image", "description", "descriptor" })
25 26 public class WidgetTypeDetails extends WidgetType {
26 27
  28 + @ApiModelProperty(position = 8, value = "Base64 encoded thumbnail", readOnly = true)
27 29 private String image;
28 30 @NoXss
  31 + @ApiModelProperty(position = 9, value = "Description of the widget", readOnly = true)
29 32 private String description;
30 33
31 34 public WidgetTypeDetails() {
... ...
... ... @@ -15,6 +15,7 @@
15 15 */
16 16 package org.thingsboard.server.common.data.widget;
17 17
  18 +import io.swagger.annotations.ApiModelProperty;
18 19 import lombok.Data;
19 20 import org.thingsboard.server.common.data.id.WidgetTypeId;
20 21 import org.thingsboard.server.common.data.validation.NoXss;
... ... @@ -22,10 +23,13 @@ import org.thingsboard.server.common.data.validation.NoXss;
22 23 @Data
23 24 public class WidgetTypeInfo extends BaseWidgetType {
24 25
  26 + @ApiModelProperty(position = 7, value = "Base64 encoded widget thumbnail", readOnly = true)
25 27 private String image;
26 28 @NoXss
  29 + @ApiModelProperty(position = 7, value = "Description of the widget type", readOnly = true)
27 30 private String description;
28 31 @NoXss
  32 + @ApiModelProperty(position = 8, value = "Type of the widget (timeseries, latest, control, alarm or static)", readOnly = true)
29 33 private String widgetType;
30 34
31 35 public WidgetTypeInfo() {
... ...
... ... @@ -15,6 +15,10 @@
15 15 */
16 16 package org.thingsboard.server.common.data.widget;
17 17
  18 +import io.swagger.annotations.ApiModel;
  19 +import io.swagger.annotations.ApiModelProperty;
  20 +import lombok.Getter;
  21 +import lombok.Setter;
18 22 import org.thingsboard.server.common.data.HasTenantId;
19 23 import org.thingsboard.server.common.data.SearchTextBased;
20 24 import org.thingsboard.server.common.data.id.TenantId;
... ... @@ -23,17 +27,37 @@ import org.thingsboard.server.common.data.validation.NoXss;
23 27
24 28 import java.util.Arrays;
25 29
  30 +@ApiModel
26 31 public class WidgetsBundle extends SearchTextBased<WidgetsBundleId> implements HasTenantId {
27 32
28 33 private static final long serialVersionUID = -7627368878362410489L;
29 34
  35 + @Getter
  36 + @Setter
  37 + @ApiModelProperty(position = 3, value = "JSON object with Tenant Id.", readOnly = true)
30 38 private TenantId tenantId;
  39 +
31 40 @NoXss
  41 + @Getter
  42 + @Setter
  43 + @ApiModelProperty(position = 4, value = "Unique alias that is used in widget types as a reference widget bundle", readOnly = true)
32 44 private String alias;
  45 +
33 46 @NoXss
  47 + @Getter
  48 + @Setter
  49 + @ApiModelProperty(position = 5, value = "Title used in search and UI", readOnly = true)
34 50 private String title;
  51 +
  52 + @Getter
  53 + @Setter
  54 + @ApiModelProperty(position = 6, value = "Base64 encoded thumbnail", readOnly = true)
35 55 private String image;
  56 +
36 57 @NoXss
  58 + @Getter
  59 + @Setter
  60 + @ApiModelProperty(position = 7, value = "Description", readOnly = true)
37 61 private String description;
38 62
39 63 public WidgetsBundle() {
... ... @@ -53,42 +77,21 @@ public class WidgetsBundle extends SearchTextBased<WidgetsBundleId> implements H
53 77 this.description = widgetsBundle.getDescription();
54 78 }
55 79
56   - public TenantId getTenantId() {
57   - return tenantId;
58   - }
59   -
60   - public void setTenantId(TenantId tenantId) {
61   - this.tenantId = tenantId;
62   - }
63   -
64   - public String getAlias() {
65   - return alias;
66   - }
67   -
68   - public void setAlias(String alias) {
69   - this.alias = alias;
70   - }
71   -
72   - public String getTitle() {
73   - return title;
74   - }
75   -
76   - public void setTitle(String title) {
77   - this.title = title;
78   - }
79   -
80   - public String getImage() {
81   - return image;
  80 + @ApiModelProperty(position = 1, value = "JSON object with the Widget Bundle Id. " +
  81 + "Specify this field to update the Widget Bundle. " +
  82 + "Referencing non-existing Widget Bundle Id will cause error. " +
  83 + "Omit this field to create new Widget Bundle." )
  84 + @Override
  85 + public WidgetsBundleId getId() {
  86 + return super.getId();
82 87 }
83 88
84   - public void setImage(String image) {
85   - this.image = image;
  89 + @ApiModelProperty(position = 2, value = "Timestamp of the Widget Bundle creation, in milliseconds", example = "1609459200000", readOnly = true)
  90 + @Override
  91 + public long getCreatedTime() {
  92 + return super.getCreatedTime();
86 93 }
87 94
88   - public String getDescription() { return description; }
89   -
90   - public void setDescription(String description) { this.description = description; }
91   -
92 95 @Override
93 96 public String getSearchText() {
94 97 return getTitle();
... ...