312352B EN. Instruction Manual Full Line Software with Third Party Interface

Transcription

1 Instruction Manual Full Line Software with Third Party Interface B EN Full Line Matrix software (246000) sold only to retrofit existing Matrix installations. Software is part of (North America (N. A.) transceiver and software) and (Australia transceiver and software). For use with Graco Matrix Electronic Meter and Tank Level Monitor Components. Graco Inc. P.O. Box 1441 Minneapolis, MN Copyright 2007, Graco Inc. is registered to I.S. EN ISO 9001

2 Contents Definition of Terms DMS: Dealer Management System Third Party Developer Interface Validation Posting Work Order (up to 12 characters) JobCode (up to 3 characters) Introduction What is This Document? Assumptions Matrix System Component - References Graco Instruction Manuals: Dispensing by Work Order With The Matrix Full Line System How it Works Entering Work Orders into the Matrix System Matrix Full Line System with Interface to Business System Work Order Validation Work Order Posting General Interface Notes Matrix Interface Configuration File Interface Server Work Order Validation Work Order Posting Java Applets TpViewWorkorderDetailsApplet TpAddPartApplet Validation Key TpDmsInterfaceConfigurationApplet Implementation Examples Appendix A - XML Message Formats Matrix Validation Request Matrix Validation Response MatrixPostingRequest MatrixPostingResponse Appendix B - Work Order Entry Process at PC - No Interface Appendix C - Work Order Entry Process at PC - With Interface, Without TpAddPartsApplet Appendix D - Work Order Entry Process at PC - With Interface, With TpAddPartsApplet Graco Standard Warranty Graco Phone Numbers B

3 Definition of Terms Definition of Terms DMS: Dealer Management System Generic term referring to the business system a car dealership or similar organization uses to manage their business. Third Party Developer The software developer who creates a software communication link between Matrix and a Matrix customer s DMS. The developer might be an independent software consultant/contractor or might be a programmer on the customer s staff. Interface A custom software program provided by a Third Party Developer (not Graco) that communicates with both Graco s Matrix fluid management system and the Matrix user s DMS. The Matrix half of this communication link is defined in this document. The other half, required to communicate to the DEMS, is undefined in this document and is to be determined by the developer and end user. The exact functionality provided by the Interface depends on the developer and the needs of the end user, but at minimum the Interface performs work order validation and post-dispense processing of the shop s fluid dispenses reported by Matrix. Validation A means by which Matrix confirms that a work order entered by a user into the Matrix system is a valid work order, that it exists and can have fluid charged to it. The validation process happens before the fluid is dispensed. Posting The process of adding a fluid charge to a work order in the DMS. The posting process happens after the fluid is dispensed. Work Order (up to 12 characters) A unique (within the scope of the dealership) numeric or alphanumeric identifier that is linked to a list of labor and parts charges representing the expenses associated with a specific customer s vehicle repair. Also referred to as a repair order, or RO. In Matrix, the allowed work order characters are: A-Z, 0-9, dash (-), forward slash (/), period (.) and space ( ). The work order can be used more than once in Matrix (it does not have to be unique). JobCode (up to 3 characters) A code that identifies where on a work order the fluid charge should be added. The content of this field must be defined by the developer of the Interface. The JobCode can be up to 3 characters long. The allowed JobCode characters are: A-Z, 0-9 and space ( ) B 3

4 Introduction Introduction What is This Document? The purpose of this document is to explain to a software developer how they can create a custom software program that communicates between Graco s Matrix Total Fluid Management System and a Matrix user s business system, reporting the amount of fluid dispensed and the charges associated with that fluid for a specific customer s work order. This software program is called an Interface in this document. This document only focuses on the Matrix portion of the Interface, illustrating what is required and supported by Matrix. This document only applies to Matrix Full Line software version It does not apply to any version of Matrix Full Line with ADP interface, Matrix Full Line with Reynolds & Reynolds interface or Tank Level Monitor Only software. Assumptions 1. The reader is a software developer who understands networking, Java, XML and web technologies. 2. The reader knows or can learn how the business system works at the Matrix installation site. 3. The reader has a basic understanding of Matrix: what it is, what it does, and how it works. 4. The reader is familiar with the end user s business process of using Matrix. 5. The target Matrix system uses work orders to track fluid dispenses. While the user s-defined identifier for this term may be something else (i.e., repair order or RO), work order is used in this document. Matrix System Component - References Graco Instruction Manuals: Full Line System Design and Installation Matrix Meter Transceiver Full Line Software B

