Show/Hide Toolbars

Therefore Programming Interface 3.0

Therefore 2022

New Classes

TheDocumentRetentionInfo

TheRetentionPolicy

TheRetentionPolicyList

 

New Properties

TheLinkedObject.IndexData

TheLinkedObject.TaskInfo

TheLinkedObject.WorkflowInstanceInfo

 

New Methods

TheConversionOptions.LoadConversionSettings

TheIndexData.FillAutoAppendFields (new overload)

TheTableDataType.GetKeywordsSorted

 

TheServer.CreateNewManualLink

TheServer.QueryDependentFieldsDirect (new overload)

TheServer.RemoveManualLink

 

Therefore 2021

New Classes

TheFieldValidator

ThePortalUserSync

 

New Methods

TheCaseDefinition.GetKeywordsSorted

TheCategory.GetKeywordsSorted

TheIndexData.GetKeywordsSorted

TheTableDataType.GetKeywordsSorted

 

TheServer.GetEFormTokenForUser

TheServer.GetKeywordsSorted

TheServer.GetLocaleInfos

TheServer.GetSmartCaptureVerificationLink

TheServer.GetUserGroupNo

 

Therefore 2020

 

Modified feature: Role Based Permission Control

With Thereforeā„¢ 2020 all permission management is based on roles.

A role is a collection of permissions and can be assigned to a user or group on a Thereforeā„¢ object like categories, case definitions, workflow processes and folders but also on any other supported object like indexing profiles and many more.

TheRoleAssignments class is used to assign roles to users on a specific object (replaces the obsolete class TheSecurity) and is a collection of TheRoleAssignment objects.

Role assignments can have Conditions so that the role assignment only applies if the condition is met. Conditions can only be set for categories and case definitions.

 

TheRolePermission contains properties, each for a single permission (replaces the obsolete class ThePermissionConstants) while TheRoleAccessMask can contain a collection of permissions and is used for safely combining permission values and as parameter for several methods (replaces the obsolete class TheAccessMask).

Note that some permission values have changed. Do not mix permission values from new classes and methods with values from old classes and method.

 

Many methods and properties have been replaced to make use of the new classes exclusively. All old methods and classes are still usable for existing developments and are still compatible.

The ITheRightsServer interfaces will continue to work with old values. A replacement interface is planned for the next release.

 

New Classes

TheClientConnectionSettings

TheClientDiscoveryInfo

 

TheRole

TheRoleAccessMask

TheRoleAssignment

TheRoleAssignments

TheRolePermission

 

Obsolete Classes

TheAccessMask

ThePermission

ThePermissionConstants

ThePermissionList

TheSecurity

 

New Properties

TheCategoryField.SortDescending

 

TheFullTextQueryResultRow.IndexData

TheFullTextQueryResultRow.RoleAccessMask

TheQueryResultRow.RoleAccessMask

 

TheDependentFieldsQueryResult.AllRowsReturned

TheServer.CustomerId

TheTask.CaseNo

 

New Methods

TheDocument.GetThumbnail (new overload)

TheMultiQuery.ExecuteAsync (new overload)

TheQuery.ExecuteAsync (new overload)

 

TheServer.GetCategories (new overloads)

TheServer.GetClientDiscoveryInfo

TheServer.GetKeywords (new overload)

TheServer.GetObjects (new overloads)

TheServer.GetObjectRightsRole

TheServer.GetPublicSettingInt

TheServer.GetPublicSettingString

TheServer.HasPermission (new overloads)

TheServer.RenameObject

TheServer.ResetUserPwd

TheServer.SetUserPassword

TheServer.ShowCategorySelectionDialog (new overload)

 

Therefore 2019

 

New feature: Calculated Fields

TheCategoryField support field value calculations. If a field has a Formula, it can't be set directly but its values is set by executing CalculateFields on a TheIndexData object. If a specific field value is calculated, a recursive chain reaction is triggered that calculates all other field values this field has part of its Formula.

