Upgrading Caliach Vision to V3.00 from Earlier Versions

Version 3.00 radically changed the way Customer, Delivery Details, Marketing and Supplier addresses and contacts are handled in the programme and structured in the database.

Unlike less significant version upgrades of Caliach Vision, in V3.00 many internal fields and some files within the data structure have been removed and replaced by alternative simplified address and contact files. The following tabulates the fields that are no longer present in the structure and their replacements, Note that the CADFILE and DECFILE are now no longer present.

Old

New

CUSTITL

con(ADCSALU,' ',ADCFIRS)

CUSGVNM

ADCDEAR

CUSLSNM

ADCLAST

CUSJOB

ADCJOB

CUSDEPT

ADCDEPT

CUSADDR

ADRADDR

CUSZIP

ADRZIP

CUSCTEL

ADCMOBI

CUSWTEL

ADCTEL

CUSFTEL

ADCFAX

CUSTLX

ADRTLX

CUSHTEL

ADCHOME

CUSTAMC

ADRTAMC

CUSCONC

ADRCONC

CUSEMAI

ADCEMAI

CUSWWW

ADRWWW

CUSINCO

ADRINCO

CUSINCP

ADRINCP

SUPLSNM

ADCLAST

SUPTITL

con(ADCSALU,' ',ADCFIRS)

SUPADDR

ADRADDR

SUPZIP

ADRZIP

SUPGVNM

ADCDEAR

SUPCTEL

ADCMOBI

SUPWTEL

ADCTEL

SUPFAX

ADCFAX

SUPTELX

ADRTLX

SUPHTEL

ADCHOME

SUPCONC

ADRCONC

SUPEMAI

ADCEMAI

SUPWWW

ADRWWW

CADADR

ADRADDR

CADCONT

con(ADCSALU,' ',ADCFIRS,' ',ADCLAST,pick(len(ADCJOB)>0,'',con(' - ',ADCJOB)))

CADTEL

ADRTEL

CADFAX

ADRFAX

CADFACT

ADRFACT

CADEMAI

ADCEMAI

CADWWW

ADRWWW

CADNO

ADRID

CADZIP

ADRZIP

CADCONC

ADRCONC

CADCOMA

ADRCOMA

CADINCO

ADRINCO

CADINCP

ADRINCP

DEAADR1

ADRADDR

DEAADR2

''

DEAADR3

''

DEAPOST

ADRZIP

DEACONT

''

DEATEL1

ADCTEL

DEATEL2

ADCFAX

DEATEL3

ADRTLX

DEADEAR

ADCDEAR

DEACTRY

ADRCONC

DEAEMAI

ADCEMAI

DEAWWW

ADRWWW

DECID

ADCID

DECDEAR

ADCDEAR

DECDEA

ADCADR

DECSALU

ADCSALU

DECFIRS

ADCFIRS

DECNAME

ADCLAST

DECJOB

ADCJOB

DECTEL1

ADCTEL

DECTEL2

ADCFAX

DECTEL3

ADCMOBI

DECEMAI

ADCEMAI

DECWWW

ADRWWW

DECCOMM

ADCCOMM

DECMAIL

ADCMAIL

DELADR

$cinst.iDelAddress

There are two special tasks that need to be undertaken to upgrade a working Caliach Vision site. Firstly, data upgrade needs to be carried out in a two-stage process. Secondly, any custom designs of reports, windows, etc. should pass through a conversion process before being copied into the new V3.00 OpenVision.lbs. Both tasks are carried out using V2to3Upgrade.lbs located in the Upgrading folder of the Vision directory tree.

Converting Data

This process takes any Caliach Vision (or CaliachMRP V2.60) datafile and pre-converts the data into a form ready to be accommodated by Caliach Vision itself. Caliach Vision V3.00 or later will not open a datafile that has not been pre-converted in this manner. The process is needed because Caliach Vision V3.00 or later does not support the old data structures and therefore cannot move existing data from the old form into the new. The converter library V2to3Upgrade.lbs located in the Upgrading folder of the Vision directory tree, contains both the old and new structures.