5 Dispensing by Work Order With The Matrix Full Line System Dispensing by Work Order With The Matrix Full Line System A standard Matrix Full Line System tracks bulk fluid dispenses in a shop, including exact quantities and times of the dispenses. Matrix tracks these dispenses by work order, a user-defined identifier that maps to a specific job or project in the end user s business system. How it Works Entering Work Orders into the Matrix System There are two ways to enter work orders into the Matrix system. At a Matrix PC 1. An alphanumeric work order is entered into the Maxtrix system prior to dispense either via: Browser-based screens at the Matrix PC or, Matrix Meter (Graco Instruction Manual ) See Entering Work Orders into the Matrix System (page 5). 2. User selects a meter (fluid) and enters the, up to, 12-digit, alphanumeric work order. (a) 3. An optional data field called Job Code can be used to add identifying information about the dispense. 4. When fluid is dispensed, the Matrix software records fluid amount for the associated work order. FIG. 1 A meter can dispense fluid against a work order at any time. (b) (c) (d) FIG Navigate to work order screen. Click Add Work Order button (a) (FIG. 1). 2. From popup window (FIG. 2): select meter (b) enter work order number (c) enter job code (optional) (c) 3. Click Send to Meter button (d) (FIG. 2). The Matrix PC sends the work order to the meter, which puts the work order into the meter s local work order list B 5

6 Dispensing by Work Order With The Matrix Full Line System At Meter 1. The technician chooses the appropriate meter for the fluid being dispensed. 3. Type in the work order number and select ENTER (FIG. 5). WORKORDER ENTER NEW SELECT SELECT FIG. 5- Enter New Work Order Number FIG. 3- Meter 2. On the work order screen on the meter choose ENTER NEW (FIG. 3) to add a new work order. The meter sends the work order to the PC. Summary Whichever method of entering the work order is used, the following process occurs: 1. Technician selects meter to dispense required fluid. WORKORDER ENTER NEW SELECT SELECT 2. Technician selects appropriate work order from work order list. 3. Technician dispenses fluid. 4. Meter communicates with PC, reporting exact volume of fluid dispensed. FIG. 4- Select Enter New 5. PC records amount of fluid in the meters dispense history. The Matrix system tracks: Type of fluid dispensed Amount of fluid dispensed Time and date fluid was dispensed Associated work order number By itself, the Matrix system cannot apply the proper charge for the dispensed fluid to the work order in the business system. The end user must monitor Matrix and manually add the appropriate charge to the work order B

7 Matrix Full Line System with Interface to Business System Matrix Full Line System with Interface to Business System The Interface provides two important basic functions that a standard Matrix system does not have: work order validation automatic posting of charges for dispensed fluid. Work Order Validation When a user enters a work order into the Matrix system, Matrix does not know if it is a legitimate work order in the user s business system. Even if the work order exists in the business system, it s possible that it s been closed or has a status that doesn t allow making any additional charges to it. Since the goal is to ensure that the work order is charged for the fluid dispensed against it, it is important to confirm the legitimacy of the work order prior to dispensing the fluid. The process is known as Work Order Validation. Matrix validates work orders in two ways: XML message an applet See page 9, Work Order Validation for a description of XML message validation and page 16 for a description of applet validation. Work Order Posting After the user has finished dispensing fluid with the Matrix system, the process of calculating the appropriate charge for the fluid and adding the charge to the work order in the business system is called Work Order Posting. Matrix s ability to work with a third party application to accomplish these functions is somewhat configurable. The various implementation options are covered in this document. General Interface Notes A minimal interface implementation involves writing a standalone application this document refers to as the Interface Server. This application performs the validation and posting functions. The Interface Server can be optionally supplemented by Java applets that are embedded within Matrix screens to provide an integrated look and feel to the interface. The Interface Server and applets are provided by a third party developer. The developer must determine the programming language used to create the Interface Server. Matrix is written in Java 1.4 and the sample code is also provided in Java. If the developer chooses to implement the applets, they must also must be written in Java. Matrix Interface Configuration File In the installation directory of Matrix (c:\program Files\Graco\MatrixNet) is a file called MatrixInterfaceConfig.xml. This XML file contains interface-specific configuration settings that Matrix read (only) at startup. The elements contained in this file define for Matrix which of the available interface-specific features are used and how they are implemented. Required elements in the configuration file: ThirdPartyInterfaceEnabled - Tells Matrix whether to use the third party interface by selecting either yes or no. The default setting is no. This element globally turns on or turns off the interface. This is one of two settings that must be configured to enable the interface. The other setting is in the Meter s configuration settings, located within the Matrix setup screens. InterfaceAddress, InterfaceUrl and InterfacePort - The host name/ip address and port number of the Interface Server. The defaults are and Optional elements in the configuration file: ViewWorkorderDetailsApplet - The full HTML <APPLET> tag for TpViewWorkorderDetailsApplet, an applet that displays work order status. AddPartsApplet - The full HTML <APPLET> tag for TpAddPartApplet, an applet that performs work order validation and other application-specific functions prior to dispensing fluid against a work order B 7

