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 Import matches the Service ID, Equipment ID, and Equipment Location full path.

Fields

Location Name

Required

Datatype is String.

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

This field expects the full Location hierarchy in a single string with individual parts of the Location Hierarchy separated by the HIERARCHYPATH_CONCATENATOR .

Multiple levels of a hierarchy "path" (like Locations) are connected by the HIERARCHYPATH_SEPARATOR string.

The default value for this string is right angle-brace (>) with a space on either side: " > ".

When importing nested Locations, the separator you use for each level of the hierarchy must match the concatenator string.

For example, Site A > Building B > Room C.

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 String.

Permitted values are from 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.

The full Location path with each Type in a single string with individual parts of the path separated by the HIERARCHYPATH_CONCATENATOR .

Multiple levels of a hierarchy "path" (like Locations) are connected by the HIERARCHYPATH_SEPARATOR string.

The default value for this string is right angle-brace (>) with a space on either side: " > "

When importing nested Locations, the separator you use for each level of the hierarchy must match the concatenator string.

For example, Site A > Building B > Room C.

Service Catalog

Datatype is 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 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 String.

The Default value is blank.

Location Building Number

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

The following errors cause the Cable Full Path INSERT or UPDATE to fail:

Error : Services RECID is invalid

Error : This Service has status 'Order Pending', so no updates allowed

Error : Missing Service ID and Location - one is required

Error : Missing Path Legs Array

Error : Invalid from Equipment Location <pathLeg_from_EqpLocationName>; ID=<pathLeg_from_EqpId>

Error : Invalid to Equipment Location <pathLeg_to_EqpLocationName>; ID=<pathLeg_to_EqpId>

Error : Invalid from Equipment ID=<pathLeg_from_EqpId> Location=<pathLeg_from_EqpLocationName>

Error : Invalid to Equipment ID=<pathLeg_to_EqpId> Location=<pathLeg_to_EqpLocationName>

Error : Couldn't process path Location <pathsLocationName>; <errorMessage>

Error : Couldn't update Service Id <pathsServiceID>

Error : Couldn't find GLA <pathsServiceGla> for Service Id <pathsServiceID>

Error : Couldn't save Service Id <pathsServiceID>; <$errorMessage>

Error : No Service or Location for Path.

Error : Service <serviceId> has multiple existing Paths

Error : Service <serviceId> already has a Path

Error : Location <pathsLocationName> has multiple existing Paths

Error : Location <pathsLocationName> already has a Path

Error : Missing Equipment Catalog <from_equipment_EqpCatalog> for from equipment id <from_equipment_EqpId>

Error : Missing Equipment Catalog <to_equipment_EqpCatalog> for to equipment id <to_equipment_EqpId>

Error : Path leg <pathLegIndex> from equipment <importPathLeg_from_EQP> existing properties are different

Error : Path leg <pathLegIndex> to equipment <importPathLeg_to_EQP> existing properties are different

Error : Couldn't update from equipment <PathLeg_from_EQUIPMENT_RECID> to IP <PathLeg_from_IP; <errorMessage>

Error : Couldn't update to equipment <PathLeg_to_EQUIPMENT_RECID> to IP <PathLeg_to_IP; <errorMessage>

Error : Couldn't process Path <serviceId> <locationId>; <errorMessage>

Error : Couldn't process Path Leg Location <pathLeg_LocationName>; <errorMessage>

Error : Invalid Cable Name <pathLeg_CableName>

Error : Invalid Pair/Strand <pathLeg_PairStrand> for cable <pathLeg_CableName>

Error : Couldn't process from equipment <from_EqpId> Location <from_EqpLocationName>; <errorMessage>

Error : Couldn't process to equipment <to_EqpId> Location <to_EqpLocationName>; <errorMessage>

Error : Unable to find from equipment <from_EqpId> at Location <from_EqpLocationName>; <errorMessage>

Error : Unable to find to equipment <to_EqpId> at Location <to_EqpLocationName>; <errorMessage>

Error : Unable to add from equipment <from_EqpId> at Location <from_EqpLocationName>; <errorMessage>

Error : Unable to add to equipment <to_EqpId> at Location <to_EqpLocationName>; <errorMessage>

Error : Couldn't process from Equipment <from_EqpId> Remarks; <errorMessage>

Error : Couldn't process to Equipment <to_EqpId> Remarks; <errorMessage>

Error : Couldn't process Equipment <EqpId> Ports Information; <errorMessage>

Error : Couldn't process Leg <pathLeg_FROM_EQP_PPL_RECID> to <pathLeg_TO_EQP_PPL_RECID> <errorMessage>

Error : Couldn't update Service Id <pathsServiceID>; <errorMessage>

Error : Failed to create new Vlan <vlan>; <errorMessage>

Error : Failed to add new Vlan <vlan> to port; <errorMessage>

Browser not supported