# 20.10.0 (Chicago) Release Notes for Cloud

# New Features

# [59264] - Device API v2 - C2D Message Time To Live (TTL) set to 60 days

# New Functionality

Ability Platform guarantees 60 days of time to live cloud-to-device messages on Service Bus.

# [61803] - Tenant capacity per instance has been increased

# New Functionality

A Policy limit of 1000 per B2C instance, a maximum of 995 Tenants can be on-boarded assuming each Tenant has one Solution.

# Required Migrations

This change has impact to end users under two different areas,

Adapting to Login UI flow - The Login URL needs to be constructed using the Tenant Name only and does not require the Solution Namespace. Admin Portal and other client applications will need to adapt to this change,

Old Authorize URL for tenant=ABB-Abilityand solution_namespace=abb.ability

 https://{{B2CTenantName}}.b2clogin.com/{{B2CTenantName}}.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1A_abb.ability_ABB-Ability_RP&client_id={{client_id}}&nonce=defaultNonce&redirect_uri={{redirect_uri}}&scope=openid&response_type=code&prompt=login

New Authorize URL

https://{{B2CTenantName}}.b2clogin.com/{{B2CTenantName}}.onmicrosoft.com/oauth2/v2.0/authorize?p=B2C_1A_abb.ability_RP&client_id={{client_id}}&nonce=defaultNonce&redirect_uri={{redirect_uri}}&scope=openid&response_type=code&prompt=login

Change in User Token generation RP policy name - User token generation process needs to be updated to use new RP policy name

Old user token URL:

https://{tenantAddress}.b2clogin.com/{b2CName}/B2C_1A_{solutionNamespace}_{tenantName}_RP/oauth2/v2.0/token

New user token URL:

https://{tenantAddress}.b2clogin.com/{b2CName}/B2C_1A_{tenantName}_RP/oauth2/v2.0/token

# [62325] - Pagination & Search/filtering mechanism are provided with the Principal Manager API

# New Functionality

Currently, when querying for Users , Devices, Applications and Tenants, all results are fetched at once which can cause performance issues in case of large data sets. Pagination has been introduced. This means, for Users , Devices, Applications and Tenants clients of Principal manager can perform the following action:

Fetch the data in specified portions (e.g. give 'n' results)
by continuation token can fetch next portion of data
Fetch the data in specified range (give results from 300-600);
Sort the results by specific field (e.g. by Tenant, Identity etc. ascending/descending)
Get total number of available results so as to display possible pages
Filter results by mentioning characters and using starts with, ends with and has specifiers

# [64685] - Application Identity is added to Platform Audit Logs for AuthZ event types

# New Functionality

Applications that are calling Principle Manager APIs now log the application identity as part of the audit logs.

# [65855] - Data Processing Pipeline extensible types variable validation updates

# New Functionality

Validation procedure for type definition validation for telemetry data was updated. The new procedure is the following (updated parts in bold):

It is currently only executed for variable and timeSeries message type (other types are valid by default here)
To obtain type definition the following TDR API endpoint is called:
```
https://{tdr}/v1/modelDefintions/{model}/types/{typeId}/versions/{version}
```
- when TDR response indicates non-existing type definition, validation fails
- when TDR indicates extensible type, additional variables are collected with an InfoModel extensions endpoint: https://{im}/api/v1.0/objects/{objectId}/models/{model}/extension.
When variable does not exist in type definition nor in type extensions, validation fails
When variable exists in either type definition or type extensions, we execute set of validation rules depending on the type of variable:
- string variable: types must match, value length must fall within minLength and maxLength, if TDR type definition contains regEx pattern for variable, its value must match this pattern
- boolean variable: types must match
- numeric variable: types must match, value must fall within min and max constraints, if TDR type definition indicates an enum type, value must match an enum definition

# [66870] - Global level Platform APIs protect by Akamai WAF

# New Functionality

Global level Platform APIs are now protected by Akamai WAF (Web Application Framework) instead of Microsoft WAF.

# [69228] - Cosmos DB autoscaling has been implemented for the Region Plane

# New Functionality

Azure Cosmos Databases used by Principal Manager automatically adjust RUs allocation to respond to dynamic load. Maximum allowed RUs value is configurable per environment in environment file, this change improves costs and performance using dynamic scaling as needed by the applications.

# [69328] - Data consistency of Object Model enforced - existing outgoing references following type definition minor updates

# New Functionality

Reference data consistency is required for allowing type structures changes upon ObjectModel update planned in the future.

# Required Migrations

Breaking Change

Information Model API for GET /objects/{objectId}/models/{modelId}/extension/{version} is removed entirely. This action now always returns only the latest extension which is not versioned.

