This section describes in detail how to carry out the new customer tasks in the installation workflow described in the Overview (on page 7).
Install Step Notes
Set up a basic SPARCS N4 topology (on page 134)
This is only necessary for new customers, or if you have changed your topology.
Load initial reference data (on page 133)
This is only necessary for new customers.
Create a Yard Model and Configure the Yard (on page 141)
This is only necessary for new customers.
Load initial reference data
This task is only necessary for new SPARCS N4 customers. If you are upgrading from an earlier version of SPARCS N4, this information is already in your database.
Before you can set up a basic topology and implement an SNX import, SPARCS N4 requires three types of initial reference data at the global scope level (on page 138):
ISO Codes - Standard equipment types for the Equipment Types view at a global scope level.
SPARCS N4 also associates the equipment types with the appropriate icons that XPS uses to represent the equipment type.
UNLOC Codes - United Nations (UN) Location codes.
Line Operators - A default list of master organizations, including line operators.
SPARCS N4: Installation Guide 2.4 133
Process for loading initial reference data at the global scope level
To load the initial reference data at the global scope level:
1 Log in to a Cluster node host at the Global scope level (see Verify SPARCS N4 node installation with a first startup (on page 62) for instructions.)
2 Generate ISO Codes.
This step adds the standard equipment types to the Equipment types view at a global scope level, and also lets SPARCS N4 associate the equipment types with the appropriate icons that XPS uses to represent the equipment type.
a. Open the Set-up Database view: Administration DBA Set-up Database.
b. Click Generate ISO Codes. The ISO codes load. When the progress bar fills with color, it is finished.
3 Import UNLOC codes.
This step adds the list of UNLOC codes to various forms throughout SPARCS N4.
From in the Set-up Database view, click Import UNLOC Codes. The UNLOC codes load. When the progress bar fills with color, it is finished.
4 Import Line operators. This step adds a default list of master organizations to the Master
Organizations view at a global scope level, and makes them available for the SNX import. For more information about SNX imports, see Implement the SNX import in the SPARCS N4 Administrator's Manual.
From in the Set-up Database view, click Import Line Operators. The Line operators load. When the progress bar fills with color, it is finished.
The initial reference data is loaded.
Set up a basic SPARCS N4 topology
Installing the core components of SPARCS N4 requires you to define a topology—the hierarchy of your physical operation. If you are upgrading to version 2.4, the database reads your existing topology into 2.4 when it first starts up.
(It gets this information from the database backup.)
However, if you are a new SPARCS N4 customer, you must set up a topology using the Administration DBA Topology view in the SPARCS N4 client.
The topology you set up roughly reflects the physical and legal structure of the operations at your terminal. Your Navis representative will work with you to fine-tune these categories. To review general
134 SPARCS N4: Installation Guide 2.4
terms and concepts about topology and scope levels, see Scope levels (on page 138), in the appendix.
Before you attempt to set up a basic SPARCS N4 topology, you must have already loaded the initial reference data (on page 133) at the global level. If you have not done this, you will not be able to create a facility or a yard.
Topology Element
Description Source
Operator Code
Your Navis customer code. Get this from your Navis representative.
Complex Code
The United Nations (UN) location code for the city in (or nearby) which the complex is located.
The UN location codes are part of the initial reference data you loaded in to SPARCS N4. However, you can also look this up at the UN website:
http://www.unece.org/cefact/locode/service/location.htm
Facility Code
The natural name of the terminal, usually as a set of initials, or an acronym.
Determine this with your Navis representative.
Yard Code
The code used for the yard.
It should be the same as the facility code.
Determine this with your Navis representative.
The diagram below illustrates the basic process. We have greatly simplified it here to streamline the steps during installation. Once you have verified that the various components of the SPARCS N4 installation are communicating and functioning correctly, you can go back and configure the many different options that essentially customize SPARCS N4 operations for your terminal. These options include whether or not you have multiple complexes, facilities, and yards; your master organizations, routing points, operator types, cargo types, equipment types and uses, etc.
Process for setting up a topology in SPARCS N4
SPARCS N4: Installation Guide 2.4 135
To set up a basic topology for testing a SPARCS N4 installation:
1 Log in to the SPARCS N4 client at the Global scope level:
a. From a networked client, open a web browser.
b. Enter the path to SPARCS N4 through the load balancer. This has the following format:
http://loadbalancer.example.com/apex/apex.jnlp, where
loadbalancer.example.com represents the host address of the load balancer. The client application downloads, and a SPARCS N4 Login window appears.
If you do not have a load balancer installed, enter the path to a node:
http://[sparcsn4hostip]:[port]/apex/apex.jnlp
c. Enter your Username and Password in the SPARCS N4 Login dialog, and click Login. A Site Selection dialog appears.
d. In the Site Selection dialog, locate the Operator drop-down list, and select -. SPARCS N4 automatically selects - in the other drop-down lists.
e. Click Go!.
2 Add an Operator:
a. Open the Operators view: Administration DBA Operators.
b. Click Add on the top right. The Add Operator dialog opens.
c. In the Add Operator dialog, leave the Organization field blank.
d. In the Operator field, enter an ID that uniquely identifies the operator in the system. This is your Navis Customer code, which your Navis representative provides.
Required fields in SPARCS N4 have a pale green highlight.
e. Optionally, in the Operator Name field, enter a descriptive name for the operator.
f. Leave the Enforce One Active Unit check box clear for now.
g. Click Save. The Add Operator dialog closes, and the operator appears in the list in the Operator view.
3 Add a Complex:
a. Open the Topology view: Administration DBA Topology. A list of operators appears in the left frame.
b. Select the operator you created in step 2.
c. Click the Add Complex button above the list of operators. An Add Complex dialog opens.
d. In the Complex field, enter a unique identifier for the complex. During installation, you simply use the United Nations (UN) location code for the city in (or nearby) which the complex is located.
e. Optionally, in the Complex Name field, enter a descriptive name for the complex.
f. From the Time Zone ID drop-down list, select the ID of the time zone local to the complex you selected.
g. Click Save. The Add Complex dialog closes, and the complex appears in the hierarchy under the operator.
4 Log out of SPARCS N4 (File Exit), and log back in again at the Complex scope level:
a. After you enter your Username and Password in the SPARCS N4 Login dialog, a Site Selection
136 SPARCS N4: Installation Guide 2.4
dialog appears.
b. In the Site Selection dialog, locate the Operator drop-down list, and select the operator you created in step 2. SPARCS N4 automatically selects the complex you created in step 3 in the Complex drop-down list.
c. Leave the drop-down lists for Facility and Yard null.
d. Click Go!. SPARCS N4 opens.
5 Add a Routing Point. A routing point specifies a terminal or rail hub associated with a port or city, for both port and inland destinations. For the purposes of installing SPARCS N4, simply create a routing point associated with a nearby route from your terminal.
In SPARCS N4, you can add routing points only for the current scope level.
a. Open the Routing Points view: Configuration Routing Routing Points. Then click the '+' button on the top right. The Add Routing Point dialog opens.
b. In the Point ID field, enter an ID that uniquely identifies the routing point. You can enter up to six characters in this field.
c. From the UnLoc Code lookup field, select the UN/LOCODE for the routing point.
d. Click Save. The Add Routing Point dialog closes, and the new routing point appears in the list.
6 Add a Facility:
a. Open the Topology view: Administration DBA Topology.
b. Select the complex you created in step 3.
c. Click the Add Facility button above the list of operators. An Add Facility dialog opens.
d. In the Facility field, enter a unique identifier for the facility.
e. Optionally, in the Facility Name field, enter a descriptive name for the facility.
f. From the Routing Point lookup field, select the routing point for the facility. The routing point is usually the port or city code for the facility, but you can select the routing point you created in step 5.
g. Leave the optional fields blank for now.
h. Click Save.
7 Add a Yard:
a. From the Topology view (Administration DBA Topology), select the facility you created in the previous step.
b. Click the Add... button above the Operator in the left pane. An Add Yard dialog opens.
c. In the Yard field, enter a unique identifier for the yard. The value you enter for Yard must not be longer than six characters.
d. Optionally, in the Yard Name field, enter a descriptive name for the yard.
e. From the XPS State drop-down list, select READY. This is the normal state for a yard using XPS.
f. Click Close. The yard is created and appears in the topology under the facility for which you created it.
The yard is not yet functional. You must still create a yard model using the Yard Model form,
SPARCS N4: Installation Guide 2.4 137
and link it to a yard created in the Topology view through the Owning Yard field. Further, you must use the Yard Editor to describe the details of the yard and to apply the yard model changes to become active.
A basic topology now exists in SPARCS N4.
Scope levels
In SPARCS N4, scope levels represent organizational hierarchy, also called topology, that defines the levels at which reference and operational data is available to a user. The scope levels also determine the applicable configuration settings and menu options available to the user. The scope levels, from high to low, are:
Global
Operator
Complex
Facility
Yard
Scope levels reflect the organization of marine terminal operators, as shown in the following diagram:
A user logs into SPARCS N4 at a specific operational scope level. This enables the user to access information that exists at that scope level and at any lower scope levels.
Global
The global scope level is the highest scope level that a user can log on in SPARCS N4. You use the global scope level to set up the system, add an operator, and set up some of the reference data for your site. The data defined at the global scope level is available at all the lower scope levels.
Operator
An operator is a single client using the system, including all the complexes, facilities, and yards. An operator can have several complexes that may operate independently of each other. An operator can choose to have different reference data at each complex. For more information, see Entity Set view and Entity Set Use view in the SPARCS N4 application help or the SPARCS N4 Administrator's Guide.
Complex
A complex is a collection of facilities that use the same reference data, such as port codes, routing points, services, commodity codes, and equipment types. This means that:
138 SPARCS N4: Installation Guide 2.4
A specific container visit (unit) can reside in the Active state only at one facility within a complex at any one time.
Example:
You cannot make a container in one facility active at another facility within the same complex before it departs the prior facility.
A vessel visit is associated with a single facility of the complex, but it is visible and actionable across all facilities of the same complex.
Example:
A vessel visit calling a specific facility within a complex can have multiple cutoff times, one per facility within the complex, for receiving containers. In this example, an actionable item is the definition of various cutoff times for each of the facilities within the complex.
Sharing reference data ensures that business entities, such as vessel visits and bookings, which reference a single facility, are visible and actionable across all the facilities of the complex.
Examples:
A set of terminals comprising a facility with:
A quay for vessel-based container load and discharge operations
One gate complex to receive and deliver containers on trucks
A rail ramp with four rail tracks managing the receival and delivery of containers via trains
An empty container depot 10 kilometers from the marine container terminal receiving and dispatching empty containers
To dispatch empty containers, you can use vessel bookings for vessels that are departing the marine terminal. You can use the same booking entity that you create at the marine terminal to validate empty dispatch at the empty depot.
A small percentage of dispatched containers are not for bookings that are departing from the marine terminal but for other purposes, such as repositioning of line operator equipment, repairs, or off-hires.
A rail terminal 100 kilometers from the marine container terminal with:
One gate complex to receive and deliver containers on trucks
A rail ramp with four rail tracks managing the receival and delivery of containers via trains Export containers are received into the rail terminal against vessel bookings for vessels that are departing the marine terminal.
Vessel cutoff times are greater than at the marine terminal to deal with the rail transit time from this terminal to the marine terminal.
All containers arriving via truck at the rail terminal depart for the marine terminal via rail and all containers arriving via rail originate at the marine terminal and depart by truck from the rail terminal.
Facility
A facility is a uniquely identifiable transport hub located at a specific geographic location and identified by a unique address.
A facility may include multiple gates, yards, vessel berths, and rail ramps, all of which are contained within the bounds of a single secure area with specific points for the movement of containers and cargo
SPARCS N4: Installation Guide 2.4 139
(gate, vessel load and discharge, and rail load and discharge) in and out of the facility.
All SPARCS N4 operational data (versus reference data) is associated with a specific facility. This includes, but is not limited to, vessel visits, train visits, and container visits (units).
Example:
A single container terminal with:
3 adjoining berths
2 gate structures, one for the receival and delivery of full containers and the other for the receival and delivery of empty containers
A container freight station for the stuffing and stripping of containers
A combination of a fence and water bounds all of the above operations. The movement of containers into and out of the facility is limited to the two gate structures and vessel operations (load and discharge).
Yard
A yard is a discrete and named area within a facility. A facility can only have one yard. Because a complex can have multiple facilities, a complex can have multiple yards. Reference data, configuration settings, and user access privileges shared at the yard level apply only to the selected yard.
Apply your license to SPARCS N4
SPARCS N4 requires that you upload the signed license file you receive from your Navis representative.
Your license file contains information about all functions you have licensed from Navis. Without the license, critical privileges for creating, modifying, and deleting content from SPARCS N4 are not available.
The following instructions walk you through the process from the Licenses view in SPARCS N4.
You apply licenses to each node, including the Center node, and must be logged in at the Facility level.
Users can start using the features associated with the license when you upload a new license into the database, and apply it to the nodes in the cluster (on page 109). You use the Licenses view to upload a new license file into the database for your site.
To upload a license file to the database:
1 Make sure you are logged in at the facility level.
Licenses apply at the facility level. You must be logged in at the facility level to load and apply SPARCS N4 licenses.
2 In the Licenses view (Administration Security Licenses Licenses view), click .
3 In the Import License form, select the appropriate folder and the license file that you want to upload.
If the selected license file is not valid, SPARCS N4 displays an error message.
If a license already exists for the scope and the new license file is a valid license file, SPARCS N4 overwrites the existing license with the new license file.
If you cannot successfully upload a new license, the existing license remains unaffected.
4 Click Open.
5 Click to view the new licenses in the Licenses view.
6 For the new license to take effect, reload the license for each node in the cluster. Licensing in SPARCS 140 SPARCS N4: Installation Guide 2.4
N4 is effective per node.
The new license takes effect when you log in to SPARCS N4 the next time and you can assign appropriate privileges to various roles to enable the end users to use the new features.
See the SPARCS N4 Help module for information about assigning privileges and roles to users.
Create a Yard Model and configure a placeholder yard
Installing the core components of SPARCS N4 requires a fully-configured yard. If you are upgrading to version 2.4, the database reads your existing yard information into version 2.4 when it first starts up. (It gets this information from the database backup.)
However, if you are a new SPARCS N4 customer, you must configure a yard model with bin name tables, reference points, a perimeter, etc., and apply it to the yard you created in the Administration DBA Topology view. To prevent you from having to go through a lengthy configuration exercise before getting the basic system components up and running, Navis has created the details for a 'placeholder' yard that you can use during installation.
The diagram below illustrates the basic process. We have simplified it here to show only the steps you need to take to create a placeholder yard. Once you have verified that the various components of the SPARCS N4 installation are communicating and functioning correctly, you can go back and configure your actual yard. Full instructions are in the SPARCS N4 Administrator's Manual.
SPARCS N4: Installation Guide 2.4 141
Initial Yard Configuration with Yard Editor (Without Legacy Files)
Create a placeholder Yard Model
A yard model describes the physical layout of the container terminal facility to the functional modules in SPARCS N4. It is key to keeping track of the container inventory and making intelligent decisions concerning container movements.
A yard model consists of the naming tables that reference the blocks in your yard. Defining these naming tables is part of creating a yard model.
The Yard Models view (Configuration Models Yard Models Yard Models view) lists the yard
142 SPARCS N4: Installation Guide 2.4
models that exist at the current scope level (Facility or Yard). Multiple yard models may exist per yard, but only one yard model can be active. The Active column indicates which yard model is active. The
models that exist at the current scope level (Facility or Yard). Multiple yard models may exist per yard, but only one yard model can be active. The Active column indicates which yard model is active. The