8 Matrix Full Line System with Interface to Business System DMSInterfaceConfigurationApplet - The full HTML <APPLET> tag for TpDmsInterfaceConfigurationApplet, an applet used to configure the interface itself from within Matrix screens. Meter Setup The presence of the HTML <APPLET> tags in the configuration file, coupled with the ThirdPartyInterfaceEnabled element being set to yes, turns on that feature; the absence of the tag turns it off. (a) Elements in the file other than those listed above are ignored. (b) The default settings for this file point to example Java applets and an Interface Server provided by Graco. These examples are not intended for production use; they are provided solely to illustrate how the various parts of the interface are supposed to function. It is the interface developer s responsibility to modify or replace these examples with production-ready versions. The source code for the example applets is in the C:\Program Files\Graco\MatrixNet\docroot\interface directory. The source code for the example Interface Server is in C:\Program Files\Graco\MatrixNet\Acme. Enabling a Matrix Meter In the previous section covering the MatrixInterfaceConfig.xml file, the element called ThirdPartyInterfaceEnabled is a system-wide switch that enables or disables the third party interface within Matrix. If ThirdPartyInterfaceEnabled is no, Matrix will function as a standard system with no interface. No work order validation or posting occurs. If ThirdPartyInterfaceEnabled is yes and the individual meter is configured to use the interface, work order validation and posting will occur. FIG. 6- Typical meter setup screen The Matrix setup screens include a screen called Meter Setup. This screen includes a list of all the meters in the system (a) (FIG. 6). Clicking on the modify link for a meter displays the configuration screen for that meter. See Graco Matrix Instruction Manual for complete instructions for Adding a Meter and Modifying Existing Meter Information. For a meter to use the interface, the meter must be configured to use work orders, i.e., Use Work Orders set (b) to yes (FIG. 6). and the interface link for this meter turned on, i.e., Enable DMS Link For This Meter (c) set to yes. Typically all meters in the system have these settings. However, under certain circumstances a Matrix user may choose to have different settings for specific meters. This is fine. It is important to note, however, that the interface only works for meters configured with the yes option selected in the Use Work Orders (b) and Enable DMS Link For This Meter (c) fields. See next section, Meter Setup, on how to configure the meter to use the interface. You must reprogram the meter if you change the Use Work Orders field. See Graco Instruction Manual for meter programming instructions. (c) You do not have to reprogram the meter if you change the Enable DMS Link For This Meter field B

9 Interface Server Interface Server This standalone application is the core of the interface between Matrix and the end user s business system. The Interface Server listens on a predetermined network port and accepts incoming socket connections from Matrix. The XML messages Matrix sends (and expects to receive in return) over this connection are listed in Appendix A. The Interface Server: reads in a Matrix request message, processes the message, and returns a response to Matrix. The Interface Server should be able to handle multiple simultaneous requests and be running whenever Matrix is running. Matrix is usually launched using a short cut in the Windows Startup folder. The Interface Server s primary job is to perform work order validation and posting of charges to the work order. At the developer s discretion, it may also perform other related tasks. Work Order Validation The work order validation process allows the Interface Server, working in conjunction with the business system, to decide whether a work order is valid so fluid can be dispensed against it. The validation process occurs prior to any fluid being dispensed by the Matrix system. If a work order is not validated, Matrix will not allow fluid to be dispensed against it. If the Interface Server allows dispensing against a particular work order, then the appropriate charges are posted to that work order in the business system. The following list is provided as a sample of suggested and/or typical validation criteria: the work order exists the work order is open, charges can be added to the work order. All third party interfaces to Matrix must implement this method of work order validation. Work orders entered into the Matrix system from a meter always use this method. An alternate method of validating work orders entered at the Matrix PC is described on page 7. Work Order Posting Regardless of how the work order was validated, when a meter finishes dispensing fluid against it, the meter sends the Matrix PC the amount that was dispensed. The Matrix PC, in turn, sends this information along with the work order number, fluid name, etc. to the Interface Server in a MatrixPostingRequest message. The Interface Server calculates the appropriate charges for the fluid and adds that charge to the work order in the business system. When it is complete, a success/failure indication in a MatrixPostingResponse message is sent back to the Matrix PC. Exactly what happens when a posting request is processed by the Interface Server is up to the developer. When entering a work order into Matrix, a user may need to enter more than just the work order. A work order may contain multiple lines with multiple labor operations. The fluid charge usually applies to one specific labor operation. The job code field in Matrix is used to provide a way for the end user to designate where on a work order to apply the fluid charge. The job code field is limited to three alphanumeric digits that are defined by the interface developer. This field exists in Matrix even if no interface is being used, but it s use is entirely optional. With an interface, it becomes the means by which a posting destination can be supplied at the time the work order is entered into Matrix. When a work order is entered into the Matrix system, Matrix makes a socket connection to the Interface Server and sends it a MatrixValidationRequest XML message. The Interface Server: queries the business system, determines the answer, and responds to Matrix with a MatrixValidationResponse message B 9

