PI Client: System Administration Guide

Introduction

This document is a guide to the PartsTrader PI client, with particular emphasis on the questions and requirements from systems engineers and system administrators.

The PI Client’s integration within a repair facility must be carefully considered and planned. This guide will answer the questions generally asked by system engineers when planning this deployment and installation.

What is the PI Client

The PI (PartsTrader Integration) Client is a small windows tray application and windows service which run on a repair shop PC or server. This set of apps makes sure that estimates from a repair facility’s Estimating software are exported to PartsTrader.

The repairer can now use PartsTrader to request quotes or order parts from suppliers. Once this process is completed, the repairer can import the part prices and changes back into the Estimating software. PartsTrader exports these details back to the PI Client which exported the estimate from the repair facility. The PI Client provides these details back to the Estimating software, which imports the pricing and parts information back into the originating estimate.

Exporting Estimate Parts Info from your estimates

The PI Client automatically exports parts information from a given estimate into PartsTrader, with the export of the Estimating’s EMS or BMS files. The following diagram explains how.

Figure 1: PI Client exporting estimate parts info to PartsTrader

Once your parts have flowed over into PartsTrader, you can send these parts out for quoting from suppliers on PartsTrader, or you can order the parts directly from your preferred suppliers.

Technical Detail: What exactly does the PI Client do during an export?

While the above description gives a high-level overview of what the PI Client does, for an IT specialist, a more precise diagram of the actual actions is provided below.

  1. The Estimating software exports the estimate files to its export directory.
  2. The PI client, listening to this directory, writes the PICL file if one doesn’t already exist, and proceeds to grab the estimate files for that exported estimate.
  3. The PI Client copies these files to the PI Client working directory, under a directory structure:

%PI Client Working Directory%/Estimating Software Name/EstimateBaseName

  1. The PI Client transforms these files into a BMS xml message. BMS is a world-wide standard for the collision industry of how to exchange xml data about automotive data.
  2. The PI Client submits this BMS.xml file to PartsTrader, using the repairer’s credentials configured on the PI Client.

ImportingPart Pricing and Changes back into your estimates

Once you’re ready (you’ve selected or ordered parts), you can import these part prices and changes back into your estimate. You choose “Export to Estimate”, and PartsTrader will send the Parts information you’ve selected back into your Estimating software.

Figure 2: PI Client importing parts changes into your estimate

Where should I install the PI Client?

Probably the most important thing to understand is where you should install the PI Client in your shop. Do you install it on every PC? Do you install it on any PC running your Estimating software? Do you install it on your file server?
As there are so many different kinds of shops, and so many different configurations, we won’t try to answer that here. We’ve set up a website which will walk you or your system administrator / IT Guy through a series of questions, and we can provide the best configuration for your environment.

As a good rule of thumb, if your shop stores its estimate imports and exports on a file server, we suggest you install the PI Client on this machine only. Why?

  1. Installing the PI Client on your file server means less software installed on your network
  2. The file server has all the files already and it’s a logical place for the PI Client to be in order to process these files.
  3. The file server is always on. If you install the PI Client on someone’s PC or laptop, and that machine is turned off overnight or over a week, then your estimates can’t be imported or exported from PartsTrader

We realize that not everyone has a file server, and your shop’s setup might not work this way. If it does, we’d say this is the best way to set it up. No matter how your shop is set up, we highly recommend you use the link above to determine how best to set up and configure your PI Client before doing an installation. Measure twice, cut once, as the old saying goes.

What does my server need in order to host the PI Client?

The PI Client’s requirements are reasonably light. However, there are some requirements which may affect your decision of where to host it:

Operating Systems:
Windows XP, SP3
Windows XP (64-BIT) SP2
Windows Vista
Windows 7
Windows 2008
Windows 2008 R2

Internet connection
Your server should have an always-on connection, but any internet connection will work. The server MUST be able to access the internet itself, not simply your own internal network.

Software Requirements
.Net Framework 4.0 Client Profile (if you do not have this, the PI Client will download this for you)


