Technology And Deployment

Teneo Manager

Teneo 7.3 brings an entirely new Teneo Manager User Interface (UI) based on React. Being the centralized source for authentication, permissions and configurations for the Teneo Platform, focus has been on updating Teneo Manager to keep the technology up-to-date and secure, including removing a number of vulnerabilities related to the previous usage of dependencies such as PrimeFaces and JSP, while providing the frontend with a more modern look and feel.

Most functionalities and the usability should be recognizable for users of the previous Teneo Manager versions, while some improvements have found their way into Manager 7.3 and the user will now, for example, find the options to view and run the hourly and daily maintenance tasks for Studio clients directly on the Clients section.

On the Users and Groups pages, the information about accessible accounts is now displayed similar to the information related to access roles in Log Data Sources. This means that each account is displayed on a line in the table specifying the permissions granted directly to the user and through membership of group(s), where the dark grey check marks indicate the direct user permissions and the lighter grey check marks indicate the indirect permissions obtained through a group membership. Note that informative tooltips are available on hover over.

At creation and editing of settings such as users, groups, or LDS, input field validation is performed to ensure that required fields have values and if this isn't the case, the Create / Update button is disabled until all required fields have values. Should errors be detected upon creation or editing of settings, informative messages are displayed below the field.

Note that in Chrome and Firefox it is possible to navigate from one field to the next by pressing Tab; to allow for tab navigation in Safari the user must enable Press Tab to highlight each item on a webpage for Safari in Settings > Advanced.

Studio Client

The Studio Clients (found under oAuth2 in the left-side menu) come with the following updates to the settings:

• A new Studio URL field is available for clients when selecting Studio as client type; existing oAuth2 clients must be updated with the new field
• The CORS origin setting previously allowed for an empty value, but as of Teneo 7.3 this is changed and an empty value is no longer accepted. This is done to enforce adding a value; note that the default value is still "allow all origins" visualized as an asterisk in Teneo Manager.

Audit Logs

When a user with an administrator role logs in or gets an access token with the token endpoint, all the actions are now logged as admin in the audit logs. The same is the case for the built-in admin user. A user without the administrator role is still logged as user.

Old password hash no longer supported

In Teneo 7.3 the support for decoding old password hashes in Teneo Manager generated before Teneo 4.1 is removed.

This affects user password hashes stored in the Teneo Manager database and settings.xml file (for the built-in admin user). Generating the old hash format was dropped with Teneo 4.1, but there could still be old hashes stored in existing Teneo Manager instances created before Teneo 4.1. So, by removing support for the old hash format, those users/built-in admin won't be able to log in anymore. Though, the probability is very low because the password hash stored in the database is recalculated with the new format after each successful user login. So, only users that haven't logged in or reset their password since the old hash format was dropped will be affected. Those users will need to reset their password or regenerate the password hash stored in the settings.xml file (built-in admin user).

Teneo Studio Properties File

This section covers updates and improvements related to the Teneo Studio properties file; note that improvements are also available for the Teneo Engine Logs which are described here.

Optimization Timeout

A configurable timeout is now supported for Optimization queries and the Teneo Studio properties file therefore contain the new property inquire.optimizationTimeout

.

If the optimizationTimeout

is not set, please note that the optimization queries default to use the inquire.defaultTimeout

:

defaultTimeout value	optimizationTimeout value	TqlQueryRequest timeout	OptimizationQueryRequest timeout
not set	not set	system default (1200 s / 20 m)	system default (1200 s / 20 m)
2400	not set	defaultTimeout value: 2400	defaultTimeout value: 2400
2400	3600	defaultTimeout value: 2400	optimizationTimeout value: 3600
not set	3600	system default (1200 s / 20 m)	optimizationTimeout value: 3600

CLU

Based on the CLU implementation, the following new properties are added to the properties file:

• microsoft.azure.clu.apiVersion=2022-05-01
• microsoft.azure.clu.resourceUrlTemplate=https://{resourceName}.cognitiveservices.azure.com

The first one defines the API version to be used when interacting with the CLU service, it is exposed to be easy configurable, but it should not be updated without thorough testing. The second one is the template string for the resource URL. This should only be changed if wanting to test Studio with a proxy CLU server. The resource name will be injected into the URL (after validation). Users will not be able to set the entire URL of their resource directly for security reasons.

Due to the new Teneo Manager frontend, the following change is performed:

• The property monitor.warning.duration
  has been removed from teneo-studio.properties

APIs

Versioning

7.3 introduces versioning to the REST API endpoints in preparation for friction-free upgrades in future releases if breaking changes need to be introduced in the API.

Use of the version-specific API should be considered for any business critical systems which must continue to function across Teneo Platform releases.
It is recommended to continue to use the "latest" API endpoints (i.e., without specified version) where the system is not business critical in order to simplify mainentance load.

From next Teneo Release (after 7.3):

• Teneo will continue to support version-agnostic API at /rest/(endpoint)
  • Recommended where there is no business impact if the connected system does not function continuously across Teneo upgrades
• Teneo will support API version X (i.e., the current / latest API version)
  • e.g., if API version for current Teneo release is 3: .../(component)/rest/v3/
• Teneo will support API version X-1 (X minus one, where X is the current API version)
  • e.g., if API version for current Teneo release is 3: .../(component)/rest/v2/
  • This support will continue for 1 Platform version.

For Teneo 7.3, the groundwork has been put into place to support this in future upgrades, meaning that in 7.3:

• Teneo continues supporting version-agnostic API at /rest/endpoint)
• Teneo supports API version 1 (i.e., the current / latest API version)
  • e.g., .../(component)/rest/v1/

To prepare a business critical system to support friction-free upgrades after 7.3 - imagine the roadmap:

Platform version	API version	Versioned path
Teneo 7.3	1	/rest/v1
Teneo X	2	/rest/v2
Teneo Y	3	/rest/v3

• After upgrade to Teneo 7.3
  • Modify system endpoints to connect explicitly to version 1 of the API
    • /(component)/rest/(endpoint)
      to /(component)/rest/vx/(endpoint)
      • e.g., https://myteneo/studio/rest/auth/login
      • becomes https://myteneo/studio/rest/v1/auth/login
  • Test the updated system and roll out before next Teneo upgrade.
• After upgrade to Teneo X
  • Version 1 will still be available until next release
  • Modify system endpoints to connect explicitly to version 2 of the API
    • /(component)/rest/v1(endpoint)
      to /(component)/rest/v2/(endpoint)
  • Test the updated system and roll out before next Teneo upgrade
• After upgrade to Teneo Y
  • Version 1 is no longer available
  • Version 2 is available until next release
  • Connect explicitly to version 3 of the API, test and roll out before next Teneo upgrade.

Teneo Manager API

Teneo 7.3 brings several new endpoints to the Teneo Manager API within various contexts: please note the change of the endpoint PUT/admin/settings

(used to save settings and restart) to PUT/admin/settings/apply-and-restart

; also see below table for further changes.

In Teneo 7.3, error handling is implemented with a new error response format:

• 400, 401, 500, 503 responses are added to all endpoints standardizing error messages in case of error.

Also see section Manager Client Error Info further below.

Note that the default value of a returned endpoint is changed in the sense that endpoints which previously returned plain string are now converted and returned as JSON.

Endpoint Changes

Context	Status	Old Endpoint	New Endpoint	Comment
admin	Modified	PUT/admin/settings	PUT/admin/settings/apply-and-restart
	New		POST/admin/settings/delegated/idp-metadata/convert-to-settings	Converts IdP metadata XML file into settings
	New		GET/admin/settings/delegated/sp-metadata/export	Export delegated SP metadata XML
	New		POST/admin/settings/ldap/test-connection	Test LDAP connection
	New		POST/admin/settings/validate	Validate a list of settings
	New		GET/admin/statistics	Gets statistic data
	New		POST/admin/task/begin	Triggers task according task type passed in post params
	New		GET/admin/task/result	Retrieve last execution results for a given task