Warning WARNING: At each stage in the process make sure there is plenty of spare space in the datafile. If need be add a segment. Typically the data contents of your datafile will expand by up to 20%. It is always a good idea to archive off unwanted history before upgrading data. After each stage backup your data in case the following process fails to complete correctly.

Use the following procedure to upgrade your data:

  1. Launch Omnis Studio (Design or Runtime).
  2. File -- Open Library and select the V2to3Upgrade.lbs library located in the Upgrading folder of the Vision directory tree.
  3. Navigate to your pre-version 3.00 data file when the Open Data File dialogue appears.
  4. A window will open from which you can start the data upgrading process.
  5. Because all new addresses have names or descriptions to help users identify them among many, you can at this point set the name for the default address.
  6. The process will take a considerable time and under no circumstances should it be interrupted. It is therefore recommended that the datafile should be local to the processing machine and unavailable to other users. Any automated screen-save, power-save or backup software should be disabled so that the process can be completed unhindered.
  7. When you are happy you are attached to the correct datafile and have set the name of the default address, click on the Convert Data ready for V3 button.
  8. When the process has completed, you should close Omnis Studio and launch Caliach Vision V3.00. When you then attach to the pre-converted datafile and log in, final data conversion to V3 (and/or further conversions) will be processed.
  9. The data will now be ready for normal use by the latest version of Caliach Vision.

Customisation Conversion

Because fields for addresses, telephone numbers, etc. have changed, any custom designs will now be obsolete. This particularly applies to custom documents, such as Sales Orders, Invoices and Purchase Orders.

Warning WARNING: Simply copying your custom classes into the new OpenVision.lbs from your ProgCode.usa in the normal way will cause any reference to the old file/field structure to be lost and effectively render the classes corrupt.

It is strongly recommended that where you have such designs that the designs be replicated using the new standard documents in OpenVision.lbs V3.00. Taking a pre-V3.00 design and, even with the conversion utility, attempting to use it with Caliach Vision V3 will produce unexpected results. This is because the converted Address and Contact data now resides in separate files from the master data and therefore needs to be appropriately fetched as well as rendered on a report.

Because, by their nature, custom reports are unique to a site it is impossible to devise a conversion tool that can fully convert a design into the new structure. Hence the strong recommendation that custom designs be re-designed from scratch using the new standards provided in OpenVision V3.00.

The following describes a tool that, in the most part, will convert obsolete fields into their new form so that, at least, the converted designs are not rendered corrupt when they are copied into the new OpenVision and then Caliach Vision.

To upgrade your custom classes, they need to be in a V2.10 OpenVision.lbs:

  1. Launch Omnis Studio Design.
  2. File -- Open Library and select the V2to3Upgrade.lbs library located in the Upgrading folder of the Vision directory tree.
  3. Navigate to your converted 3.00 data file when the Open Data File dialogue appears.
  4. A window will open and you will be told that the data has already been upgraded to V3.
  5. You can open the Customisation Conversion Tool by either using the Open Customisation Conversion Utility button at the bottom of the window or from the Upgrade Caliach Vision menu.
  6. This utility operates as a wizard and consists of three steps.
  7. First, click on the button to select the V2.10 OpenVision.lbs (it should also work with earlier versions), and click Next.
  8. Second, in the resulting class list select only the classes that are your customised classes that typically will have been in your ProgCode.usa file. Click on the Next button. Object scanning will then take place to locate instances of obsolete data elements.
  9. The resulting list of changes that will be made shows the details of the proposed change. You should at this stage print the results using the Print button. You need to do this so that after conversion you can review the changes to ensure that they have a suitable (see later) data record environment to work correctly.
  10. Finally, click on the Convert button to implement the changes.
  11. Note that the Trace Log will have opened automatically and will show any failure to make changes. This can be printed and the failures can be investigated and manually corrected. To do this, do not close the window as this will close the library.
  12. Having completed the Customisation Conversion, you can now open your old converted OpenVision using Caliach Vision V3.00 File -- Advanced -- Customisation Utility, then File -- Advanced -- Change Management System. Transfer your custom classes from the old OpenVision into a new ProgCode.usa, and from there into your new V3.00 or later OpenVision.
  13. Use normal techniques to test your custom classes.