10 Interface Server EXAMPLE: A business system may structure a work order in the following manner for the fictitious work order Work Order #: Line A: Quick Lube Change Special #1 Labor Operation 1: Change motor oil Labor Operation 2: Change transmission oil Line B: New Tires Labor Operation 1: Mount and balance 4 new tires When dispensing motor oil against this work order, the end user wants the charge to be applied to Labor Operation 1 under Line A. The interface developer may choose to have the user enter A1 in the job code field to convey this intent. Other conventions are certainly possible. The business system and the end user s needs generally define what the job code field contains B

11 Java Applets Java Applets The Interface Server provides the basic functionality required to make an interface between Matrix and a business system work. The developer of the Interface Server should provide a way for the user to monitor the interface to review tasks such as work order validation and posting status. This can be done by building the Interface Server with its own user interface or by implementing one or more Java applets that are integrated within the Matrix user interface. While a separate user interface can provide more flexibility in the design, the applets provide an integrated look and feel with the rest of Matrix. The Matrix user interface is browser-based. Web pages are served by an embedded web server and are displayed within the Internet Explorer browser. Several pages have reserved screen real estate for Java applets provided by a third party. These applets must implement a Java interface that allow Matrix limited communication abilities with the applet through inter-applet communication. The applets provide an integrated look and feel for the business system interface with Matrix and also allow the developer to build a custom functionality into the interface. TpViewWorkorderDetailsApplet The primary purpose of this applet is to provide detailed interface-related information about a specific work order the Matrix user has selected. This Java applet is displayed in reserved screen space on the Meter Dispense History page, FIG. 8, page 13. The Meter Dispense History is found in section b. The Work Order Details section is found in section c. Space allocated to the TpViewWorkorderDetailsApplet is shown at the bottom. The TpViewWorkorderDetailsApplet must implement a Java interface called TpWorkorderDetailsInterface. This Java interface specifies the viewdetails ( ) and cleardetails ( ) methods, which are called by a Matrix applet on the same HTML page. The viewdetails ( ) method has a single String array arrangement that contains detailed information about what the user clicked on, such as work order and job code. The cleardetails ( ) method is used to clear the information shown in the TpViewWorkoderDetailsApplet, because the user has clicked off any specific work order. Third-party provided applets embedded in Matrix pages require a means to communicate with the outside world to perform tasks such as work order validation and work order posting status. Any Java applet can make a network connection back to the machine from which the applet was served, but for an applet to connect to other networked resources requires the applet be a signed applet. To avoid creating signed applets, consider creating a proxy application that can do the networking on the applet s behalf. The Interface Server may be able to perform this role. Matrix is designed to accommodate up to three different Java applets: 1. TpViewWorkorderDetailsApplet 2. TpAddPartApplet 3. TpDmsInterfaceConfigurationApplet Any combination, or none of these can be implemented. Each one appears in a predetermined page. Applet locations cannot be changed, although the size (width and height) can be adjusted. Specific details about each of these applets is reviewed in the following sections B 11

12 Java Applets The Meter Dispense History page displays two applets (FIG. 7). The top applets shows two JTables. Active Work Orders (a) - shows all active work orders that have yet to be dispensed. Dispense History (b) - shows completed dispenses. Below this applet is reserved space (c) for the TpViewWorkorderDetailsApplet. When the user clicks on any completed dispense, the viewdetails ( ) method of the TpViewWorkorderDetailsApplet is called. (a) (b) (c) FIG. 7- Meter Dispense History screen. In this screen shot the TpViewWorkorderDetailsApplet is the grey JTable shown at the bottom of the screen. (This example applet is provided by Graco to show applet placement. A real implementation of this applet would likely show a different UI.) B

13 Java Applets The work Orders page also shows two applets (FIG. 8). The top applet shows: a JTable (a) - displays the work order list for all meters in the system. Below the applet is reserved space (b) for the TpViewWorkorderDetailsApplet. When the user clicks on any work order in the top applet, the viewdetails ( ) method of the TpViewWorkorderDetailsApplet is called. (a) (b) FIG. 8- Work Order Information screen. The TpViewWorkorderDetailsApplet is the grey Jtable shown at the bottom of the screen. (This example applet is provided by Graco to show applet placement. The top applet shows a single row representing one meter. A real system would likely have many meters [many rows] listed here.) On both screens (FIG. 7 and FIG. 8) the TpViewWorkorderDetailsApplet should display the validation status of the work order and posting status of the dispense charge in the business system. The graphical content of the TpViewWorkorderDetailsApplet applet is ultimately up to the developer. The following list is provided for suggestion only: Show work order, job code, meter name, units Show work order validation status Show dispense posting status Other information that may be relevant to the fluid dispense and work order The default XML tag for this applet in the configuration file is: <ViewWorkorderDetailsApplet> <APPLET CODEBASE= / CODE= TpViewWorkorderDetailsApplet.class ARCHIVE= mm.mysql bin.jar WIDTH= 800 HEIGHT= 100 NAME= view_details >Applet not supported.</applet> </ViewWorkorderDetailsApplet> Note that while the applet is used on two different screens it is not explicitly told which screen the user is currently viewing. The presence of this applet s HTML tag in the configuration file will cause the applet to automatically be displayed on both screens. Modify the height and width as necessary but do not edit the applet s CODEBASE, NAME and MAY- SCRIPT attributes. The ARCHIVE tag must be set to include the jar file shown. This is necessary even if the applet doesn t use it; inter-applet communication will not work without it B 13