# [71878] - Deprecation of Proof of Concept Principle Manager Portal

# New Functionality

PoC version of Administrator Portal is removed from Platform deployment. It is replaced with new version of Administrator Portal which addresses security issues and bring new functionalities.

# Deprecated Functionality

The PoC Principle Manager Portal is deprecated in the Chicago release, and is replaced by the Ability Platform Admin Portal.

# [74507] - Cosmos DB autoscale - Instance Plane

# New Functionality

Azure Cosmos Databases used by IM, TDR, and DA automatically adjust RUs allocation to respond to dynamic load. Maximum allowed RUs value is configurable per environment in environment file. This change improves costs and performance using dynamic scaling as needed by the applications.

# Resolved Issues

# [64099] - Empty string as file input results in 500 error

Invoking a method that expects a file as an input, passing in an empty string for the file results in a 500 error being returned from the API. Normally, the error should be 400 with a proper description.

# [73176] - Data Processing Pipeline validation - telemetry data is rejected, when values are out of range

Telemetry data of variable type, when a corresponding type definition indicates value range (min/max for numeric variables or minLength/maxLength for string variables), validation process does not reject a telemetry message with an out of range value and the telemetry change is available through Ability Platform Data Access APIs.

# [76435] - Edge module name cannot contain '-' character - identity-create returns bad request

A fix has been applied to the child device identity validation to accept "-" character

# [76857] - Incomplete/discrepancy in data retrieval for DA for select filter

Timeouts to the redis service occurred in the Tel Cache function, which prevented data from being inserted. After review with Microsoft it was determined thread starvation was the root cause. Thread workers have been set to 64 and completion port threads to 32. These are configurable and can be set via "MinWorkerThreads" and "MinCompletionPortThreads" in app settings.

# [77508] - POST /references/out regression

The functionality of creating references with base type covariance, which was working in earlier versions, was not available in this version. This missing functionality was enabled again - user is able to create references with full reference covariance support.

# [78226] - DSL query cannot include `$` character

The user was not able to query the object model with fluent DSL when using *$*in the query. This limitation is now fixed and *$*can be included in DSL queries.

# Known Issues and Limitations

# [84304] - Max limit of properties in TSI

Max limit of properties (columns) in TSI v1 is equal to 600 on S1 and 800 on S2 SKU.

# [81401] - Ingress limit limitation

On TSI v1 S1 Ingress limit is equal to 720 events per minute. On TSI v1 S2 Ingress limit is equal to 7200 events per minute.

# [81547] - Downloading files requires a filter change adding 'dt' to the filter string

An optimizations for filter parsing in all Data Access components was added, this improved system stability and reliability, and introduced following change in the API format due to a library update:

Before this change Data Access allowed filters format supported the following "timestamp > '2019-01-01T00:00:00Z'". After - It is required that all filter format include the following format change: "timestamp > dt'2019-01-01T00:00:00Z'".

Affected endpoints:

POST request for variables data: /api/v1/data/variables
POST request for events data: /api/v1/data/events
POST request for alarms data: /api/v1/data/alarms
object storage search for files: /api/v1/storage/object/files/search
global storage search for files: /api/v1/storage/global/files/search
create subscription for variables: /api/v1/subscriptions/variables
create subscription for events: /api/v1/subscriptions/events
create subscription for alarms: /api/v1/subscriptions/alarms

# [73963] - Latency issue causes newly created app in principal manager to be created without secrets

Known Issue: Occasionally a newly created application in the principal manager service will be created without secrets causing the app to become unusable because a bearer token cannot be obtained.

Workaround: Try creating the application once again after about 60 secs.

# [77948] - Data Process Pipeline may store additional duplicate values

Known Issue: The data processing pipeline may generate additional values for hot path, warm path, and cold path storage. The values can be recognized by an identical timestamp. This behavior may have existed in prior versions, but is more likely seen in the current version with the enhancements in the processing pipeline (new validation and data quality decoration functionality, revamped hosting. infrastructure).

Workaround: The user applications must ensure that they apply a filter prior to processing the data in the application. There is no workaround when aggregates are processed. For example, if aggregates count, sum or avg are used the duplicate values will be included in the results.

# [76861] - Querying for multiple objectIds in a filter and condition result in the same filter

When querying for multiple objectIds in a filter, the combination of the filter, the resulting Ability condition header from Authz results in a large filter, and calls to the shared kernel library to optimize result in the same filter.

Example:

A filter:

"variable = 'myVariable' AND (objectId = '123' OR objectId = '434' OR ... 200+ objectIds)

result condition from AuthZ:

((model = 'Abb.Ability.Device' and (objectId = '123' OR objectId = '456' OR ...)) OR (model = 'Abb.Ability.Config' and (objectId = '434' OR objectId = '424')... repeat for remaining Ids)

Combining the above example filter with the example header is a much bigger filter. Calls to shared kernel to optimize still results in the same large filter. The filter is then difficult / not possible to

Be broken up into small filters for use in service bus filters, which have a limit of 1024 characters
Be sent to TSI as there is a limit of 32KB requests

# [58452] - Device Registration Function (DPS) fails to respond to device requests when 15 Edges are starting simultaneously

Known Issue: Any attempts to register more than 8-10 devices parallelly will result in device registration failures

Workaround: Limit the parallelism to a maximum of 10 devices to overcome this issue

# [77522] - AuditLog events Count Mismatch for Device Created, Updated and Deleted operations

The body of platform events is stored in Audit Logging storage. However, in some cases this body contains a JSON object which exceeds Azure Table Storage column limitations.

In this case, when a platform event body is longer than 16k of characters, Audit Logging saves the following warning information into the "data" column: {"auditLogInformation": "Event body too long"}.

The original body of the event is not saved, however the user can still navigate to actual changes by using the event correlationId.

Limitations source:

size of an entity in table storage up to 1MB (https://docs.microsoft.com/en-us/azure/cosmos-db/table-storage-design-guide#capacity-considerations)
size of single string column up to 64 Kb (which equals to 32k characters, https://docs.microsoft.com/en-us/rest/api/storageservices/understanding-the-table-service-data-model#property-types)

# [69975] - Few devices are missing while searching devices for tenants

Known Issue: In the Principal Manager APIs, we currently return a maximum of 1000 results due to performance considerations. Due to this limitation when the number of objects under a resource exceeds 1000, the request client will not see all the objects in the database.

Workaround: The only option currently available to the user is to apply filters and parameters in the request, to narrow down to the number of returned results to be less than 1000 items.

# [73453] - A Solution it is currently not able to register more than 40K devices.

There is no workaround to this except to create a duplicate solution to add additional devices beyond 40K devices.

Limitation in caused by a maximum 2MB document size in CosmosDb.

# [73073] - Bad Request on variable subscription for long request not including objectIDs

Known Issue: When creating a subscription with a user token, filters that do not contain an objectId may result in an error preventing the subscription from being created of which the http response code may be 4xx. This is due to a limitation of a service bus filter only allowing for up to 1024 characters. This is usually hit due to a large ability-condition header being unable to be broken down into small enough filters for service bus.

Workaround: To workaround, include an objectId in the filter property for the Data Access request. Up to 40 objectids can be included in the filter.

Background tokens do not have tenancy therefore the authorization service does not optimize the ability-condition based on the given objectId in the filter.

# [76007] - DSL query escape sequence handling for backward slash ("`\`") in property value filter is not consistent

Known Issue: When using the backslashes ("\") in the object model properties and then trying to query them using DSL, the user cannot obtain it by a single escape character ("\\"), which is expected behavior.

Workaround: The workaround is to use double escaping in DSL query ("\\").

For example, having property:

{
    "browseName": {
        "value": "some\\path"
    }
}

one needs to use the DSL:

models(...).hasProperty("browseName", "some\\\\\\\\path")

# [75339] - Sorting functionality which has been implemented as part of Pagination & Searching feature in Principal Manager APIs, is case sensitive

Sorting functionality which has been implemented as part of Pagination & Searching feature in Principal Manager APIs, is case sensitive.

For example: when trying to sort a set of tenants, {ABB01, Robotics01, abb02, Volvo01, robotics02, volvo02} the result which will be returned when sorting ascending is {ABB01, Robotics01, Volvo01, abb02, robotics02, volvo02}

# [75168] - Instance API return - error code 502 Bad Gateway

Known Issue: Occasionally when calling any API endpoint on Instance stamp 502 Bad Gateway error can be returned.

Workaround: Contact the Ability Operations team, indicate that a 502 bad gateway error has been received, reference this release note an indicate that the AuthZ and principle manager should be restarted.

# [62908] - Principle Manager API fails to remove tenants - BadGateway

The problem can occur based on concurrent requests to the principal manager API. The Principal Manager APIs are using Azure B2C services to create Applications for business entities, e.g. Application, Solution, etc. The workflow in the PM is sequential and dependent on the result of the B2C operation. After a successful result from the B2C operation, the request is further processed to provide the respective response to the caller. For any B2C related request, some buffer time needs to be provided so that the action can be completed.

It is advised to maintain a gap of 60 secs between two requests.

# [59246] - Requests for bearer token for new apps lead to Bad Request

Known Issue: When concurrent requests to get a bearer token are sent, a client can receive a Bad Request response.

Workaround: The recommendation from Microsoft is that we should wait for a few seconds before trying to get the token for the application that has been created. According to Microsoft, it takes a maximum of 60 seconds to replicate the Application Settings across Azure regions.

# [55864] - Solution create audit log shows wrong event for audit log

The audit log for create solution shown is incorrect as an update instead of create.

# [77345] - When creating a solution or resource, principle manager service sporadically returns a 400 Bad Gateway response code

Known Issue: When creating a solution (or possibly another resource), Microsoft Graph API sporadically returns a 400 Bad Gateway response code with the message, "One or more of your reply urls is not valid". As a result the Solution is not created.

Workaround: The end user will need to resubmit the request

# [68309] - Unable to search for a file using user token after upload

Know Issue: When searching for files uploaded via Edge, requests using a user token are failing when the number of objects exceeds 500.

Workaround: When querying, the objectid, along with the path, can be passed in QEL format to overcome this limitation.

# [74065] - User cannot access applications when his "read" permission is limited to "user" delegation

Known Issue: When querying for applications using the "Query apps" endpoint, passing 'user' instead of 'User' for the delegation parameter returns empty results. Similarly, when using the get Apps endpoint, passing 'User' instead of 'user' for the delegation parameter returns empty results

Workaround: When querying for applications using the "Query apps" or "Get apps' endpoint, limited to user delegation, pass (delegation='user' OR delegation='User') for delegation parameter to get the expected results

← 20.10.1 & 20.10.2

# 20.10.0 (Chicago) Release Notes for Cloud

# New Features

# [59264] - Device API v2 - C2D Message Time To Live (TTL) set to 60 days

# New Functionality

# [61803] - Tenant capacity per instance has been increased

# New Functionality

# Required Migrations

# [62325] - Pagination & Search/filtering mechanism are provided with the Principal Manager API

# New Functionality

# [64685] - Application Identity is added to Platform Audit Logs for AuthZ event types

# New Functionality

# [65855] - Data Processing Pipeline extensible types variable validation updates

# New Functionality

# [66870] - Global level Platform APIs protect by Akamai WAF

# New Functionality

# [69228] - Cosmos DB autoscaling has been implemented for the Region Plane

# New Functionality

# [69328] - Data consistency of Object Model enforced - existing outgoing references following type definition minor updates

# New Functionality

# Required Migrations

# [71878] - Deprecation of Proof of Concept Principle Manager Portal

# New Functionality

# Deprecated Functionality

# [74507] - Cosmos DB autoscale - Instance Plane

# New Functionality

# Resolved Issues

# [64099] - Empty string as file input results in 500 error

# [73176] - Data Processing Pipeline validation - telemetry data is rejected, when values are out of range

# [76435] - Edge module name cannot contain '-' character - identity-create returns bad request

# [76857] - Incomplete/discrepancy in data retrieval for DA for select filter

# [77508] - POST /references/out regression

# [78226] - DSL query cannot include $ character

# Known Issues and Limitations

# [84304] - Max limit of properties in TSI

# [81401] - Ingress limit limitation

# [81547] - Downloading files requires a filter change adding 'dt' to the filter string

# [73963] - Latency issue causes newly created app in principal manager to be created without secrets

# [77948] - Data Process Pipeline may store additional duplicate values

# [76861] - Querying for multiple objectIds in a filter and condition result in the same filter

# [58452] - Device Registration Function (DPS) fails to respond to device requests when 15 Edges are starting simultaneously

# [77522] - AuditLog events Count Mismatch for Device Created, Updated and Deleted operations

# [69975] - Few devices are missing while searching devices for tenants

# [73453] - A Solution it is currently not able to register more than 40K devices.

# [73073] - Bad Request on variable subscription for long request not including objectIDs

# [76007] - DSL query escape sequence handling for backward slash ("\") in property value filter is not consistent

# [75339] - Sorting functionality which has been implemented as part of Pagination & Searching feature in Principal Manager APIs, is case sensitive

# [75168] - Instance API return - error code 502 Bad Gateway

# [62908] - Principle Manager API fails to remove tenants - BadGateway

# [59246] - Requests for bearer token for new apps lead to Bad Request

# [55864] - Solution create audit log shows wrong event for audit log

# [77345] - When creating a solution or resource, principle manager service sporadically returns a 400 Bad Gateway response code

# [68309] - Unable to search for a file using user token after upload

# [74065] - User cannot access applications when his "read" permission is limited to "user" delegation

# [78226] - DSL query cannot include `$` character

# [76007] - DSL query escape sequence handling for backward slash ("`\`") in property value filter is not consistent