The returned TheFieldCalculationResult contains a list of all field values that have been calculated, the calculated value and information about errors. The index data values in the TheIndexData object are updated automatically.

When saving index data, the server will always calculate field values, independent from if the client already calculated all values or not.

 

All fields used in a Formula can be get by TheCategory.GetCalculationTriggerFields for categories and TheCaseDefinition.GetCalculationTriggerFields for case definitions.

 

New feature: Conditional Formatting

Similar to calculated fields, TheCategoryField supports conditional formatting that allows a change of the visual appearance of fields in the index data dialog. For conditional formatting a Condition has to be set as well as some visual properties, the ConditionalFormatting.

By executing EvaluateConditionalFormatting on a TheIndexData object, the ConditionalFormatting properties of all fields according to the Condition are returned.

 

All fields used in a Condition can be get by TheCategory.GetFormattingTriggerFields for categories and TheCaseDefinition.GetFormattingTriggerFields for case definitions.

 

New feature: Field IDs

In the UI of the Solution Designer, the FieldID takes the place of the Column Name. They have to be unique per category or case definition, cannot be changed and does not change when importing into a different system, other than the IndexDataFieldName, which is composed of "TWF" followed by the FieldNo for fields with no ColName. This makes the FieldID replace the IndexDataFieldName in the API.

Other than column names, field IDs apply to every field, even if the field has no column in the related index data table in the database.

 

The FieldID can be used for Formulas of field calculations and Conditions for conditional formatting of fields.

 

 

New Classes

TheConditionalFormatting

TheConditionalFormattingList

TheConditionalFormattingResult

TheConditionalFormattingResultList

TheFieldCalculationResult

TheFieldCalculationResultItem

 

New Properties

TheCategoryField.Condition

TheCategoryField.ConditionalFormatting

TheCategoryField.FieldID

TheCategoryField.Formula

TheCategoryField.ValidDefaultMacros

 

TheDependentFieldsQueryResult.AllRowsReturned

TheServer.CustomerId

TheTask.CaseNo

 

New Methods

TheCaseDefinition.GetFieldByFieldID

TheCaseDefinition.GetCalculationTriggerFields

TheCaseDefinition.GetFormattingTriggerFields

 

TheCategory.GetFieldByFieldID

TheCategory.GetCalculationTriggerFields

TheCategory.GetFormattingTriggerFields

 

TheCategoryField.ChangeDependencyMode

TheCategoryField.GetValidDefaultMacros

TheCategoryField.SetCondition

TheCategoryField.SetFormula

 

TheIndexData.CalculateFields

TheIndexData.EvaluateConditionalFormatting

TheIndexData.GetValueByFieldID

TheIndexData.SetValueByFieldID

 

ThePDFPrinter.SetDefaultPrinter

 

TheServer.ConnectBearerToken

TheServer.GetKeywordsByKeyDic

TheServer.GetTokenForCurrentUser

TheServer.QueryDependentFieldsDirect

TheServer.SetParentFolder

 

TheWFInstance.Load (new overload)

TheWFInstance.LoadWorkflowHistory

 

TheUser.SetPassword

 

Therefore 2018

 

New feature: Culture sensitive query conditions

Additional to the language sensitive query conditions introduced in Thereforeā„¢ 2017, additional options are available in Thereforeā„¢ 2018. The new class TheCultureInfo provides the possibility to specify an LCID for language, an extra LCID for formats for Date, DateTime and Decimal field condition values and a custom time zone to enable the possibility to use local date and time values from a different client that may use a different time zone, language and format.

 

Modified feature: Money Fields become Decimal Fields

The field type Money has been transformed to the field type Decimal. Decimal fields will now return a value of type decimal instead of double. Decimal values can be converted to double and vice versa.

Setting a double or float value on a TheIndexData object is still supported.

For compatibility reasons fields that are specified with length 15 and scale 2 (all previous Money fields will have this configuration) will still be returned as double value.

 

Decimal fields are more precise and support a configurable number of decimal digits that can be different for each decimal field.