auth			POST/auth/login	Logs in a user and returns an access token
			POST/auth/logout	Logs out a user invalidating the access token
common			GET/common/groups/indirect-users/{groupId}
	New		GET/common/groups/lds-access-roles/{groupId}
	New		GET/common/groups/studio-account-permissions/{groupId}
			GET/common/groups/users/{groupId}
			PUT/common/groups/users/{groupId}
	New		GET/common/ldss/user-access-roles-overview/{ldsId}
	New		GET/common/ldss/{ldsId}/user-access-roles/{userId}
	New		POST/common/log-archives/import/begin/{logArchiveId}
	New		POST/common/log-archives/import/cancel/{logArchiveId}
	New		GET/common/log-archives/import/errors/{logArchiveId}
	New		DELETE/common/log-archives/import/errors/{logArchiveId}
	New		GET/common/log-archives/import/errors/{logArchiveId}/{sessionId}
	New		GET/common/log-archives/import/status/{logArchiveId}
	New		GET/common/log-archives/overview/{logArchiveId}
	New		GET/common/users/lds-access-roles-overview/{userId}
	New		GET/common/users/lds-access-roles/{userId}
	New		GET/common/users/studio-account-permissions-overview/{userId}
	New		GET/common/users/studio-account-permissions/{userId}
documentation	New		GET/documentation/url
oauth2	Modified	GET/oauth2/access-token-info	GET/oauth2/token-info
	New		GET/oauth2/api-tokens
	New		POST/oauth2/api-tokens	Creates an API token
	New		GET/oauth2/api-tokens/{apiTokenId}
	New		PUT/oauth2/api-tokens/{apiTokenId}
	New		DELETE/oauth2/api-tokens/{apiTokenId}
	New		POST/oauth2/clients/studio/admin/maintenance/daily/begin/{clientId}	Only admin tokens are allowed to call this endpoint
	New		GET/oauth2/clients/studio/admin/maintenance/daily/status/{clientId}	Only admin tokens are allowed to call this endpoint; returns a model with status information
	New		POST/oauth2/clients/studio/admin/maintenance/hourly/begin/{clientId}	Only admin tokens are allowed to call this endpoint
	New		GET/oauth2/clients/studio/admin/maintenance/hourly/status/{clientId}	Only admin tokens are allowed to call this endpoint; returns a model with status information
	New		GET/oauth2/clients/types
	New		GET/oauth2/refresh-tokens	Returns list of refresh tokens
	New		GET/oauth2/tokens/types
studio	New		GET/studio/accounts/user-account-permissions-overview/{accountId}
	New		GET/studio/accounts/settings/{accountId}
	New		PUT/studio/accounts/settings/{accountId}

Breaking Changes in Models

• Modified: GET/common/ldss/{ldsId}/group-access-roles
  default response was modified
  roles attribute was removed
• Modified: GET/common/ldss/{ldsId}/group-access-roles/{groupId}
  default response was modified
  roles attribute was removed
• Modified: GET/common/ldss/{ldsId}/user-access-roles
  default response was modified
  roles attribute was removed
• Modified: GET/common/users/lds-access-roles/{userId}
  ldsId path parameter was removed
  default response was modified
  roles attribute was removed
• Modified: GET/oauth2/access-tokens
  default response was modified
  expiresAtDate, apiToken attributes were removed
• Modified: GET/studio/accounts/{accountId}/group-permissions
  default response was modified
  permissions attribute was removed
• Modified: GET/studio/accounts/{accountId}/group-permissions/{groupId}
  default response was modified
  permissions attribute was removed
