Automatic Conversion Processes

Last updated
Save as PDF

When the installer detects an existing version 2.5 SP4 Update 1 installation, it runs multiple tools to transform expressions, tags, and other elements from the version 2.x style to the version 4.x style. This section focuses on conversion of custom screen tags.

Manual conversion

It is possible to run a conversion tool manually against a single XML file to get a report of possible errors in the file. upgrade.bat, found in the exploded contents of setup.exe, should be run from the command line, taking the XML path and file name as a command-line argument. Example:

upgrade.bat \work\MyCustomJavaBlock.xml

The file specified in the argument is converted and then overwritten with the conversion results.

The output from upgrade.bat can be found in files ConversionLog.txt and ManualConversionLog.txt, in the same folder.

Note: ManualConversionLog.txt is only created when the tool encounters situations that are known to require manual intervention. Such situations are also listed in the console window as the job executes.

Logging

The results of the conversion tools' work is logged in two files:

ConversionLog.txt contains progress messages for the automated tools.
ManualConversionLog.txt identifies situations that can't be handled by the automated tool and will require manual editing by a developer familiar with HTML and Javascript and, in some cases, Java.

These files are found in a subfolder beneath the installation media folder:

upgrade/tools/external/CustomScreenConversionTool/logs

It is essential that you read the logs after the installer has run, watching for possible conversion issues.

If a conversion situation is detected then you will find, near the beginning of the log file, the phrase "Custom screen conversion is needed". Additional messages regarding conversion will be found throughout the log file.

In the ConversionLog.txt excerpt below, a summary of successful conversion actions is presented:

06/11/2009 13:08:09 (266ms) --- --------Custom screen conversion-Started-------- 
06/11/2009 13:08:09 (376ms) --- Root/System/Object Definitions/Account 06/11/2009 
13:08:09 (579ms) --- Root/System/Object Definitions/Advice & Counsel 06/11/2009 
13:08:09 (719ms) --- WzCjbAdviceCounselSearchResultsSYS.xml
06/11/2009 13:08:10 (251ms) --- Updated 1 tc:component componentType:CLString tag
06/11/2009 13:08:10 (251ms) --- Updated 1 HTML Tag : link tag 06/11/2009 
13:08:10 (251ms) --- Updated 11 tc:CLTextField tag
06/11/2009 13:08:10 (251ms) --- Updated 1 tc:useBlockTemplate tag
06/11/2009 13:08:10 (251ms) --- Updated 1 tc:component componentType:WORepetition tag
06/11/2009 13:08:10 (251ms) --- Updated 2 tc:CLRadioButton tag 06/11/2009 
13:08:17 (298ms) --- WzCjbAdviceCounselUseExistingSYS.xml
06/11/2009 13:08:17 (313ms) --- Converted Cjb expression cjb.acWasRelated() for class WzCjbAdviceCounselSearchResultsSYS
06/11/2009 13:08:17 (329ms) --- Converted Cjb expression cjb.acWasRelated() for class WzCjbAdviceCounselSearchResultsSYS
06/11/2009 13:08:17 (329ms) --- Updated 4 tc:if tag
06/11/2009 13:08:17 (329ms) --- Updated 1 HTML Tag : link tag 
06/11/2009 13:08:17 (329ms) --- Updated 1 tc:useBlockTemplate tag 
06/11/2009 13:08:17 (923ms) --- CjbAdviceCounsel.xml
06/11/2009 13:08:18 (016ms) --- Updated 1 tc:if tag 06/11/2009 
13:08:18 (016ms) --- Updated 8 tc:label tag
06/11/2009 13:08:18 (016ms) --- Updated 2 tc:component componentType:CLLabel tag

Any problems in conversion will be highlighted by the word ERROR in uppercase. Search the log files for this word and note the preceding conversion action. It will require manual intervention by a TeamConnect professional.

Here is an example of ManualConversionLog.txt, showing some situations that can't be handled by the automated tool. Suggestions for handling some of these situations can be found in Manual Conversion Suggestions.

This file contains XML screens that could not be automatically converted to the 3.x format due to the presence of tags or JavaScript code that need to be rewritten using 3.x API.

Please refer to the 3.x developer guide for the details.

==============================================

Filename: Root/System/Object Definitions/Advice & Counsel/Screens/ CjbAdviceCounsel.xml

Tag: <script ...>

No. of occurrences: 5

Instructions: HTML element names have changed in 3.x. Please rewrite the JavaScript using the 3.x UI element names.

==============================================

