diff --git a/build-jar.gradle b/build-jar.gradle index de56b84..5eedc46 100644 --- a/build-jar.gradle +++ b/build-jar.gradle @@ -6,7 +6,7 @@ plugins { jar { archiveBaseName = 'cumulocity-clients-kotlin' - archiveVersion = '10.18.0-4' + archiveVersion = '-8' } repositories { @@ -18,7 +18,7 @@ publishing { maven(MavenPublication) { groupId = 'com.cumulocity' artifactId = 'cumulocity-clients-kotlin' - version = '10.18.0-4' + version = '-8' from components.java } } diff --git a/build.gradle b/build.gradle index a292d1f..6aab8a8 100644 --- a/build.gradle +++ b/build.gradle @@ -26,8 +26,8 @@ android { defaultConfig { minSdkVersion 19 targetSdkVersion 33 - versionCode 4 - versionName "10.18.0" + versionCode 8 + versionName "" testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner" } diff --git a/src/main/java/com/cumulocity/client/api/AlarmsApi.kt b/src/main/java/com/cumulocity/client/api/AlarmsApi.kt index df129ed..e5da91b 100644 --- a/src/main/java/com/cumulocity/client/api/AlarmsApi.kt +++ b/src/main/java/com/cumulocity/client/api/AlarmsApi.kt @@ -108,8 +108,12 @@ interface AlarmsApi { * When set to `true` also alarms for related source devices will be included in the request. When this parameter is provided a `source` must be specified. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.alarmcollection+json") @GET("/alarm/alarms") @@ -254,7 +258,7 @@ interface AlarmsApi { * * Remove alarm collections specified by query parameters. * - * > **������ Important:** Note that it is possible to call this endpoint without providing any parameter - it will result in deleting all alarms and it is not recommended.Also note that DELETE requests are not synchronous. The response could be returned before the delete request has been completed. + * > **������ Important:** DELETE requires at least one of the following parameters: `source`, `dateFrom`, `dateTo`, `createdFrom`, `createdTo`.Also note that DELETE requests are not synchronous. The response could be returned before the delete request has been completed. * * ##### Required roles * diff --git a/src/main/java/com/cumulocity/client/api/ApplicationsApi.kt b/src/main/java/com/cumulocity/client/api/ApplicationsApi.kt index 95cde25..97eb099 100644 --- a/src/main/java/com/cumulocity/client/api/ApplicationsApi.kt +++ b/src/main/java/com/cumulocity/client/api/ApplicationsApi.kt @@ -28,7 +28,7 @@ import com.cumulocity.client.model.ApplicationCollection * * For each tenant, Cumulocity IoT manages the subscribed applications and provides a number of applications of various types.In case you want to subscribe a tenant to an application using an API, you must use the application name in the argument (as name). * - * Refer to the tables in [Administration > Managing applications](https://cumulocity.com/guides/users-guide/administration#managing-applications) in the *User guide* for the respective application name to be used. + * Refer to the tables in [Platform administration > Standard tenant administration > Managing the ecosystem > Managing applications](https://cumulocity.com/docs/standard-tenant/ecosystem/#managing-applications) in the Cumulocity IoT user documentation for the respective application name to be used. * * > **ⓘ Info:** The Accept header should be provided in all POST/PUT requests, otherwise an empty response body will be returned. */ @@ -91,8 +91,12 @@ interface ApplicationsApi { * The ID of a user that has access to the applications. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. * @param hasVersions * When set to `true`, the returned result contains applications with an `applicationVersions` field that is not empty. When set to `false`, the result will contain applications with an empty `applicationVersions` field. */ @@ -362,8 +366,12 @@ interface ApplicationsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.applicationcollection+json") @GET("/application/applicationsByOwner/{tenantId}") @@ -400,8 +408,12 @@ interface ApplicationsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.applicationcollection+json") @GET("/application/applicationsByUser/{username}") diff --git a/src/main/java/com/cumulocity/client/api/AuditsApi.kt b/src/main/java/com/cumulocity/client/api/AuditsApi.kt index 4f85e78..a780009 100644 --- a/src/main/java/com/cumulocity/client/api/AuditsApi.kt +++ b/src/main/java/com/cumulocity/client/api/AuditsApi.kt @@ -68,9 +68,9 @@ interface AuditsApi { * @param currentPage * The current page of the paginated results. * @param dateFrom - * Start date or date and time of the audit record. + * Start date or date and time of the audit record (device time). * @param dateTo - * End date or date and time of the audit record. + * End date or date and time of the audit record (device time). * @param pageSize * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param source @@ -81,8 +81,12 @@ interface AuditsApi { * The username to search for. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.auditrecordcollection+json") @GET("/audit/auditRecords") diff --git a/src/main/java/com/cumulocity/client/api/BinariesApi.kt b/src/main/java/com/cumulocity/client/api/BinariesApi.kt index 62f48ea..5e622fc 100644 --- a/src/main/java/com/cumulocity/client/api/BinariesApi.kt +++ b/src/main/java/com/cumulocity/client/api/BinariesApi.kt @@ -80,11 +80,13 @@ interface BinariesApi { * @param pageSize * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param text - * Search for managed objects where any property value is equal to the given one. Only string values are supported. + * Search for managed objects where a property value is equal to the given one.The following properties are examined: `id, type, name, owner, externalIds`. * @param type * The type of managed object to search for. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobjectcollection+json") @GET("/inventory/binaries") diff --git a/src/main/java/com/cumulocity/client/api/BulkOperationsApi.kt b/src/main/java/com/cumulocity/client/api/BulkOperationsApi.kt index 8784928..c930a53 100644 --- a/src/main/java/com/cumulocity/client/api/BulkOperationsApi.kt +++ b/src/main/java/com/cumulocity/client/api/BulkOperationsApi.kt @@ -79,6 +79,8 @@ interface BulkOperationsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.bulkoperationcollection+json, application/vnd.com.nsn.cumulocity.error+json") @GET("/devicecontrol/bulkoperations") diff --git a/src/main/java/com/cumulocity/client/api/ChildOperationsApi.kt b/src/main/java/com/cumulocity/client/api/ChildOperationsApi.kt index b7acac4..2c70e3a 100644 --- a/src/main/java/com/cumulocity/client/api/ChildOperationsApi.kt +++ b/src/main/java/com/cumulocity/client/api/ChildOperationsApi.kt @@ -83,8 +83,12 @@ interface ChildOperationsApi { * When set to `true`, the returned result will contain the total number of children in the respective objects (`childAdditions`, `childAssets` and `childDevices`). * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json") @GET("/inventory/managedObjects/{id}/childAdditions") @@ -201,7 +205,7 @@ interface ChildOperationsApi { */ @Headers(*["Content-Type:application/vnd.com.nsn.cumulocity.managedobject+json", "Accept:application/json"]) @POST("/inventory/managedObjects/{id}/childAdditions") - @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "self", "assetParents", "deviceParents", "id") + @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "c8y_LatestMeasurements", "self", "assetParents", "deviceParents", "id") fun assignAsChildAddition( @Body body: ManagedObject, @Path("id") id: String, @@ -339,8 +343,12 @@ interface ChildOperationsApi { * When set to `true`, the returned result will contain the total number of children in the respective objects (`childAdditions`, `childAssets` and `childDevices`). * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json") @GET("/inventory/managedObjects/{id}/childAssets") @@ -457,7 +465,7 @@ interface ChildOperationsApi { */ @Headers(*["Content-Type:application/vnd.com.nsn.cumulocity.managedobject+json", "Accept:application/json"]) @POST("/inventory/managedObjects/{id}/childAssets") - @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "self", "assetParents", "deviceParents", "id") + @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "c8y_LatestMeasurements", "self", "assetParents", "deviceParents", "id") fun assignAsChildAsset( @Body body: ManagedObject, @Path("id") id: String, @@ -595,8 +603,12 @@ interface ChildOperationsApi { * When set to `true`, the returned result will contain the total number of children in the respective objects (`childAdditions`, `childAssets` and `childDevices`). * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobjectreferencecollection+json") @GET("/inventory/managedObjects/{id}/childDevices") @@ -713,7 +725,7 @@ interface ChildOperationsApi { */ @Headers(*["Content-Type:application/vnd.com.nsn.cumulocity.managedobject+json", "Accept:application/json"]) @POST("/inventory/managedObjects/{id}/childDevices") - @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "self", "assetParents", "deviceParents", "id") + @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "c8y_LatestMeasurements", "self", "assetParents", "deviceParents", "id") fun assignAsChildDevice( @Body body: ManagedObject, @Path("id") id: String, diff --git a/src/main/java/com/cumulocity/client/api/CurrentUserApi.kt b/src/main/java/com/cumulocity/client/api/CurrentUserApi.kt index f337356..57a6386 100644 --- a/src/main/java/com/cumulocity/client/api/CurrentUserApi.kt +++ b/src/main/java/com/cumulocity/client/api/CurrentUserApi.kt @@ -130,7 +130,7 @@ interface CurrentUserApi { * * Generate a secret code to create a QR code to set up the two-factor authentication functionality using a TFA app/service. * - * For more information about the feature, see [User Guide > Administration > Two-factor authentication](https://cumulocity.com/guides/users-guide/administration/#tfa) in the *Cumulocity IoT documentation*. + * For more information about the feature, see [Platform administration > Authentication > Two-factor authentication](https://cumulocity.com/docs/authentication/tfa/) in the Cumulocity IoT user documentation. * * * ##### Required roles @@ -177,7 +177,7 @@ interface CurrentUserApi { * * Activates or deactivates the two-factor authentication feature for the current user. * - * For more information about the feature, see [User Guide > Administration > Two-factor authentication](https://cumulocity.com/guides/users-guide/administration/#tfa) in the *Cumulocity IoT documentation*. + * For more information about the feature, see [Platform administration > Authentication > Two-factor authentication](https://cumulocity.com/docs/authentication/tfa/) in the Cumulocity IoT user documentation. * * * ##### Required roles @@ -191,7 +191,7 @@ interface CurrentUserApi { * * HTTP 204 The two-factor authentication was activated or deactivated. * * HTTP 401 Authentication information is missing or invalid. * * HTTP 403 Cannot deactivate TOTP setup. - * * HTTP 404 User not found. + * * HTTP 409 TFA TOTP secret does not exist. First generate secret. * * @param body */ diff --git a/src/main/java/com/cumulocity/client/api/DeviceCredentialsApi.kt b/src/main/java/com/cumulocity/client/api/DeviceCredentialsApi.kt index 5a64f0a..4440805 100644 --- a/src/main/java/com/cumulocity/client/api/DeviceCredentialsApi.kt +++ b/src/main/java/com/cumulocity/client/api/DeviceCredentialsApi.kt @@ -20,7 +20,7 @@ import com.cumulocity.client.model.BulkNewDeviceRequest /** * API methods to create device credentials in Cumulocity IoT. * - * Device credentials can be enquired by devices that do not have credentials for accessing a tenant yet.Since the device does not have credentials yet, a set of fixed credentials is used for this API.The credentials can be obtained by [contacting support](https://cumulocity.com/guides/about-doc/contacting-support/). + * Device credentials can be enquired by devices that do not have credentials for accessing a tenant yet.Since the device does not have credentials yet, a set of fixed credentials is used for this API.The credentials can be obtained by [contacting support](https://cumulocity.com/docs/additional-resources/contacting-support/). * * > **������ Important:** Do not use your tenant credentials with this API. * > **ⓘ Info:** The Accept header should be provided in all POST requests, otherwise an empty response body will be returned. @@ -92,7 +92,7 @@ interface DeviceCredentialsApi { * A separator is automatically obtained from the CSV file. Valid separator values are: `\t` (tabulation mark), `;` (semicolon) and `,` (comma). * * > **������ Important:** The CSV file needs the "com_cumulocity_model_Agent.active" header with a value of "true" to be added to the request. - * > **ⓘ Info:** A bulk registration creates an elementary representation of the device. Then, the device needs to update it to a full representation with its own status. The device is ready to use only after it is updated to the full representation. Also see [credentials upload](https://cumulocity.com/guides/users-guide/device-management/#creds-upload) and [device integration](https://cumulocity.com/guides/device-sdk/rest/#device-integration). + * > **ⓘ Info:** A bulk registration creates an elementary representation of the device. Then, the device needs to update it to a full representation with its own status. The device is ready to use only after it is updated to the full representation. Also see [Device management > Device management application > Registering devices > Single device registration > Security token policy](https://cumulocity.com/docs/device-management-application/registering-devices/#security-token-policy) and [Device management > Device integration > Device integration using REST > Integration life cycle](https://cumulocity.com/docs/device-integration/rest/#integration-life-cycle). * A CSV file can appear in many forms (with regard to the optional tenant column and the occurrence of device information): * * * If a user is logged in as the management tenant, then the columns ID, CREDENTIALS and TENANT are mandatory, and the device credentials will be created for the tenant mentioned in the TENANT column. diff --git a/src/main/java/com/cumulocity/client/api/DeviceStatisticsApi.kt b/src/main/java/com/cumulocity/client/api/DeviceStatisticsApi.kt index 837c4a0..2e5c362 100644 --- a/src/main/java/com/cumulocity/client/api/DeviceStatisticsApi.kt +++ b/src/main/java/com/cumulocity/client/api/DeviceStatisticsApi.kt @@ -109,6 +109,8 @@ interface DeviceStatisticsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") @GET("/tenant/statistics/device/{tenantId}/monthly/{date}") @@ -151,6 +153,8 @@ interface DeviceStatisticsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") @GET("/tenant/statistics/device/{tenantId}/daily/{date}") diff --git a/src/main/java/com/cumulocity/client/api/EventsApi.kt b/src/main/java/com/cumulocity/client/api/EventsApi.kt index 086fe1c..0b737aa 100644 --- a/src/main/java/com/cumulocity/client/api/EventsApi.kt +++ b/src/main/java/com/cumulocity/client/api/EventsApi.kt @@ -101,8 +101,12 @@ interface EventsApi { * When set to `true` also events for related source devices will be included in the request. When this parameter is provided a `source` must be specified. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.eventcollection+json") @GET("/event/events") @@ -170,7 +174,7 @@ interface EventsApi { * * DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when the deleted event has a lot of associated data. After sending the request, the platform starts deleting the associated data in an asynchronous way. Finally, the requested event is deleted after all associated data has been deleted. * - * > **������ Important:** Note that it is possible to call this endpoint without providing any parameter - it will result in deleting all events and it is not recommended. + * > **������ Important:** DELETE requires at least one of the following parameters: `source`, `dateFrom`, `dateTo`, `createdFrom`, `createdTo`. * * ##### Required roles * diff --git a/src/main/java/com/cumulocity/client/api/ExternalIDsApi.kt b/src/main/java/com/cumulocity/client/api/ExternalIDsApi.kt index 4f7e6ed..45b3b86 100644 --- a/src/main/java/com/cumulocity/client/api/ExternalIDsApi.kt +++ b/src/main/java/com/cumulocity/client/api/ExternalIDsApi.kt @@ -87,6 +87,7 @@ interface ExternalIDsApi { * * * HTTP 201 An external ID was created. * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 404 Global ID not found. * * HTTP 409 Duplicate ��� Identity already bound to a different Global ID. * * @param body diff --git a/src/main/java/com/cumulocity/client/api/FeatureTogglesApi.kt b/src/main/java/com/cumulocity/client/api/FeatureTogglesApi.kt new file mode 100644 index 0000000..ac6931b --- /dev/null +++ b/src/main/java/com/cumulocity/client/api/FeatureTogglesApi.kt @@ -0,0 +1,242 @@ +// Copyright (c) 2014-2023 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. +// Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG. + +package com.cumulocity.client.api +import retrofit2.converter.scalars.ScalarsConverterFactory +import retrofit2.converter.gson.ExtendedGsonConverterFactory +import retrofit2.Retrofit +import retrofit2.Call +import retrofit2.http.GET +import retrofit2.http.PUT +import retrofit2.http.DELETE +import retrofit2.http.Path +import retrofit2.http.Body +import retrofit2.http.Headers +import okhttp3.OkHttpClient +import retrofit2.converter.gson.ReadOnlyProperties +import okhttp3.ResponseBody +import com.cumulocity.client.model.FeatureToggleValue +import com.cumulocity.client.model.FeatureToggle +import com.cumulocity.client.model.TenantFeatureToggleValue + +interface FeatureTogglesApi { + + companion object Factory { + fun create(baseUrl: String): FeatureTogglesApi { + return create(baseUrl, null) + } + + fun create(baseUrl: String, clientBuilder: OkHttpClient.Builder?): FeatureTogglesApi { + val retrofitBuilder = retrofit().baseUrl(baseUrl) + if (clientBuilder != null) { + retrofitBuilder.client(clientBuilder.build()) + } + return retrofitBuilder.build().create(FeatureTogglesApi::class.java) + } + + fun retrofit(): Retrofit.Builder{ + return Retrofit.Builder() + .addConverterFactory(ExtendedGsonConverterFactory()) + .addConverterFactory(ScalarsConverterFactory.create()) + } + } + + /** + * Retrieve list of feature toggles with values for current tenant. + * + * Retrieve a list of all defined feature toggles with values calculated for a tenant of authenticated user. + * + * + * ##### Required roles + * + * none, any authenticated user can call this endpoint + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggles are sent in the response. + * * HTTP 401 Authentication information is missing or invalid. + */ + @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") + @GET("/features") + fun listCurrentTenantFeatures( + ): Call> + + /** + * Retrieve a specific feature toggle with value for current tenant. + * + * Retrieve a specific feature toggles defined under given key, with value calculated for a tenant of authenticated user. + * + * + * ##### Required roles + * + * none, any authenticated user can call this endpoint + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggle is sent in the response. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 404 Managed object not found. + * + * @param featureKey + * A unique key of the feature toggle. + */ + @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") + @GET("/features/{featureKey}") + fun getCurrentTenantFeature( + @Path("featureKey") featureKey: String + ): Call + + /** + * Retrieve list of feature toggles values overrides of all tenants. + * + * Retrieve a list of all existing feature toggle value overrides for all tenants. + * + * + * ##### Required roles + * + * ROLE_TENANT_MANAGEMENT_ADMIN *AND* current tenant is management + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggles are sent in the response. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 403 Not authorized to perform this operation. + * * HTTP 404 Managed object not found. + * + * @param featureKey + * A unique key of the feature toggle. + */ + @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") + @GET("/features/{featureKey}/by-tenant") + fun listTenantFeatureToggleValues( + @Path("featureKey") featureKey: String + ): Call> + + /** + * Sets the value of feature toggle override for the current tenant. + * + * Sets the value of feature toggle override for a tenant of authenticated user. + * + * + * ##### Required roles + * + * ROLE_TENANT_MANAGEMENT_ADMIN *AND* (current tenant is management *OR* the feature toggle phase is PUBLIC_PREVIEW or GENERALLY_AVAILABLE) + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggle value override was set. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 403 Not authorized to perform this operation. + * * HTTP 404 Managed object not found. + * + * @param body + * @param featureKey + * A unique key of the feature toggle. + */ + @Headers(*["Content-Type:application/json", "Accept:application/json"]) + @PUT("/features/{featureKey}/by-tenant") + fun setCurrentTenantFeatureToggleValue( + @Body body: FeatureToggleValue, + @Path("featureKey") featureKey: String + ): Call + + /** + * Removes the feature toggle override for the current tenant. + * + * Removes the feature toggle override for a tenant of authenticated user. + * + * + * ##### Required roles + * + * ROLE_TENANT_MANAGEMENT_ADMIN *AND* (current tenant is management *OR* the feature toggle phase is PUBLIC_PREVIEW or GENERALLY_AVAILABLE) + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggle value override was removed. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 403 Not authorized to perform this operation. + * * HTTP 404 Managed object not found. + * + * @param featureKey + * A unique key of the feature toggle. + */ + @Headers("Accept:application/json") + @DELETE("/features/{featureKey}/by-tenant") + fun unsetCurrentTenantFeatureToggleValue( + @Path("featureKey") featureKey: String + ): Call + + /** + * Sets the value of feature toggle override for a given tenant. + * + * Sets the value of feature toggle override for a given tenant. + * + * + * ##### Required roles + * + * ROLE_TENANT_MANAGEMENT_ADMIN *AND* current tenant is management. + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggle value override was set. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 403 Not authorized to perform this operation. + * * HTTP 404 Managed object not found. + * + * @param body + * @param featureKey + * A unique key of the feature toggle. + * @param tenantId + * Unique identifier of a Cumulocity IoT tenant. + */ + @Headers(*["Content-Type:application/json", "Accept:application/json"]) + @PUT("/features/{featureKey}/by-tenant/{tenantId}") + fun setGivenTenantFeatureToggleValue( + @Body body: FeatureToggleValue, + @Path("featureKey") featureKey: String, + @Path("tenantId") tenantId: String + ): Call + + /** + * Removes the feature toggle override for a given tenant. + * + * Removes the feature toggle override for a given tenant. + * + * + * ##### Required roles + * + * ROLE_TENANT_MANAGEMENT_ADMIN *AND* current tenant is management. + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 The request has succeeded and the feature toggle value override was removed. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 403 Not authorized to perform this operation. + * * HTTP 404 Managed object not found. + * + * @param featureKey + * A unique key of the feature toggle. + * @param tenantId + * Unique identifier of a Cumulocity IoT tenant. + */ + @Headers("Accept:application/json") + @DELETE("/features/{featureKey}/by-tenant/{tenantId}") + fun unsetGivenTenantFeatureToggleValue( + @Path("featureKey") featureKey: String, + @Path("tenantId") tenantId: String + ): Call +} diff --git a/src/main/java/com/cumulocity/client/api/GroupsApi.kt b/src/main/java/com/cumulocity/client/api/GroupsApi.kt index 7fe5043..124e946 100644 --- a/src/main/java/com/cumulocity/client/api/GroupsApi.kt +++ b/src/main/java/com/cumulocity/client/api/GroupsApi.kt @@ -75,8 +75,12 @@ interface GroupsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.groupcollection+json") @GET("/user/{tenantId}/groups") @@ -143,12 +147,15 @@ interface GroupsApi { * Unique identifier of a Cumulocity IoT tenant. * @param groupId * Unique identifier of the user group. + * @param forceLogout + * If set to `true`, users with this global role will be force logged out. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.group+json") @GET("/user/{tenantId}/groups/{groupId}") fun getUserGroup( @Path("tenantId") tenantId: String, - @Path("groupId") groupId: Int + @Path("groupId") groupId: Int, + @Query("forceLogout") forceLogout: Boolean? = null ): Call /** @@ -176,6 +183,8 @@ interface GroupsApi { * Unique identifier of a Cumulocity IoT tenant. * @param groupId * Unique identifier of the user group. + * @param forceLogout + * If set to `true`, users with this global role will be force logged out. */ @Headers(*["Content-Type:application/vnd.com.nsn.cumulocity.group+json", "Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.group+json"]) @PUT("/user/{tenantId}/groups/{groupId}") @@ -183,7 +192,8 @@ interface GroupsApi { fun updateUserGroup( @Body body: Group, @Path("tenantId") tenantId: String, - @Path("groupId") groupId: Int + @Path("groupId") groupId: Int, + @Query("forceLogout") forceLogout: Boolean? = null ): Call /** @@ -209,12 +219,15 @@ interface GroupsApi { * Unique identifier of a Cumulocity IoT tenant. * @param groupId * Unique identifier of the user group. + * @param forceLogout + * If set to `true`, users with this global role will be force logged out. */ @Headers("Accept:application/json") @DELETE("/user/{tenantId}/groups/{groupId}") fun deleteUserGroup( @Path("tenantId") tenantId: String, - @Path("groupId") groupId: Int + @Path("groupId") groupId: Int, + @Query("forceLogout") forceLogout: Boolean? = null ): Call /** @@ -277,8 +290,12 @@ interface GroupsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.groupreferencecollection+json") @GET("/user/{tenantId}/users/{userId}/groups") diff --git a/src/main/java/com/cumulocity/client/api/InventoryRolesApi.kt b/src/main/java/com/cumulocity/client/api/InventoryRolesApi.kt index a7f3dd7..cc2ca4f 100644 --- a/src/main/java/com/cumulocity/client/api/InventoryRolesApi.kt +++ b/src/main/java/com/cumulocity/client/api/InventoryRolesApi.kt @@ -73,6 +73,8 @@ interface InventoryRolesApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.inventoryrolecollection+json") @GET("/user/inventoryroles") diff --git a/src/main/java/com/cumulocity/client/api/LoginOptionsApi.kt b/src/main/java/com/cumulocity/client/api/LoginOptionsApi.kt index e02a8c7..2f33ca1 100644 --- a/src/main/java/com/cumulocity/client/api/LoginOptionsApi.kt +++ b/src/main/java/com/cumulocity/client/api/LoginOptionsApi.kt @@ -25,7 +25,7 @@ import com.cumulocity.client.model.LoginOptionCollection /** * API methods to retrieve the login options configured in the tenant. * - * More detailed information about the parameters and their meaning can be found in [Administration > Changing settings](https://cumulocity.com/guides/users-guide/administration/#changing-settings) in the *Users guide*. + * More detailed information about the parameters and their meaning can be found in [Platform administration > Standard tenant administration > Changing settings](https://cumulocity.com/docs/standard-tenant/changing-settings/) in the Cumulocity IoT user documentation. * * > **ⓘ Info:** If OAuth external is the only login option shown in the response, the user will be automatically redirected to the SSO login screen. */ diff --git a/src/main/java/com/cumulocity/client/api/ManagedObjectsApi.kt b/src/main/java/com/cumulocity/client/api/ManagedObjectsApi.kt index f5ff26b..3ab1310 100644 --- a/src/main/java/com/cumulocity/client/api/ManagedObjectsApi.kt +++ b/src/main/java/com/cumulocity/client/api/ManagedObjectsApi.kt @@ -28,6 +28,8 @@ import com.cumulocity.client.model.SupportedSeries /** * The inventory stores devices and other assets relevant to your IoT solution. We refer to them as managed objects and such can be ���smart objects���, for example, smart electricity meters, home automation gateways or GPS devices. * + * For further information, refer to [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Managed objects](https://cumulocity.com/docs/concepts/domain-model/#managed-objects) in the Cumulocity IoT user documentation. + * * > **ⓘ Info:** The Accept header should be provided in all POST/PUT requests, otherwise an empty response body will be returned. */ interface ManagedObjectsApi { @@ -92,7 +94,7 @@ interface ManagedObjectsApi { * @param skipChildrenNames * When set to `true`, the returned references of child devices won't contain their names. * @param text - * Search for managed objects where any property value is equal to the given one. Only string values are supported. + * Search for managed objects where a property value is equal to the given one.The following properties are examined: `id, type, name, owner, externalIds`. * @param type * The type of managed object to search for. * @param withChildren @@ -105,8 +107,16 @@ interface ManagedObjectsApi { * When set to `true`, the returned references of child parents will return the device's parents (if any). Otherwise, it will be an empty array. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. + * @param withLatestValues + * If set to true the platform returns managed objects with the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform. + * + * **������ Feature Preview:** The parameter is a part of the Latest Measurement feature which is still under public preview. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobjectcollection+json") @GET("/inventory/managedObjects") @@ -130,7 +140,8 @@ interface ManagedObjectsApi { @Query("withGroups") withGroups: Boolean? = null, @Query("withParents") withParents: Boolean? = null, @Query("withTotalElements") withTotalElements: Boolean? = null, - @Query("withTotalPages") withTotalPages: Boolean? = null + @Query("withTotalPages") withTotalPages: Boolean? = null, + @Query("withLatestValues") withLatestValues: Boolean? = null ): Call /** @@ -148,7 +159,7 @@ interface ManagedObjectsApi { * * Imagine, for example, that you want to describe electric meters from different vendors. Depending on the make of the meter, one may have a relay and one may be capable to measure a single phase or three phases (for example, a three-phase electricity sensor). A fragment `c8y_ThreePhaseElectricitySensor` would identify such an electric meter. Devices' characteristics are identified by storing fragments for each of them. * - * > **ⓘ Info:** For more details about fragments with specific meanings, review the sections [Device management library](#section/Device-management-library) and [Sensor library](#section/Sensor-library). + * > **ⓘ Info:** For more details about fragments with specific meanings, refer to [Device management & connectivity > Device integration > Fragment library](https://cumulocity.com/docs/device-integration/fragment-library/) in the Cumulocity IoT user documentation. * * ##### Required roles * @@ -168,7 +179,7 @@ interface ManagedObjectsApi { */ @Headers(*["Content-Type:application/vnd.com.nsn.cumulocity.managedobject+json", "Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobject+json"]) @POST("/inventory/managedObjects") - @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "self", "assetParents", "deviceParents", "id") + @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "c8y_LatestMeasurements", "self", "assetParents", "deviceParents", "id") fun createManagedObject( @Body body: ManagedObject, @Header("X-Cumulocity-Processing-Mode") xCumulocityProcessingMode: String? = null @@ -202,6 +213,10 @@ interface ManagedObjectsApi { * When set to `true`, the returned result will contain the total number of children in the respective objects (`childAdditions`, `childAssets` and `childDevices`). * @param withParents * When set to `true`, the returned references of child parents will return the device's parents (if any). Otherwise, it will be an empty array. + * @param withLatestValues + * If set to true the platform returns managed objects with the fragment `c8y_LatestMeasurements, which contains the latest measurement values reported by the device to the platform. + * + * **������ Feature Preview:** The parameter is a part of the Latest Measurement feature which is still under public preview. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobject+json") @GET("/inventory/managedObjects/{id}") @@ -210,7 +225,8 @@ interface ManagedObjectsApi { @Query("skipChildrenNames") skipChildrenNames: Boolean? = null, @Query("withChildren") withChildren: Boolean? = null, @Query("withChildrenCount") withChildrenCount: Boolean? = null, - @Query("withParents") withParents: Boolean? = null + @Query("withParents") withParents: Boolean? = null, + @Query("withLatestValues") withLatestValues: Boolean? = null ): Call /** @@ -243,7 +259,7 @@ interface ManagedObjectsApi { */ @Headers(*["Content-Type:application/vnd.com.nsn.cumulocity.managedobject+json", "Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.managedobject+json"]) @PUT("/inventory/managedObjects/{id}") - @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "self", "assetParents", "deviceParents", "id") + @ReadOnlyProperties("owner", "additionParents", "lastUpdated", "childDevices", "childAssets", "creationTime", "childAdditions", "c8y_LatestMeasurements", "self", "assetParents", "deviceParents", "id") fun updateManagedObject( @Body body: ManagedObject, @Path("id") id: String, diff --git a/src/main/java/com/cumulocity/client/api/MeasurementsApi.kt b/src/main/java/com/cumulocity/client/api/MeasurementsApi.kt index 7e85e7d..73c553f 100644 --- a/src/main/java/com/cumulocity/client/api/MeasurementsApi.kt +++ b/src/main/java/com/cumulocity/client/api/MeasurementsApi.kt @@ -17,7 +17,6 @@ import retrofit2.http.Headers import okhttp3.OkHttpClient import retrofit2.converter.gson.ReadOnlyProperties import okhttp3.ResponseBody -import com.cumulocity.client.supplementary.SeparatedQueryParameter import com.cumulocity.client.model.Measurement import com.cumulocity.client.model.MeasurementCollection import com.cumulocity.client.model.MeasurementSeries @@ -92,8 +91,12 @@ interface MeasurementsApi { * A characteristic which identifies the measurement. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.measurementcollection+json") @GET("/measurement/measurements") @@ -121,7 +124,7 @@ interface MeasurementsApi { * * `value` - The value of the individual measurement. The maximum precision for floating point numbers is 64-bit IEEE 754. For integers it's a 64-bit two's complement integer. The `value` is mandatory for a fragment. * * `unit` - The unit of the measurements. * - * Review the [System of units](#section/System-of-units) section for details about the conversions of units. Also review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) in the Concepts guide. + * Review the [System of units](#section/System-of-units) section for details about the conversions of units. Also review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation. * * The example below uses `c8y_Steam` in the request body to illustrate a fragment for recording temperature measurements. * @@ -130,7 +133,7 @@ interface MeasurementsApi { * * It is also possible to create multiple measurements at once by sending a `measurements` array containing all the measurements to be created. The content type must be `application/vnd.com.nsn.cumulocity.measurementcollection+json`. * - * > **ⓘ Info:** For more details about fragments with specific meanings, review the sections [Device management library](#section/Device-management-library) and [Sensor library](#section/Sensor-library). + * > **ⓘ Info:** For more details about fragments with specific meanings, refer to [Device management & connectivity > Device integration > Fragment library](https://cumulocity.com/docs/device-integration/fragment-library/) in the Cumulocity IoT user documentation. * * ##### Required roles * @@ -167,7 +170,7 @@ interface MeasurementsApi { * * `value` - The value of the individual measurement. The maximum precision for floating point numbers is 64-bit IEEE 754. For integers it's a 64-bit two's complement integer. The `value` is mandatory for a fragment. * * `unit` - The unit of the measurements. * - * Review the [System of units](#section/System-of-units) section for details about the conversions of units. Also review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) in the Concepts guide. + * Review the [System of units](#section/System-of-units) section for details about the conversions of units. Also review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation. * * The example below uses `c8y_Steam` in the request body to illustrate a fragment for recording temperature measurements. * @@ -176,7 +179,7 @@ interface MeasurementsApi { * * It is also possible to create multiple measurements at once by sending a `measurements` array containing all the measurements to be created. The content type must be `application/vnd.com.nsn.cumulocity.measurementcollection+json`. * - * > **ⓘ Info:** For more details about fragments with specific meanings, review the sections [Device management library](#section/Device-management-library) and [Sensor library](#section/Sensor-library). + * > **ⓘ Info:** For more details about fragments with specific meanings, refer to [Device management & connectivity > Device integration > Fragment library](https://cumulocity.com/docs/device-integration/fragment-library/) in the Cumulocity IoT user documentation. * * ##### Required roles * @@ -210,7 +213,7 @@ interface MeasurementsApi { * * DELETE requests are not synchronous. The response could be returned before the delete request has been completed. This may happen especially when there are a lot of measurements to be deleted. * - * > **������ Important:** Note that it is possible to call this endpoint without providing any parameter - it may result in deleting all measurements and it is not recommended. + * > **������ Important:** DELETE requires at least one of the following parameters: `source`, `dateFrom`, `dateTo`. * In case of enhanced time series measurements, both `dateFrom` and `dateTo` parameters must be truncated to full hours (for example, 2022-08-19T14:00:00.000Z), otherwise an error will be returned.The `fragmentType` parameter allows to delete measurements only by a measurement fragment when enhanced time series measurements are used.It's not possible to delete by a custom (non-measurement) fragment. * * Example for a valid measurement value fragment: @@ -360,7 +363,7 @@ interface MeasurementsApi { * @param series * The specific series to search for. * - * **ⓘ Info:** If you query for multiple series at once, comma-separate the values. + * **ⓘ Info:** If you want to query multiple series at once, you must specify the parameter multiple times. * @param source * The managed object ID to which the measurement is associated. */ @@ -371,7 +374,7 @@ interface MeasurementsApi { @Query("dateFrom") dateFrom: String, @Query("dateTo") dateTo: String, @Query("revert") revert: Boolean? = null, - @Query("series") series: SeparatedQueryParameter? = null, + @Query("series") series: Array? = null, @Query("source") source: String ): Call } diff --git a/src/main/java/com/cumulocity/client/api/NewDeviceRequestsApi.kt b/src/main/java/com/cumulocity/client/api/NewDeviceRequestsApi.kt index c512ab2..d09c6af 100644 --- a/src/main/java/com/cumulocity/client/api/NewDeviceRequestsApi.kt +++ b/src/main/java/com/cumulocity/client/api/NewDeviceRequestsApi.kt @@ -71,8 +71,12 @@ interface NewDeviceRequestsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.newdevicerequestcollection+json") @GET("/devicecontrol/newDeviceRequests") diff --git a/src/main/java/com/cumulocity/client/api/OperationsApi.kt b/src/main/java/com/cumulocity/client/api/OperationsApi.kt index 65bb1c8..c6e248d 100644 --- a/src/main/java/com/cumulocity/client/api/OperationsApi.kt +++ b/src/main/java/com/cumulocity/client/api/OperationsApi.kt @@ -93,8 +93,12 @@ interface OperationsApi { * Status of the operation. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.operationcollection+json") @GET("/devicecontrol/operations") @@ -120,6 +124,10 @@ interface OperationsApi { * * It is possible to add custom fragments to operations, for example `com_cumulocity_model_WebCamDevice` is a custom object of the webcam operation. * + * There are some custom fragments which are used by web applications (like Device management) to provide additional context to operations, for example: + * + * * `description` - this fragment can be used to provide a brief user-friendly description of the operation which is later displayed in the operations list views within web applications. + * * * ##### Required roles * diff --git a/src/main/java/com/cumulocity/client/api/OptionsApi.kt b/src/main/java/com/cumulocity/client/api/OptionsApi.kt index 7643b3c..35c2187 100644 --- a/src/main/java/com/cumulocity/client/api/OptionsApi.kt +++ b/src/main/java/com/cumulocity/client/api/OptionsApi.kt @@ -54,6 +54,7 @@ interface OptionsApi { * * Retrieve all the options available on the tenant. * + * > **������ Important:** Note that Enterprise Tenants are also allowed to read inherited tenant options from the management tenant. * * ##### Required roles * @@ -72,6 +73,8 @@ interface OptionsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.optioncollection+json") @GET("/tenant/options") @@ -94,7 +97,7 @@ interface OptionsApi { * * **access.control** * - * | Key | Default value | Predefined | Description ||--|--|--|--|| allow.origin | * | Yes | Comma separated list of domains allowed for execution of CORS. Wildcards are allowed (for example, `*.cumuclocity.com`) | + * | Key | Default value | Predefined | Description ||--|--|--|--|| allow.origin | * | Yes | Comma separated list of domains allowed for execution of CORS. Wildcards are allowed (for example, `*.cumulocity.com`) | * * **alarm.type.mapping** * @@ -140,6 +143,7 @@ interface OptionsApi { * * Retrieve all the options (by a specified category) on your tenant. * + * > **������ Important:** Note that Enterprise Tenants are also allowed to read inherited tenant options from the management tenant. * * ##### Required roles * @@ -195,6 +199,7 @@ interface OptionsApi { * * Retrieve a specific option (by a given category and key) on your tenant. * + * > **������ Important:** Note that Enterprise Tenants are also allowed to read inherited tenant options from the management tenant. * * ##### Required roles * diff --git a/src/main/java/com/cumulocity/client/api/RealtimeNotificationApi.kt b/src/main/java/com/cumulocity/client/api/RealtimeNotificationApi.kt index 8d80f01..414c7e9 100644 --- a/src/main/java/com/cumulocity/client/api/RealtimeNotificationApi.kt +++ b/src/main/java/com/cumulocity/client/api/RealtimeNotificationApi.kt @@ -205,6 +205,9 @@ import com.cumulocity.client.model.RealtimeNotification * } * ] * ``` + * ## Long-running connections + * + * To keep a long-running connection alive when there are no new notifications to deliver, the server will periodically send an empty `/meta/connect` response to the client.The client should send a new `/meta/connect` request immediately after receiving such a response, to ensure that the connection remains active and future notifications are delivered. */ interface RealtimeNotificationApi { diff --git a/src/main/java/com/cumulocity/client/api/RetentionRulesApi.kt b/src/main/java/com/cumulocity/client/api/RetentionRulesApi.kt index e7eed0b..d10a2f5 100644 --- a/src/main/java/com/cumulocity/client/api/RetentionRulesApi.kt +++ b/src/main/java/com/cumulocity/client/api/RetentionRulesApi.kt @@ -71,8 +71,12 @@ interface RetentionRulesApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.retentionrulecollection+json") @GET("/retention/retentions") diff --git a/src/main/java/com/cumulocity/client/api/RolesApi.kt b/src/main/java/com/cumulocity/client/api/RolesApi.kt index 1d15445..932d13d 100644 --- a/src/main/java/com/cumulocity/client/api/RolesApi.kt +++ b/src/main/java/com/cumulocity/client/api/RolesApi.kt @@ -72,8 +72,12 @@ interface RolesApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.rolecollection+json") @GET("/user/roles") diff --git a/src/main/java/com/cumulocity/client/api/SubscriptionsApi.kt b/src/main/java/com/cumulocity/client/api/SubscriptionsApi.kt index b9ffbbd..c70a723 100644 --- a/src/main/java/com/cumulocity/client/api/SubscriptionsApi.kt +++ b/src/main/java/com/cumulocity/client/api/SubscriptionsApi.kt @@ -79,8 +79,12 @@ interface SubscriptionsApi { * **ⓘ Info:** Filtering by `typeFilter` may affect paging. Additional post filtering may be performed if OData-like expressions are used in the subscriptions. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.subscriptioncollection+json") @GET("/notification2/subscriptions") @@ -162,7 +166,7 @@ interface SubscriptionsApi { * @param context * The context to which the subscription is associated. * - * **ⓘ Info:** If the value is `mo`, then `source` must also be provided in the query. + * **ⓘ Info:** If the value is `mo` (managed object), then `source` must also be provided in the query. * @param source * The managed object ID to which the subscription is associated. */ diff --git a/src/main/java/com/cumulocity/client/api/TenantApplicationsApi.kt b/src/main/java/com/cumulocity/client/api/TenantApplicationsApi.kt index 30db423..a92a3a8 100644 --- a/src/main/java/com/cumulocity/client/api/TenantApplicationsApi.kt +++ b/src/main/java/com/cumulocity/client/api/TenantApplicationsApi.kt @@ -74,8 +74,12 @@ interface TenantApplicationsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.applicationreferencecollection+json") @GET("/tenant/tenants/{tenantId}/applications") diff --git a/src/main/java/com/cumulocity/client/api/TenantsApi.kt b/src/main/java/com/cumulocity/client/api/TenantsApi.kt index 3dff371..70249fd 100644 --- a/src/main/java/com/cumulocity/client/api/TenantsApi.kt +++ b/src/main/java/com/cumulocity/client/api/TenantsApi.kt @@ -18,6 +18,7 @@ import okhttp3.OkHttpClient import retrofit2.converter.gson.ReadOnlyProperties import okhttp3.ResponseBody import com.cumulocity.client.model.Tenant +import com.cumulocity.client.model.TenantTfaStrategy import com.cumulocity.client.model.TenantCollection import com.cumulocity.client.model.CurrentTenant import com.cumulocity.client.model.TenantTfaData @@ -36,7 +37,7 @@ import com.cumulocity.client.model.TenantTfaData * > **������ Important:** For support user access, the tenant ID must be used and not the tenant domain. * See [Tenant > Current tenant](#operation/getCurrentTenantResource) for information on how to retrieve the tenant ID and domain of the current tenant via the API. * - * In the UI, the tenant ID is displayed in the user dropdown menu, see [Getting started > User options and settings](https://cumulocity.com/guides/users-guide/getting-started/#user-settings) in the User guide. + * In the UI, the tenant ID is displayed in the user dropdown menu, see [Getting started > Get familiar with the UI > User options and settings](https://cumulocity.com/docs/get-familiar-with-the-ui/user-settings/) in the Cumulocity IoT user documentation. * * ### Access rights and permissions * @@ -46,7 +47,7 @@ import com.cumulocity.client.model.TenantTfaData * * In the RBAC approach, managing access is the most complicated part because a misconfiguration can potentially give customers access to data that they must not see, like other customers' data. The inventory roles allow you to granularly define access for only certain parts of data, but they don't protect you from accidental misconfigurations. A limitation here is that customers won't be able to create their own roles. * - * For more details, see [RBAC versus multi-tenancy approach](https://cumulocity.com/guides/concepts/tenant-hierarchy/#comparison). + * For more details, see [RBAC versus multi-tenancy approach](https://cumulocity.com/docs/concepts/tenant-hierarchy/#comparison-of-various-use-cases). * * > **ⓘ Info:** The Accept header should be provided in all POST/PUT requests, otherwise an empty response body will be returned. */ @@ -95,8 +96,12 @@ interface TenantsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. * @param company * Company name associated with the Cumulocity IoT tenant. * @param domain @@ -288,4 +293,33 @@ interface TenantsApi { fun getTenantTfaSettings( @Path("tenantId") tenantId: String ): Call + + /** + * Sets TFA settings for a specific tenant + * + * Sets the two-factor authentication settings of a specific tenant for a specific tenant ID. + * + * + * ##### Required roles + * + * ((ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_MANAGEMENT_UPDATE) *AND* (the current tenant is its parent *OR* the current user belongs to the tenant))) + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 204 The tenant's TFA configuration was updated. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 404 Tenant not found. + * + * @param body + * @param tenantId + * Unique identifier of a Cumulocity IoT tenant. + */ + @Headers(*["Content-Type:application/json", "Accept:application/json"]) + @PUT("/tenant/tenants/{tenantId}/tfa") + fun updateTenantTfaSettings( + @Body body: TenantTfaStrategy, + @Path("tenantId") tenantId: String + ): Call } diff --git a/src/main/java/com/cumulocity/client/api/TrustedCertificatesApi.kt b/src/main/java/com/cumulocity/client/api/TrustedCertificatesApi.kt index 942ae5c..a00837a 100644 --- a/src/main/java/com/cumulocity/client/api/TrustedCertificatesApi.kt +++ b/src/main/java/com/cumulocity/client/api/TrustedCertificatesApi.kt @@ -24,13 +24,15 @@ import com.cumulocity.client.model.UploadedTrustedCertificate import com.cumulocity.client.model.UploadedTrustedCertificateCollection import com.cumulocity.client.model.TrustedCertificate import com.cumulocity.client.model.UploadedTrustedCertSignedVerificationCode +import com.cumulocity.client.model.UpdateCRLEntries import com.cumulocity.client.model.TrustedCertificateCollection import com.cumulocity.client.model.VerifyCertificateChain +import com.cumulocity.client.model.AccessToken /** * API methods for managing trusted certificates used to establish device connections via MQTT. * - * More detailed information about trusted certificates and their role can be found in [Device management > Managing device data](https://cumulocity.com/guides/users-guide/device-management/#managing-device-data) in the *User guide*. + * More detailed information about trusted certificates and their role can be found in [Device management > Device management application > Managing device data](https://cumulocity.com/docs/device-management-application/managing-device-data/) in the Cumulocity IoT user documentation. * * > **ⓘ Info:** The Accept header must be provided in all POST/PUT requests, otherwise an empty response body will be returned. */ @@ -64,7 +66,7 @@ interface TrustedCertificatesApi { * * ##### Required roles * - * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN) *AND* (is the current tenant) + * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN *OR* ROLE_TENANT_MANAGEMENT_READ) *AND* (is the current tenant) * * ##### Response Codes * @@ -83,8 +85,12 @@ interface TrustedCertificatesApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") @GET("/tenant/tenants/{tenantId}/trusted-certificates") @@ -180,7 +186,7 @@ interface TrustedCertificatesApi { * * ##### Required roles * - * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN) *AND* (is the current tenant *OR* is the management tenant) + * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN *OR* ROLE_TENANT_MANAGEMENT_READ) *AND* (is the current tenant *OR* is the management tenant) * * ##### Response Codes * @@ -361,64 +367,211 @@ interface TrustedCertificatesApi { ): Call /** - * Verify a certificate chain via file upload + * Verify a certificate chain + * + * Verify a device certificate chain against a specific tenant using file upload or by HTTP headers.The tenant ID is `optional` and this api will try to resolve the tenant from the chain if not found in the request header.For file upload, the max chain length support is 10 and for a header it is 5. * - * Verify a device certificate chain against a specific tenant. Max chain length support is 10.The tenant ID is `optional` and this api will be further enhanced to resolve the tenant from the chain in future release. + * If CRL (certificate revocation list) check is enabled on the tenant and the certificate chain is identified to be revoked during validation the further validation of the chain stops and returns unauthorized. * + * > **ⓘ Info:** File upload takes precedence over HTTP headers if both are passed. * * ##### Required roles * - * (ROLE_TENANT_MANAGEMENT_ADMIN) *AND* (is the current tenant *OR* is current management tenant) + * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_MANAGEMENT_READ) *AND* (is the current tenant *OR* is current management tenant) *OR* (is authenticated *AND* is current user service user) * * ##### Response Codes * * The following table gives an overview of the possible response codes and their meanings: * - * * HTTP 200 The request has succeeded and the validation result is sent in the response. + * * HTTP 200 The certificate chain is valid and not revoked. * * HTTP 400 Unable to parse certificate chain. + * * HTTP 401 One or more certificates in the chain are revoked or the certificate chain is not valid. Revoked certificates are checked first, then the validity of the certificate chain. * * HTTP 403 Not enough permissions/roles to perform this operation. * * HTTP 404 The tenant ID does not exist. * * @param tenantId * @param file * File to be uploaded. + * @param xCumulocityClientCertChain + * Used to send a certificate chain in the header. Separate the chain with `,` and also each 64 bit block with ` ` (a space character). */ @Headers(*["Content-Type:multipart/form-data", "Accept:application/vnd.com.nsn.cumulocity.error+json, application/json"]) - @POST("/tenant/tenants/verify-cert-chain/fileUpload") + @POST("/tenant/trusted-certificates/verify-cert-chain") @Multipart - fun validateChainByFileUpload( + fun validateChain( @Part("tenantId") tenantId: String, - @Part("file") file: UByteArray + @Part("file") file: UByteArray, + @Header("X-Cumulocity-Client-Cert-Chain") xCumulocityClientCertChain: String ): Call /** - * Verify a certificate chain via HTTP header + * Get revoked certificates * - * Verify a device certificate chain against a specific tenant. Max chain length support is 6.The tenant ID is `optional` and this api will be further enhanced to resolve the tenant from the chain in future release. + * This endpoint downloads current CRL file containing list of revoked certificate ina binary file format with `content-type` as `application/pkix-crl`. * * * ##### Required roles * - * (ROLE_TENANT_MANAGEMENT_ADMIN) *AND* (is the current tenant *OR* is current management tenant) + * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN *OR* ROLE_TENANT_MANAGEMENT_READ) * * ##### Response Codes * * The following table gives an overview of the possible response codes and their meanings: * - * * HTTP 200 The request has succeeded and the validation result is sent in the response. - * * HTTP 400 Unable to parse certificate chain. + * * HTTP 200 The CRL file of the current tenant. + */ + @Headers("Accept:application/pkix-crl") + @GET("/tenant/trusted-certificates/settings/crl") + fun downloadCrl( + ): Call + + /** + * Add revoked certificates + * + * > **ⓘ Info:** A certificate revocation list (CRL) is a list of digital certificatesthat have been revoked by the issuing certificate authority (CA) before expiration date.In Cumulocity IoT, a CRL check can be in online or offline mode or both. + * An endpoint to add revoked certificate serial numbers for offline CRL check via payload or file. + * + * For payload, a JSON object required with list of CRL entries, for example: + * + * ```json + * { + * "crls": [ + * { + * "serialNumberInHex": "1000", + * "revocationDate": "2023-01-11T16:12:36.288Z" + * } + * ] + * } + * ``` + * Each entry is composed of: + * + * * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g As (1000)^16 == (4096)^10, So we have to enter 1000.If duplicate serial number exists in payload, the existing entry stays
+ * * `revocationDate` - accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`, for example: `2023-01-11T16:12:36.288Z`.This is an optional parameter and defaults to the current server UTC date time if not specified in the payload.If specified and the date is in future then those entries will be also defaulted to current date. + * + * For file upload, each file can hold at maximum 5000 revocation entries.Multiple upload is allowed.In case of duplicates, the latest (last uploaded) entry is considered. + * + * See below for a sample CSV file: + * + * | SERIAL NO. | REVOCATION DATE ||--|--|| 1000 | 2023-01-11T16:12:36.288Z | + * + * Each entry is composed of : + * + * * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g (1000)^16 == (4096)^10, So we have to enter 1000.If duplicate serial number exists in payload, the latest entry will be taken.
+ * * revocationDate: Accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` e.g: 2023-01-11T16:12:36.288Z.This is an optional and will be default to current server UTC date time if not specified in payload.If specified and the date is in future then those entries will be skipped. + * + * The CRL setting for offline and online check can be enabled/disabled using /tenant/options.Keys are `crl.online.check.enabled` and `crl.offline.check.enabled` under the category `configuration`. + * + * + * ##### Required roles + * + * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN) *AND* is the current tenant + * + * **������ Important:** According to CRL policy, added serial numbers cannot be reversed. + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 204 CRLs updated successfully. + * * HTTP 400 Unsupported date time format. + * * HTTP 401 Authentication information is missing or invalid. * * HTTP 403 Not enough permissions/roles to perform this operation. - * * HTTP 404 The tenant ID does not exist. * - * @param xCumulocityTenantId - * Used to send a tenant ID. - * @param xCumulocityClientCertChain - * Used to send a certificate chain in the header. Separate the chain with `,` and also each 64 bit block with ` ` (a space character). + * @param body + */ + @Headers(*["Content-Type:application/json", "Accept:application/json"]) + @PUT("/tenant/trusted-certificates/settings/crl") + fun updateCRL( + @Body body: UpdateCRLEntries + ): Call + + /** + * Add revoked certificates + * + * > **ⓘ Info:** A certificate revocation list (CRL) is a list of digital certificatesthat have been revoked by the issuing certificate authority (CA) before expiration date.In Cumulocity IoT, a CRL check can be in online or offline mode or both. + * An endpoint to add revoked certificate serial numbers for offline CRL check via payload or file. + * + * For payload, a JSON object required with list of CRL entries, for example: + * + * ```json + * { + * "crls": [ + * { + * "serialNumberInHex": "1000", + * "revocationDate": "2023-01-11T16:12:36.288Z" + * } + * ] + * } + * ``` + * Each entry is composed of: + * + * * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g As (1000)^16 == (4096)^10, So we have to enter 1000.If duplicate serial number exists in payload, the existing entry stays
+ * * `revocationDate` - accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'`, for example: `2023-01-11T16:12:36.288Z`.This is an optional parameter and defaults to the current server UTC date time if not specified in the payload.If specified and the date is in future then those entries will be also defaulted to current date. + * + * For file upload, each file can hold at maximum 5000 revocation entries.Multiple upload is allowed.In case of duplicates, the latest (last uploaded) entry is considered. + * + * See below for a sample CSV file: + * + * | SERIAL NO. | REVOCATION DATE ||--|--|| 1000 | 2023-01-11T16:12:36.288Z | + * + * Each entry is composed of : + * + * * serialNumberInHex: Needs to be in `Hexadecimal Value`. e.g (1000)^16 == (4096)^10, So we have to enter 1000.If duplicate serial number exists in payload, the latest entry will be taken.
+ * * revocationDate: Accepted Date format: `yyyy-MM-dd'T'HH:mm:ss.SSS'Z'` e.g: 2023-01-11T16:12:36.288Z.This is an optional and will be default to current server UTC date time if not specified in payload.If specified and the date is in future then those entries will be skipped. + * + * The CRL setting for offline and online check can be enabled/disabled using /tenant/options.Keys are `crl.online.check.enabled` and `crl.offline.check.enabled` under the category `configuration`. + * + * + * ##### Required roles + * + * (ROLE_TENANT_MANAGEMENT_ADMIN *OR* ROLE_TENANT_ADMIN) *AND* is the current tenant + * + * **������ Important:** According to CRL policy, added serial numbers cannot be reversed. + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 204 CRLs updated successfully. + * * HTTP 400 Unsupported date time format. + * * HTTP 401 Authentication information is missing or invalid. + * * HTTP 403 Not enough permissions/roles to perform this operation. + * + * @param file + * File to be uploaded. + */ + @Headers(*["Content-Type:multipart/form-data", "Accept:application/json"]) + @PUT("/tenant/trusted-certificates/settings/crl") + @Multipart + fun updateCRL( + @Part("file") file: UByteArray + ): Call + + /** + * Obtain device access token + * + * Only those devices which are registered to use cert auth can authenticate via mTLS protocol and retrieve JWT token. Device access token API works only on port 8443 via mutual TLS (mTLS) connection.Immediate issuer of client certificate must present in Platform's truststore, if not then whole certificate chain needs to send in header and root or any intermediate certificate must be present in the Platform's truststore.We must have the following: + * + * * private_key + * * client certificate + * * whole certificate chain (Optional - This API requires the client to send a custom header `X-SSL-CERT-CHAIN` only if the immediate issuer of the client's certificate is not uploaded as a trusted certificate on the platform. If the immediate issuer is already uploaded and trusted, the header can be omitted) + * + * ##### Response Codes + * + * The following table gives an overview of the possible response codes and their meanings: + * + * * HTTP 200 Successfully retrieved device access token from device certificate. + * * HTTP 400 Unable to parse certificate chain. + * * HTTP 401 One or more certificates in the chain are revoked or the certificate chain is not valid. Revoked certificates are checked first, then the validity of the certificate chain. + * * HTTP 404 Device access token feature is disabled. + * * HTTP 422 The verification was not successful. + * + * @param xSslCertChain + * Used to send a certificate chain in the header. Separate the chain with ` ` (a space character) and also each 64 bit block with ` ` (a space character). */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/json") - @POST("/tenant/tenants/verify-cert-chain") - fun validateChainByHeader( - @Header("X-Cumulocity-TenantId") xCumulocityTenantId: String? = null, - @Header("X-Cumulocity-Client-Cert-Chain") xCumulocityClientCertChain: String - ): Call + @POST("/devicecontrol/deviceAccessToken") + fun obtainAccessToken( + @Header("X-Ssl-Cert-Chain") xSslCertChain: String? = null + ): Call } diff --git a/src/main/java/com/cumulocity/client/api/UsageStatisticsApi.kt b/src/main/java/com/cumulocity/client/api/UsageStatisticsApi.kt index 09cab07..de5561e 100644 --- a/src/main/java/com/cumulocity/client/api/UsageStatisticsApi.kt +++ b/src/main/java/com/cumulocity/client/api/UsageStatisticsApi.kt @@ -154,8 +154,12 @@ interface UsageStatisticsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.tenantusagestatisticscollection+json") @GET("/tenant/statistics") @@ -261,6 +265,8 @@ interface UsageStatisticsApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.tenantStatisticsfilecollection+json") @GET("/tenant/statistics/files") diff --git a/src/main/java/com/cumulocity/client/api/UsersApi.kt b/src/main/java/com/cumulocity/client/api/UsersApi.kt index 6c15709..6e23b6a 100644 --- a/src/main/java/com/cumulocity/client/api/UsersApi.kt +++ b/src/main/java/com/cumulocity/client/api/UsersApi.kt @@ -20,7 +20,6 @@ import retrofit2.converter.gson.ReadOnlyProperties import okhttp3.ResponseBody import com.cumulocity.client.supplementary.SeparatedQueryParameter import com.cumulocity.client.model.User -import com.cumulocity.client.model.PasswordChange import com.cumulocity.client.model.SubscribedUser import com.cumulocity.client.model.UserCollection import com.cumulocity.client.model.UserTfaData @@ -92,8 +91,12 @@ interface UsersApi { * If set to `true`, then each of returned user will contain an additional field ���subusersCount���.It is the number of direct subusers (users with corresponding ���owner���). * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. * @param withTotalPages * When set to `true`, the returned result will contain in the statistics object the total number of pages. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalPages` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.usercollection+json") @GET("/user/{tenantId}/users") @@ -184,6 +187,8 @@ interface UsersApi { * * When the user is updated with changed permissions or groups, a corresponding audit record is created with type "User" and activity "User updated". * + * Note that you cannot update the password or email of another user, they can only be updated for the current user. + * * * ##### Required roles * @@ -247,44 +252,6 @@ interface UsersApi { @Path("userId") userId: String ): Call - /** - * Update a specific user's password of a specific tenant - * - * Update a specific user's password (by a given user ID) of a specific tenant (by a given tenant ID). - * - * Changing the user's password creates a corresponding audit record of type "User" and activity "User updated", and specifying that the password has been changed. - * - * > **������ Important:** If the tenant uses OAI-Secure authentication, the target user will be logged out. - * - * ##### Required roles - * - * ROLE_USER_MANAGEMENT_ADMIN to update root users in a user hierarchy *OR* users that are not in any hierarchy - * ROLE_USER_MANAGEMENT_ADMIN to update non-root users in a user hierarchy *AND* whose parents have access to assigned roles, groups, device permissions and applications - * ROLE_USER_MANAGEMENT_CREATE to update descendants of the current user in a user hierarchy *AND* whose parents have access to assigned roles, groups, device permissions and applications - * - * ##### Response Codes - * - * The following table gives an overview of the possible response codes and their meanings: - * - * * HTTP 200 A user was updated. - * * HTTP 401 Authentication information is missing or invalid. - * * HTTP 403 Not enough permissions/roles to perform this operation. - * * HTTP 422 Unprocessable Entity ��� invalid payload. - * - * @param body - * @param tenantId - * Unique identifier of a Cumulocity IoT tenant. - * @param userId - * Unique identifier of the a user. - */ - @Headers(*["Content-Type:application/json", "Accept:application/json"]) - @PUT("/user/{tenantId}/users/{userId}/password") - fun updateUserPassword( - @Body body: PasswordChange, - @Path("tenantId") tenantId: String, - @Path("userId") userId: String - ): Call - /** * Retrieve the TFA settings of a specific user * @@ -376,6 +343,8 @@ interface UsersApi { * Indicates how many entries of the collection shall be returned. The upper limit for one page is 2,000 objects. * @param withTotalElements * When set to `true`, the returned result will contain in the statistics object the total number of elements. Only applicable on [range queries](https://en.wikipedia.org/wiki/Range_query_(database)). + * + * **ⓘ Info:** To improve performance, the `totalElements` statistics are cached for 10 seconds. */ @Headers("Accept:application/vnd.com.nsn.cumulocity.error+json, application/vnd.com.nsn.cumulocity.userreferencecollection+json") @GET("/user/{tenantId}/groups/{groupId}/users") diff --git a/src/main/java/com/cumulocity/client/model/Alarm.kt b/src/main/java/com/cumulocity/client/model/Alarm.kt index 6a1848a..566a5e4 100644 --- a/src/main/java/com/cumulocity/client/model/Alarm.kt +++ b/src/main/java/com/cumulocity/client/model/Alarm.kt @@ -88,7 +88,7 @@ class Alarm { /** * It is possible to add an arbitrary number of additional properties as a list of key-value pairs, for example, `"property1": {}`, `"property2": "value"`. These properties are known as custom fragments and can be of any type, for example, object or string. Each custom fragment is identified by a unique name. * - * Review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) as there are characters that can not be used when naming custom fragments. + * Review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation as there are characters that can not be used when naming custom fragments. */ var customFragments: MutableMap = hashMapOf() diff --git a/src/main/java/com/cumulocity/client/model/ApplicationVersionTag.kt b/src/main/java/com/cumulocity/client/model/ApplicationVersionTag.kt index 1c87939..a93c34d 100644 --- a/src/main/java/com/cumulocity/client/model/ApplicationVersionTag.kt +++ b/src/main/java/com/cumulocity/client/model/ApplicationVersionTag.kt @@ -4,8 +4,8 @@ package com.cumulocity.client.model import com.google.gson.Gson -data class ApplicationVersionTag(var tag: Array?) { - constructor() : this(tag = null) +data class ApplicationVersionTag(var tags: Array?) { + constructor() : this(tags = null) override fun toString(): String { return Gson().toJson(this).toString() diff --git a/src/main/java/com/cumulocity/client/model/AuthConfig.kt b/src/main/java/com/cumulocity/client/model/AuthConfig.kt index d2e802d..3b64ea0 100644 --- a/src/main/java/com/cumulocity/client/model/AuthConfig.kt +++ b/src/main/java/com/cumulocity/client/model/AuthConfig.kt @@ -66,7 +66,7 @@ data class AuthConfig(var providerName: String?, var type: Type?) { var onNewUser: OnNewUser? = null /** - * SSO specific. URL used for redirecting to the Cumulocity IoT platform. + * SSO specific. URL used for redirecting to the Cumulocity IoT platform. Do not set or leave it empty to allow SSO flow to be controlled by client (UI) applications. */ var redirectToPlatform: String? = null @@ -78,7 +78,7 @@ data class AuthConfig(var providerName: String?, var type: Type?) { var self: String? = null /** - * The session configuration properties are only available for OAuth internal. See [Changing settings > OAuth internal](https://cumulocity.com/guides/users-guide/administration/#oauth-internal) for more details. + * The session configuration properties are only available for OAI-Secure. See [Platform administration > Authentication > Basic settings > OAI Secure session configuration ](https://cumulocity.com/docs/authentication/basic-settings/#oai-secure-session-configuration) in the Cumulocity IoT user documentation. */ var sessionConfiguration: OAuthSessionConfiguration? = null @@ -94,6 +94,11 @@ data class AuthConfig(var providerName: String?, var type: Type?) { var tokenRequest: RequestRepresentation? = null + /** + * If set to `true`, user data and the userId are retrieved using the claims from the id_token; otherwise, they are based on the access_token. + */ + var useIdToken: Boolean? = null + /** * SSO specific. Points to the field in the obtained JWT access token that should be used as the username in the Cumulocity IoT platform. */ @@ -222,6 +227,11 @@ data class AuthConfig(var providerName: String?, var type: Type?) { */ var manageRolesOnlyFromAccessMapping: Boolean? = null + /** + * If set to `true`, dynamic access mapping is performed using the claims from the id_token; otherwise, it is based on the access_token. + */ + var mapFromIdToken: Boolean? = null + override fun toString(): String { return Gson().toJson(this).toString() } diff --git a/src/main/java/com/cumulocity/client/model/C8yLatestMeasurements.kt b/src/main/java/com/cumulocity/client/model/C8yLatestMeasurements.kt index 3172aa1..9ee195a 100644 --- a/src/main/java/com/cumulocity/client/model/C8yLatestMeasurements.kt +++ b/src/main/java/com/cumulocity/client/model/C8yLatestMeasurements.kt @@ -7,7 +7,7 @@ import com.google.gson.Gson /** * The read only fragment which contains the latest measurements reported by the device.The returned optionally only if the query parameter `withLatestValues=true` is used. * - * > **⚠️ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. + * > **������ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. */ class C8yLatestMeasurements { diff --git a/src/main/java/com/cumulocity/client/model/Event.kt b/src/main/java/com/cumulocity/client/model/Event.kt index d4a26d6..34c3c8d 100644 --- a/src/main/java/com/cumulocity/client/model/Event.kt +++ b/src/main/java/com/cumulocity/client/model/Event.kt @@ -67,7 +67,7 @@ class Event { /** * It is possible to add an arbitrary number of additional properties as a list of key-value pairs, for example, `"property1": {}`, `"property2": "value"`. These properties are known as custom fragments and can be of any type, for example, object or string. Each custom fragment is identified by a unique name. * - * Review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) as there are characters that can not be used when naming custom fragments. + * Review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation as there are characters that can not be used when naming custom fragments. */ var customFragments: MutableMap = hashMapOf() diff --git a/src/main/java/com/cumulocity/client/model/FeatureToggle.kt b/src/main/java/com/cumulocity/client/model/FeatureToggle.kt new file mode 100644 index 0000000..eff5bfc --- /dev/null +++ b/src/main/java/com/cumulocity/client/model/FeatureToggle.kt @@ -0,0 +1,59 @@ +// Copyright (c) 2014-2023 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. +// Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG. + +package com.cumulocity.client.model +import com.google.gson.Gson +import com.google.gson.annotations.SerializedName + +class FeatureToggle { + + /** + * A unique key of the feature toggle. + */ + var key: String? = null + + /** + * Current phase of feature toggle rollout. + */ + var phase: Phase? = null + + /** + * Current value of the feature toggle marking whether the feature is active or not. + */ + var active: Boolean? = null + + /** + * The source of the feature toggle value - either it's feature toggle definition provided default, or per tenant provided override. + */ + var strategy: Strategy? = null + + /** + * Current phase of feature toggle rollout. + */ + enum class Phase(val value: String) { + @SerializedName(value = "IN_DEVELOPMENT") + INDEVELOPMENT("IN_DEVELOPMENT"), + @SerializedName(value = "PRIVATE_PREVIEW") + PRIVATEPREVIEW("PRIVATE_PREVIEW"), + @SerializedName(value = "PUBLIC_PREVIEW") + PUBLICPREVIEW("PUBLIC_PREVIEW"), + @SerializedName(value = "GENERALLY_AVAILABLE") + GENERALLYAVAILABLE("GENERALLY_AVAILABLE") + } + + /** + * The source of the feature toggle value - either it's feature toggle definition provided default, or per tenant provided override. + */ + enum class Strategy(val value: String) { + @SerializedName(value = "DEFAULT") + DEFAULT("DEFAULT"), + @SerializedName(value = "TENANT") + TENANT("TENANT") + } + + + + override fun toString(): String { + return Gson().toJson(this).toString() + } +} diff --git a/src/main/java/com/cumulocity/client/model/FeatureToggleValue.kt b/src/main/java/com/cumulocity/client/model/FeatureToggleValue.kt new file mode 100644 index 0000000..a963b3c --- /dev/null +++ b/src/main/java/com/cumulocity/client/model/FeatureToggleValue.kt @@ -0,0 +1,17 @@ +// Copyright (c) 2014-2023 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. +// Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG. + +package com.cumulocity.client.model +import com.google.gson.Gson + +class FeatureToggleValue { + + /** + * Current value of the feature toggle marking whether the feature is active or not. + */ + var active: Boolean? = null + + override fun toString(): String { + return Gson().toJson(this).toString() + } +} diff --git a/src/main/java/com/cumulocity/client/model/LatestMeasurementFragment.kt b/src/main/java/com/cumulocity/client/model/LatestMeasurementFragment.kt index 6e61cd5..0049edd 100644 --- a/src/main/java/com/cumulocity/client/model/LatestMeasurementFragment.kt +++ b/src/main/java/com/cumulocity/client/model/LatestMeasurementFragment.kt @@ -7,7 +7,7 @@ import com.google.gson.Gson /** * The read only fragment which contains the latest measurements series reported by the device. * - * > **⚠️ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. + * > **������ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. */ class LatestMeasurementFragment { diff --git a/src/main/java/com/cumulocity/client/model/LatestMeasurementValue.kt b/src/main/java/com/cumulocity/client/model/LatestMeasurementValue.kt index ef73954..328f053 100644 --- a/src/main/java/com/cumulocity/client/model/LatestMeasurementValue.kt +++ b/src/main/java/com/cumulocity/client/model/LatestMeasurementValue.kt @@ -7,7 +7,7 @@ import com.google.gson.Gson /** * The read only fragment which contains the latest measurements series values reported by the device. * - * > **⚠️ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. + * > **������ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. */ data class LatestMeasurementValue(var value: Number?) { constructor() : this(value = null) diff --git a/src/main/java/com/cumulocity/client/model/LoginForm.kt b/src/main/java/com/cumulocity/client/model/LoginForm.kt index 5ce2e52..fc61b8a 100644 --- a/src/main/java/com/cumulocity/client/model/LoginForm.kt +++ b/src/main/java/com/cumulocity/client/model/LoginForm.kt @@ -19,18 +19,18 @@ class LoginForm { var grantType: GrantType? = null /** - * Used in cases of basic or OAI-Secure authentication. + * Used in case of OAI-Secure authentication. */ var password: String? = null /** - * Current TFA code, sent by the user, if a TFA code is required to log in. + * Current TFA code, sent by the user, if a TFA code is required to log in. Used in case of OAI-Secure authentication. */ @SerializedName(value = "tfa_code") var tfaCode: String? = null /** - * Used in cases of basic or OAI-Secure authentication. + * Used in case of OAI-Secure authentication. */ var username: String? = null diff --git a/src/main/java/com/cumulocity/client/model/LoginOption.kt b/src/main/java/com/cumulocity/client/model/LoginOption.kt index a7cd272..44c590d 100644 --- a/src/main/java/com/cumulocity/client/model/LoginOption.kt +++ b/src/main/java/com/cumulocity/client/model/LoginOption.kt @@ -51,7 +51,7 @@ class LoginOption { var self: String? = null /** - * The session configuration properties are only available for OAuth internal. See [Changing settings > OAuth internal](https://cumulocity.com/guides/users-guide/administration/#oauth-internal) for more details. + * The session configuration properties are only available for OAI-Secure. See [Platform administration > Authentication > Basic settings > OAI Secure session configuration ](https://cumulocity.com/docs/authentication/basic-settings/#oai-secure-session-configuration) in the Cumulocity IoT user documentation. */ var sessionConfiguration: OAuthSessionConfiguration? = null diff --git a/src/main/java/com/cumulocity/client/model/ManagedObject.kt b/src/main/java/com/cumulocity/client/model/ManagedObject.kt index 7494444..da8c923 100644 --- a/src/main/java/com/cumulocity/client/model/ManagedObject.kt +++ b/src/main/java/com/cumulocity/client/model/ManagedObject.kt @@ -96,6 +96,14 @@ class ManagedObject { @SerializedName(value = "c8y_IsDevice") var c8yIsDevice: C8yIsDevice? = null + /** + * The read only fragment which contains the latest measurements reported by the device.The returned optionally only if the query parameter `withLatestValues=true` is used. + * + * > **������ Feature Preview:** The feature is part of the Latest Measurement feature which is still under public feature preview. + */ + @SerializedName(value = "c8y_LatestMeasurements") + var c8yLatestMeasurements: C8yLatestMeasurements? = null + /** * A fragment which identifies this managed object as a device group. */ @@ -117,7 +125,7 @@ class ManagedObject { /** * It is possible to add an arbitrary number of additional properties as a list of key-value pairs, for example, `"property1": {}`, `"property2": "value"`. These properties are known as custom fragments and can be of any type, for example, object or string. Each custom fragment is identified by a unique name. * - * Review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) as there are characters that can not be used when naming custom fragments. + * Review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation as there are characters that can not be used when naming custom fragments. */ var customFragments: MutableMap = hashMapOf() @@ -186,6 +194,7 @@ class ManagedObject { src?.assetParents?.let { it -> jsonTree.add("assetParents", context?.serialize(it)) } src?.deviceParents?.let { it -> jsonTree.add("deviceParents", context?.serialize(it)) } src?.c8yIsDevice?.let { it -> jsonTree.add("c8y_IsDevice", context?.serialize(it)) } + src?.c8yLatestMeasurements?.let { it -> jsonTree.add("c8y_LatestMeasurements", context?.serialize(it)) } src?.c8yIsDeviceGroup?.let { it -> jsonTree.add("c8y_IsDeviceGroup", context?.serialize(it)) } src?.c8yDeviceTypes?.let { it -> jsonTree.add("c8y_DeviceTypes", context?.serialize(it)) } src?.c8ySupportedOperations?.let { it -> jsonTree.add("c8y_SupportedOperations", context?.serialize(it)) } diff --git a/src/main/java/com/cumulocity/client/model/Measurement.kt b/src/main/java/com/cumulocity/client/model/Measurement.kt index ff670b6..7c7ce27 100644 --- a/src/main/java/com/cumulocity/client/model/Measurement.kt +++ b/src/main/java/com/cumulocity/client/model/Measurement.kt @@ -45,7 +45,7 @@ data class Measurement(var source: Source?, var time: String?, var type: String? /** * It is possible to add an arbitrary number of additional properties as a list of key-value pairs, for example, `"property1": {}`, `"property2": "value"`. These properties are known as custom fragments and can be of any type, for example, object or string. Each custom fragment is identified by a unique name. * - * Review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) as there are characters that can not be used when naming custom fragments. + * Review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation as there are characters that can not be used when naming custom fragments. */ var customFragments: MutableMap = hashMapOf() diff --git a/src/main/java/com/cumulocity/client/model/NotificationSubscription.kt b/src/main/java/com/cumulocity/client/model/NotificationSubscription.kt index 6e0f599..5520c98 100644 --- a/src/main/java/com/cumulocity/client/model/NotificationSubscription.kt +++ b/src/main/java/com/cumulocity/client/model/NotificationSubscription.kt @@ -41,7 +41,7 @@ data class NotificationSubscription(var context: Context?, var subscription: Str /** * The context within which the subscription is to be processed. * - * > **ⓘ Info:** If the value is `mo`, then `source` must also be provided in the request body. + * > **ⓘ Info:** If the value is `mo` (managed object), then `source` must also be provided in the request body. */ enum class Context(val value: String) { @SerializedName(value = "mo") @@ -82,8 +82,7 @@ data class NotificationSubscription(var context: Context?, var subscription: Str class SubscriptionFilter { /** - * For the `mo` (Managed object) context, notifications from the `alarms`, `alarmsWithChildren`, `events`, `eventsWithChildren`, `managedobjects` (Inventory), `measurements` and `operations` (Device control) APIs can be subscribed to. - * The `alarmsWithChildren` and `eventsWithChildren` APIs subscribe to alarms and events respectively from the managed object identified by the `source.id` field, and all of its descendant managed objects. + * For the `mo` (managed object) context, notifications from the `alarms`, `alarmsWithChildren`, `events`, `eventsWithChildren`, `managedobjects` (Inventory), `measurements` and `operations` (Device control) APIs can be subscribed to.The `alarmsWithChildren` and `eventsWithChildren` APIs subscribe to alarms and events respectively from the managed object identified by the `source.id` field, and all of its descendant managed objects. * * For the `tenant` context, notifications from the `alarms`, `events` and `managedobjects` (Inventory) APIs can be subscribed to. * diff --git a/src/main/java/com/cumulocity/client/model/OAuthSessionConfiguration.kt b/src/main/java/com/cumulocity/client/model/OAuthSessionConfiguration.kt index 729ba29..6a1c33c 100644 --- a/src/main/java/com/cumulocity/client/model/OAuthSessionConfiguration.kt +++ b/src/main/java/com/cumulocity/client/model/OAuthSessionConfiguration.kt @@ -5,7 +5,7 @@ package com.cumulocity.client.model import com.google.gson.Gson /** - * The session configuration properties are only available for OAuth internal. See [Changing settings > OAuth internal](https://cumulocity.com/guides/users-guide/administration/#oauth-internal) for more details. + * The session configuration properties are only available for OAI-Secure. See [Platform administration > Authentication > Basic settings > OAI Secure session configuration ](https://cumulocity.com/docs/authentication/basic-settings/#oai-secure-session-configuration) in the Cumulocity IoT user documentation. */ class OAuthSessionConfiguration { diff --git a/src/main/java/com/cumulocity/client/model/Operation.kt b/src/main/java/com/cumulocity/client/model/Operation.kt index 4b66d8d..10eee4c 100644 --- a/src/main/java/com/cumulocity/client/model/Operation.kt +++ b/src/main/java/com/cumulocity/client/model/Operation.kt @@ -65,7 +65,7 @@ class Operation { /** * It is possible to add an arbitrary number of additional properties as a list of key-value pairs, for example, `"property1": {}`, `"property2": "value"`. These properties are known as custom fragments and can be of any type, for example, object or string. Each custom fragment is identified by a unique name. * - * Review the [Naming conventions of fragments](https://cumulocity.com/guides/concepts/domain-model/#naming-conventions-of-fragments) as there are characters that can not be used when naming custom fragments. + * Review [Getting started > Technical concepts > Cumulocity IoT's domain model > Inventory > Fragments > Naming conventions of fragments](https://cumulocity.com/docs/concepts/domain-model/#naming-conventions-of-fragments) in the Cumulocity IoT user documentation as there are characters that can not be used when naming custom fragments. */ var customFragments: MutableMap = hashMapOf() diff --git a/src/main/java/com/cumulocity/client/model/TenantFeatureToggleValue.kt b/src/main/java/com/cumulocity/client/model/TenantFeatureToggleValue.kt new file mode 100644 index 0000000..1b8d218 --- /dev/null +++ b/src/main/java/com/cumulocity/client/model/TenantFeatureToggleValue.kt @@ -0,0 +1,22 @@ +// Copyright (c) 2014-2023 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. +// Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG. + +package com.cumulocity.client.model +import com.google.gson.Gson + +class TenantFeatureToggleValue { + + /** + * Identifier of a tenant this feature toggle value is for. + */ + var tenantId: String? = null + + /** + * Current value of the feature toggle marking whether the feature is active or not. + */ + var active: Boolean? = null + + override fun toString(): String { + return Gson().toJson(this).toString() + } +} diff --git a/src/main/java/com/cumulocity/client/model/TenantTfaStrategy.kt b/src/main/java/com/cumulocity/client/model/TenantTfaStrategy.kt new file mode 100644 index 0000000..58ddc10 --- /dev/null +++ b/src/main/java/com/cumulocity/client/model/TenantTfaStrategy.kt @@ -0,0 +1,25 @@ +// Copyright (c) 2014-2023 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. +// Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG. + +package com.cumulocity.client.model +import com.google.gson.Gson +import com.google.gson.annotations.SerializedName + +data class TenantTfaStrategy(var strategy: Strategy?) { + constructor() : this(strategy = null) + + /** + * Two-factor authentication strategy. + */ + enum class Strategy(val value: String) { + @SerializedName(value = "SMS") + SMS("SMS"), + @SerializedName(value = "TOTP") + TOTP("TOTP") + } + + + override fun toString(): String { + return Gson().toJson(this).toString() + } +} diff --git a/src/test/java/com/cumulocity/client/api/FeatureTogglesApiTest.kt b/src/test/java/com/cumulocity/client/api/FeatureTogglesApiTest.kt new file mode 100644 index 0000000..5a8514e --- /dev/null +++ b/src/test/java/com/cumulocity/client/api/FeatureTogglesApiTest.kt @@ -0,0 +1,62 @@ +// Copyright (c) 2014-2023 Software AG, Darmstadt, Germany and/or Software AG USA Inc., Reston, VA, USA, and/or its subsidiaries and/or its affiliates and/or their licensors. +// Use, reproduction, transfer, publication or disclosure is prohibited except as specifically provided for in your License Agreement with Software AG. + +package com.cumulocity.client.api +import okhttp3.Credentials +import okhttp3.Interceptor +import okhttp3.OkHttpClient +import okhttp3.Request +import okhttp3.Headers +import org.junit.Assert +import org.junit.Test +import retrofit2.Call +import retrofit2.Callback +import retrofit2.Response +import java.util.concurrent.CountDownLatch +import okhttp3.ResponseBody +import com.cumulocity.client.model.FeatureToggleValue +import com.cumulocity.client.model.FeatureToggle +import com.cumulocity.client.model.TenantFeatureToggleValue + +// TODO parameterise servers +class FeatureTogglesApiTest { + + private var clientBuilder: OkHttpClient.Builder = OkHttpClient.Builder() + + init { + val authToken = Credentials.basic("userName", "password") + val headerAuthorizationInterceptor = Interceptor { chain -> + var request: Request = chain.request() + val headers: Headers = request.headers().newBuilder().add("Authorization", authToken).build() + request = request.newBuilder().headers(headers).build() + chain.proceed(request) + } + this.clientBuilder.addInterceptor(headerAuthorizationInterceptor) + } + + @Test + fun testFactoryCreatesObject() { + val api = FeatureTogglesApi.Factory.create("your tenant") + Assert.assertNotNull(api) + } + + @Test + fun testListCurrentTenantFeatures() { + val latch = CountDownLatch(1) + val api = FeatureTogglesApi.Factory.create("tenant", this.clientBuilder) + api.listCurrentTenantFeatures().enqueue(object : Callback> { + + override fun onResponse(call: Call>?, response: Response>?) { + println(response?.message()) + println(response?.body()) + latch.countDown() + } + + override fun onFailure(call: Call>?, t: Throwable?) { + println(t) + latch.countDown() + } + }) + latch.await() + } +} diff --git a/src/test/java/com/cumulocity/client/api/MeasurementsApiTest.kt b/src/test/java/com/cumulocity/client/api/MeasurementsApiTest.kt index b5da8fc..6b420dc 100644 --- a/src/test/java/com/cumulocity/client/api/MeasurementsApiTest.kt +++ b/src/test/java/com/cumulocity/client/api/MeasurementsApiTest.kt @@ -14,7 +14,6 @@ import retrofit2.Callback import retrofit2.Response import java.util.concurrent.CountDownLatch import okhttp3.ResponseBody -import com.cumulocity.client.supplementary.SeparatedQueryParameter import com.cumulocity.client.model.Measurement import com.cumulocity.client.model.MeasurementCollection import com.cumulocity.client.model.MeasurementSeries diff --git a/src/test/java/com/cumulocity/client/api/TenantsApiTest.kt b/src/test/java/com/cumulocity/client/api/TenantsApiTest.kt index 0fefe44..6d66586 100644 --- a/src/test/java/com/cumulocity/client/api/TenantsApiTest.kt +++ b/src/test/java/com/cumulocity/client/api/TenantsApiTest.kt @@ -15,6 +15,7 @@ import retrofit2.Response import java.util.concurrent.CountDownLatch import okhttp3.ResponseBody import com.cumulocity.client.model.Tenant +import com.cumulocity.client.model.TenantTfaStrategy import com.cumulocity.client.model.TenantCollection import com.cumulocity.client.model.CurrentTenant import com.cumulocity.client.model.TenantTfaData diff --git a/src/test/java/com/cumulocity/client/api/TrustedCertificatesApiTest.kt b/src/test/java/com/cumulocity/client/api/TrustedCertificatesApiTest.kt index eef2179..3fef68e 100644 --- a/src/test/java/com/cumulocity/client/api/TrustedCertificatesApiTest.kt +++ b/src/test/java/com/cumulocity/client/api/TrustedCertificatesApiTest.kt @@ -18,8 +18,10 @@ import com.cumulocity.client.model.UploadedTrustedCertificate import com.cumulocity.client.model.UploadedTrustedCertificateCollection import com.cumulocity.client.model.TrustedCertificate import com.cumulocity.client.model.UploadedTrustedCertSignedVerificationCode +import com.cumulocity.client.model.UpdateCRLEntries import com.cumulocity.client.model.TrustedCertificateCollection import com.cumulocity.client.model.VerifyCertificateChain +import com.cumulocity.client.model.AccessToken // TODO parameterise servers class TrustedCertificatesApiTest { @@ -43,4 +45,23 @@ class TrustedCertificatesApiTest { Assert.assertNotNull(api) } + @Test + fun testDownloadCrl() { + val latch = CountDownLatch(1) + val api = TrustedCertificatesApi.Factory.create("tenant", this.clientBuilder) + api.downloadCrl().enqueue(object : Callback { + + override fun onResponse(call: Call?, response: Response?) { + println(response?.message()) + println(response?.body()) + latch.countDown() + } + + override fun onFailure(call: Call?, t: Throwable?) { + println(t) + latch.countDown() + } + }) + latch.await() + } } diff --git a/src/test/java/com/cumulocity/client/api/UsersApiTest.kt b/src/test/java/com/cumulocity/client/api/UsersApiTest.kt index 8bbe913..2455cd3 100644 --- a/src/test/java/com/cumulocity/client/api/UsersApiTest.kt +++ b/src/test/java/com/cumulocity/client/api/UsersApiTest.kt @@ -16,7 +16,6 @@ import java.util.concurrent.CountDownLatch import okhttp3.ResponseBody import com.cumulocity.client.supplementary.SeparatedQueryParameter import com.cumulocity.client.model.User -import com.cumulocity.client.model.PasswordChange import com.cumulocity.client.model.SubscribedUser import com.cumulocity.client.model.UserCollection import com.cumulocity.client.model.UserTfaData