With SPARCS N4 version 2.4, there are few important actions existing customers need to take upon upgrade. These are tasks that have been mentioned as critical actions in the SPARCS N4 2.4 Release Notes.
*Critical Actions* Conditions
Upgrade your database-backed variforms (on page 74)
For upgrading customers who have overridden any system variforms, or who have created custom variforms.
Remap some flex fields to standard fields (on page 77)
For upgrading customers who have created user fields or flex fields to accommodate attributes that now have standard fields.
Configure the SPARCS settings.txt file (on page 78)
For upgrading and new customers.
Review automatic yard block conversions (on page 86)
For upgrading customer who have logical blocks defined in their pre-2.2 yard file.
To do this, you must import an image map of your yard (on page 84).
Prepare for proper conveyance of vessel berthing information to XPS (on page 97)
For upgrading customers. This task ensures that XPS clients properly display berths and update berth locations for the vessel schedule.
Convert data from legacy SPARCS or test systems for XPS (on page 98)
For upgrading customers. Navis has created a simple procedure for converting data from XPS Test systems to live production systems, or from SPARCS legacy systems.
Retest Groovy Code Extensions (on page 102)
For upgrading customers who use Groovy code extensions. With the N4 2.4 release, the Groovy library is upgraded to release 1.8.6.
Instructions for general post-installation set-up tasks are in the SPARCS N4 Administrator's Manual.
Optional Actions Conditions
Configure unicast communication (on page 105)
For upgrading customers who want to post-configure for the unicast protocol.
Contact your Navis representative, or read the Frequently asked questions for unicast mode (on page 107) if you have questions about whether to configure with unicast.
Import a gate configuration (on page 108)
For upgrading customers.
SPARCS N4: Installation Guide 2.4 73
Optional Actions Conditions
Upload the license file (on page 109) For upgrading customers who have changed their licensing.
Upgrade database-backed variforms
Navis has made structural changes to certain forms for SPARCS N4 versions 2.2 and above. If you have overridden any of these forms using the database-backed variform override functionality, you will need to perform specific upgrade actions in order for these forms to work.
The following changes make upgrade actions for database-backed variforms necessary:
With each release, Navis is converting selected forms and tables in SPARCS N4 to be platform neutral.
This requires a change to the XML for that form. Therefore, when a form or table is made platform-neutral, any existing database-backed variform override to that form or table will not work without an upgrade action.
Actions:
Before the upgrade, export your database-backed variforms to a temporary location. See Export database-backed variforms before backing up (on page 14).
Immediately after the upgrade, you must reapply your database-backed variform changes to the new platform-neutral form or table. Note that the XML syntax for the platform-neutral form is different from the syntax used in your original variform override. For instructions, see Re-create database-backed variform customizations to platform-neutral forms (on page 74).
For versions 2.2 and above, database-backed variforms use an .xsd schema instead of .dtd.
Additionally in versions 2.2 and above, you can select a scope for each of your database-backed variforms. Therefore, if you are upgrading from a version below 2.2, and if your terminal has
overridden any system variforms, or if you have created custom variforms, you must convert them to use the new .xsd schema. This means the database table config_variform should not contain any records that use .dtd as the schema.
Action: Immediately after the upgrade, you must change the header lines in all of your overridden variforms to refer to the .xsd schema. For instructions, see Convert .dtd variform overrides to .xml variform overrides (on page 76).
Re-create database-backed variform customizations to platform-neutral forms
Navis is in the process of changing SPARCS N4 forms and table views to be platform-neutral to make them more configurable. Platform-neutral forms let you have more detailed control over the layout, and let you add your own before-commit, commit, and after-commit actions. (Note: The after-commit actions that are supported only apply to the UI tier or to a custom table where the update is not part of core business functionality.)
However, when Navis makes a form platform-neutral, any existing database-backed variform override to that form will not function without an upgrade action. The previously functional forms appear with the buttons grayed-out and unavailable. You must reapply your variform changes to the new platform-neutral form.
74 SPARCS N4: Installation Guide 2.4
To find out whether an existing SPARCS N4 form or view is platform-neutral, click the info button for the form or table. A view-only form opens, showing the variform code definition. The first line in platform-neutral forms is: "NOTE: This form view supports form submission code extension." For a table, a line similar to the following in the top section (usually the second or the third line from the top) indicates that it is platform-neutral: "Table Shared UI Manager:
com.navis.carina.announcement.presentation.AnnouncementSharedUiTableManager@
40bef321".
To re-create each deleted database-backed variform after the upgrade:
Before upgrading to a new version, to maintain any previous variform customizations during an upgrade to a SPARCS N4 version that contains platform-neutral forms, it is essential to export your existing variform overrides to a temporary location. For instructions, see Export database-backed variforms before backing up (on page 14).
1 In the Database Backed Variforms view (Administration Settings Database Backed Variforms Database Backed Variforms view), select Actions Override a Variform Object.
2 Select the appropriate variform scope level and object type. For more information, see Override for a Variform Object form in the SPARCS N4 help or the SPARCS N4 Administrator's Guide.
3 Check the release note for the converted platform-neutral form to see if the variform ID has changed.
If not, for Variform ID, select the original ID for the variform you want to override. If the variform ID has changed, select the new variform ID from the list.
If you cannot find the variform ID, check the release note to see if it has changed.
4 Click Edit Contents. Then copy and save the variform definition as a backup.
Do NOT first select Import File, then re-import the original file you used for the original database backed override. This will overwrite the upgraded form. Instead, select Edit Contents. Also, it is critical that you back up the contents of the new variform definition in case you have to roll-back after creating the override.
5 Open the original override definition that you exported before the upgrade.
6 Identify the customizations in the original override definition and integrate them into the new variform definition.
It is recommended that you include inline comments to identify the changes you have inserted and comment out the elements that you want to remove.
7 Enter the name for the override in the Name field.
8 Click Save.
9 In the Database Backed Variforms view, select the override, then select Actions Reload All Variforms. A dialog box opens, asking if you want to update only the local node or all nodes. Select Only update local node.
10 Test the database backed variform override on the local node. If there are any problems with the override, you can re-import the backup you made before you reintegrated the changes for the override.
11 Once you have confirmed that the override works, return to the Database Backed Variforms view, again select the override, and then select Actions Reload All Variforms. When asked you if you want to update locally or on all nodes, select Propagate change to all nodes.
SPARCS N4: Installation Guide 2.4 75
Convert .dtd variform overrides to .xml variform overrides
If you are upgrading from any version of SPARCS N4 below 2.2, immediately after the upgrade, you must change the header lines in all of your overridden variforms to refer to the .xsd schema. If you do not do this, you will see the following errors when testing:
Error log examples:
[REQUIRES IMMEDIATE MANUAL ATTENTION: db-backed variform record 'test' needs to be converted to use new schema 'Variforms.xsd'. Please correct problem once the application starts.
[REQUIRES IMMEDIATE MANUAL ATTENTION: db-backed variform record 'test'.
Validation exception: xxx ]. Please correct problem once the application starts.
If you are upgrading previously-scoped forms, SPARCS N4 preserves the scope on import. You do not need to re-specify scope for your database-backed variforms. Pre-2.2 variforms with no scope default to Global scope. Therefore, if you are upgrading from a version of SPARCS N4 that did not allow scoped overrides, you can review your override forms to identify whether it makes sense to restrict scope at this time.
To convert .dtd variform overrides to .xml variform overrides:
1 In the Database Backed Variforms view (Administration Settings Database Backed Variforms), double-click an overriden variform.
2 In the Variform File Definition form, replace the .dtd header information with the .xml string, as follows:
a. Above the Contents Edit Area, click Edit Contents. The Contents Edit Area becomes editable.
b. If applicable, replace the following lines:
<!DOCTYPE variforms PUBLIC "" "Variforms.dtd">
<variforms>
SPARCS N4 validates your changes and alerts you to any validation issues. If no issues occur, the Edit Variform File Definition form closes.
d. If errors occur while saving the form, correct the errors. SPARCS N4 does not save the form if there are validation errors.
3 Repeat step 2 for all records in the Database-Backed Variforms list.
4 After changing all records in the list, select Actions Reload All Variforms. The Variforms Reset form appears.
5 In the Variforms Reset form, select the Only update local node option to test the form locally before propagating the changes to all nodes. This is strongly recommended.
Only select the Propagate changes to all nodes option after testing the changes locally.
76 SPARCS N4: Installation Guide 2.4
6 Click OK. The Variforms Reset form closes, and the new forms are propagated to all nodes.
Remap some flex fields to standard fields
The SPARCS N4 XPS client has an integer value that serves as a protection against unreasonable values in the settings.xml file. The XPS client refuses to start if the number of characters for the data fields for the container object are set too high. Since there are many new fields added to the container object in releases 2.1 and above, Navis has raised the "too high" threshold value for releases 2.1 and above.
This indicates an important related action for customers who are upgrading to SPARCS N4 2.4:
Many sites on earlier versions have created user fields or flex fields to accommodate attributes that now have standard fields. To get full system functionality, you must use the standard field.
This may require:
Remapping EDI. For instructions, see EDI Message Map form in the application help.
Changing groovy code. For instructions, see Direct code injection with Groovy in the SPARCS N4 Administrator's Manual.
Here are some standard XPS fields for which many customers have created flex fields. Please review all of your Flex Fields before upgrading, and revert to using the standard field if necessary.
fCntrTruckCompany fCntrTruckDriver fCntrCustomsAgent fCntrShipper fCntrConsignee fCntrContainerGrade fCntrImportDelivGroup fCntrECn
fCntrOpdPort1 fCntrBillOfLading fCntrFireCode fCntrOrigin fCntrBoxStrength fCntrLowBillOfLading fCntrBookingRelease
SPARCS N4: Installation Guide 2.4 77
Configure the SPARCS settings.txt file
The SPARCS settings.txt file contains configuration settings for XPS that the server must share with the clients. You use it to customize XPS for your terminal. You can enable or disable standard XPS features as they suit your operational needs, change the titles for container attributes, modify the format of printed reports, and even create different formats for the same report to accommodate the needs of various line operators.
SPARCS settings.txt is a tab-delimited text file that you can view and edit using a simple text editor or spreadsheet program such as Microsoft Excel. Your Navis representative provides an initial file that has many of the optimal settings we think you need. However, you can review it to fine-tune it before
importing it into SPARCS N4 when you create a topology (on page 134).
See the Settings Management and Diagnostics chapter in the SPARCS N4 Administrator's Guide for details about each segment in SPARCS settings.txt.
Do not confuse the SPARCS settings.txt file with the settings.xml file, which also used for XPS configuration. The settings.xml file contains licensing data, data sizes, log levels and other elements that configure XPS against SPARCS N4. It is stored at the installation root level, whereas the SPARCS settings.txt file is stored in the data folder, one level down.
If you open the SPARCS settings.txt file with a spreadsheet program, be sure that when you save it and close it, keep the file in the .txt format. Do not save it as an .xls or .xlsx file.
Tips for upgrading with the Yard Editor
During a point upgrade to SPARCS N4 version 2.4, you start up SPARCS N4 for the first time against a database backup that you took from a previous version. Starting up SPARCS N4 2.4 loads the yard data into the new Yard Models and Yard Editor views, and makes it the active yard. When you install and start version 2.4 of the Bridge daemon and then the XPS server for the first time, SPARCS N4 pushes the yard file from the backed-up database to the cache. XPS loads the yard file from the cache. (As does ECN4, if you are using it.) If there is a yard file in the XPS data folder, SPARCS N4 overwrites it with the yard data from SPARCS N4.
In versions 2.4 and above, the Yard Editor does not open from the Yard Models view in SPARCS N4 (Configuration Models Yard Models). To optimize performance, Navis has made the Yard Editor view available instead in an internet browser.
To access Yard Editor, go to
http://<machine_name_of_N4_cluster_node:port/apex/yard.zul (The port number is either 9080 or 10080, as noted in the services.) You can log in using your SPARCS N4 username and password. Once logged in, select: Models Yard Models Yard Models view.
78 SPARCS N4: Installation Guide 2.4
Tips for setting up your existing yard
When you initialize SPARCS N4 2.4 for the first time against a backup of an earlier version, the yard in the backup automatically becomes the active yard in the Yard Editor. The Yard Editor does not permit manipulation of an active yard, so you must clone the active yard to manipulate your existing data in the visual GUI provided by the Yard Editor.
It can be very helpful to refer to a screen capture of your yard's Plan View in XPS when you are placing your blocks.
Even though the data for yard.nyd is already being used in the active yard, the first time you clone the active yard model after starting up against an earlier version's database backup, you also need to import the active yard.nyd file. Once you do this, the bin name tables for the active yard appear in the clone.
You also have to import the yard.nyd for the active yard.
When you import a compiled yard file, SPARCS N4 prompts you to reset the geometries for the imported yard model. If you accept, SPARCS N4 disregards the geometric information included in the yard file in favor of the geometries defined in the Yard Editor.
In general, it is a good idea to reset the geometries, assuming that the geometric information provided in the Yard Editor is more accurate. If you decide not to reset the geometries, you can still do so at a later stage.
Getting started with placing existing blocks in the Yard Editor:
1 With XPS and the Bridge daemon shut down, open the Yard Models view in SPARCS N4 (Configuration Models Yard Models).
2 Clone the active yard in the Yard Models view (Right-click the Active Yard Model Clone).
While cloning the yard model, SPARCS N4 displays a progress bar.
3 Open the Yard Editor (with an internet browser, go to
http://<machine_name_of_N4_cluster_node:port/apex/yard.zul (The port number is either 9080 or 10080, as noted in the services.) You can log in using your SPARCS N4 username and password. Once logged in, select: Models Yard Models Yard Models view) and import the yard.nyd file for the active yard model (Actions Import Compiled Yard File).
4 Import an image map of the yard (Actions Import New Map). For more information, see Tips for working with yard image maps (on page 81) and Import an image map of your yard (on page 84).
Once the image is imported, the reference point tool appears.
If the image map does not appear after about 30 seconds, close the Yard Editor tab and reopen it.
If you need to reload the image map, do not reload a new image over one you previously imported. Instead, start over and create a new clone.
5 Using the reference point tool , configure two reference points on the image map. For more information, see Import an image map of your yard (on page 84). When two reference points are configured, the yard perimeter tool appears.
6 Using the yard perimeter tool , draw the perimeter of the yard. On the map, start drawing the perimeter line by clicking an anchor point (sometimes, one of the reference points makes a good anchor point), and move clockwise or counter clockwise.
SPARCS N4: Installation Guide 2.4 79
It is helpful to have the whole yard visible while drawing the perimeter. The orange circle that acts as the pointer turns corners when you click once, and remains engaged until you double-click the starting point.
Drag and click at each corner to draw each leg of the perimeter, and then move on. SPARCS N4 colors the designated area orange.
Complete the perimeter by double-clicking the initial anchor point. SPARCS N4 replaces the orange markup with a solid black line.
7 Now you are ready to add elements to the map. Because you imported an existing yard file, your yard blocks are already defined. Therefore, you will choose the option to place existing blocks instead of adding (creating) new ones.
If you have a screen capture of the Yard Plan view from XPS, now is a good time to review it. Decide which block to place; then, in the Yard Editor, choose the appropriate tool. The tools available are:
to add a stack block
to add a non-stack block
to add a track plan
to add a berth
8 Locate the point on the image map for the lower left corner of the block you intend to place. On the map, do one of the following:
For a stack block: Click the anchor point for the lower left corner of the block.
For a non-stack block or track plan: Click the map for the first anchor point; drag the pointer and click each anchor point of the block or track plan; double-click to finalize the outline.
For a non-stack block or track plan: Click the map for the first anchor point; drag the pointer and click each anchor point of the block or track plan; double-click to finalize the outline.