If there are too many decimal digits in a value, the value will be rounded to the next even number.

Double values are not precise. At a certain number of digits the value can contain errors. Make sure to consider this when working with Decimal fields and using more than 15 digits in total.

 

For Decimal fields TheCategoryField.Length specifies the total number of digits for the number, including the decimal digits.

TheCategoryField.Scale specifies the number of decimal digits.

 

New feature: DateTime Fields

The new field type TheCategoryFieldType.DateTimeField holds a date and a time value. Thereforeā„¢ stores these values in UTC, expects the values to be set in UTC and returns them in UTC. The bIsUTC parameter in TheConditionList.Add and the property TheCondition.IsUTC can be used with DateTime fields to enable the possibility of setting query conditions in the local time zone without worrying about the time zone conversion.

 

In addition to this the new class TheCultureInfo provides the possibility to set a different time zone that is used for converting query conditions correctly if necessary as well as the string format for Date, DateTime and Decimal fields.

 

New feature: Multi Language Keyword Dictionaries and Workflow Processes

With Thereforeā„¢ 2017 it is possible to configure the visible text in categories and case definitions including fields and tabs in different languages. Now this feature can also be used with following classes:

TheKeyword

TheKeywordDictionary

TheWFChecklistItem

TheWFInstance

TheWFProcess

TheWFTask

TheWFTransition

 

The concept is the same as with categories and case definitions, as are newly added methods and their names. For reference see What's New in Therefore 2017.

 

New Class

TheCultureInfo

 

New Properties

TheCategoryField.Scale

TheCondition.IsUTC

TheFullTextQueryResultRow.CategoryName

 

New Methods

TheConditionList.Add (new overloads)

 

TheKeyword.GetAvailableLCIDs

TheKeyword.GetCurrentLCID

TheKeyword.DeleteTranslation

TheKeyword.GetName

TheKeyword.SetCurrentLCID

TheKeyword.SetName

 

TheKeywordDictionary.GetAvailableLCIDs

TheKeywordDictionary.DeleteTranslation

 

TheServer.ClaimWorkflowInstance

TheServer.GetCultureInfo

TheServer.SetCultureInfo

 

TheWFChecklistItem.GetText

 

TheWFInstance.GetCurrentLCID

TheWFInstance.SetCurrentLCID

 

TheWFProcess.GetCurrentLCID

TheWFProcess.SetCurrentLCID

TheWFProcess.GetName

TheWFProcess.GetDescription

 

TheWFTask.GetName

 

TheWFTransition.GetActionText

TheWFTransition.GetDescription

 

Thereforeā„¢ 2017 Update 2:

Breaking Change: UTC for DateTime Properties

Until Thereforeā„¢ Update 2, DateTime properties were inconsistent regarding the time zone they used. Some properties were using UTC, some local time. With Thereforeā„¢ 2017 Update 2 all DateTime properties have been changed to use UTC, including query conditions.

Query conditions can only make use of the time values in conditions made on meta data fields from the TheIntQueryField enumeration like LastModified and CreatedOn.

 

This is a list of all DateTime properties that were changed from local time to UTC:

 

TheDocumentProperties.CheckedOutOn

TheDocumentProperties.CreatedOn

TheDocumentProperties.LastModified

 

TheRecycleBinQuery.DeletedOnFrom

TheRecycleBinQuery.DeletedOnTo

 

TheTaskInfo.LastUpdate

 

TheWFHistoryEntry.ActionDate

 

TheWFInstance.ProcessDueDate

TheWFInstance.ProcessStartDate

TheWFInstance.TaskStartDate

TheWFInstance.TaskDueDate

 

TheWFInstanceInfo.ProcessDueDate

TheWFInstanceInfo.ProcessStartDate

TheWFInstanceInfo.TaskStartDate

TheWFInstanceInfo.TaskDueDate

 

All other DateTime values have not been changed because they either already used UTC in previous versions or the time value is ignored.

 