14 Java Applets TpAddPartApplet The primary purpose of this applet is to provide an alternative method for work order validation and to provide other application-specific features in the work order entry/validation process that must occur prior to dispensing fluid against the work order. This applet is shown to the user in the last step of adding a new work order to the Matrix system from a Matrix PC. Implementing this applet is referred to as the Non-Fluid Parts feature in this document. To better understand how this applet is used and what a developer can do with it, review Work Order Entry Process at PC - No Interface in Appendix B, page 23 and Work Order Entry Process at PC - With Interface, Without TpAddPartsApplet in Appendix C and D, starting on page 24 and 25. In all cases, the work order is initially entered in the same manner, but when the TpAddPart Applet is used, the user is presented with the applet prior to submitting the work order. The applet must implement the Java interface called TpAddPartInterface. This interface requires the applet provide these methods: public void setworkorderdetails(string workorder, String jobcode, String presetamount, String unitsofmeasure, String metername, int interfaceoption); public boolean isfinishedprocessing ( ); public boolean workorderisvalidated ( ); public void cancelworkorder ( ); public String getvalidationkey ( ). The HTML applet tag for this applet in the MatrixInterfaceConfig.xml file must contain the mayscript attribute because the methods listed above are called by JavaScript embedded in the HTML page with the applet. (a) FIG. 9- Sample (non-production) implementation of the TpAddPartsApplet. The applet shown here displays the information passed to it and implements the requisite Java interface, but it is otherwise, non-functional. The applet is expected to, at minimum, validate the work order. Matrix will not send to the Interface Server a MatrixValidationRequest for work orders submitted via this applet. When the Send to Meter button (a) is clicked, Matrix marks the work order as validated and directly sends the work order to the meter B

15 Java Applets There are other things the developer can do with this applet. EXAMPLE: The applet shows the user a list of non-fluid parts to choose from, similar to the shopping cart concept frequently used in on-line shopping. Once the fluid has been dispensed against the work order, the interface could add the selected parts to the work order at the same time as the fluid charge is posted. The TpAddPartsApplet screen (FIG. 12) contains two buttons, Send to Meter and Cancel Work Order. The Send to Meter button is initially disabled. The technical implementation details of this page and the applet it hosts are as follows: Context: The user wants to enter a new work order. The user has navigated to the Work Order Information page and has clicked the ADD WORK ORDER button (a) (FIG. 10). FIG. 10- Work Order Information Page (a) A meter (b) is selected (FIG. 11). A work order / job code (c), and preset amount (d) are entered (FIG. 11). The end user clicks the Continue button (e) (FIG. 11). FIG. 12- TPAddPartApplet 1. When the page body s onload event is fired, JavaScript embedded in the page calls the applet s setworkorderdetails ( ) method, providing the applet with the parameters entered by the user on the previous page. 2. JavaScript polls the applet, calling the applet s isfinishedprocessing ( ) method once per second until the method returns a boolean true value. During this time the applet is validating the work order and/or performing other tasks the developer has programed it to do, such as displaying a list of non-fluid parts. This work should be done in its own thread of execution in order for Matrix to properly communicate to the interface applet. 3. When isfinishedprocess ( ) returns to true, the applet s isworkordervalidated ( ) method is called. If it is true, the Send To Meter button is enabled. 4. If Send To Meter button is clicked, the applet s getvalidationkey ( ) method is called prior to closing the window and submitting the work order to Matrix. Details of the Validation Key function are provided in the next section. (e) (b) (d) (c) 5. If isworkordervalidated ( ) returns false or if at any time the Cancel button is pressed (or the page is closed by clicking the X button in the title bar) the work order entry process is stopped and the page is closed. The applet s cancelworkorder ( ) method is called prior to closing the screen. The work order is not added to Matrix. FIG. 11- Assign Work Order to Meter B 15