**For Windows XP SP2 users, you will need to install SP3

This can be installed from Windows Update

Or directly here

Which of my Estimates will go up to PartsTrader?

This will ultimately be up to your shop. PartsTrader will soon release functionality that will let your shop state which estimates you want uploaded to PartsTrader and which you do not.

Does the PI Client need updates?

The PI Client is set up to automatically update itself when we make fixes and changes to it. You shouldn’t need to do a thing.

Which Estimating software does the PI Client support?

The PI Client supports

  • CCC CCCOne
  • Mitchell Ultramate and RepairCenter
  • Audatex ADXE

What information does the PI Client send to PartsTrader?

We recognize that data privacy is very important to shops, and because of this, we made sure that the PI Client only reads data from your estimates which is needed for parts ordering.

With this in mind, when sending estimate data to and from your network, PartsTrader communicates with the PI Client using the Cieca BMS standards. This not only ensures we are only using data which is relevant to parts ordering but ensures cutting edge integration going forward.


In addition, if your shop is having trouble with the PI Clients installed on your network, the PI Client will send diagnostic information to PartsTrader. This diagnostic information includes:

  1. Diagnostic information about the host machine where the PI Client is installed, including the machine name, the operating system of the machine, and the import and export paths set up for each Estimating for the PI Client in question.
  2. Log Files: The PI Client will send up PI Client log files so the PartsTrader staff can determine when there are issues with the PI Client and how to resolve them.
  3. PI Client configuration file: Each PI client has its own XML configuration file, which can be useful in determining where there are problems. This XML data is specific to the PI client only.

How do I control what access the PI Client has to my network?

As outlined above, the PI Client is made up of two applications:

  1. The tray application: This is the configuration screen for the PI Client. This app only needs to be running while configuring the PI Client
  2. The PI Client service: The PI Client service is the workhorse of the PI Client, importing and exporting estimates and estimate updates to and from PartsTrader

In terms of permission / user access control, you will want to limit the access of the PI Client service. This can be done in a number of ways:

  1. By default, the PI Client service runs as the local system account. That is, as the machine hosting the PI Client.
    As long as this account has rights to:
  2. Read and write to the PI Client working directory (see Working Directory, below)
  3. Read and write to each of your Estimating export directories
  4. Read and write to each of your Estimating import directories

Then you should be fine.

  1. Set the PI Client service to run as a domain user:

For some networks, it is preferable to control the PI Client service’s access to network resources by running the PI Client service as a domain user. In order to do so, you will need a domain user which can run as a service, and which has rights to:

  • Read and write to the PI Client working directory (see Working Directory, below)
  • Read and write to each of your Estimating export directories
  • Read and write to each of your Estimating import directories

How do I set the domain user for a PI Client Service?

With the upcoming 4.1 release of the PI Client, you will be able to make these changes directly inside the PI Client Advanced Settings page.

For the 4.0 release of the PI Client, you’ll need to do this the old-fashioned way, aka using the Windows Services tab. As per standard Microsoft documentation, you can set the credentials for a service by following these steps:

  1. From the Start Menu, launch the services.msc. The services tab should appear
  2. Scroll down until you see the item “PI Client Service”. Double-click on this item. The properties page will appear.
  3. Choose the “Log on” tab.

  1. To set a domain account, choose “This account” radio button. Enter your domain and account information, and password.
  2. Click “Apply”, then “OK”.
  3. From the main services window, right-click on the PI Client service, and choose “Restart”.
  4. Done

My company accesses the internet via a proxy server. How do I configure this?

In most cases, the PI Client will automatically detect and use your proxy server for your windows machine. However, if you have custom proxy server settings, you can configure the PI Client to use these manually.

  1. Launch the PI Client tray application. You can do this from the start menu.
    Start Menu->All Programs->PI Client->PiClient.exe
  2. The PI Client configuration home screen will appear.
  3. Choose Advanced Settings
  4. The Advanced Settings tab appears. The configuration for proxy servers can be seen at the top of the page. Configure your proxy settings accordingly.
  5. Click OK.
  6. Close the PI Client.
  7. Your settings are now enabled

