PatchCableMgr User Guide

There are 3 different ways to get started with an PatchCableMgr account:

1. Demo Account

   The demo account is intended to provide you with a sandbox environment which allows you to immediately start working with the application to determine if it is right for your organization.

   To access the demo account, enter a valid email address on the landing page and click the "Instant Demo" button. You will be presented with a login page. The username is '[email protected]' and the password is 'demo'.

   The demo account is a shared environment. Any information entered in the demo account will be visible to the public. Do not enter sensitive information while using the demo account.

2. Hosted Account

   A hosted account is hosted on PCM servers. Everything related to server maintenance and support (server configuration, OS & app upgrades, SSL certificates, etc.) is handled by PCM. Upon registration, a tenant is created with a unique domain name (ie. acme.patchcablemgr.com) and individual database to create an isolated environment.

   To register for a hosted account, click here, fill out the form and click "Join Now". Your tenant environment will be created and you will be redirected to the login page. An email will be sent to the address provided confirming your account.

   A hosted account stores information on servers not owned by you or your organization. This may violate the security policies of your organization. Consult your organization before entering any information in a hosted account. Consider using a self-hosted account if you are unsure.

3. Self-Hosted Account

   A self-hosted account is hosted on your server and is maintained by you. There are two self-hosted methods available: Virtual Appliance and Docker Installation

   Virtual Appliance (recommended):

   Download the PCM virtual appliance .OVA and run it in your VMWare hypervisor. When you first navigate to https://<SERVER_IP> you will be prompted to create an administrator account.

   If you don't know your <SERVER_IP>, follow the instructions in the FAQ below.

   Docker Installation:

   Installation instructions assume a clean install of Ubuntu Server 18.04

   1. Upgrade OS:
      sudo apt-get update
sudo apt-get upgrade
   2. Install Docker:
      Official Docker install guide can be found here
   3. Install Docker-Compose:
      Official Docker-Compose install guide can be found here
   4. Clone the PCM "docker_deploy" repository:
      git clone https://github.com/patchcablemgr/docker_deploy.git
   5. Set custom variables in ~./docker_deploy/docker-compose.yml:
      • MYSQL_USER - The username used when creating the database during installation.
      • MYSQL_PASSWORD - The password used when creating the database during installation.
      • SUBJECT_ALTERNATE_NAME - The DNS name of the server. Used for generating self-signed SSL certificate.
      • SUBJECT_ALTERNATE_IP - The IP address of the server. Used for generating self-signed SSL certificate.
   6. Build and run PCM:
      cd ./docker_deploy
sudo docker-compose up
   7. Navigate to the server in your browser to complete the initial configuration.
      • Database Password - The password to be used to connect to your database. Determined by "MYSQL_PASSWORD" variable in docker-compose.yml. Defaults to "ChangeMe7492#&!".
      • Email Address - The email address to be used for administrator login.
      • Password - The password to be used for administrator login.
      • Confirm - The password to be used for administrator login.

      If everything is correct, you will be automatically redirected to the login page. Login with the administrator credentials you just submitted and start using the app.

      If there are any errors, you will be alerted to what they are and will have an opportunity to go back and correct them.

PatchCableMgr supports role-based multiple user access. From administrator account you can send an invitation to members of your team allowing them to work in your PCM environment.

The Dashboard provides a quick overview of your organization's environment.

The Cable Inventory donut chart displays a count of your organization's current patch cable inventory as well as the status which is defined below.

• In-Use - Cables that are in-use have both ends connected to an object port.
• Not In-Use - Cables that are not in-use do not have either end connected to an object port.
• Dead Wood - Cables that only have one end connected to an object port.
• Pending Delivery - Cables that have been purchased through PatchCableMgr and have not yet been delivered.

The Port Utilization table displays all devices deployed in your PCM environment and can help identify patch panel availability issues before they become a problem.

The History table displays and add/change/delete actions carried out by users.

The Build menu group contains pages where your environment is modeled by creating object templates and racking those templates into cabinets.

Templates - #back to top

Use the Template page to create and edit custom templates which represent objects in your environment. The template page is separated into 3 columns:

1. Properties - Sets the properties of the custom template.
2. Preview - Displays the custom template as you build it.
3. Template Details - Displays details about a template selected from the list of available templates.