Filename: Root/System/Object Definitions/Cost Center/Screens/ CjbCTransactionHistorySYS.xml

Tag: <tc:component componentType=CLBatchDisplay ...> No. of occurrences: 1

Instructions: Please use the 3.x batch display API to rewrite this tag, including the corresponding CJB, NewRow and RegularRow XMLs.

Automatic Custom Screen Tag Conversion

The table below describes the custom screen tags that are handled automatically during the conversion process. A subsequent table describes other tags that will require manual conversions.

Even if a tag is listed in the table below, automatic conversion might not handle every attribute that is associated with the tag. Read the remarks for details. When an attribute is described as being "ignored" in the remarks, that means that the attribute will be dropped from the code as the code is converted to version 3.x syntax.

Custom screen tags that are automatically converted

Tag syntax in 2.x	Tag syntax in 3.x	Remarks
<tc:useBlockTemplate blockTitle="{cjb.blockT itle}"> text </tc:useBlockTemplate>	tc:blockTemplate	Only the blockTitle attribute is supported. Other attributes are ignored.
<tc:component componentType="CLDropDo wnList"> or <tc:CLDropDownList>	tc:select The following attributes are renamed: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable nullValueDisplayString— nullValueDisplayName displayStringPath—displayNamePath sortKey—sortPath isMultiple—multiple	These attributes are ignored and not converted: doubleClick onKeyDown item maxLength isSubmittedOnChang e applet notUseApplet notShowRootApplet entityName forceSize notLinkToUser useDidChange emptyValueString allowEmptyList disableInactiveItem
<tc:componentType="CLDateFi eld"> or <tc:CLDateField>	tc:date or tc:dateTime or tc:time The following attributes are renamed: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable isTimeZoneIndependent— timeZoneIndependent	Converted to tc:date unless attribute showTime is true, in which case the tag is converted to tc:dateTime. Regardless of the conditions above, if attribute doNotShowDate is true, the tag is converted to tc:time These attributes are ignored and not converted: emptyValueString disableChangeCheck submitValue useDidChange dateFormatInput dateFormatOutput timeFormatInput timeFormatOutput timeUnderDate
<tc:component componentType="CLTimeFi eld"> or <tc:CLTimeField>	tc:time	These attributes are ignored and not converted: emptyValueString
<tc:component componentType="CLCheckB ox"> or <tc:CLCheckBox>	tc:checkBox	These attributes are ignored and not converted: disableChangeCheck submitValue useDidChange
<tc:component componentType="CLString "> or <tc:CLString>	tc:string (3.x) tc: out (4.x) The following attributes are renamed: displayStringPath—value	The following attribute must be handled in a special way: The attribute value of eoObject must be applied to the value attribute by taking the displayStringPath then appending to the eoObject path. Thus, value = eoObject + "." + displayStringPath.)
<tc:component componentType="CLLabel" > or <tc:CLLabel>	tc:label The following attributes are renamed: isFieldRequired—required	These attributes are ignored and not converted: blockLabel
<tc:component componentType="CLString "> or <tc:CLString>	tc:out The following attribute is converted: dsiplayPath	All other attributes are ignored and not converted.
<tc:component componentType="CLTextAr ea"> or <tc:CLTextArea>	tc:note The following attributes are renamed: isFieldRequired—required	These attributes are ignored and not converted: blockLabel
<tc:component componentType="CLTextFi eld"> or <tc:CLTextField>	tc:text The following attributes are renamed: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable maxlength—maxLength	This conversion will occur only if none of the following attributes are present in the tag: format maximumFractionDigits minimumFractionDigi ts allowNegativeValues currencySymbol showCurrencySymbol These attributes are ignored and not converted: disableChangeCheck searchKey useDidChange emptyValueString escapeXMLTags
<tc:component componentType="CLTextFi eld"> or <tc:CLTextField>	tc:number The FORMAT attribute is converted; any trailing digit becomes the value of new attribute fractionDigits. These attributes are also converted: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable maxlength—maxLength	This conversion will occur only if at least one of the following attributes is present in the tag: format maximumFractionDigits minimumFractionDigits allowNegativeValues currencySymbol showCurrencySymbol These attributes are ignored and not converted: disableChangeCheck searchKey useDidChange emptyValueString escapeXMLTags
<tc:component componentType="CLCatego ryTable"> or <tc:CLCategoryTable> or <tc:component componentType="CLCatego ryList"> or <tc:CLCategoryList>	tc:categorySelect The following attributes are renamed: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable nullValueDisplayString— nullValueDisplayName isMultiple—multiple	These attributes are ignored and not converted: item maxLength isSubmitedOnChang e applet notUseApplet notShowRootApplet entityName forceSize notLinkToUser useDidChange emptyValueString allowEmptyList action prepopulatedList realEntityCode showParent subCategoryTreePos ition usePrePopulatedList
<tc:component componentType="CLImage"> or <tc:CLImage> Example: <tc:CLImageHyperlink href="${cjb.hyperlink}" tabIndex="2" imageFileName="customim ages/spacer.gif" imageAltText="spacer" / >	img Example: <a href="#" onClick="${cjb.hyperlink}" tabIndex="2" ><img src="./ customimages/spacer.gif" alt="spacer" /></a>	Version 3.x uses conventional HTML syntax for this situation, not a custom tag.
<tc:component componentType="CLHidden Field"> or <tc:CLHiddenField>	input	Version 3.x uses conventional HTML syntax for this situation, not a custom tag. The name attribute is converted from an EO reference to an applicationEntity reference.
<tc:component componentType="CLHyperl ink"> or <tc:CLHyperlink>	link
<tc:component componentType="CLDetail Table"> or <tc:CLDetailTable>	tc:customLookup These attributes are renamed: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable nullValueDisplayString— nullValueDisplayName isMultiple—multiple detailLookupTableCode—tableCode	The following attributes are ignored and not automatically converted: displayStringPath sortKey doubleClick onKeyDown item maxLength isSubmitedOnChang e applet notUseApplet notShowRootApplet entityName forceSize notLinkToUser useDidChange emptyValueString allowEmptyList disableInactiveItem displayRootNode notUseApplet prepopulatedList useApplet usePrepopulatedList
<tc:component componentType="CLSystem Table"> or <tc:CLSystemTable>	tc:systemLookup These attributes are renamed: isAlwaysEditable—forceEditable isNotEditable—forceNotEditable nullValueDisplayString— nullValueDisplayName isMultiple—multiple tableName—tableName	The following attributes are ignored and not automatically converted: displayStringPath sortKey doubleClick onKeyDown item maxLength isSubmitedOnChang e applet notUseApplet notShowRootApplet entityName forceSize notLinkToUser useDidChange emptyValueString allowEmptyList disableInactiveItem showAll showAlmostAll pleaseDontUseTree showRoot tnApplication prepopulatedList usePrepopulatedList
<tc:registerBlockAction >	tc:useClass	If two useClass tags in the same CJB reference the same class name, that is acceptab
<tc:component componentType="CLObject Field"> or <tc:CLObjectField>	tc:account (or tc:contact, tc:project, etc.) (3.x) tc:contact, tc:project, tc:user (4.x) The actual tag depends upon the value of attritube EntityName. The 3.x tag name should be the value of that attribute, minus the leading "T" character~. The following attributes are renamed: fieldName—name isAlwaysEditable—forceEditable isNotEditable—forceNotEditable nullValueDisplayString— nullValueDisplayName displayStringPath—displayNamePath sortKey—sortPath isMultiple—multiple object—value	The following attributes are ignored and not automatically converted:allUsers alt alwaysUsePrimaryK ey applicationID containerID disableChangeCheck disabled display displayString displayStringFieldNa me emptyValueString entityName forceSize height isFieldRequired isPrintable omitOpenIcon onBlur onChange onClick onFocus onKeyDown onSubmit prepropulatedList primaryKey primaryKeyFieldNam e qualifier reloadPage searchViewName secured sortKey submitCommandArg s tabIndex type useDidChange usePrepopulatedList width
<tc:if negate="true" conditional="{cjb.isEdi table}">; text </tc:if>	<tc:if negate="true" test="{cjb.isEditable}"> text </tc:if>	The tag is the same but the attribute name changes. If the conversion tool encounters a "1" or "0" as the value for negate, it will replace those values with "true" and "false" during conversion.
<tc:component componentType="CLIntern alTable"> or <tc:CLInternalTable>	tc:enumeration The following attributes are renamed: table—enumeration isAlwaysEditable—forceEditable isNotEditable—forceNotEditable isMultiple—multiple	enumeration is both a tag name and an attribute name. For each IID class value of table attribute in 2.x, the corresponding 3.x Enum type is substituted as the value in enumeration attribute. For example, ZNContTypeIID becomes contactType. The following attributes are ignored:identifier filterIID disableInactiveItem tabIndex item emptyValueString listAsString keyPath useDidChange notLinkToUser forceSize entityName disabled maxLength isSubmitedOnChange applet notUseApplet notShowRootApplet doubleClick