My company uses a firewall to protect our network. What ports do I need to open for the PI Client to access the internet?

The PI Client uses standard internet technologies for communicating with PartsTrader. Http and Https are required. The PI Client will need the rights to download files from the internet, including DLLs and exes, as it will occasionally download updates to itself.

Is the PI Client secure?

All PI Client communication, including automatic updates, are run over secure HTTPS channels. None of your data will ever be unencrypted or publicly available.

The PI Client is not sending data to PartsTrader. What could be wrong?

This is, of course, a broad question, but there are some clear things to check:

  1. This may sound simplistic, but is the PC hosting the PI Client running?
  2. Is the PI Client service running?
  3. Does the PC have access to the internet?
  4. To ensure the PI Client can access the PartsTrader services, open a browser on the host machine, and navigate to the following URL:
  5. You can review the PI Client logs. While we don’t normally recommend log-reading for most customers, for IT specialists, we assume this is second nature to you. See “Where are the PI Client log and configuration files?” below.

Where are the PI Client log and configuration files?

  1. More often than not, you will not need to bother with the log files of the PI Client. The PI Client should run without issue, uploading and downloading estimate data behind the scenes. However, if there are issues, log files are always helpful to determining what might have gone wrong.
    The PI Client stores a working directory on the hosting PC. In order to navigate to this, follow these steps:
    Launch the PI Client tray application. You can do this from the start menu.
    Start Menu->All Programs->PI Client->PiClient.exe
  2. The PI Client configuration home screen will appear.
  3. Choose Advanced Settings
  4. The Advanced Settings tab appears. At the bottom of the page you will see a link for the “Working Directory”.
  5. Click this link. This will launch a windows explorer window to the PI Client Working Directory.

What is in the PI Client Working Directory?

The working directory contains the following data:

  1. Log files for the PI Client tray application:
  2. PiClientDebugLog.txt
  3. PiClientErrorLog.txt
  4. PiClientVerbose.txt
  5. Log files for the PI Client service:
  6. PiClientServiceDebugLog.txt
  7. PiClientServiceErrorLog.txt
  8. PiClientVerboseLog.txt
  9. Archived Logs folder: This contains older logs for the last 10 days
  10. PIClientSettings.xml: Configuration settings for the PI Client applications
  11. Estimating folders: For each configured Estimating software, you will see a folder for the imports and exports

Reading the PI Client Service debug log

The PI Client produces many distinct log files. However, the most comprehensive of these is PiClientServiceDebugLog.txt. This will contain each action the PI Client has performed; in the order it has performed them.

Sidenote: Tailing the logs
We find it useful in debugging to run a tail program against the PIClientDebug.txt file during diagnosis, so you can see, real-time, the entries being written to this file. A good program to help with this is Tail for Win32

This program is precompiled and does not require installation, so you can put this on the repairer’s machine without installing anything, fire up the program and tail the PiClientDebugLog.txt to see its output as the PI Client performs actions.

When reviewing this log, it’s often easier to do the following:

  1. Open this log file in a tail program
  2. Export your estimate from the Estimating software
  3. Review the data in the tail program / log file to see that the PI Client sent / received the data to / from PartsTrader successfully.

Let’s say the estimate exported had a file name of ae748316. This would be the output of a successful transaction of the PI Client. While this is a lot of text, we’ve highlighted the critical points in this message in bold red(with a comment above in green).

2012-03-22 14:05:34.2232 | Info | A new extract with ID ae748316 was detected at C:\CCC\CCCONE\EMS\Export |PiClient.BackgroundService.EstimatingInstance

2012-03-22 14:05:34.2232 | Info | Creating lock file at C:\CCC\CCCONE\EMS\Export\ae748316.PICL |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

Comment: the PI Client is writing the PICL file

