Cable Path Imports

1 Capability
2 Fields
- 2.1 Service ID
- 2.2 Service RECID
- 2.3 Location
- 2.4 Location Type
- 2.5 Header
- 2.6 Footer
3 Child Records
- 3.1 Path Leg
  - 3.1.1 Path Status
  - 3.1.2 Cable Name
  - 3.1.3 Pair/Strand Number
  - 3.1.4 From Equipment ID
  - 3.1.5 From Equipment Location
  - 3.1.6 From Equipment Location Type
  - 3.1.7 From Ports Pins Len
  - 3.1.8 From Port Pin Len Side
  - 3.1.9 To Equipment ID
  - 3.1.10 To Equipment Location
  - 3.1.11 To Equipment Location Type
  - 3.1.12 To Ports Pins Len
  - 3.1.13 To Port Pin Len Side
  - 3.1.14 Backbone Service ID
  - 3.1.15 Backbone Service RECID
  - 3.1.16 Leg Location
  - 3.1.17 Leg Location Type
  - 3.1.18 Notes
4 Flags / Conditional Logic
- 4.1 IMPORT FLAGS
  - 4.1.1 Legs Array
    - 4.1.1.1 Example
5 Errors

Capability

The Cable Path Import allows the User to INSERT a valid Cable Path with an Origination Equipment and a Destination Equipment record onto existing Cable. Cable Path is an association record that must have valid values before the User can create it for the Cable Name, Equipment, and Location fields. The Cable Path Import process CANNOT INSERT these records, they MUST already exist.

This import can also remove a Path from a Service or Location. To do this, simply import the Path with the Service and/or Location, but do not provide any Path Leg values. If the Path Leg values are all blank, a new Path will not get created, and any existing Path will be removed.

If you attach a Pair/Strand to a Path Leg, the Pair/Strand Status will be changed to Assigned if the Path has a Service, or Left In if the Path is just on a Location. If you remove a Path that has a Pair/Strand, it's Status will be set to Spare.

If you provide a Service and a Location, the Location must be a Location from that Service.

Fields

While the Service ID and the Location are optional, at least one of these must be provided to give the Path a valid location.

Service ID

Conditionally Required

Datatype is String.

Either a Service ID or a Location must be provided. The provided value can be formatted, unformatted, or it can be a Service Alias value.

If both are provided, the Import uses both. If provided, the value is used to lookup an existing record to UPDATE. The Cable Path Import does not INSERT a Service ID. See the Services Import to INSERT Services.

If the lookup fails, it causes an error.

Service RECID

Datatype Number

This field can be used as an alternative to the Service ID field. This is especially useful to find a Service that has a blank Service ID.

Location

Conditionally Required

Datatype is Hierarchical String.

Either a Service ID or a Location must be provided. If both are provided, the Import uses both.

If provided, the value is used to lookup an existing record to UPDATE. The Cable Path Import will not INSERT a Location. See the Locations Import to INSERT Locations.

If the lookup fails, it causes an error.

Location Type

Conditionally Required if the provided Location Name exists with multiple Types.

Datatype is String.

Permitted values are from the LOCATION_TYPE List Values.

This field is used for the Location lookup if provided.

Header

Datatype is String.

Footer

Datatype is String.

Child Records

Path Leg

Individual Legs of the Path can be Imported onto the Cable Path.

Path Status

Datatype is String.

Default Value is blank.

Permitted values are LEFT_IN, blank, or any value-added in List Values by your organization.

Cable Name

Datatype is String.

This must be a valid preexisting Cable.

Pair/Strand Number

Datatype is String.

If a Cable Name value is provided, then the Pair/Strand Number is required.

If a Cable Name value is not provided, then the Pair/Strand Number value is ignored.

This must be a valid, existing Pair/Strand Number. If the User needs to INSERT a Pair/Strand, use the Pair/Strand Import or manually create the record.

If the Cable and Pair/Strand are provided and the From or To Equipment and Port are not provided, the From or To Equipment and Port will be copied from the From or To Equipment and Port from the Pair/Strand.

In order to put a Pair Strand on the Cable Path Leg, one of these two conditions must be true:

- The Status of the Pair must be Spare.
- The Pair must have its Multiple Paths flag set, and not have Status Bad.

From Equipment ID

Datatype is String.

This must be a valid, existing Equipment ID.