Tag syntax in 2.x

Tag syntax in 3.x

Remarks

<tc:useBlockTemplate blockTitle="{cjb.blockT itle}">
text
</tc:useBlockTemplate>

tc:blockTemplate

Only the blockTitle attribute is supported. Other attributes are ignored.

<tc:component componentType="CLDropDo wnList">
or
<tc:CLDropDownList>

tc:select
The following attributes are renamed:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
nullValueDisplayString— nullValueDisplayName
displayStringPath—displayNamePath
sortKey—sortPath
isMultiple—multiple

These attributes are ignored and not converted:

doubleClick
onKeyDown
item
maxLength
isSubmittedOnChang e
applet
notUseApplet
notShowRootApplet
entityName
forceSize
notLinkToUser
useDidChange
emptyValueString
allowEmptyList
disableInactiveItem

<tc:componentType="CLDateFi eld">

<tc:CLDateField>

tc:date or tc:dateTime or tc:time
The following attributes are renamed:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
isTimeZoneIndependent— timeZoneIndependent

Converted to tc:date unless attribute showTime is true, in which case the tag is converted to tc:dateTime. Regardless of the conditions above, if attribute doNotShowDate is true, the tag is converted to tc:time

These attributes are ignored and not converted:

emptyValueString
disableChangeCheck
submitValue
useDidChange
dateFormatInput
dateFormatOutput
timeFormatInput
timeFormatOutput
timeUnderDate