• Properties:

  • Name - Defines the name of the template.
  • Category - A category is user created and applies a color to the template as well as the ability to group similar templates together for easier access.
  • Template Type - A stanadard template is one that can be installed in a cabinet by itself. An insert is a template is installed in an existing object's enclosure partition.
  • Template Size - Defines the Rack Unit size of the template. Max is 25.
  • Template Function - Defines the template as an endpoint or passive.
    1. An endpoint template will always terminate a cable path (switch, router, server, etc.).
    2. A passive template is part of the physical cable infrastructure (patch panel, fiber insert, etc.).
  • Mounting Configuration - A 2-post template will only be visible on one side of the installed cabinet and can have another 2-post template installed behind it. A 4-post template will have a front and a back which occupy both sides of the cabinet it is installed in.
  • Add/Remove Partition - Partitions allow for the template layout to accurately reflect the object it is modeling. A horizontal partition spans the entire width of the partition it is created in and can grow vertically. A vertical partition spance the full height of the partition it is created in and can grow horizontally.
  • Partition Size - Horizontal partitions grow vertically in 0.5 RU increments. Vertical partitions grow horizontally in increments equal to 10% of the entire template width.
  • Partition Type - Generic partitions have no properties and can be used as spacers or containers for other partitions. Connectable partitions contain ports or interfaces. Enclosure partitions can contain insert templates.
  • Port ID - The format describing how the template ports will be identified. Clicking the "Configure" button will open a window allowing you to add/change/delete fields that will be used to compile each port ID (ie "Port-1a"). You can configure up to 5 fields of 3 possible field types.
    1. A "Static" field will be compiled into the port ID as it is defined by the user.
    2. An "Incremental" field accepts a single alphanumeric character and will increment with the port numbers.
    3. A "Series" field accepts a comma separated list of strings that will be cycled through when compiling the port ID.
  • Port Layout - Number of port columns and rows in the selected connectable partition.
  • Port Orientation - Determines the direction in which port numbers are incremented. Switches are typically ordered top to bottom while most RJ45 patch panels are ordered left to right.
  • Port Type - The type of port for the selected connectable partition. When connecting a cable end to an object port, the cable end type and port type must match. The exception to this rule are SFP ports, which can accept any cable end type.
  • Media Type - This configuration is exclusive to passive templates. This refers to the cabling behind the passive object. When trunking two passive objects, the media type must match.
  • Enclosure Layout - This configuration is exclusive to enclosure partition types. Enclosure layout columns and rows determine the slots available to install insert objects.
  • Enclosure Tolerance - This configuration is exclusive to enclosure partition types. A "Strict" enclosure will only accept inserts that have been created using an enclosure with the same partition and enclosure dimensions. A "Loose" enclosure accepts inserts of any size, but some distortion may occur as the insert fills the enclosure space. An insert must be of the same function (endpoint or passive) as the enclosure it is being installed in.

• Preview:

  The preview card displays the template as it is created. The "Lock" checkbox determines if the preview box scrolls with the page keeping the template visible even when working at the end of the long list of properties. The "Front" and "Back" radio buttons toggle the face of the template being displayed. A yellow highlight appears around the selected partition and indicates that any partition specific configuration will be applied to it.

• Template Details:

  The Selected Template card displays information about the template selected in the Available Templates card. It also allows for some configuration as well as the ability to delete a selected template.

  The Available Templates card lists all templates grouped by category. Front and Back radio buttons toggle the face of all available templates. Clicking on an object will highlight the selected partition and display information in the Selected Template card.
  
  The "Filter" field allows you to display only templates containing one or more strings of text.
  
  The Import button opens a window that allows you to browse a catalog of templates published by PatchCableMgr. Select a template and click "Import" to add it to your organization's list of available templates.

Cabinets - #back to top

The Cabinets page allows you to create a hierarchical representation of your environment's locations, cabinets, and objects as well as their relationship to each other. The Cabinets page is separated into 3 sections:

1. Locations and Cabinets - Create locations and cabinets. Define relationships between cabinets.
2. Cabinet - Displays the selected cabinet and objects installed.
3. Object Details - Display details about selected objects and their partitions.

Locations and Cabinets:

The Location Tree card contains an editable tree of locations and cabinets. Right click on a location to rename, delete, or create a new location, pod, or cabinet nested within it.
A location can represent a physical region, building, floor, or room. Locations can only be nested under other locations.
A pod represents a group of cabinets within a location. Cabinets within the same pod can have left/right relationships with other cabinets. Pods can only be nested under locations.
A cabinet represents a physical rack or cabinet that can contain objects. Cabinets can be nested under locations or pods.
A floorplan represents the floor of a building. Floor plans can be nested under locations.

The Cabinet card allows for cabinet properties to be edited.
RU size can grow up to 50 RU and shrink as long as the top RU is not occupied by an object.
Cable Paths can be added to represent usable cable paths between cabinets. Consider a cable path as overhead cabletray, raised floor space, conduit, or any other path that patch cables can be ran. A cable path can only be created between two cabinets in the same location. Cable paths and their configured distances are considered when calculating possible cable paths with the path finder function.
Cabinet adjacencies can be configured to tell PatchCableMgr which cabinets neighbor the selected one. A cabinet adjacency can only be created between two cabinets in the same pod. Cabinet adjacencies are considered when calculating possible cable paths with the path finder function.

Cabinet:

The Cabinet card displays the selected cabinet and all of the objects it contains. Toggling the Front and Back radio buttons switches the cabinet view. To install an object in the cabinet displayed, drag and drop a template from the Available Templates section.

Object Details:

The Object Details card displays information about the selected object and partition as well as templates available to be installed.
The Selected Object section displays information about the object. The Object Name and Trunked To properties are editable. Connectable object partitions can be trunked to other connectable object partitions. When trunking a passive object partition to another passive object partition, the number of ports must be equal and the media type must match. When trunking a passive object partition to an endpoint object partition, the number of ports must be equal and the endpoint object partition port type must be RJ45. An endpoint object partition cannot be trunked to another endpoint object partition.
The delete button will remove the selected object from the cabinet.
The Available Templates section displays a list of templates available to install in the cabinet grouped by category. Drag and drop a template into the cabinet to install it as an object. An insert template can only be installed in an enclosure partition of a standard object.

The Explore page allows you to navigate the environment and display information about objects and how they are connected. The Explore page is separated into 3 sections:

• Locations and Cabinets - Navigate environment locations and select cabinets. Locations and cabinets are not editable from the Explore page.
• Cabinet - Displays the selected cabinet and objects installed. Objects cannot be added, moved, or deleted from the Explore page.
• Object Details - Display details about selected objects and their partitions. Object details are not editable from the Explore page.

Locations and Cabinets:

The Location Tree card contains a tree of locations and cabinets.
A location can represent a physical region, building, floor, or room.
A pod represents a group of cabinets within a location.
A cabinet represents a physical rack or cabinet that can contain objects.

Cabinet:

The Cabinet card displays the selected cabinet and all of the objects it contains. Toggling the Front and Back radio buttons switches the cabinet view.

Object Details:

The Object Details section displays information about the selected object and partition as well as cable path details for a specific port.
The Selected Object card displays information about the object and partition.
The Path card displays cable path information about the selected port. Select a port by clicking on an individual port in a connectable object partition. The port drop down provides an alternative way to select a port after a connectable object partition has been selected.
The Populated checkbox allows you to flag a port as populated even though an PatchCableMgr managed patch cable has not been connected to it. This is useful for when you have existing patch cables that have not yet been scanned into your PatchCableMgr inventory, or when it is not necessary for a patch cable to be managed by PatchCableMgr. Flagging a port as populated will take it out of consideration when calculating possible cable paths with the Path Finder function.
When an individual port is selected, its cable path will be displayed. The cable path is represented by colored boxes containing the full name of the object. Blue boxes represent passive objects, green boxes represent endpoint objects and red boxes indicate a patch cable is not connected to an object. A vertical double-ended arrow represents a trunk connection between two objects. Curved arrows represent a patch cable connection indicating the length of the patch cable. The currently selected object port is identified by a pin icon to the left of the object name.

Clicking the Path Finder button opens the path finder modal. The path finder modal allows you to calculate all possible paths between two ports (Endpoint A and Endpoint B). Endpoint A is determined by the currently selected port. Use the navigation dropdowns to indicate Endpoint B, the far port you wish to find available paths to. Once you've narrowed down the path selection dropdowns to an individual port, the Run Path Finder button becomes enabled. Clicking the Run Path Funder button tells PatchCableMgr to begin calculating all available paths between the two endpoints. Results are returned in a table indicating the number of patch cables required for each unique path. The results table indicates the number of local (between objects in the same cabinet), adjacent (between objects in neighboring cabinets), path (between objects reachable via cable path), and total patch cables required to connect the endpoints. Clicking on a path in the result table will display the full cable path.