The Cable Path Import will NOT INSERT Equipment IDs. This must be done with the Equipment Import, API, or manually create the Equipment record.

If the lookup fails, it causes an error and the Path does not INSERT.

From Equipment Location

Datatype is Hierarchical String.

The From Equipment Location is only used to find the correct From Equipment. It is only needed if there is more than one From Equipment with the same Equipment ID in different Locations.

From Equipment Location Type

Datatype is String.

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

The From Location Type is only used to find the correct From Location. It is only needed if there is more than one From Location with the same Name with different Location Types.

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

From Ports Pins Len

Datatype is String.

The Cable Path Import will NOT INSERT Port/Pin/Lens records. This must be done with the Ports/Pins/Lens (PPL), API, or manually create the PPL record.

This must be a valid preexisting Port/Pin/Lens record.

Value in this field is optional. If provided, the value is used to look up existing records to UPDATE.

If the lookup fails, it causes a warning. The Path is created with blank Port/Pin/Len values.

If the Port is already in use on a different Cable Path, then it must have its "Multiple Paths" flag set to true for it to be added to an additional Cable Path. If the Port is already in use and the "Multiple Paths" flag is not set, then an error will occur.

From Port Pin Len Side

Datatype is String.

This optional value is used to help identify a Port, in case an Equipment has multiple ports with the same port number, on different sides.

To Equipment ID

Datatype is String.

This must be a valid preexisting Equipment ID.

The Cable Path Import will NOT INSERT Equipment IDs. This must be done with the Equipment Import, API, or manually create the Equipment record.

To Equipment Location

Datatype is Hierarchical String.

The To Equipment Location is only used to find the correct To Equipment. It is only needed if there is more than one To Equipment with the same Equipment ID in different Locations.

To Equipment Location Type

Datatype is String.

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

The To Location Type is only used to find the correct To Location. It is only needed if there is more than one To Location with the same Name with different Location Types.

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

To Ports Pins Len

Datatype is String.

The Cable Path Import will NOT INSERT Port/Pin/Lens records. This must be done with the Ports/Pins/Lens (PPL), API, or manually create the PPL record.

This must be a valid preexisting Port/Pin/Lens record.

Value in this field is optional.

If provided, the value is used to look up existing records to UPDATE.

If the lookup fails, it causes a warning, but the Path is created with blank Port/Pin/Len values.

If the Port is already in use on a different Cable Path, then it must have its "Multiple Paths" flag set to true for it to be added to an additional Cable Path. If the Port is already in use and the "Multiple Paths" flag is not set, then an error will occur.

To Port Pin Len Side

Datatype is String.

This optional value is used to help identify a Port, in case an Equipment has multiple ports with the same port number, on different sides.

Backbone Service ID

Datatype is String.

If provided, the value is used to lookup an existing Service record. The Import will not INSERT this Service record. See the Services Import to INSERT Services.

If the lookup fails, it causes an error.

Backbone Service RECID

Datatype Number

This field can be used as an alternative to the Backbone Service ID field. This is especially useful to find a Backbone Service that has a blank Service ID.

Leg Location

Datatype is Hierarchical String.

This is optional and used to assign the location of the Path Leg. Usually, this is not needed, and the location of the leg will match the location of the Path or the Path's Service. This is usually used to differentiate Path Legs for Services that have multiple Locations.

Leg Location Type

Conditionally Required if the provided Leg Location Name exists with multiple Types.

Datatype is String.

Permitted values are from the LOCATION_TYPE List Values.

This field is used for the Leg Location lookup if provided.

Notes

Datatype is String.

Flags / Conditional Logic

IMPORT FLAGS

RECREATE_EXISTING_PATH

Datatype is boolean.

Default is false.

If the Location or Service you are creating the Path for already has a Path, the existing Path is compared to the new Path information. If the Path Legs are the same, nothing changes. If they are different, the default behavior produces an error. If this flag is set to true, then the existing Path will be removed, and a new Path will be created. If this flag is set to true and no new path leg values are provided, then the existing Paths can be removed from the Location or Service.

APPEND_PATH_LEGS

Datatype is boolean.

Default is false.

The first time a Path (as defined by the Service and Location) is encountered in an Import File and a Path Leg is provided, if the Path already exists and if the RECREATE_EXISTING_PATH flag is set, the Path is deleted and rebuilt. After the first successfully saved occurrence, the Path Legs are appended. If you want to append to the existing Path without clearing it, the APPEND_PATH_LEGS flag can be set to True. If the APPEND_PATH_LEGS flag is set to False, then the Path will be rebuilt (if the RECREATE_EXISTING_PATH flag is set) even if it is not the first occurrence in the file.