<tc:component componentType="CLTimeFi eld">

<tc:CLTimeField>

tc:time

These attributes are ignored and not converted:

emptyValueString

<tc:component componentType="CLCheckB ox">

<tc:CLCheckBox>

tc:checkBox

These attributes are ignored and not converted:

disableChangeCheck
submitValue
useDidChange

<tc:component componentType="CLString ">

<tc:CLString>

tc:string (3.x)
tc: out (4.x)
The following attributes are renamed: displayStringPath—value

The following attribute must be handled in a special way:

The attribute value of eoObject must be applied to the value attribute by taking the displayStringPath then appending to the eoObject path. Thus, value = eoObject + "." + displayStringPath.)

<tc:component componentType="CLLabel" >

<tc:CLLabel>

tc:label
The following attributes are renamed: isFieldRequired—required

These attributes are ignored and not converted:

blockLabel

<tc:component componentType="CLString ">

<tc:CLString>

tc:out
The following attribute is converted: dsiplayPath

All other attributes are ignored and not converted.

<tc:component componentType="CLTextAr ea">

<tc:CLTextArea>

tc:note
The following attributes are renamed:

isFieldRequired—required

These attributes are ignored and not converted:

blockLabel

<tc:component componentType="CLTextFi eld">

<tc:CLTextField>

tc:text
The following attributes are renamed:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
maxlength—maxLength

This conversion will occur only if none of the following attributes are present in the tag:

format
maximumFractionDigits
minimumFractionDigi ts
allowNegativeValues
currencySymbol
showCurrencySymbol
These attributes are ignored and not converted:
disableChangeCheck
searchKey
useDidChange
emptyValueString
escapeXMLTags

<tc:component componentType="CLTextFi eld">

<tc:CLTextField>

tc:number

The FORMAT attribute is converted; any trailing digit becomes the value of new attribute fractionDigits.

These attributes are also converted:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
maxlength—maxLength

This conversion will occur only if at least one of the following attributes is present in the tag:

format
maximumFractionDigits
minimumFractionDigits
allowNegativeValues
currencySymbol
showCurrencySymbol

These attributes are ignored and not converted:

disableChangeCheck
searchKey
useDidChange
emptyValueString
escapeXMLTags

<tc:component componentType="CLCatego ryTable">
or
<tc:CLCategoryTable> or <tc:component componentType="CLCatego ryList">
or
<tc:CLCategoryList>

tc:categorySelect

The following attributes are renamed:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
nullValueDisplayString— nullValueDisplayName
isMultiple—multiple

These attributes are ignored and not converted:

item
maxLength
isSubmitedOnChang e
applet
notUseApplet
notShowRootApplet
entityName
forceSize
notLinkToUser
useDidChange
emptyValueString
allowEmptyList
action
prepopulatedList
realEntityCode
showParent
subCategoryTreePos ition
usePrePopulatedList

<tc:component componentType="CLImage">
or
<tc:CLImage>

Example:

<tc:CLImageHyperlink href="${cjb.hyperlink}" tabIndex="2" imageFileName="customim ages/spacer.gif" imageAltText="spacer" / >