Warning WARNING: Instances of obsolete fields are only scanned for in the following object types and attributes: All method lines. The $dataname attribute of kEntry, kCheckbox, kCombo, kMultilineEntry, kRadio object types. The $text attribute of the kText and kEntry (when $calculated=kTrue) object and the $calculation attribute of the kHeadedListBox object.

Hints and Tips on New Addresses

Firstly, an explanation. Prior to V3 Caliach Vision held a single address's data within master data records for customers, marketing and suppliers. With customers and suppliers additional addresses could be added but only within marketing could there be more than one contact per address. Version 3 rationalised this so that master records can have any number of addresses and each address can have any number of contacts. Each is stored in its own file and linked to the master record using the ADRLINK field which is constructed using a prefix of CUS, DEA, DEL, SUP followed by the unique identifier of the master record. For example:

Each Address and contact record contains unique identifier numbers (ADRID and ADCID). In turn, master records contain a field for the default address, CUSDADR, DEADADR and SUPDADR. Note that Delivery Addresses are special in this respect as only one address record is allowed per Delivery Point so there is no need for a default address.

Contact records are optional for addresses. An address record can have no associated contacts or many (a maximum of one in the case of Delivery Details). Contact records are linked to the address record with the address record identifier stored in the ADCADR field. A default contact for the address is stored in the ADRADC field in the address record. So, for example, the default address and contact for a customer would be available in the CRB (current record buffer) after the following code segment:

Single file find on ADRID (Exact match) {CUSDADR}
Single file find on ADCID (Exact match) {ADRADC}
Single file find on CONCODE (Exact match) {ADRCONC}

Alternatively, for a report, the same thing could be achieved using a series of fields with the $calculated and $autofind properties set kTrue and the $visible property set kFalse:

$dataname=ADRFILE.ADRID, $text=CUSDADR
$dataname=ADCFILE.ADCID, $text=ADRADC
$dataname=CONFILE.CONCODE, $text=ADRCONC

All address, contact and country fields will then be available to the right and below the above autofind fields.

However, in most cases the work of linking address and contact data will have already been carried out by the programme. In particular this applies where documents are produced. Typically, documents have two addresses, invoice and delivery (for SOs, Jobs, Invoices, etc.). These will be stored in the document record:

SOHINVA and SOHIADC: SO Invoice address and contact
SOHCADS and SOHDADC: SO Delivery address and contact
INVINVA and INVIADC: Invoice/CN/Despatch Note Invoice address and contact
INVCADS and INVDADC: Invoice/CN/Despatch Note Invoice address and contact
JOBINVA and JOBIADC: Job Invoice address and contact
JOBCADS and JOBDADC: Job Delivery address and contact
POHCADS and POHADC: PO supplier address and contact
PUHCADS and PUHADC: Received PO supplier address and contact
SNOADR and SNOADC: Serial Number location address and contact
SNTADR and SNTADC: Serial Number Tracking record location address and contact

There is also a document linking and address/contact formatting system built into documents and this is only available using the built-in methods of the document superclass or the oAdrAdc object standard methods. To establish what is available, you should examine the standard documents in OpenVision. These are single multi-line text fields so should have the $vertextend property set kTrue and be immediately followed by a positioning section so that they can flow downward. You should where possible avoid using ADRFILE and ADCFILE fields separately as you can not guarantee which address/contact is set in the CRB. For example, the rSalesOrder standard Sales Order document design has four field as follows:

There are also standard methods that can be called to generate this address and contact data, either in a Do command in a method or as a calculation for a field.

Method (parameters)

Function

$ctask.tAdrAdc.$PrintDocAddress(pAdrId, pCompanyName, pAdcId, pDocType, pTelecoms)

Run to prepare addresses on documents. Designed for documents with explicit address id, such as SOs, in pAdrId. Returns formatted address for printing and telecoms in pTelecoms. For example for a Job Address:

Do $ctask.tAdrAdc.$PrintDocAddress(JOBINVA,CUSCNAM,JOBIADC,'JOB',iJobTelecoms) Returns iJobAddress

The above would be in a method. You can also use it in a calculated field in this form where iJobTelecoms is an instance variable that is printed to the right or below the address field:

$ctask.tAdrAdc.$PrintDocAddress(JOBINVA,CUSCNAM,JOBIADC,'JOB',iJobTelecoms)

$ctask.tAdrAdc.$PrintLetterAddress(pAdrId, pCompanyName, pAdcId, pDocType, pContact)

Run to prepare addresses on letters. Returns formatted address for printing and Contact and Job in pContact. For example, this would be appropriate for a marketing letter:

Do $ctask.tAdrAdc.$PrintLetterAddress(ADRID,ADRCNAM,ADCID,'LETTER',iContact) Returns iAddress

You could use this in a $printrecord method of a report. iAddress would then be the $dataname of the field showing the address and iContact would be for the Attn: Name and Job Title.

$ctask.tAdrAdc.$DefaultAdrAdc(pDefaultId)

This is a simple method that sets the ADRFILE and ADCFILE in the CRB based on the AddressId passed in pDefaultId. This is the easiest way of joining address and contact data to a master record where all you want is the default contact for the default address. After its use you can then make use of ADRFILE and ADCFILE data.

For example, in a customer listing report you may want to show the country (linked to the address) and the contact's email address or other data. You would place this method in the $printrecord method (or in a calculated field, although it returns no explicit value):

Do $ctask.tAdrAdc.$DefaultAdrAdc(CUSDADR)

$ctask.tAdrAdc.$DocAdrAdc(pAdrLink, pDocType, pDefaultAdr, pAdrId, pAdcId, pInco, pIncp)

Sets up ADRFILE and ADCFILE in CRB for the linked master record set in pAdrLink (e.g. con(''CUS',CUSCODE) ) and document type in pDocType ('SO' etc). If no address link is found pDefaultAdr is used. pAdrId, pAdcId, pInco and pIncp are populated with ADRID, ADCID, ADRINCO and ADRINCP. No explicit value is returned.

This method can be used to obtain the address and contact data complying with the document link system. For example, you may wish to build a report that will list details of customer linked addresses and contacts for statements. You would use the following in the $printrecord method:

Do $ctask.tAdrAdc.$DocAdrAdc(con('CUS',CUSCODE), 'CusState', CUSDADR, iAdrId, iAdcId, iInco, iIncp)

The four final parameters are optional and in most circumstances of no use.

Work Order Route Changes

In addition to the address and contact structural change, V3.00 introduced independent Work Order Operation Routes. This will effect any customisation associated with Shopfloor data collection or work-in-progress. These changes have added a data structure and have not led to any data field removal, so customisation will not be corrupted, but customisation may well need to be changed to accommodate the new independent route structure.

When a WO is created a copy of the Operation Route is stored in the new WOOFILE. This can then be modified so that alternate operations can be accommodated. The operation records associated with a WO are then deleted when the WO is complete, but whilst the WO is active (before and after kitting and throughout its active life when backflushed) any previous reference to the PROFILE should be changed to the new WOOFILE. The following fields should therefore be substituted:

Old

New

PROPTNO

Changed to the key field WOOWONO exact match to WKOWONO

PROOPNO

WOOOPNO

PROINST

WOOINST

PROSETT

WOOSETT

PRORUNT

WOORUNT

PROLEAD

WOOLEAD

PROTXW

WOOTXW

PROWKC

WOOWKC

PROMASS

WOOMASS

PROXTRA

WOOXTRA

PROALT

WOOALT

Work Order document record sections typically contain PROFILE fields. These should be altered based on the above table. The simple way of doing this is to use the Omnis Studio design Find and Replace function, restricted to your custom classes in your OpenVision, to Find All on PRO, case-sensitive. Any found, then, in most cases, replace with WOO.

Customised shop floor data collection features will need to be modified by your support provider, who will charge accordingly.

Compiled in Program Version 5.04. Help data last modified 4 Jun 2012 04:48. No class.