16 Java Applets Validation Key Within Matrix it is possible for the user to enter the same work order and job code multiple times, even for the same meter. EXAMPLE: A car s engine is under filled with oil and a second dispense is made to top it off. This means that some mechanism for differentiating between dispenses is necessary. The Matrix third party interface uses a validation key generated by the interface to accomplish this. TpDmsInterfaceConfigurationApplet The primary purpose of this applet is to provide a way for the interface developer to produce the user interface for configuration parameters that can be embedded within Matrix resulting in a seamless, integrated look and feel. If this applet is defined in the MatrixInterfaceConfig.xml file, a button labeled DMS Interface Setup (a) (FIG. 13) appears in the setup screens. The validation key returned by TpAddPartsApplet s getvalidationkey ( ) is the third party interface s unique identifier for a given dispense against a work order. This key is the same entity as found in a MatrixValidationResponse message from the Interface Server, which is the validation mechanism used whenever work orders are entered at the meter or when the TpAddPartsApplet is not used. Matrix will reference this validation key when communications with the interface post-validation, such as when sending MatrixPostingRequests. The validation key is not used in Matrix itself in any way, except to provide it to the interface when referencing a specific defense. The value returned by getvalidationkey ( ) is a JavaString that can be up to 255 (ASCII) characters in length and each character is a letter or digit (as defined by Java s Character.isLetterOrDigit( )). the validation key is stored in Matrix s internal database with the work order. The default XML tag for this applet in the configuration file is: <AddPartsApplet> <APPLET CODEBASE= / CODE= TpAddPartApplet.class WIDTH= 650 HEIGHT= 250 NAME= add_parts MAYSCRIPT= mayscript >Applet not supported.</applet> </AddPartsApplet> Modify the height and width as necessary but do not edit the applet s CODEBASE, NAME and MAY- SCRIPT attributes. FIG. 13- DMS Interface Setup (a) Clicking on this button displays a page reserved for the interface developer to configure the TpDmsInterfaceConfigurationApplet interface. This screen is optional. The third party interface configuration mechanism could also be provided by some other means, such as a GUI that is part of the Interface Server. Using an applet within the Matrix System Setup screens is provided as a way to make the overall Matrix and interface system appear more seamless and integrated from the end user s perspective. Except for the XML-based configuration file (page 7), Matrix provides no means of storing any interface-specific information. The interface developer is expected to provide this storage mechanism as part of the interface design: database, flat file, etc. The MAYSCRIPT attribute is necessary because this applet s methods are called from JavaScript B

17 Java Applets The default XML tag for this applet in the configuration file is: <DmsInterfaceConfigurationApplet> <APPLET CODEBASE= / CODE= TpDmsInterfaceConfigurationApplet. class WIDTH= 800 HEIGHT= 600 NAME= view_details >Applet not supported.</applet> </DmsInterfaceConfigurationApplet> Modify the height and width as necessary but do not edit the applet s CODEBASE, NAME and MAY- SCRIPT attributes. Implementation Examples In all cases, an interface to Matrix will include an Interface Server. The XML messages listed in Appendix A satisfy the minimum requirements necessary for a business system to interface with Matrix. The developer can implement one or more of the three applets embedded within the Matrix user interface to design the Interface Server to work in coordination with the applet(s), exchanging data via stream pipes or some other mechanism. The developer can add extra functionality to the Interface Server, such as: its own user interface additional reporting features a server-oriented process that supports the applets, leaving the Interface Server to process XML messages from Matrix. EXAMPLE 1 Situation: A car dealership owner wants fluid dispensed by the Matrix system in the shop to be automatically billed to the work order in the business system. The owner is not interested in fancy, extravagant user interfaces. Possible Solution: 1. Create an Interface Server application, per Graco specifications. 2. Create a TpViewWorkorderDetailsApplet with a simple GUI that allows the user to see the validation posting status of each work order in the system. EXAMPLE 2 Situation: A truck dealership uses Matrix in their service shop. Work orders are entered into Matrix by the service manager at a Matrix PC on the service counter. The dealership management wants fluid dispensed to be automatically charged to the work order in the business system and they want the interface to have a completely integrated look and feel. Possible Solution: 1. Create an Interface Server application, per Graco specifications. This is a console application. 2. Modify the Interface Server to work with the applets described below. a. Create a TpViewWorkorderdetailsApplet to show validation and posting status. b. Create a TpDmsInterfaceConfigurationApplet to show/edit interface configuration settings B 17

18 Java Applets EXAMPLE 3 Situation: A car dealership uses Matrix in their quick lube oil change service bays. Nearly all oil changes use on of 10 oil filters and a drain plug gasket. Management is looking for a way to make the quick lube bays more efficient. Possible Solution: 1. Create an Interface Server application, per Graco specifications. 2. Modify the Interface Server to work with the TpAddPartsApplet and TpViewWorkorderDetailsApplet described below. 3. Create a TpViewWorkOrderDetailsApplet to show validation and posting status. 4. Create a TpAddPartsApplet. This applet works with the Interface Server to: a. validate work orders, and b. allow the service tech to choose from a short list, the correct oil filter and drain plug gasket for the vehicle being serviced. The interface server is smart enough to remember lists of parts for each work order validated using the validation key as the list identifier. When posting charges for the fluid, the Interface Server also adds the list of parts to the work order in the business system. EXAMPLE 4 Situation: A municipal garage has a business system that does batch processing on work orders. At the end of the workday, garage personnel tally the day s work orders against the work performed. They would like their Matrix system to produce a specifically formatted file containing the day s fluid dispenses that their business system can import and process. Possible Solution: 1. Create an Interface Server application, per Graco specifications. 2. Create a reporting-oriented GUI for the Interface Server. 3. Modify the Interface Server to queue the posting requests sent by Matrix. Allow the user to query this queue and create a file of to-be-posted fluid dispenses in a format defined by the business system. The business system can import this file and process it s contents as a single batch. 4. The developer could optionally create a TpViewWorkorderDetailsApplet to show validation and posting status within Matrix screens B