The Scan page allows you to request and edit data about a Unique Cable End Identifier (UCEI). Clicking the Scan button displays the scan modal. Either scan the barcode, or switch to manual input to enter the UCEI.

When a valid UCEI has been scanned and has already been initialized, details about the cable and its local and remote ends will be populated. To connect a cable end to an object port select the location path, object, and port using the navigation dropdowns.

When a valid UCEI has been scanned but has not already been initialized, you must scan the remote UCEI and define the cable length, media type, and local/remote connector types. Once all cable properties have been defined, the Finalize button will be enabled. Clicking the Finalize button disables the cable property inputs preventing the cable from being edited.

A UCEI is invalid when it does not exist in either the initialized cable table or Available Userspace table of the Cable Inventory page.

UCEIs are specific to an organization. UCEIs must be unique with an organization. UCEIs can be initialized in any order as long as they are listed in the Available Userspace table of the Cable Inventory page.

The Cable Inventory page displays all unique cable end identifiers (UCEI) that have been applied to a cable end and scanned into the application as well as unused UCEIs which are available.

The Initialized Cables table is separated into 3 column groups. Each cable end column group contains details specific to that cable end. The ID column which displays the base36 encoded UCEI as well as a barcode button. Clicking the UCEI in the ID column will navigate to the scan page and display its properties as if it was scanned. The barcode button displays the UCEI represented as a code39 barcode. The Connector column displays the connector type. The connected column indicates whether the cable end is connected to a port.

The Cable Properties columns display details specific to the entire cable. The Finalized column indicates whether or not the cable is editable (it is suggested that all cables be finalized to prevent unwanted editing). The Media column displays the cable media type. The Length column displays the cable length (fiber length is displayed in meters, UTP length is displayed in feet).

The Available Userspace table lists all UCEIs that have not been initialized and are available to be attached to a cable end and scanned into the database for use in the application. UCEIs are uppercase base36 encoded strings. UCEIs are specific to each organization and must be unique within that organization. Be cautious not to introduce duplicate UCEIs into your environment as this may cause unwanted behavior. Each organization is allocated 100 userspace UCEIs upon creation. Once the number of available UCEIs falls below 100, you may request additional UCEIs by clicking the Add More button. UCEIs are allocated in sequence.

The Admin page allows organization administrators to perform privileged functions.

The Invite User section allows you to send an invitation to an individual to join your organization. Recipients will receive an email with a link to join. Existing users can also accept the invitation from their user Profile and can revert back to their original organization at any time. Invited users are added to your organization with "User" level privileges by default.

The Email Settings section allows you to configure how PCM will send emails for the invitation and password reset functions. There are three methods of sending emails:

• PCM Proxy - This is the simplest method and uses PCM's email service to send eamils.
• SMTP - Using an anonymous SMTP relay server is an easy way to deliver emails assuming your organization allows for unauthenticated SMTP relay.
• SMTP (authenticated) - This method is the most successful way for PCM to deliver emails, but requires an account on an SMTP server. Google allows for SMTP relay using gmail account.

The Organization Name section allows an Administrator to change the organization name which is displayed a the top of the page and is visible by all users.

The Manage Users section allows you to remove or change roles of a user. You cannot delete your own account, you cannot downgrade your role if you are the only administrator.

• Self-hosted Virtual Appliance: How do I find the server IP address?
  Open a console to your PCM virtual appliance from you hypervisor and you'll find the IP address printed above the login prompt.
• Self-hosted Virtual Appliance: What are the default credentials?
  pcmuser / PatchCableMgr
• Self-hosted Virtual Appliance: How do I upgrade?
  Login to the webmin console https://<SERVER_IP>:10000 and navigate to "Others->Custom Commands". Run "PCM: Reload App" to reload PCM and pull down the latest code in the process.
• Self-hosted Docker Installation: How do I upgrade?
  Login to your server and enter the following commands:
  cd ~/docker_deploy
sudo docker-compose down
sudo docker-compose up