• Modified: GET/studio/accounts/{accountId}/user-permissions
  default response was modified
  permissions attribute was removed
• Modified: GET/studio/accounts/{accountId}/user-permissions/{userId}
  default response was modified
  permissions attribute was removed
• Modified: POST/common/ldss/{ldsId}/group-access-roles/{groupId}
  body was modified
  roles attribute was removed
  default response was modified
  roles attribute was removed
• Modified: POST/common/ldss/{ldsId}/user-access-roles/{userId}
  body was modified
  roles attribute was removed
  default response was modified
  roles attribute was removed
• Modified: POST/oauth2/token
  400 response was modified
  error_description attribute was changed by description
  error attribute was modified
  503 response was modified
  error_description attribute was changed by description
  error attribute was modified
• Modified: POST/studio/accounts/{accountId}/group-permissions/{groupId}
  body was modified
  permissions attribute was removed
  default response was modified
  permissions attribute was removed
• Modified: POST/studio/accounts/{accountId}/user-permissions/{userId}
  body was modified
  permissions attribute was removed
  default response was modified
  permissions attribute was removed
• Modified: PUT/common/ldss/{ldsId}/group-access-roles/{groupId}
  body was modified
  roles attribute was removed
  default response was modified
  roles attribute was removed
• Modified: PUT/common/ldss/{ldsId}/user-access-roles/{userId}
  body was modified
  roles attribute was removed
  default response was modified
  roles attribute was removed
• Modified: PUT/studio/accounts/{accountId}/group-permissions/{groupId}
  body was modified
  permissions attribute was removed
  default response was modified
  permissions attribute was removed
• Modified: PUT/studio/accounts/{accountId}/user-permissions/{userId}
  body was modified
  permissions attribute was removed
  default response was modified
  permissions attribute was removed

Changes in Models

• Modified: DELETE/common/log-archives/{logArchiveId}
  force query parameter was added
• Modified: GET/admin/settings
  default response was modified
  description attribute was added
• Modified: GET/common/groups
  default response was modified
  ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: GET/common/groups/{groupId}
  default response was modified
  ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: GET/common/user-info
  default response was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: GET/common/users
  default response was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: GET/common/users/{userId}
  default response was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: GET/inquire/settings
  default response was modified
  description attribute was added
• Modified: GET/oauth2/access-tokens
  default response was modified
  userId, expiresAt, uiToken attributes were added
• Modified: GET/oauth2/clients
  default response was modified
  studioUrl attribute was added
• Modified: GET/oauth2/clients/{clientId}
  default response was modified
  studioUrl attribute was added
• Modified: GET/studio/accounts/{accountId}/users
  default response was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: GET/studio/settings
  default response was modified
  description attribute was added
• Modified: POST/common/groups
  body was modified
  ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
  default response was modified
  ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: POST/common/users
  body was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
  default response was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: POST/oauth2/clients
  body was modified
  studioUrl attribute was added
  default response was modified
  studioUrl attribute was added
• Modified: PUT/common/groups/{groupId}
  body was modified
  ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
  default response was modified
  ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: PUT/common/users/{userId}
  body was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
  default response was modified
  delegatedLogin, indirectGroupIds, ldapBaseDN, ldapDN, ldapWhenChanged attributes were added
• Modified: PUT/oauth2/clients/{clientId}
  body was modified
  studioUrl attribute was added
  default response was modified
  studioUrl attribute was added
• Modified: GET/oauth2/access-tokens
  default response was modified
  userId, expiresAt, uiToken attributes were added
• Modified: GET/studio/accounts/{accountId}/group-permissions
  default response was modified
  modifyAccountSettings attribute was added
• Modified: GET/studio/accounts/{accountId}/group-permissions/{groupId}
  default response was modified
  modifyAccountSettings attribute was added
• Modified: GET/studio/accounts/{accountId}/user-permissions
  default response was modified
  modifyAccountSettings attribute was added