New Properties

TheDocumentProperties.CreatedByDisplayName

TheDocumentProperties.CreatedByUserNo

TheDocumentProperties.CheckedOutByDisplayName

TheDocumentProperties.CheckedOutByUserNo

TheDocumentProperties.ModifiedByDisplayName

TheDocumentProperties.ModifiedByUserNo

 

New Methods

TheCase.CreateCaseLink

TheCase.CreateDocumentLink

TheCase.DeleteCaseLink

TheCase.DeleteDocumentLink

 

TheDocument.CreateCaseLink

TheDocument.DeleteCaseLink

 

 

Thereforeā„¢ 2017:

New feature: Tab Control Fields

The new field type TheCategoryFieldType.TabControlField is meant for better organization of categories and case definitions. Like label, table and image fields, tab controls do not hold any index data values.

Every tab control consists of one or more tabs. Tabs are represented by the TheTabInfo class. Each tab has a TabNo, defining the order the tabs were added to the tab control, and a Position, containing the order for displaying the tabs.

 

The new TheCategoryField.ParentFieldNo property can be used to determine if a field is located in tab control field. This property is now also used for column fields in table fields and thereby replaces the old BelongsToTable property. The BelongsToTable property is hereby deprecated but still compatible and will return field numbers for table fields only.

 

New feature: Workflow Errors

Errors in automatic workflow errors can be queried in the Thereforeā„¢ Navigator in Thereforeā„¢ 2017. To perform a query returning error information with the API, execute a workflow query with TheQuery.ExecuteWorkflowQuery in combination with the new enumeration value TheWorkflowFalgs.ErrorInstances.

Using the flag AllInstances will also return error information while DefaultInstances and RunningInstances won't.

In the TheQueryResultRow the workflow error information will always be present in the positions TheQueryResultRow.Count - 6 to - 9.

 

The classes TheWFInstance and TheWFInstanceInfo have the new properties ErrorString, ErrorInfo and ErrorTimestamp to access detailed information about the error.

Errors can be cleared with TheWFInstance.ClearError for a single workflow instance and TheServer.ClearWorkflowError for multiple workflow instances.

 

New feature: Multi Language Categories and Case Definitions

With Thereforeā„¢ 2017 it is possible to configure the visible text in categories and case definitions including fields and tabs in different languages. For this the concept of the connection default language has been introduced.

By default the connection default language is the default UI language selected in the Thereforeā„¢ Navigator. This setting is only loaded on application startup. It can be overwritten by TheServer.SetLanguage. This parameter can only be changed when not being connected to the server.

When being set on a server object, loading a TheCategory and TheCaseDefinition with this server object hands over the connection default language from the server to the loaded object and from these to every TheCategoryField and in further succession to every TheTabInfo object. The properties Name and Description of TheCategory and TheCaseDefinition and the property Caption of TheCategoryField and TheTabInfo will now return their value in the connection default language if available.

The connection default language is not dependent on the language resource files installed with Thereforeā„¢ as it only refers to the category and case definition configuration.

 

The language for the properties can always be change by calling SetCurrentLCID (find directs links below) in all four classes. When using 0 as parameter, the currently used language will be changed back to the connection default language.

Additionally each property has a Get and Set method with an LCID parameter to get and set values in the corresponding language independent of the currently used language.

With the GetAvailableLCIDs method in the TheCategory and TheCaseDefinition classes, a list of LCIDs the corresponding object has been configured with is returned.

 

New feature: Language sensitive query conditions

Opposing to the multi language feature for categories and case definitions, language sensitive query conditions are partially bound to the language resource files installed with Thereforeā„¢ on the machine executing the API code. For this new overloads of the TheQuery.Execute and TheQuery.ExecuteAsync with an additional LCID parameter.

Language sensitive conditions parsing consists of two different parts: Thereforeā„¢ query operators and macros (as they can be used in the Navigator) and language sensitive formats of values like dates and the decimal point.

 

