Document toolboxDocument toolbox

(2024.1) Cable Path Full Imports

Owned by Brian Dixon
Last updated: Mar 28, 2024
9 min read

Capability

This Import allows the User to INSERT new records or UPDATE Services, Equipment, Ports/Pins/Lens, and Cable Paths all in one pass.

The Import will notice if any 'Location' already exists in a 'Hidden' state. The process will locate that hidden Location record and update it to 'Not Hidden'. It will also blank out any old information on the Location from before it was hidden, so it will seem like a fresh new record. The remainder if the process will treat the record like a new record, and fill in values as normal. The 'Imported Records' Grid will display a line showing a new Location record added.

A consequence of this is that if there were any old 'Service Orders' that referenced this Location, then any details of the location that were displayed on the Service Order will now show the new Location values instead of the original values. This problem will eventually be solved by "Service Order Archiving", when the ability to hide Locations will be removed.

Matches On

The Full Path import can create records for 'Path', 'Path Legs', 'Locations', 'Equipment' (from and to, each leg), 'Services', 'Ports/Pins/Lens' (from and to, each leg) and 'Vlans'. Each of these needs to check to see if the record it is trying to save already exists.

 Here is a list of the fields used to match existing records.

  • For Paths: Service ID, and/or Location Name and Location Type.

  • For Services: Service ID or Services RECID.

  • For Location of the Path: Location Name and Location Type, or Location of the Path Legs.

  • Location of the Path Leg From Equipment.

  • Location of the Path Leg To Equipment.

  • Path Leg From Equipment.

  • Path Leg To Equipment.

  • Path Leg From Equipment Ports/Pins/Len.

  • Path Leg To Equipment Ports/Pins/Len.

  • Vlan

Fields

Location Name

Required

Datatype is Hierarchical String.

If the Location does not exist, the Import will INSERT a new record.

Service ID

Required

Datatype is String.

If the Service ID does not exist, the Import will INSERT a new record.

Location Type

Conditionally Required when the Import is attempting to INSERT the Location.

Datatype is Hierarchical String.

Permitted values are from (2024.1) List Values of type LOCATION_TYPE: Site, Building, Floor, Room, Cube, Truck, Closet, Rack, Elevation, or Manhole.

User entered values to the LOCATION_TYPE list may also be used.

Service Catalog

Datatype is Hierarchical String.

Conditionally Required if the Import is attempting to INSERT.

Ignored if Service already exists.

Service Status

Datatype is String.

Conditionally Required if the Import is attempting to INSERT.

Service Owner

Datatype is Hierarchical String.

Conditionally Required if the Import is attempting to INSERT.

The Import expects this to be a Department Hierarchy.

Match requires the Department Hierarchy in the following format: 'Code - Description'.

Service Reference

Datatype is String.

Service GLA

Datatype is Hierarchical String.

The Default value is blank.

Location Building ID

Datatype is String.

Default value is blank.

Only used to provide a building number if a new building location is being created by this Import.

Service RecID

Datatype is Number.

Default value is blank.

Used to specify an existing Service that is getting the path if the Service has a blank Service ID.

Note: If the Service already exists, the Service Status, Service Owner, and Service Reference can be updated by the provided values.

Flags / Conditional Logic

Import Flags

These optional flags can be set in the Conditional Logic.

Example - [FLAGS.ADD_EQUIPMENT] = True

ADD_EQUIPMENT:

Default Value is False.

  • True: If True, INSERT To Equipment and From Equipment when there is not an existing Equipment record.

  • False: If False, an error generates when the Equipment does not exist.

RECREATE_EXISTING_PATH:

Default Value = False

  • True: If a Cable Path already exists on the Service or Location, UPDATE all existing Paths with the Path value in the Import File.

  • False: If a Cable Path already exists, the Import generates an error.

REPLACE_IP:

Default Value False.

  • True: Allows the IP Address of Equipment to UPDATE when the Import File record has a different value.

  • False: Causes an error when the IP Address doesn't match.

REPLACE_VLANS:

Default Value False.

  • True: If True, when a VLAN is already assigned to a Port, UPDATE all the previously existing VLANs on that Port with the record from the Import File.

  • False: If False, append VLANs into the list of VLANs for that Port.

LOOKUP_PATH_BY_EQUIPMENT:

Default Value False.

  • True: Sets the Import to try to match the existing Equipment ID and its full Location path.

  • False: When the flag is False, the Lookup is done by the Service ID.

Legs Array

The real magic of the Cable Paths Full Import is the Legs Array field. This field cannot be assigned in the field mappings. It must be set in the Conditional Logic because it must be assigned to a PHP associative array of values containing the possibly multiple Legs of the Cable Path. For each Path Leg, the User is required to specify the Location Name, Type, From Equipment, To Equipment, Port, and optional VLAN. If any of these Locations, Equipment, Ports, or VLANs do not exist, the Import will INSERT them.

You can have as many Path Legs in a Path as needed. Each Path Leg may have a variety of associative indexes.