19 Appendix A - XML Message Formats Appendix A - XML Message Formats This appendix presents two messages that Matrix will send to an Interface Server and the corresponding replies that the Interface Server returns to Matrix. Matrix will open a socket connection to the Interface Server (connection details are defined in the Matrix Interface Configuration File section, page 7), send the request and wait for the response before closing the connection. Every XML message that Matrix sends to the Interface Server will end with an EOT (0x04) byte. Matrix expects all incoming messages to also end with an EOT (0x04) byte. Matrix Validation Request This message is sent by Matrix to the Interface Server when a work order is entered into the Matrix system. Message Format: <MatrixValidationRequest> <ValidationRequestKey/> <Workorder/> <JobCode/> <MatrixValidationRequest> Definition of Elements: 1. ValidationRequestKey - An identifier assigned by Matrix to a particular MatrixValidationRequest. This key must be included in the MatrixValidationResponse message returned to Matrix. 2. Workorder - See Definition of Terms (page 3). 3. JobCode - See Definition of Terms (page 3). Usage: The purpose of this message is to ensure the validity of the work order entered into the Matrix system. The interface confirms: the work order exists in the business system, the work order is still open the work order status allows additional charges/parts to be added to it The interface must respond with a MatrixValidationResponse message. The MatrixValidationResponse message allows or disallows fluid to be dispensed in the Matrix system. Matrix will send this message to the interface each time a work order is entered into the system. The only exception occurs when the interface developer has implemented the TpAddPartApplet (see page 14). This message is sent immediately after the user has entered the work order. The interface must respond with a MatrixValidationResponse message within 30 seconds. If no response is received within that time frame, the work order is not validated. This means the user cannot dispense fluid against it and must either try reentering the same work order or try entering a different work order number. Once the work order is validated, Matrix will not send this message again for the same work order instance. Because Matrix does not stop a user from entering the same work order (and job code) multiple times, it could appear from the Interface Server s perspective that the same work order is sent multiple times. This message could also be sent multiple times if the work order was not initially validated and the user is retrying the entry B 19

20 Appendix A - XML Message Formats Matrix Validation Response This message is sent by the Interface Server back to Matrix in response to receiving a MatrixValidationRequest message. Message Format: <MatrixValidationResponse> <ValidationRequestKey/> <ValidationStatus/> <ValidationErrorDescription/> <TpValidationKey/> <MatrixValidationRequest> Definition of Elements: 1. ValidationRequestKey - This element is an echo of the field by this same name in the ValidationRequestMessage. This field is used by Matrix to match the response to the original request. 2. ValidationStatus - Indicates the result of the validation request. Valid values for this field are 1 if the work order is validated and 0 if it is not validated. Any other value translates to the work order not being validated. 3. ValidationErrorDescription - Limited to 100 characters. This description is shown to the Matrix user as the reason why the work order was not validated if ValidationStatus is anything other than TpValidationKey - Limited to 255 (ASCII) characters that are either a digit or letter (according to Java s Charcter.isLetterOrDigit ( )). This is an identifier key generated by the Interface Server and used by the Interface Server to uniquely identify a fluid dispense. Usage: The interface must respond to each MatrixValidationRequest with a MatrixValidationResponse message. The ValidationRequestKey elements in both messages must match exactly. The interface must respond with a MatrixValidationResponse message within 30 seconds. If no response is received within that time frame, the work order is not validated. This means the user cannot dispense fluid against it and must either try reentering the same work order or try entering a different work order number. The intent of the TpValidationKey element is to provide a mechanism by which a third party developer can place a unique identifier (key) in this field that enables them to distinguish between duplicate work order entries. Within Matrix there are not restrictions against using the same work order (or work order and job code combinations) multiple times. If the returned ValidationStatus is 1, and the work order was entered at the meter, the PC tells the meter the work order was validated. and the work order was entered at the PC, the PC sends the work order to the meter. The work order appears in the meter s work order list. The technician can dispense fluid against this work order at any time by selecting it from the list on the meter. If the returned ValidationStatus is 0, and the work order was entered at the meter, the PC sends the meter a rejection message for this work order. the meter appears as shown in FIG. 14 with a WO REJECTED message and does not allow dispensing against the work order. and the work order was entered at the PC, the PC will display the message in ValidationErrorDescription. the PC will not send the work order to the meter. the work order will appear highlighted in red on the work order screen. the PC user has the ability to delete it or retry validation. additional work orders for this meter cannot be entered until this one is deleted or validated. WO REJECTED CANCEL ENTER WORKORDER LEFT JOB RIGHT FIG. 14- Work order not approved message B