CHECK_SERVICE_STATUS

Datatype is boolean.

Default is false.

When adding or modifying a Path on a Service, this import does not check the Status of the Service. If you set this flag to True, the import will error if the Service Status is not Active and you try to add or modify a Path (Path removal will still happen, regardless of Service Status).

SERVICE_ALIAS_SEARCH

Datatype is string

Default First

The provided Service ID value might match a Service ID, and also match an Alias value of a different Service ID. This flag tells the import which result to use. You can set the flag to one of these 3 values:

'First' The alias value will be used first. 'Last' The alias value will be used last. 'None' The alias value will not be used at all.

Legs Array

To use the above fields to provide Path Leg data, Users can only create a Path with one Path Leg. To use this optional Legs Array field, Users can create Paths with any number of legs.

To use this method, do not use any of the Path Leg fields listed above. If the Legs Array is assigned, all of the individual Path Leg fields are ignored.

The Legs Array lets Users assign values to these array indexes for each Path Leg:

"pathLegLocationName"

"pathLegLocationType"

"pathLegCableName"

"pathLegPairStrand"

"backboneServiceId"

"backboneServiceRecid"

"FROM_EqpId"

"FROM_EqpLocation"

"FROM_EqpLocationType"

"FROM_EqpPPLPort"

"FROM_EqpPPLSide"

"TO_EqpId"

"TO_EqpLocation"

"TO_EqpLocationType"

"TO_EqpPPLPort"

"TO_EqpPPLSide"

"pathLegNotes"

These indexes have the same requirements and data types as the Path Leg import fields listed above.

The Legs Array must be assigned in the Conditional Logic and not mapped.

Example

Here is an example of how this is done with a two-leg Path, from a switch to a panel then a panel to a jack. 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 recommend using the variables to make the logic slightly more readable and easier to maintain.

///// begin Conditional Logic /////

// Values for first leg
$cl_cable_1 = [5];
$cl_pair_1 = [6];
$cl_location_1 = [7];
$cl_backbone_1 = [8];
$cl_from_eqp_1 = [9];
$cl_from_port_1 = [10];
$cl_from_side_1 = [11];
$cl_to_eqp_1 = [12];
$cl_to_port_1 = [13];
$cl_to_side_1 = [14];

// Values for second leg
$cl_location_2 = [15];
$cl_cable_2 = [16];
$cl_pair_2 = [17];
$cl_backbone_2 = [18];
$cl_from_eqp_2 = [19];
$cl_from_port_2 = [20];
$cl_from_side_2 = [21];
$cl_to_eqp_2 = [22];
$cl_to_port_2 = [23];
$cl_to_side_2 = [24];

[PATHS.LEGS_ARRAY] = array(
    // first leg
    array(
        "pathLegLocationName" => $cl_location_1,
        "pathLegCableName" => $cl_cable_1,
        "pathLegPairStrand" => $cl_pair_1,
        "backboneServiceId" => $cl_backbone_1,
        "FROM_EqpId" => $cl_from_eqp_1,
        "FROM_EqpPPLPort" => $cl_from_port_1,
        "FROM_EqpPPLSide" => $cl_from_side_1,
        "TO_EqpId" => $cl_to_eqp_1,
        "TO_EqpPPLPort" => $cl_to_port_1,
        "TO_EqpPPLSide" => $cl_to_side_1,
    ),
    // second leg
    array(
        "pathLegLocationName" => $cl_location_2,
        "pathLegCableName" => $cl_cable_2,
        "pathLegPairStrand" => $cl_pair_2,
        "backboneServiceId" => $cl_backbone_2,
        "FROM_EqpId" => $cl_from_eqp_2,
        "FROM_EqpPPLPort" => $cl_from_port_2,
        "FROM_EqpPPLSide" => $cl_from_side_2,
        "TO_EqpId" => $cl_to_eqp_2,
        "TO_EqpPPLPort" => $cl_to_port_2,
        "TO_EqpPPLSide" => $cl_to_side_2,
    ),
);

///// end Conditional Logic /////

Errors

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

The value provided from another table was not found within the Database
The value provided is not acceptable for the record type being created
The System was unable to save the record