• Modified: GET/studio/accounts/{accountId}/user-permissions/{userId}
  default response was modified
  modifyAccountSettings attribute was added
• Modified: POST/studio/accounts/{accountId}/group-permissions/{groupId}
  body was modified
  modifyAccountSettings attribute was added
  default response was modified
  modifyAccountSettings attribute was added
• Modified: POST/studio/accounts/{accountId}/user-permissions/{userId}
  body was modified
  modifyAccountSettings attribute was added
  default response was modified
  modifyAccountSettings attribute was added
• Modified: PUT/studio/accounts/{accountId}/group-permissions/{groupId}
  body was modified
  modifyAccountSettings attribute was added
  default response was modified
  modifyAccountSettings attribute was added
• Modified: PUT/studio/accounts/{accountId}/user-permissions/{userId}
  body was modified
  modifyAccountSettings attribute was added
  default response was modified
  modifyAccountSettings attribute was added

Teneo Studio API

Context	Status	Old Endpoint	New Endpoint	Comment
admin	New		POST/admin/maintenance/daily/begin	Can only be called using admin tokens
	New		GET/admin/maintenance/daily/status	Returns a model with status information; can only be called using admin tokens
	New		POST/admin/maintenance/hourly/begin	Can only be called using admin tokens
	New		GET/admin/maintenance/hourly/status	Returns a model with status information; can only be called using admin tokens
clu	New		POST/clu/models/remove/begin/{solutionId}/{modelId}	Removes a CLU model
	New		POST/clu/models/train/begin/{solutionId}	Starts a CLU model training for the specified solution
	New		GET/clu/models/{solutionId}	Returns the CLU models of the solution
customer	New		GET/customer/settings/clu/{accountId}
	New		PUT/customers/settings/clu/{accountId}
intent-models	New		GET/intent-models/assignment/{solutionId}	Gets the intent model assignment
	New		PUT/intent-models/assignment/{solutionId}]	Updates the model assignment
	New		GET/intent-models/assignment/{solutionId}/{version}	Gets the specified version of the model assignment
	New		POST/intent-models/evaluations/begin/{solutionId}	Starts a Test Data Evaluation?
	New		GET/intent-models/evaluations/{solutionId}	Gets the results of the Test Data Evaluations?
	New		GET/intent-models/evaluations/{solutionId}/{evaluationId}	Gets the result of the specified Test Data Evaluation
optimization	New		POST/optimization/query/begin/{solutionId}/{logDataSourceId}
	New		GET/optimization/query/result/{taskId}
	New		POST/optimization/reviewed-inputs/{solutionId}/{logDataSourceId}

Updates to API Models

Due to the implementation work of the Test Data Evaluation, new and more generic error codes are introduced and the below listed error codes are updated. Note that the error codes were exposed in previous models of the public API although they were not returned by any endpoint!

Old error code	New error code
INVALID_CV_REQUEST_EMTPY	INVALID_EVALUATION_NO_TRAINING_DATA
INVALID_CV_REQUEST_INSUFFICIENT_EXAMPLES	INVALID_EVALUATION_INSUFFICIENT_TRAINING_EXAMPLES
INVALID_CV_REQUEST_MULTIPLE_RUNS	removed
INVALID_CV_REQUEST_SINGLE_CLASS	INVALID_EVALUATION_SINGLE_CLASS
new	INVALID_EVALUATION_NO_TEST_DATA

A few other changes are also made affecting models in the public API: the following enums in the model Engine ActionType have been renamed; note that they are not used in the REST API, but in events in the WebSocket's API.

Old enum	New enum
TRAINING_STARTED	MODEL_UPDATE_STARTED
TRAINING_FAILED	MODEL_UPDATE_FAILED
TRAINING_COMPLETED	MODEL_UPDATE_COMPLETED

Breaking Changes in Models

• Modified: GET/publish-environments/{solutionId}
  default response was modified
  saveHistory attribute was removed