21 Appendix A - XML Message Formats MatrixPostingRequest This message is sent by Matrix to the Interface Server at the completion of the fluid dispense. Message Format: <MatrixPostingRequest> <PostingRequestKey/> <TpValidationKey/> <Workorder> <JobCode/> <Dispense/> <MeterName/> <FluidName/> <Volume/> <Units/> <Dispense/> <MatrixPostingRequest> Definition of Elements: 1. PostingRequestKey - An identifier assigned by Matrix to particular MatrixPostingRequest. This key must be included in the MatrixPostingResponse message returned to Matrix. This key s value is not necessarily the same as the ValidationRequestKey in the MatrixValidationRequest message. 2. TpValidationKey - The identifier originally assigned by the Interface Server to this dispense via the work order validation process. 3. Workorder - See Definition of Terms (page 3). 4. JobCode - See Definition of Terms (page 3). 5. Dispense - This element defines the fluid dispense event, including what fluid was dispensed by what meter and how much. a. MeterName (up to 64 characters) - The name is assigned to this meter in Matrix. b. FluidName (up to 20 characters) - The name is assigned to this fluid in Matrix. c. Volume (a number in the format X.XXX) - The exact volume of fluid dispensed. d. Units - the units of measure for the volume element (c). Units are expressed as one of the following: pints quarts gallons liters Usage The main purpose of this message is to inform the interface of the dispense of a specific (single) fluid. The interface will then apply the appropriate charge(s) to the work order in the business system. The location on the work order where the fluid charge is placed is specified by the Job Code. The interface must respond to this message with a MatrixPostingResponse message. There is no specific time limit in which the interface must respond, but Graco recommends that a response must be sent within 30 seconds of receipt of the MatrixPostingRequest. Matrix will send this message to the interface immediately upon completion of a fluid dispense event. The exact same message could be sent again if the initial posting attempt fails for any reason, i.e., the Posting Status in the MatrixPostingResponse message was not 1 or a socket connection to the Interface Server could not be established. Any repeats are a result of the user manually initiating the retry by right-clicking on the dispense in the meter s dispense history and choosing Retry Posting B 21

22 Appendix A - XML Message Formats MatrixPostingResponse This message is sent by the Interface Server to Graco in response to having received a MatrixPostingRequest message. Message Format: <MatrixPostingResponse> <PostingRequestKey/> <PostingStatus/> <PostingErrorDescription> <MatrixPostingResponse> In any case, the meter does not display any posting status information on its local display; this information is exclusively shown on Matrix screens at the PC. If the work order was entered at the PC and a Matrix administrator overrode validation and posting, the resulting dispense will appear highlighted in yellow to indicate the override status. Definition of Elements: 1. PostingRequestKey - This element is an echo of the field by this same name in the MatrixPostingRequest message. This field is used by Matrix to match the response to the original request. 2. PostingStatus- Indicates the result of the posting request for the fluid itself. Valid values for this field are 1 if the fluid was successfully posted and 0 if it was not. 3. PostingErrorDescription - Limited to 100 characters. This is a required field if PostingStatus is not 1. This description is shown to the Matrix user as the reason why the fluid dispensed against this work order was not successfully posted. Usage: The interface must respond to this message with a MatrixPostingResponse message. There is no specific time limit in which the interface must respond, but Graco recommends that a response must be sent within 30 seconds of receipt of the MatrixPostingRequest. If the returned PostingStatus is 1, the dispense will appear in the dispense history table on the Meter Dispense Information page with Posting Status of Complete. If the returned Posting Status is not 1, the dispense will appear highlighted in red to indicate it was not completely successful. Right-clicking the dispense record and choosing View Posting Details will show the error message returned in PostingErrorDescription. The user has the ability to retry the posting effort by right-clicking on the dispense record and selecting Retry Posting Charges, which will cause Matrix to resend the MatrixPostingRequest B

23 Appendix B - Work Order Entry Process at PC - No Interface Appendix B - Work Order Entry Process at PC - No Interface 5. When complete, the user clicks the Send to Meter button (e) (FIG. 16). 6. The Matrix PC sends the work order to the selected meter. (a) FIG. 15 (b) (c) (d) (e) FIG The user navigates to the Work Order Information screen (FIG. 15). 2. The user clicks on the ADD WORK ORDER button (a) (FIG. 15), which causes the Assign Work Order to Meter screen (FIG. 16) to appear. 3. A meter is selected from the drop-down list (b) (FIG. 16). 4. The work order, job code (c) and preset amount field (d) (FIG. 16) are filled in. The job code field is optional. If the meter is not in preset mode, the preset amount field is not editable B 23