Operators and macros can now be accessed in the different languages by using TheQuery.GetValidOperandMacros and TheQuery.GetValidOperators. Any LCID can be used here. If there is no language resource file present for this LCID, the default will be used. The macros and operators returned are always in the same static order.

 

Executing a query with the LCID as parameter will parse conditions with macros and operators for the given LCID. If there is no language resource file present for this LCID, the default will be used. Dates and decimal numbers will also be parsed with the default formatting settings for this LCID. By default the date and decimal point format configured by the user (can be changed under Language in the Windows Control Panel). These settings will be ignored here.

Please note: To date there is a bug in Microsoft Windows preventing the standard Hungarian date format to be parsed correctly.

 

New feature: Design Object Lock

The new feature to lock objects like categories and case definitions in the Thereforeā„¢ Solution Designer leads to a breaking change in the API. This breaking change will cause compatibility problems with existing solutions that modify categories and case definitions.

Categories and case definitions loaded with TheCategory.Load and TheCaseDefinition.Load can not be changed anymore. Executing SaveChanges will always fail. To be able to change categories and case definitions loading has to be performed by TheCategory.LoadForEdit and TheCaseDefinition.LoadForEdit. This will put an object lock on the loaded category or case definition. Executing SaveChanges will remove the object lock when saved successfully but will not put a new lock on the object.

With TheCategory.Unlock and TheCaseDefinition.Unlock the lock can be removed as well.

 

New Classes

TheTabInfo

TheTabInfoList

TheWFInstanceList

 

New Properties

TheCategoryField.ParentFieldNo

TheCategoryField.ShowInTabNo

TheCategoryField.Tabs

 

TheQueryResultRow.InstanceNo

TheQueryResultRow.TokenNo

 

TheWFInstance.ErrorString

TheWFInstance.ErrorInfo

TheWFInstance.ErrorTimestamp

 

TheWFInstanceInfo.ErrorString

TheWFInstanceInfo.ErrorInfo

TheWFInstanceInfo.ErrorTimestamp

 

New Methods

TheCaseDefinition.CreateTab

TheCaseDefinition.GetCurrentLCID

TheCaseDefinition.DeleteTab

TheCaseDefinition.DeleteTranslation

TheCaseDefinition.GetDescription

TheCaseDefinition.GetName

TheCaseDefinition.LoadForEdit

TheCaseDefinition.MoveField

TheCaseDefinition.SetCurrentLCID

TheCaseDefinition.SetDescription

TheCaseDefinition.SetName

TheCaseDefinition.Unlock

 

TheCategory.CreateTab

TheCategory.GetCurrentLCID

TheCategory.DeleteTab

TheCategory.DeleteTranslation

TheCategory.GetDescription

TheCategory.GetName

TheCategory.LoadForEdit

TheCategory.MoveField

TheCategory.SetCurrentLCID

TheCategory.SetDescription

TheCategory.SetName

TheCategory.Unlock

 

TheCategoryField.GetCaption

TheCategoryField.GetCurrentLCID

TheCategoryField.SetCaption

TheCategoryField.SetCurrentLCID

 

TheMultiQuery.Execute (new overload)

TheMultiQuery.ExecuteAsync (new overload)

 

TheQuery.Execute (new overload)

TheQuery.ExecuteAsync (new overload)

TheQuery.GetValidOperandMacros

TheQuery.GetValidOperators

 

TheServer.ClearLocalCache

TheServer.ClearWorkflowError

TheServer.Connect (new overload)

TheServer.GetCategories (new overloads)

TheServer.GetObjects (new overload)

TheServer.SetLanguage

 

TheWFInstance.ClearError

 

 

Thereforeā„¢ 2016:

New feature: Forms

The new Thereforeā„¢ Forms feature is implemented as Therefore documents without files in combination with new options for displaying category fields and properties. To represent these new options in the API the new TheDisplayProperties class has been introduced. Every TheCategoryField object has a new property DisplayProperties with this type. The TheCategory class has the BackgroundColor property only.

 