2012-03-22 14:05:34.2320 | Info | Successfully created lock file at C:\CCC\CCCONE\EMS\Export\ae748316.PICL |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:34.2320 | Info | Added extract ae748316 to extract set. | PiClient.BackgroundService.EstimatingInstance

2012-03-22 14:05:34.9527 | Info | Executing command CompoundExtractCommand consisting of:

Modify extract ae748316 policy to PiClient.Model.EmptyPollingResponsePolicy

PauseExecutionCommand pausing for 20ms

FillExtractDetailsCommand on ae748316

Modify extract ae748316 policy to PiClient.BackgroundService.EstimatingExtracts.PollingResponsePolicies.AwaitingEstimatingFilesPolicy |PiClient.BackgroundService.EstimatingMonitor
Comment: checking the estimate is of type Estimate or Supplement. This one is a Supplement

2012-03-22 14:05:34.9791 | Info | Reading extract details from envelope at C:\CCC\CCCONE\EMS\Export\ae748316.ENV |PiClient.BackgroundService.EmsFiles.EnvelopeReader

2012-03-22 14:05:34.9820 | Info | Attempting to copy C:\CCC\CCCONE\EMS\Export\ae748316.ENV to dbf format. | PiClient.BackgroundService.EmsFiles.EnvelopeReader

2012-03-22 14:05:35.0518 | Info | Attempting to delete file C:\CCC\CCCONE\EMS\Export\ae748316.dbf |PiClient.BackgroundService.EmsFiles.EnvelopeReader

2012-03-22 14:05:35.0518 | Info | Extract envelope ID ae748316 was successfully parsed with transaction type Supplement | PiClient.BackgroundService.EstimatingExtracts.ExtractCommands.FillExtractDetailsCommand

2012-03-22 14:05:35.9728 | Info | Executing command Modify extract ae748316 policy to PiClient.BackgroundService.EstimatingExtracts.PollingResponsePolicies.NewExtractReadyPolicy |PiClient.BackgroundService.EstimatingMonitor

2012-03-22 14:05:37.0085 | Info | Executing command CompoundExtractCommand consisting of:

Modify extract ae748316 policy to PiClient.Model.EmptyPollingResponsePolicy

CopyEmsFilesCommand: Extract ae748316 to C:\ProgramData\PartsTrader\CCC\ae748316

CreateCreateEmsXmlCommand on ae748316

SaveEmsXmlOutputCommand on extract ae748316 to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.xml

ValidateEmsXmlCommand on extract ae748316

XsltTransformCommand from C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.xml to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316-bms.xml using C:\Program Files (x86)\PartsTrader\PiClient\Schemas\EMStoBMS.xslt

Send BMS message command |PiClient.BackgroundService.EstimatingMonitor

Comment: Copying all estimate files to working directory

2012-03-22 14:05:37.0124 | Info | Attempting to copy EMS files for extract ae748316 from C:\CCC\CCCONE\EMS\Export to C:\ProgramData\PartsTrader\CCC\ae748316 |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0124 | Info | Target directory not found. Creating directory C:\ProgramData\PartsTrader\CCC\ae748316 |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0124 | Debug | Copying file C:\CCC\CCCONE\EMS\Export\ae748316.ad1 to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.ad1 |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0124 | Debug | Copying file C:\CCC\CCCONE\EMS\Export\ae748316.ad2 to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.ad2 |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0275 | Debug | Copying file C:\CCC\CCCONE\EMS\Export\ae748316.dbt to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.dbt |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0275 | Debug | Copying file C:\CCC\CCCONE\EMS\Export\ae748316.env to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.env |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0275 | Debug | Copying file C:\CCC\CCCONE\EMS\Export\ae748316.lin to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.lin |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper

2012-03-22 14:05:37.0275 | Debug | Copying file C:\CCC\CCCONE\EMS\Export\ae748316.pfh to C:\ProgramData\PartsTrader\CCC\ae748316\ae748316.pfh |PiClient.BackgroundService.EmsFiles.PiClientFileSystemHelper