• Modified: GET/publish-environments/{solutionId}/{environmentId}
  default response was modified
  saveHistory attribute was removed
• Modified: POST/publish-environments/pre-configured/{solutionId}/{type}
  default response was modified
  saveHistory attribute was removed
• Modified: POST/publish-environments/{solutionId}
  body was modified
  saveHistory attribute was removed
  default response was modified
  saveHistory attribute was removed
• Modified: PUT/publish-environments/{solutionId}/{environmentId}
  body was modified
  saveHistory attribute was removed
  default response was modified
  saveHistory attribute was removed

More Changes in Models

• Modified: GET/classes/{solutionId}
  default response was modified
  testData attribute was added
• Modified: GET/classes/{solutionId}/{classId}
  default response was modified
  testData attribute was added
• Modified: GET/classes/{solutionId}/{classId}/{version}
  default response was modified
  testData attribute was added
• Modified: GET/publish-environments/history/{solutionId}/{environmentId}
  default response was modified
  modelId, modelType attributes were added
• Modified: GET/publish-environments/status/{solutionId}
  default response was modified
  inputProcessorErrorCounts attribute was added
• Modified: GET/publish-environments/status/{solutionId}/{targetId}
  default response was modified
  inputProcessorErrorCounts attribute was added
• Modified: POST/classes/{solutionId}
  body was modified
  testData attribute was added
  default response was modified
  testData attribute was added
• Modified: POST/engines/input/{solutionId}
  body was modified
  forceImmediateInputAnnotation attribute was added
• Modified: POST/engines/matching-triggers/{solutionId}
  body was modified
  forceImmediateInputAnnotation attribute was added
• Modified: PUT/classes/{solutionId}/{classId}
  body was modified
  testData attribute was added
  default response was modified
  testData attribute was added

Teneo Inquire API

Changes in Models

• Modified: GET/auth/me
  200 response was modified
  User schema changed, attributes added:
  • delegatedLogin
  • indirectGroupIds
  • ldapBaseDN
  • ldapDN
  • ldapWhenChanged

Teneo Manager Client

Java Packages Naming

The changes to Teneo Manager brings some updates in the below-mentioned Java packages of the Teneo Manager API.

These changes are breaking changes and therefore, if in use, any references to these must be updated

• com.artisol.teneo.manager.api.entity

  is renamed to com.artisol.teneo.manager.api.models

  (Note: models

  instead of entity

  )

  This also implies changes to the following packages:

  • com.artisol.teneo.manager.api.entity.common
  • com.artisol.teneo.manager.api.entity.oauth2
  • com.artisol.teneo.manager.api.entity.studio

• com.artisol.teneo.manager.api.exception

  is renamed to com.artisol.teneo.manager.api.exceptions

  (Note exceptions

  in plural form).

ErrorInfo

The Teneo Manager Client previously ignored the HTTP status of the backend response silently for methods that do not return a value (that is, have return type void

) thus, if the backend returned an error status this was not indicated in any way to the caller of the client method. In Teneo 7.3, error handling is implemented with a new error response format:

• ErrorInfo
  is base class for extension by any module and has 2 attributes:
  • error: mandatory, will hold Enum class from the module
  • description: optional, can hold plain text

It is remarkable that the ErrorInfoDeserializer

class is ready to accept any specialization of ErrorInfo

so that the new fields that extend this class will be automatically deserialized.

In summary, Teneo 7.3 has an ErrorInfo

specialization by module, e.g., ManagerErrorInfo

class in the Manager project.

KI Resolutions

Description	Known Issue
LDS configuration: until field kept original week but showed current week	KI-607
Manager: user filter now fully resets in Studio account user permissions dialogue	KI-624
Date restriction of augmenters works again	KI-693
Solution Owners are again persisting, also after backend restart.	KI-694
It is again possible to have file resource	KI-695
Fixed class asks for a pending 'save' if in edit mode as server restarts	KI-696