img Example:

Version 3.x uses conventional HTML syntax for this situation, not a custom tag.

<tc:component componentType="CLHidden Field">
or
<tc:CLHiddenField>

input

Version 3.x uses conventional HTML syntax for this situation, not a custom tag. The name attribute is converted from an EO reference to an applicationEntity reference.

<tc:component componentType="CLHyperl ink">
or
<tc:CLHyperlink>

link

<tc:component componentType="CLDetail Table">
or
<tc:CLDetailTable>

tc:customLookup

These attributes are renamed:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
nullValueDisplayString— nullValueDisplayName
isMultiple—multiple
detailLookupTableCode—tableCode

The following attributes are ignored and not automatically converted:

displayStringPath
sortKey
doubleClick
onKeyDown
item
maxLength
isSubmitedOnChang e
applet
notUseApplet
notShowRootApplet
entityName
forceSize
notLinkToUser
useDidChange
emptyValueString
allowEmptyList
disableInactiveItem
displayRootNode
notUseApplet
prepopulatedList
useApplet
usePrepopulatedList

<tc:component componentType="CLSystem Table">
or
<tc:CLSystemTable>

tc:systemLookup

These attributes are renamed:

isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
nullValueDisplayString— nullValueDisplayName
isMultiple—multiple tableName—tableName

The following attributes are ignored and not automatically converted:

displayStringPath
sortKey
doubleClick
onKeyDown
item
maxLength
isSubmitedOnChang e
applet
notUseApplet
notShowRootApplet
entityName
forceSize
notLinkToUser
useDidChange
emptyValueString
allowEmptyList
disableInactiveItem
showAll
showAlmostAll
pleaseDontUseTree
showRoot
tnApplication
prepopulatedList
usePrepopulatedList

<tc:registerBlockAction >

tc:useClass

If two useClass tags in the same CJB reference the same class name, that is acceptab

<tc:component componentType="CLObject Field">
or
<tc:CLObjectField>

tc:account (or tc:contact, tc:project, etc.) (3.x)

tc:contact, tc:project, tc:user (4.x)

The actual tag depends upon the value of attritube EntityName. The 3.x tag name should be the value of that attribute, minus the leading "T" character~.

The following attributes are renamed:

fieldName—name
isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
nullValueDisplayString— nullValueDisplayName
displayStringPath—displayNamePath
sortKey—sortPath
isMultiple—multiple
object—value

The following attributes are ignored and not automatically converted:allUsers

alt
alwaysUsePrimaryK ey
applicationID
containerID
disableChangeCheck
disabled
display
displayString
displayStringFieldNa me
emptyValueString
entityName
forceSize
height
isFieldRequired
isPrintable
omitOpenIcon
onBlur
onChange
onClick
onFocus
onKeyDown
onSubmit
prepropulatedList
primaryKey
primaryKeyFieldNam e
qualifier
reloadPage
searchViewName
secured
sortKey
submitCommandArg s
tabIndex
type
useDidChange
usePrepopulatedList
width

<tc:if negate="true" conditional="{cjb.isEdi table}">;
text
</tc:if>

<tc:if negate="true" test="{cjb.isEditable}">
text
</tc:if>

The tag is the same but the attribute name changes. If the conversion tool encounters a "1" or "0" as the value for negate, it will replace those values with "true" and "false" during conversion.

<tc:component componentType="CLIntern alTable">
or
<tc:CLInternalTable>

tc:enumeration
The following attributes are renamed:

table—enumeration
isAlwaysEditable—forceEditable
isNotEditable—forceNotEditable
isMultiple—multiple

enumeration is both a tag name and an attribute name. For each IID class value of table attribute in 2.x, the corresponding 3.x Enum type is substituted as the value in enumeration attribute. For example, ZNContTypeIID becomes contactType.

The following attributes are ignored:identifier

filterIID
disableInactiveItem
tabIndex
item
emptyValueString
listAsString
keyPath
useDidChange
notLinkToUser
forceSize
entityName
disabled
maxLength
isSubmitedOnChange
applet
notUseApplet
notShowRootApplet
doubleClick

This section contains suggested approaches for manual editing of code that could not be handled by the automated conversion tool. Such code will be noted in the log file ManualConversionLog.txt, which is produced during the execution of the automated conversion tool.Custom screen tags that are not automatically converted

Tag name	Remarks
<tc:component componentType="CLBatchDisplay"> or tc:CLBatchDisplay	Each instance of batch display must be manually converted by a TeamConnect professional.