Document toolboxDocument toolbox

.Equipment Imports v2023.1

Capability

The Equipment Import allows the User to INSERT new records and UPDATE existing Equipment records if a match is found.

Note: The Equipment import cannot assign an Equipment to a Service. To do this task, the Equipment must be created first, and then the Service import can be used to make the assignment.

Matches On

Equipment RECID

If an Equipment RECID is provided, the Equipment Import only attempts to match on the Equipment RECID. If no match is found, an error occurs.

Asset Tag

The Equipment Import first attempts to match on the Asset Tag.

Equipment ID

If there is not an Asset Tag match, the Import attempts to match on the Equipment ID field.

If there are multiple matches by the Equipment ID, the Import attempts matching both the Equipment ID and Location together.

If there are multiple matches by the Equipment ID and Location, an error occurs.

Serial Number

If there is not an Equipment ID match, the Import attempts to match on the Serial Number. If there are multiple matches by the Serial Number, an error occurs.

MAC Address

If there is not a Serial Number match, the Import attempts to match on the MAC Address. If there are multiple matches by the MAC Address, an error occurs.


Note: Because of all of the different methods to lookup an existing record, some extra care must be taken when intending to update key fields of a record. For example, say you want to find a record by the Equipment ID, and update the Asset Tag. If the Asset Tag you provide already exists on a different record, then that different record will be found and updated instead. The lookup order is: Recid, Asset Tag, Equipment ID, Serial Number. Similarly, if you intend to create a new record and you provide an Asset Tag, Equipment ID, and Serial Number, if any of those values already exist, then that existing record will get updated instead of the new addition.

Fields

Asset Tag

Conditionally Required if the Equipment status is set to Installed AND the Asset Flag is set on the Equipment Catalog.

Each Asset Tag must be unique, trying to create a new piece of Equipment with a matching Asset Tag will UPDATE the existing Equipment instead.

Datatype is String.

Equipment ID

Conditionally Required if the Equipment status is set to Installed.

A duplicate error will trigger if there is already Equipment in the system with the same Equipment ID-Location pairing.

Datatype is String.

Serial Number

Data type is String.

Default value is blank.

The Serial Number may be Required, depending on the state of the REQUIRE_SERIAL_NUMBER configuration setting in your environment.

Equipment RECID

Datatype Number

This can be used to find Equipment Records for updates. This is especially useful for finding Equipment records that have blank Equipment ID, Asset Tag, and Serial Number.

If a value is provided for the RECID, then it will be assumed to be an update operation, and no other keys will be tried to find the existing record.

Equipment Status

Conditionally Required if the Import is doing an INSERT.

Datatype is String.

NOT Required if the Import is doing an UPDATE.

Permitted values are one of the following List Values of type EQP_STATUS: Unassigned, Assigned, Retired, Broken, Lost, or Installed.

No other values are permitted for the Import.

If the Equipment's Status is Unassigned, it MUST be assigned to a Location that has the Warehouse flag set or has a blank (Null) Location value.

Part Number

Conditionally Required if the Import is doing an INSERT.

Datatype is String.

The Part Number field come from Equipment Catalog field not the full Catalog Path.

Units

Conditionally Required if the Has Units flag is set on the Equipment Catalog.

Datatype is Number.

New Equipment ID

Datatype is String.

If a New Equipment ID value is provided, it is used to UPDATE the Equipment ID field.

Billable

Datatype is Boolean

Default Value = False

Consumed

Datatype is Boolean

Only used if the Configuration Option SHOW_CONSUMED is set to True [1].

Default Value = False

Cabling Eqp Type

Datatype is String.

The value must be one of the following List Values of type CABLING_EQP_TYPE: Switch, Router, Jack, IDF, MDF, or BDF.

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

Parent Equipment ID

Datatype is Hierarchical String.

Should match an existing Equipment ID.

Look up is based on the Match On values for Equipment records.

Parent Location

Datatype is String

Optionally Used with Parent Equipment ID to identify a Parent Equipment.

Parent Location Type

Datatype is String

Optionally Used with Parent Location to identify a Parent Equipment.

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

Parent Asset Tag

Datatype is String

Optional method to identify a Parent Equipment.

Parent Serial Number

Datatype is String

Optional method to identify a Parent Equipment.

Parent MAC Address

Datatype is String

Optional method to identify a Parent Equipment.

Parent Equipment RECID

Datatype is Number

Optional method to identify a Parent Equipment.

Private

Data type is Boolean.

Default value is false.

Card Number

Data type is String.

Default value is blank.

Owner

At least one Owner (either Customer Number, Dept Hierarchy Code, or Dept Hierarchy Name) may be Required IF the following conditions are met:

The Import is attempting to INSERT the Equipment record and the Equipment Status is Assigned.

Otherwise, the Owner field is NOT Required.

Customer Number

Data type is String.

Default value is blank.

Dept Hierarchy Code

Data type is Hierarchical String or String.

Default value is blank.

The value for this field can be the full Hierarachial Path, or it can be just the last part of the Path. If you provide only the last part, then there is a chance that there could be duplicate values in the database. If duplicate values are found, then you will get an error.

Dept Hierarchy Name

Datatype is Hierarchical String or String.

Default value is blank.

The value for this field can be the full Hierarachial Path, or it can be just the last part of the Path. If you provide only the last part, then there is a chance that there could be duplicate values in the database. If duplicate values are found, then you will get an error.

Billing Group Override

Datatype is String

Value must match an existing Billing Group.

Eqp Condition

Default value is blank.

Allowed values are from the EQP_CONDITION List Type values.