The new image field type (see TheCategoryFieldType for reference) the TheCategoryField class has a new property ImageDocNo containing the document number of the image used. The image document has to be in the system category Templates with the template type set to "Index Dialog Image" to be valid.

 

New feature: Category Design

Categories and case definitions can now be created and changed with the API. Most properties of the classes TheCaseDefinition, TheCategory and TheCategoryField have been changed from read-only to read-write. For more detailed information take a look at the new methods and properties for these classes below.

To be able to add fields from referenced table to a case definition or category the TheReferencedTable and TheReferencedTableColumn classes have been introduced.

 

New feature: Query Dependent Fields

With the new TheDependentFieldsQuery class the content of referenced table fields and their dependent field can be queried. This class' functionality is similar to the data look-up dialog introduced with Thereforeā„¢ 2014.

 

Performance Enhancement Options for Documents

There are new performance enhancement options for operations with documents.

 

By default saving a document is automatically reloading the document again like the Viewer is doing it. If the document is not needed anymore after it has been saved this is not necessary. Because of this a new overload for TheDocument.Archive with a new parameter to specify whether the document should be reloaded or not has been introduced.

 

The new overloads for TheDocument.AddStream, TheDocument.AddStreamEx and TheDocument.AddStreamsEx have an additional parameter to specify if the file should be added as content file or not. Content files are not added to the compound file. Adding a file to the compound file needs some processing time. Usually it is better to add files to the compound file that are well suited to be compressed for faster data transfer though like text or Office documents though. Compressed image files like TIFF, JPEG and PNG are already compressed so that not adding them to the compound file can increase performance.

The API recognizes some of these formats and might automatically add a file as content file automatically without the need to set the content file parameter. But if the parameter is set to false (do not add as content file) the file will be added to the compound file.

 

In addition to the new option when adding a new file to the document there is a new overload for TheDocument.Retrieve with a new parameter to specify if content files should be retrieved separately or if they should be integrated to the compound file before the retrieve.
Retrieving compound files separately is faster but sometimes it might be necessary to have the compound file contain all files (e.g. when the complete compound file is sent to a user via email).

 

New Workflow Interface

ITheWorkflowAutomaticTask

Please note that the old workflow interfaces have been removed from the documentation and shouldn't be used anymore. They will stay compatible with Thereforeā„¢ 2016 and future versions unless stated otherwise.

 

New Classes

TheDisplayProperties

TheDependentFieldsQuery

TheDependentFieldsQueryResult

TheDependentFieldsQueryResultRow

TheReferencedTable

TheReferencedTableColumn

 

New Properties

TheCaseDefinition.TypeNo

TheCaseDefinition.SubCaseFieldIx

 

TheCategory.BackgroundColor

TheCategory.EmptyDocMode

TheCategory.CoverMode

 

TheCategoryField.DisplayProperties

TheCategoryField.ImageDocNo

TheCategoryField.SelectFromDropDownBox

 

TheIndexData.CaseNo

 

TheUser.OneTimePwd

TheUser.Disabled

 

New Methods

TheCaseDefinition.Create

TheCaseDefinition.CreateField

TheCaseDefinition.DeleteField

TheCaseDefinition.SaveChanges

TheCaseDefinition.SetSubCaseFieldIx

 

TheCategory.Create

TheCategory.CreateField

TheCategory.DeleteField

TheCategory.SaveChanges

TheCategory.SetSubCtgryFieldIx

TheCategory.SetWatermarkDocNo

 

TheCategoryField.SetImageDocNo

 

TheDocument.AddStream (new overload)

TheDocument.AddStreamEx (new overload)

TheDocument.AddStreamsEx (new overload)

TheDocument.Archive (new overload)

 

TheUser.Create

TheUser.AddUserToGroup

TheUser.RemoveUserFromGroup

TheUser.SaveChanges

TheUser.ResetPassword

TheUser.Load

Ā© 2023 Therefore Corporation, all rights reserved.