Each Path Leg has these array indexes:
"INSTANCE" => Path Leg arbitrary instance number. If not provided, the first leg is set to 100, and each leg after is incremented by 100 (100, 200, 300...).
"pathLegLocationName" => The Path Leg full Location path.

This can be the same as the Path location, or it can be different in the case of multiple Location Services.

"pathLegLocationType" => The Path Leg Types.

Formatted like the Path Location Types.

"pathLegCableName" => The preexisting Cable Name to be assigned to the Path Leg.
"pathLegPairStrand" => The preexisting Pair/Strand Number to be assigned to the Path Leg.
"FROM" => Associative array of Equipment, Port, and VLAN values.

The same values are available for both the FROM and TO arrays.

All of the values are optional.

Assigning a value of Null is the same as not assigning the value at all.

"TO" => Associative array of Equipment, Port, and VLAN values.

The same values are available for both the FROM and TO arrays.

All of the values are optional.

Assigning a value to Null is the same as not assigning the value at all.

The following indexes are indexes in the FROM and TO arrays not the PATH_LEG array.
"EqpCatalog" => Equipment Catalog Name

Conditionally Required and only used when Import is attempting to INSERT the Equipment.

If the Import is attempting to UPDATE the Equipment, Status is always set to Installed.

"EqpId" => Equipment ID
"EqpLocationName" => Location of the Equipment
"EqpLocationType" => Location Type

Formatted like the Path location types.

Only used if Location is provided.

"EqpIP" => IP4 Address
"EqpRemarks" => Equipment Remarks
"EqpPPLPort" => Equipment Port
"EqpPPLStatus" => Port Status
"EqpPPLSpeed" => Port Speed
"EqpPPLPOE" => Port POE flag

Datatype is Boolean.

Should be set to 0 for False or 1 for True.

"EqpPPLTxrx" => Port TxRx value
"EqpPPLType" => Port Type
"EqpPPLSide" => Port Side
"EqpPPLVlan" => Port Vlan
"EqpPPLVlanDesc" => Port VLAN Description.

Only used when the Import is attempting to INSERT the VLAN.

Example

The best way to describe how to do this is by example. This example creates two Path Legs: Jack to Panel and Panel to Switch. The strings that are in double quotes are associative array indexes, and they must be written exactly as they appear in this example. The values after the '=>' operators can be literal strings, they can come from the input CSV file using the index syntax, or come from Conditional Logic variables that were previously assigned. We noticed it is slightly more readable when we assign the input values to variables before doing the path_leg assignments.

Here is an example of some Conditional Logic:

///// begin Conditional Logic ///// $cl_switch = [0]; // for Port number, if length is 1 then zero pad value. $cl_switch_port = strlen([1]) == 1 ? '0'.[1] : [1]; $cl_switch_location = [2]; $cl_jack = [3]; $cl_jack_port = [4]; $cl_jack_location = [5]; $cl_panel = [6]; $cl_panel_port = strlen([7]) == 1 ? '0'.[7] : [7]; [PATHS.LEGS_ARRAY] = array( // first leg array( "pathLegLocationName" => $cl_jack_location, "pathLegLocationType" => 'Building > Room', "pathLegCableName" => $cl_cable_name, "pathLegPairStrand" => $cl_pair_strand, "FROM" => array( "EqpId" => $cl_jack, "EqpCatalog" => 'Faceplate', "EqpLocationName" => $cl_jack_location, "EqpLocationType" => 'Building > Room', "EqpPPLPort" => $cl_jack_port, "EqpPPLStatus" => 'Assigned', ), "TO" => array( "EqpId" => $cl_panel, "EqpCatalog" => 'Block / Panel', "EqpLocationName" => $cl_switch_location, "EqpLocationType" => 'Building > Closet', "EqpPPLPort" => $cl_panel_port, "EqpPPLStatus" => 'Assigned', ) ), // second leg array( "pathLegLocationName" => $cl_jack_location, "pathLegLocationType" => 'Building > Room', "pathLegCableName" => $cl_cable_name, "pathLegPairStrand" => $cl_pair_strand, "FROM" => array( "EqpId" => $cl_panel, "EqpCatalog" => 'Block / Panel', "EqpLocationName" => $cl_switch_location, "EqpLocationType" => 'Building > Closet', "EqpPPLPort" => null, "EqpPPLStatus" => null, ), "TO" => array( "EqpId" => $cl_switch, "EqpCatalog" => 'CISCO 3750X', "EqpLocationName" => $cl_switch_location, "EqpLocationType" => 'Building > Closet', "EqpPPLPort" => $cl_switch_port, "EqpPPLStatus" => 'Assigned', ) ), ); ///// end Conditional Logic /////

Errors

When an Import Line fails, it is usually because the Line falls into one of the following categories:

  1. The value provided from another table was not found within the Database





  2. The value provided from another table has at least one existing Path





  3. A blank value was provided, for a field with a required value





  4. The value provided is not acceptable for the record type being created





  5. The System was unable to save the record