Common values are: New, Used, and Refurbished but may vary for your organization.

Host Name

Data type is String.

Default value is blank.

IPv4 Address

Data type is String.

Default value is blank.

The IPv4 Address must be in the form "a.b.c.d" where each part is a decimal number between 0 and 255.

IPv4 Gateway

Data type is String.

Default value is blank.

IPv4 Gateway Address

Data type is String.

Default value is blank.

The IPv4 Address must be in the form "a.b.c.d" where each part is a decimal number between 0 and 255.

IPv4 Subnet Mask

Data type is String.

Default value is blank.

The IPv4 Address must be in the form "a.b.c.d" where each part is a decimal number between 0 and 255.

IPv6 Address

Data type is String.

Default value is blank.

The IPv6 Address must be in a valid IPv6 address format. The basic layout of this format is 8 sets of 0-4 length hex digits, separated by colons. For example: 001:0db8:85a3::0000:a2e:0370:7334

IPv6 Gateway

Data type is String.

Default value is blank.

IPv6 Gateway Address

Data type is String.

Default value is blank.

The IPv6 Address must be in a valid IPv6 address format. The basic layout of this format is 8 sets of 0-4 length hex digits, separated by colons. For example: 001:0db8:85a3::0000:a2e:0370:7334

IPv6 Subnet Mask

Data type is String.

Default value is blank.

The IPv6 Address must be in a valid IPv6 address format. The basic layout of this format is 8 sets of 0-4 length hex digits, separated by colons. For example: 001:0db8:85a3::0000:a2e:0370:7334

LAN Name

Data type is String.

Default value is blank.

MAC Address

Data type is String.

Default value is blank.

The MAC Address must be in a valid MAC address format. These examples are valid: 99:00:34:4a:44:44, 99-00-34-4a-44-44, 990.034.4a4.444, 9900344a4444.

Billed Date

Data type is String.

Default value is blank.

Ordered Date

Data type is String.

Default value is blank.

Received Date

Data type is String.

Default value is blank.

Warranty End Date

Data type is String.

Default value is blank if Received Date is not provided. If Received Date is provided, Warranty End Date is automatically set.

Purchase Price

Data type is String.

Default value is blank.

Parent Equipment

Datatype is Hierarchical String.

Default value is blank.

The value must be a unique Equipment ID if provided.

Serial Number Barcode

Data type is String.

Default value is blank.

Use DHCP

Data type is Boolean.

Default value is false.

Location

Conditionally Required if the Import is doing an Insert AND the Location Required Flag is set on the Equipment Catalog.

Datatype is Hierarchical String.

Location Type

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

Datatype is String.

Used for the Location lookup if provided.

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

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

New Location

Datatype is Hierarchical String.

Used to UPDATE the Location of an existing record, or INSERT a Location into a new record.

If both Location and New Location are given while attempting to insert a record, the Import Process will use the New Location field.

New Location Type

Datatype is String.

Used to UPDATE the Location Type of an existing record, or INSERT a Location Type into a new record.

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

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

Remarks

Datatype is String

Remarks are always appended to the Remarks list.

Author First Name

Datatype is String

Optional Author for the Remark. If provided, this value must match an existing Contact record.

This field will be ignored if there is no Remark value.

Author Last Name

Datatype is String

Optional Author for the Remark. If provided, this value must match an existing Contact record.

This field will be ignored if there is no Remark value.

Author Customer Number

Datatype is String

Optional Author for the Remark. If provided, this value must match an existing Contact record.

This field will be ignored if there is no Remark value.

GLA Expense Type

Datatype is String

The Expense Type of the GLA being provided. The value must be one of the List Values of type EXPENSE_TYPE: Default, Usage, Equipment, Labor, or any custom type.

GLA

Datatype is Hierarchical String.

Multiple GLA values can be provided on one input line. See the notes at the bottom of this page.

GLA Percent

Datatype is Number

Errors

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

  1. The value provided was found with multiple matches

  2. The value provided from another table is Inactive

  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

Notes

  • If attempting to UPDATE existing Equipment, none of these Required fields except the Match On fields are needed.
    For updates, it is assumed that the Required values are already entered. For updates, you only need to provide enough values to successfully find the Equipment record you are trying to update (Asset Tag or Equipment ID, and maybe Location).
  • If the Equipment Catalog has the 'Has Units' flag set, a Units value must be provided or an error happens.
    Units must be a positive integer or a zero. Null and negative values are not allowed. If the Equipment Catalog does not have the Has Units flag set to True [1], any provided Units value is ignored with no error or warning.
  • The Equipment import cannot associate Equipment to a Service. See the Service Import for a way to do this.
  • If you want to provide a single GLA, you can use the regular field mappings. If you want to provide multiple GLA values on one input line, you will need to use some Conditional Logic to create an array of values. This will let you provide GLAs for different Expense Types, and/or do split GLA Percentages.

Here is an example of how this is done:

// Assign fields 13-18 into the GLA array
[FLAGS.GLA_ARRAY] = array(
   array(
      'Expense_Type' = [13];
      'GLA' = [14];
      'Percent' = [15];
      ),
   array(
      'Expense_Type' = [16];
      'GLA' = [17];
      'Percent' = [18];
   ),
);

Using this method, you can provide any number of sets of GLA values.

If you provide a set of GLA values, you must provide all 3 parts: the Expense Type, GLA, and Percent.

UDF Associations

User Defined fields on any given Import are all handled the same way with Conditional Logic.

For more information about adding a UDF to the Import, see the User Defined Fields section of the Imports main page.

Help Desk Portal - Email: help@pcr.com - Phone: 616.259.9242