equipmentData.pdf

Equipment Data (ED) InterfaceLast Updated: Saturday, 25 August 2012 Last Reviewed: December 2012 This document contains confidential and trade secret information of CATERPILLAR, and may not be copied or used except under license from CATERPILLAR. The inclusion of a copyright notice hereon is precautionary only, and does not imply publication or disclosure. Copyright © 2006 Caterpillar Inc., 100 N.E. Adams, Peoria IL 61629 Cat and Caterpillar are trademarks of Caterpillar, Inc. All other trademarks and registered trademarks are the property of their respective holders. Table of Contents Modification History ......................................................................................................5 Glossary .........................................................................................................................6 Process Overview ............................................................................................................8 Caterpillar Preferred Option .........................................................................................9 Related Interfaces ........................................................................................................9 Field Types and Definitions ..........................................................................................9 Upload Equipment Information – Text File ................................................................10 General Comments & Definitions ...............................................................................10 Error Architecture, Error Codes, and Error Messages 11 Elements, Characteristics, Operator Symbols 11 Array Sizes 11 Currency Considerations ............................................................................................11 Regional Considerations ............................................................................................11 Layouts .......................................................................................................................12 Layout Comments 12 Layout Types 12 Equipment Information Record FLAT FILE record layout 12 Transmission/Media Type ..........................................................................................12 Testing Procedures ....................................................................................................13 Testing Coordination 13 Testing Comments 13 Who To Contact 13 Test Configuration 13 Sample Test Data 13 Production Information ...............................................................................................14 Production Comments 14 Production Configuration 14 Application URL .........................................................................................................14 DMS Download Function in Equipment Data Web Site ............................................14 General Comments & Definitions ...............................................................................14 Error Architecture, Error Codes, and Error Messages 16 Elements, Characteristics, Operator Symbols 17 Array Sizes 17 Currency Considerations ............................................................................................17 Regional Considerations ............................................................................................17 Layouts .......................................................................................................................17 Layout Comments 17 Layout Types 18 Equipment Information Record Fields Updating 18 Equipment XML record layout 18 Transmission/Media Type ..........................................................................................19 Testing Procedures ....................................................................................................19 Testing Coordination 19 Caterpillar: Confidential Green 2 Testing Comments 19 Who To Contact 19 Test Configuration 20 Sample Test Data 20 Production Information ...............................................................................................20 Production Comments 20 Production Configuration 20 DMS Automatic Download ..........................................................................................21 General Comments & Definitions ...............................................................................21 Error Architecture, Error Codes, and Error Messages 23 Elements, Characteristics, Operator Symbols 23 Array Sizes 23 Currency Considerations ............................................................................................23 Regional Considerations ............................................................................................24 Layouts .......................................................................................................................24 Layout Comments 24 Layout Types 24 Equipment XML record layout 24 Transmission/Media Type ..........................................................................................25 Testing Procedures ....................................................................................................25 Testing Coordination 25 Testing Comments 25 Who To Contact 25 Test Configuration 25 Sample Test Data 26 Production Information ...............................................................................................26 Production Comments 26 Production Configuration 26 Download Equipment Information from Search Results – Text File .......................27 General Comments & Definitions ...............................................................................27 Error Architecture, Error Codes, and Error Messages 28 Elements, Characteristics, Operator Symbols 28 Array Sizes 28 Currency Considerations ............................................................................................28 Regional Considerations ............................................................................................28 Layouts .......................................................................................................................29 Layout Comments 29 Layout Types 29 Equipment Information File FLAT FILE record layout 29 Transmission/Media Type ..........................................................................................29 Testing Procedures ....................................................................................................29 Testing Coordination 29 Testing Comments 29 Who To Contact 30 Test Configuration 30 Sample Test Data 30 Caterpillar: Confidential Green 3 Production Information ...............................................................................................30 Production Comments 30 Production Configuration 30 Application URL .........................................................................................................30 Caterpillar: Confidential Green 4 Modification History Date 29 Mar 2010 1 Nov 2010 Author Deanna Sundell Deanna Sundell Description of Change Transition documentation into new template. Document reviewed in compliance with semi-annual review process to insure current information. No issues found. Updated last reviewed date. Updated the field 'Ownership Status' to required. Updated the field ‘Product Status’ to have ‘U’ for Used instead of ‘US’. Added two new options DMS Download function in Equipment Data Web site (requires dealer setup) and DMS Automatic Download (requires dealer setup) Added Business rules as provided by Earlene “Sha” Williams in the overview section Fixed broken links by pointing to dealer.cat.com 23 Feb 2011 2 Mar 2011 18 Mar 2011 Deanna Sundell Deanna Sundell Debra Lammers 31 July 2012 25 August 2012 Jim Eilts Jim Eilts Please Note: All interface modifications noted above (with the exception of corrections of typographical errors) should be accompanied by a change communication notice as a result of the Dealer Facing Interface Documentation CITA Standard. The date the above changes are implemented, as well as the retirement of any previous formats, is noted within that communication. Each Caterpillar application owner reserves the right to determine the dates(s) in which an interface change is implemented as well as when previous versions of interfaces are retired, as long as the advance notification of these changes is provided in accordance with this standard. Below is a link to where all interface change communications are posted for review: https://dealer.cat.com/cda/alias/DealerITServices Link to Dealer-Facing Interface Documentation Standard https://gis.cat.com/cda/files/3428040/7/DealerFacing%20Interface%20Standard%20v3.0.doc Caterpillar: Confidential Green 5 Glossary Corporate CWS Corporate Web Security. CWS is a standards-based site-independent set of infrastructure components that web masters and web application developers can use to easily control access to some or all of their web content. Delimited Text File A text file (ASCII) that uses a given character to separate data elements. Dealer Management System. A bundled management information system containing software that supports all aspects of running a dealership. DCN Dealer Customer Number Element Specifies the kind of information in the XSD Schema. ED Equipment Data. Allows dealers and their customers to view, manage and maintain equipment inventories. Equipment Data offers a subset of equipment information that is maintained wholly by the dealer and/or the customer. EM EquipmentManager. Allows remote monitoring of a single machine or fleet of machines. With machine location, SMU and health information, customers can manage the location and basic usage of machines, schedule events like planned maintenance and major repairs, address condition-based events such as fault or diagnostic codes, or detect problems before they may cause a major component failure. ISO International Organization for Standardization. PartStore Web Customer application for convenient parts ordering from dealers that provides parts pricing and availability as well as replacement and reman parts from the dealer’s management system. To maximize update and ensure correct parts are chosen, provides 24/7 customer access to SIS parts books, Planned Maintenance Checklist, Related Parts and General Parts Information. Includes optional access to Core Tracking, order status e-mails, credit card payments, multiple shipping methods, hose Assembly information, etc. Caterpillar: Confidential Green 6 REST REpresentational State Transfer. REST describes an architectural pattern and is not a specific technology implementation. The model for RESTful web services is based on sending XML data defined by an XML Schema definition (XSD) via HTTP(s) using the standard HTTP protocol operations such as GET, PUT, DELETE and POST. The service is Resource Oriented, a resource e.g. a document, an image, an equipment is addressable via the addressability semantic built into HTTP the URI (Uniform Resource Identifier). SIS Service Information System. Provides access to 1 million numbers, 1.3 million graphics and thousands of parts and service documents. SIS provides fast searches, keeps the dealer and customer up-to-date with the latest information in print and makes it easier to order parts, even after normal business hours. UCID Universal Customer Identifier. A unique identifier assigned to a customer. URI Uniform Resource Identifier. A string of characters used to identify a name or a resource on the Internet. Such identification enables interaction with representations of the resource over a network (typically the World Wide Web) using specific protocols. Schemes specifying a concrete syntax and associated protocols define each URI. VisionLink The VisionLink™ application will replace Product Link’s current user interface, EquipmentManager, with intuitive tools and features for processing and conveying information to customers and dealers. XML eXtensible Markup Language. XML is an open standard language that allows information to be encoded with meaningful structure for exchanging over the Internet. XML Attribute Provides additional information about an element. XSD XML Schema Definition. Provides the syntax and defines a way in which elements and attributes can be represented in an XML document. Caterpillar: Confidential Green 7 Process Overview Equipment Data (ED) is a Web application enabling dealers and their customers to track and maintain equipment inventories. The data stored in ED is used with PartStore Web, EquipmentManager, VisionLink and SIS Web. For DBS dealers, the primary methods of getting information in ED is by downloading the information from your DBS system on a customer-by-customer basis. Information can also be manually entered into ED and then uploaded into DBS via the Caterpillar Mailbox to the gatekeeper. Several different scenarios exist for when data will need to be sent in to ED. Each are documented below with instructions on what data needs to be sent into ED. 1. An internal customer owns the equipment. - Send internal Dealer Customer Number using the POST option. 2. The Equipment is sold/rented to an external customer. - Send external Dealer Customer Number using the POST option. 3. Equipment is returned to the dealer - Send old External Dealer Customer Number using the DELETE option and Send internal Dealer Customer Number using the POST option. 4. Equipment is returned to the dealer and then delivered to a new customer - Send old external Dealer Customer Number using the DELETE option and Send new external Dealer Customer Number using the POST option. 5. Dealer Ownership Change - Old Dealer sends intern and external Dealer Customer Numbers using the DELETE option and new dealer sends external and/or internal Dealer Customer Number using the POST option 6. When customer has it serviced by another dealer - Old Dealer sends intern and external Dealer Customer Numbers using the DELETE option and new dealer sends external and/or internal Dealer Customer Number using the POST option 7. Customer trades machine to a different dealer - Old Dealer sends intern and external Dealer Customer Numbers using the DELETE option and new dealer sends external and/or internal Dealer Customer Number using the POST option Note 1: There should never be more than one External DCN found for a dealership (This should be avoided by always deleting the old DCN before adding the new DCN) Caterpillar: Confidential Green 8 If there is more than 1 DCN for a dealership the results will be as documented below. 1. The system will collect all External UCID's for the registering dealer (Dealer Registered to the module). 2. If multiple UCID's are found for the registering dealer, or if the registering dealer has no EO records and multiple external UCID's are found the system will: a) Place all external DCN's in Natural Alphabetical Order by Dealer Customer Number. b) Select the 1st DCN in the ordered list. Note 2: If the machine information changes from one dealer to another, old dealer has to manually delete (any external) all records before new dealer will add the internal and external customer information. Rules: 1. All DCN's must be tied to a dealer (DMT) using the UCID Tool to a UCID prior to sending ownership data 2. All make codes must be mapped in ED prior to sending ownership information 3. Make codes on ownership should match the Make code for Module Registration For DMS dealers, equipment can be added four different ways: 1. 2. 3. 4. Manually entered into the Equipment Data Website File Upload DMS Download function in Equipment Data Web site (requires dealer setup) DMS Automatic Download (requires dealer setup) Equipment information can also be manually downloaded from within Search Equipment using a specified file delimiter. The main purpose of this documentation is to document the DMS options. Caterpillar Preferred Option DMS Download function in Equipment Data Web site (requires dealer setup) or DMS Automatic Download (requires dealer setup) Related Interfaces N/A Field Types and Definitions Caterpillar: Confidential Green 9 The following list provides the references to field types that will be used in this document. Reference Description Example Alpha Alpha-Numeric Date Numeric Composed of only letters and spaces, with no numbers or punctuation. Composed of only letters, punctuation, and the numbers 0-9 represented as characters. Field containing only a date. Composed of only numbers. example D11R 01082004 1234 Upload Equipment Information – Text File Owner Author Go to https://dealer.cat.com/DealerITServices then click on the link Caterpillar Application Interface Contact List under the Related Links in the right column. Sha Williams For an e-mail address or phone number of the appropriate DICE Team Contact for this interface, please click on their name to receive current contact information. https://dealer.cat.com/cda/files/2789564/7/DICE+Team+Contats.xls General Comments & Definitions Comments For DMS dealers, equipment information can be uploaded into Equipment Data from a file that is formatted correctly. Each record must be on a single line. The upload verifies the number of fields in each record before processing. 1. Begin by clicking on the Administration link. 2. Click Upload. 3. When the Upload Equipment screen is displayed, select the desired Universal Customer ID and Customer Account Number. Click Browse and locate the file containing the equipment information to be uploaded. Caterpillar: Confidential Green 10 4. Once the file has been attached, click Upload. Error Architecture, Error Codes, and Error Messages The upload verifies the number of fields in each record before processing and will report an error for invalid records. To use a quotation mark within the data, use a slash before the quotation mark. For example, this syntax: “/Joe’s/” is required if the information in the field was “Joe’s” When equipment is uploaded by attaching a correctly formatted text file, the serial numbers of the equipment are checked against existing equipment serial numbers. If the serial number already exists and is tied to a different UCID, an ownership conflict exists. Elements, Characteristics, Operator Symbols N/A Array Sizes N/A Currency Considerations N/A Regional Considerations N/A Caterpillar: Confidential Green 11 Layouts Layout Comments N/A Layout Types Equipment Information Record Field Name Dealer Manufacturing Code Cat Manufacturing Code Serial Number Equipment Type Model Number Equipment ID (previously known as Nickname) Product Status Ownership Status Year Made Purchase Date Engine Arrangement Number PWC Code Type AlphaNumeric AlphaNumeric AlphaNumeric Alpha AlphaNumeric AlphaNumeric AlphaNumeric AlphaNumeric Date Date AlphaNumeric Alpha Length 2 3 20 1 50 50 FLAT FILE record layout Description Dealer make code Caterpillar corporate code signifying the manufacturer of the equipment Serial Number of the equipment. Type of the equipment. M=Machine, E=Engine, A=Attachment. Model of the equipment Dealer or customer description of the equipment. Status of the product. (N) New, (U) Used, (X)-Unknown Owned, Rented, Leased, Unknown Year of manufacture. Date equipment was acquired. Also called acquisition date. Free form A Caterpillar code signifying the principal work code. In Equipment Data, this is labeled ‘Industry.’ DON’T USE, LEAVE BLANK. If no date specified, default to 01011901 Required if date is entered. Required if date/value is entered. Valide Values are K=KiloMeters, M=Miles, H=Hours. Required Sample (Y/N/C) Y AA Y Y Y N N CAT 7XM99999 M D11R ZACKTEST 1 1 yyyy ddmmy yyy 50 3 N Y Y Y N N N O 1966 10011992 engarr Meter Reading Date Meter Reading Value Meter Reading Unit of Measure Date Numeric Alpha ddmmy yyy 6 1 Y Y Y 01082004 1234 K Transmission/Media Type o Mailbox o Web service Caterpillar: Confidential Green 12 o LU6.2 o XML o API PC to Web Application – Text File o Web Download/SIFT o CD Testing Procedures Testing Coordination Testing requires coordination with the Caterpillar DICE team Testing can be performed without Caterpillar DICE Team assistance Testing Comments Once testing is complete, please send a screen shot showing the data has been successfully uploaded into Equipment Data to the correct DICE team member. Who To Contact For the scheduling of your testing needs, please contact your local dealer IT Representative to coordinate the needed testing with the DICE Team. If you are not sure who your IT Representative is, visit the Caterpillar website listed below for this information: https://dealer.cat.com/cda/alias/DealerITServices Test Configuration QA Server: https://qadealername.rd .cat.com https://qadealername.rd.cat.com/DSFUnbundled/servlet/DSF CentralServlet?appName=EquipmentData Sample Test Data Example Record structure: "Dealer Manufacturing Code","Cat Manufacturing Code","Serial Number","Equipment Type","Model Number”,”Equipment ID","Product Status","Ownership Status","Year Made",”Purchase Date”,"Engine Arrangement Number","PWC Code","Meter Reading Date","Meter Reading Value","Meter Reading Unit of Measure " Example File format: Caterpillar: Confidential Green 13 “AA”,”CAT”,”ZACHEQP”,”M”,”Z11R”,”ZACKTEST”,”N”,”O”,”2004”,”07012004”,”engarr”,”” ,30072004”,”1234”,”H” Production Information Production Comments N/A Production Configuration Server Production Server: https://dealername.cat.com Application URL https://dealername.cat.com/DSFUnbundled/servlet/DSFCe ntralServlet?appName=EquipmentData DMS Download Function in Equipment Data Web Site Owner o to https://dealer.cat.com/DealerITServices then click on the link Caterpillar Application Interface Contact List under the Related Links in the right column. Sha Williams Author For an e-mail address or phone number of the appropriate DICE Team Contact for this interface, please click on their name to receive current contact information. https://dealer.cat.com/cda/files/2789564/7/DICE+Team+Contats.xls General Comments & Definitions Comments For DMS dealers, equipment information can be downloaded from the Dealer’s database into the Equipment Data database using RESTful Web Services set up on the dealer side to interact with Equipment Data processing. Once the Dealer has setup this RESTful Web Service, the dealer will enter either the DMT Equipment Data Web site or the Equipment Data Web site and initiate a download through the interface. Dealers should also create the file with UTF-8 encoding. Dealer Setup includes: • Implementing a RESTful Web service hosted at the dealership. • Securing the RESTful Web service by Basic AUTH. Caterpillar: Confidential Green 14 • Creating a credential [user name and password] for Equipment Data to use. This user name and password is set up according to the dealer’s practices and authentication occurs on the dealer side. Set up The dealership will need to implement a RESTful Web service hosted at the dealership. The RESTful Web service should be secured using Basic AUTH. http://www.w3.org/Protocols/Specs.html http://www.ietf.org/rfc/rfc2617.txt The dealership will create a credential [user name and password] for Equipment Data to use. This user name and password is set up according to the dealer’s practices and authentication occurs on the dealer side. URI can be anything that ends in a trailing slash and is defined through your root website address. We will append the DCN when we make the service call. Initialization of the URL, password, and login id for this service occurs in the DMT Equipment Data interface. After successful execution of the service call, an HTTP 200 success code should be sent. Return codes outside of the 200 range will result in the updates not being processed. Insertion of the URL, password, and login id for this service occurs in Equipment Data general settings through the DMT tool using the Equipment Data link. 1. Check that DBS is disabled in the DMT tool. • Login into DMT. • Go to the Administration Tab. • Select DBS/DBSi Settings. Make sure that DBS Disabled is selected. 2. Initialize the URL, password, and login id. • Login into DMT. • Go to the Home Tab. • Select the Equipment Data Link • Go to General Settings • Mark Enable REST Service Download as enabled. • Type in the login, URL, and password you have assigned to your system. Make sure you keep a backup copy of this information. Disabling this feature will remove the information from our system. • Click on the Save button at the bottom of the page. Now you are ready to use the RESTful Web service. Caterpillar: Confidential Green 15 4. Begin by clicking on the Administration link in Equipment Data. 5. Click Download Equipment on the left menu bar (either in Equipment Data or in the DMT) 6. When the Download Equipment Data from DBS screen is displayed, select [1] Download for A Single Universal Customer ID or [2] Download for all my Dealer Store Front Run the second option during off hours as it is system intensive. 7. Click on the Download Equipment button at the bottom of the page. 8. When the Download Equipment Information from DBS screen is displayed, select a UCID and 1 to all DCN numbers. 9. The user email address will automatically populate. If you want to send the report to another email address, enter the new address in the box. 10. Click Download Equipment. 11. When the equipment download is completed, you should expect to receive an email with general results. An example of a result email is shown below. Only failed Serial Numbers are listed in the Serial Number column. This email format is the same format used in the DBS Long Download. Error Architecture, Error Codes, and Error Messages If there is a problem connecting to your dealer system, the following error will be sent in email: Caterpillar: Confidential Green 16 Unable to connect to your DBS - All download failed, please contact support Failed Serial Numbers during the download will appear in the email. Typically failed serial numbers are a result of unmapped dealer make codes. If there is an unlikely occurrence that all Caterpillar equipments fail the download, it is most likely a temporary unavailability of the SIMS resource for validation of the Caterpillar serial number. In this case a later download would resolve the issue. When equipment is downloaded into our system, the serial numbers of the equipment are checked against existing equipment serial numbers. If the serial number already exists and is tied to a different UCID, an ownership conflict exists. Errors in the application before and after the service call, will either display on the interface or in the log files. If a problem occurs that cannot be resolved, contact support help and specify the time and day of the occurrence. If the occurrence is within the current week, the logs will be reviewed for errors. Only standard HTTP codes. The most common ones encounter includes: 404 – Couldn’t find the resource 403 – Forbidden 500 – Server error Elements, Characteristics, Operator Symbols N/A Array Sizes OwnershipDetails - An array of ownership details. This array is unbounded meaning it can be as many occurrences as the author wishes. Currency Considerations N/A Regional Considerations Data may be input in up to 8 languages Layouts Layout Comments A copy of the XSD Equipment Ownership Schema can be found in the DICE KN. Caterpillar: Confidential Green 17 A dealer code is not included in the Equipment Ownership Import document since equipment importing is authenticated; the dealer of the authenticated user is the dealer this equipment belongs to. Layout Types Equipment Information Record Field Name Equipment Type Type Alpha Length 1 Description Type of Equipment: M = Machine E = Engine A = Attachment Unique identifier of the Equipment Make Code mapped in the Dealer Equipment Data to a specific Manufacturer Code Identifier for the equipment that is specific to each dealer’s criteria Model of the equipment Year of the model Status of the product. (N) New, (U) Used, (X)-Unknown The dealer customer number will be identified from the interface call. Defines date ownership began from the dealer customer. Fields Updating Required (Y/N/C) Y M Sample Serial Number Dealer Make Code AlphaNumeric AlphaNumeric AlphaNumeric AlphaNumeric Numeric Alpha 1-20 2 Y Y AB00173 AA Dealer Equipment Nickname [Equipment ID] Model Number Model Year Dealer Ownership Status Dealer Customer Number [DCN] Ownership Start Date 1-50 Y ZACKT 1-50 4 1 1-50 N N N Y D11R 1999 N Date yyyymm-dd 2001-01-01 Caterpillar serial numbers that have been validated by SIMS may input additional fields: purchase date, arrangement numbers, market segment, principle work code, application code and related serial numbers. For fields that are not included in this REST Web service and are manually updated in the Equipment Data interface, on download of equipment a blank value will replace that field. Equipment XML Tag <ownershipDetail> <serialNumber> Type N/A String 1-20 Length Description XML record layout Required (Y/N/C) Sample <manufacturerCode> String 2 A container for single equipment ownership information. The serial number of the equipment (unique identifier within a manufacturer) Mapped Dealer Make Code Y 5EK12345 Y AA Caterpillar: Confidential Green 18 <equipmentType> <model> <modelYear> <equipmentId> <ownershipType> <dealerCustomerNumber> String String Int String String String 1 1-50 4 1-50 1 1-50 <ownershipStartDate> Date yyymmdd M for Machine, E for Engine, A for Attachment, Z Engineering model The model year of the equipment A free form identifier or nickname for the equipment O = Owned, L=Leased, N = New, R=Rented, X = Unknown The dealer's customer identification. Must be mapped to a UCID in the UCID system. Defines date ownership began for the dealer customer. Y N N N Y Y A 3406 1994 MyEquipment L ABC123 2001-01-01 Transmission/Media Type Need to change this. o Mailbox Web service o LU6.2 XML o API o PC to Web Application – Text File o Web Download/SIFT o CD Testing Procedures Testing Coordination Testing requires coordination with the Caterpillar DICE team Testing can be performed without Caterpillar DICE Team assistance Testing Comments Who To Contact For the scheduling of your testing needs, please contact your local dealer IT Representative to coordinate the needed testing with the DICE Team. If you are not sure who your IT Representative is, visit the Caterpillar website listed below for this information: https://dealer.cat.com/cda/alias/DealerITServices Caterpillar: Confidential Green 19 Test Configuration QA Server: https://qadealername.rd .cat.com https://qadealername.rd.cat.com/DSFUnbundled/servlet/DSF CentralServlet?appName=EquipmentData Need to use UAT URI for testing and change to Production once testing is complete and ready to go-live. URI URI to push Web Service URI can be anything that ends in a trailing slash and is defined through your root website address. Sample Test Data <?xml version="1.0" encoding="UTF-8"?> <equipmentDataInt:ownershipDetails xmlns:equipmentDataInt="http://www.cat.com/equipmentdata/v1/EquipmentDataIntegrat ion" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cat.com/equipmentdata/v1/EquipmentDataIntegration EquipmentDataDealerIntegration.xsd "> <ownershipDetail> <serialNumber>5EK12345</serialNumber> <manufacturerCode>AA</manufacturerCode> <equipmentType>A</equipmentType> <model>3406</model> <modelYear>1994</modelYear> <equipmentId>MyEquipment</equipmentId> <ownershipType>L</ownershipType> <dealerCustomerNumber>ABC123</dealerCustomerNumber> <ownershipStartDate>2001-01-01</ownershipStartDate> </ownershipDetail> </equipmentDataInt:ownershipDetails> Production Information Production Comments The Equipment Data system will not alter the incoming data. The Equipment Data system assumes the complete representation of the machine is sent and will delete information that is not provided and does not have a default value. Production Configuration Caterpillar: Confidential Green 20 Write a web service that will take a DCN [Dealer Customer Number] as a URI parameter secured by BASIC AUTH and returns equipment ownership objects defined in the xsd. Go to the DMT in Equipment Data’s General Settings and configure the end point [URI] , login and password. Example of URI: http://localhost.cat.com/EquipmentDataServices/rest/ /mockImplementation/I500/ DMS Automatic Download Owner Go to https://dealer.cat.com/DealerITServices then click on the link Caterpillar Application Interface Contact List under the Related Links in the right column. Debra Lammers Author For an e-mail address or phone number of the appropriate DICE Team Contact for this interface, please click on their name to receive current contact information. https://dealer.cat.com/cda/files/2789564/7/DICE+Team+Contats.xls General Comments & Definitions Comments Using the XSD Equipment schema as a reference, the dealer builds an XML file used to transport and store equipment data for updating Equipment Data ownership database from their dealer management system. Once the XML is created, a simple RESTful Web Service is used to push the data to EquipmentData. The RESTful Web Service requires basic authentication and the XML data is embedded into the request of the RESTful Web Service. For the Automatic Download, items in the XML file will be processed in the order they appear. If an update, delete, and update message for the same machine appears in the file in that order, the listing will be updated, removed, and updated again. Dealers should also create the file with UTF-8 encoding. NOTE: As a new solution, this document will continue to evolve as items are identified needing further clarification. Caterpillar: Confidential Green 21 This solution provides a simple REST Web service over which equipment ownership information can be pushed. Since we are using a ‘push’ service, the client will invoke the service as needed to post equipment information to the correct URI. (Production URI): https://equipmentdataws.cat.com/EqData/rest/v1/equipmentOwnershipUpdate/ (QA TEST URI): https://equipmentdatamc.rd.cat.com/EqData/rest/v1/equipmentOwnershipUpdate/ Invoking the Service Since the equipment ownership service is accessible via HTTP POST operation, a user can access the service via a standard web browser. This can be valuable in order to understand data content and navigation. However, the equipment ownership service is designed to be a program-to-program integration technology. Programmatic access to the service can be broken into three steps: • • • Opening a connection Providing authentication Executing the “post” operation Opening a Connection Most, if not all, modern programming languages provide API's that allow for opening an HTTP connection. In order that the HTTPS connection can be opened, the client program must have access to the public SSL certificate available at the appropriate equipment service address. Providing Authentication The equipment service is secured via HTTP Basic Authentication. Access to the service can be accomplished utilizing any Caterpillar CWS (Corporate Web Security) userid/password. We store the CWS ID and password in a table for authentication to the service. To enter this information in the table you will need to place an Accenture ticket for Equipment Data and have them forward the request to the Equipment Data team. It is important to remember that when accessing the QA equipment service, the user id/password must be present in the QA Caterpillar Global Directory. When accessing the production equipment service, the user id/password must be present in the Production Caterpillar Global Directory. User ids between these directory environments may match but passwords are not synchronized automatically between these environments. QA CWS account passwords can be changed via https://loginq.rd.cat.com. Production CWS account passwords can be changed via https://login.cat.com. Caterpillar: Confidential Green 22 However, when programmatically accessing the production equipment ownership service, it is necessary that the user id utilized is a non-expiring application CWS id. This account id/password will be issued to clients upon request to use the equipment ownership Web service. Java url = new URL(targetURL); connection = (HttpURLConnection)url.openConnection(); BASE64Encoder enc = new sun.misc.BASE64Encoder(); String userpassword = username + ":" + password; String encodedAuthorization = enc.encode(userpassword.getBytes() ); connection.setRequestProperty("Authorization", "Basic "+ encodedAuthorization); Executing the Post The equipment service supports only the HTTP POST operation. The POST can be executed as follows. Java connection.setRequestMethod("POST"); connection.setDoInput(true); connection.setRequestProperty(“Content-type”, “text/xml”); An HTTP 200 is sent to the client when the action has been successfully processed on Equipment Data servers. The connection is released. Error Architecture, Error Codes, and Error Messages Only standard HTTP codes. The most common ones encounter includes: 404 – Couldn’t find the resource 403 – Forbidden 500 – Server error Elements, Characteristics, Operator Symbols N/A Array Sizes automaticDownloadEvents - -An array of ownership details. This array is unbounded meaning it can be as many occurrences as the author wishes. Currency Considerations N/A Caterpillar: Confidential Green 23 Regional Considerations Data may be input in up to 8 languages. Layouts Layout Comments A copy of the XSD Equipment Ownership Schema can be found in the DICE KN. A dealer code is not included in the Equipment Ownership Import document since equipment importing is authenticated; the dealer of the authenticated user is the dealer this equipment belongs to. Layout Types Equipment XML Tag T y p e Length Description XML record layout Required (Y/N/C) Sample <equipment-import> <automaticDownloadEvents> N/A <addOrUpdateEvent> <deleteEvent> <ownershipDetail> <serialNumber> N/A N/A N/A String 1-20 <manufacturerCode> <equipmentType> <model> <modelYear> <equipmentId> <ownershipType> <dealerCustomerNumber> String String String Int String String String 2 1 1-50 4 1-50 1 1-50 This is an equipment important document. A single import document can include multiple listings to add or update, and multiple equipment listings to delete. A list of ownership events consisting of <addOrUpdateEvent> or . <deleteEvent> elements. An event representing ownership addition or update. An event representing ownership deletion. A container for single equipment ownership information. The serial number of the equipment (unique identifier within a manufacturer) Mapped Dealer Make Code M for Machine, E for Engine, A for Attachment, Engineering model The model year of the equipment A free form identifier or nickname for the equipment O = Owned, L=Leased, N = New, R=Rented, X = Unknown The dealer's customer identification. Must be mapped to a UCID in the Y N/A Y N/A N/A N/A 1JD02931 Y Y AA M 966C 1994 ABC123 O C91916 N Y Y Caterpillar: Confidential Green 24 <ownershipStartDate> Date UCID system. Defines date ownership began for the dealer customer. 2001-01-01 Transmission/Media Type Need to change this. o Mailbox Web service o LU6.2 o XML o API o PC to Web Application – Text File o Web Download/SIFT o CD Testing Procedures Testing Coordination Testing requires coordination with the Caterpillar DICE team Testing can be performed without Caterpillar DICE Team assistance Testing Comments Who To Contact For the scheduling of your testing needs, please contact your local dealer IT Representative to coordinate the needed testing with the DICE Team. If you are not sure who your IT Representative is, visit the Caterpillar website listed below for this information: https://dealer.cat.com/cda/alias/DealerITServices Test Configuration Need to use UAT URI for testing and change to Production once testing is complete and ready to go-live URI: URI to push Web Service https://equipmentdatamc.rd.cat.com/EqData/rest/v1/equipmen tOwnershipUpdate/ Caterpillar: Confidential Green 25 Sample Test Data <?xml version="1.0" encoding="UTF-8"?> <equipmentDataInt:automaticDownloadEvents xmlns:equipmentDataInt="http://www.cat.com/equipmentdata/v1/EquipmentDataI ntegration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cat.com/equipmentdata/v1/EquipmentDataInteg ration EquipmentDataDealerIntegration.xsd "> <addOrUpdateEvent> <ownershipDetail> <serialNumber>5EK12345</serialNumber> <manufacturerCode>AA</manufacturerCode> <equipmentType>E</equipmentType> <model>3406</model> <modelYear>1994</modelYear> <equipmentId>MyEquipment</equipmentId> <ownershipType>L</ownershipType> <dealerCustomerNumber>ABC123</dealerCustomerNumber> <ownershipStartDate>2001-01-01</ownershipStartDate> </ownershipDetail> </addOrUpdateEvent> <deleteEvent> <serialNumber>6EK12345</serialNumber> <manufacturerCode>AA</manufacturerCode> <dealerCustomerNumber>ABC123</dealerCustomerNumber> </deleteEvent> </equipmentDataInt:automaticDownloadEvents> Production Information Production Comments The Equipment Data system will not alter the incoming data. The Equipment Data system assumes the complete representation of the machine is sent and will delete information that is not provided and does not have a default value. Production Configuration URI URI to push Web Service https://equipmentdataws.cat.com/EqData/rest/v1/equipmentOw nershipUpdate/ Caterpillar: Confidential Green 26 Download Equipment Information from Search Results – Text File Owner Go to https://dealer.cat.com/DealerITServices then click on the link Caterpillar Application Interface Contact List under the Related Links in the right column. Sha Williams Author For an e-mail address or phone number of the appropriate DICE Team Contact for this interface, please click on their name to receive current contact information. https://dealer.cat.com/cda/files/2789564/7/DICE+Team+Contats.xls General Comments & Definitions Comments The download option allows a user to save a search result to a delimited text file. This will allow them to import their data into another application such as Excel or Word. 1. Begin by searching for one or more pieces of equipment in Equipment Data. 2. Select a Universal Customer ID (UCID) and a Customer Account Number before selecting any Search Criteria. Limit your search by completing any of the fields such as serial number or manufacturer. 3. Click Submit. Caterpillar: Confidential Green 27 4. Click the checkbox for each piece of equipment to download. Once equipment has been selected, click Download. 5. Depending on your browser configuration, you may be prompted to choose whether to open the file or save it to disk. If so, choose Save. 6. Choose *.* from the Save as type drop-down list. 7. Enter the name of the file in the File name field. 8. Use the drop-down arrow next to Save in to navigate to where you want to save the file. 9. Click the Save button. Error Architecture, Error Codes, and Error Messages N/A Elements, Characteristics, Operator Symbols N/A Array Sizes N/A Currency Considerations N/A Regional Considerations N/A Caterpillar: Confidential Green 28 Layouts Layout Comments Layout Types Equipment Information File Field Name Type Length Description FLAT FILE record layout Sample Equipment ID Serial Number Product Model Manufacturer Ownership Status Equipment Type Customer Account AlphaNumeric AlphaNumeric AlphaNumeric AlphaNumeric AlphaNumeric Alpha Dealer or customer description of the equipment. Serial Number of the equipment. Model of the equipment LENZ 38S07839 3412 Caterpillar Inc. Owned, Rented, Leased, Unknown 1 Type of the equipment. M=Machine, E=Engine, A=Attachment. This is the dealer customer number. Owned E 000001 Transmission/Media Type Mailbox Web service LU6.2 XML API PC to Client o Web Download/SIFT o CD o o o o o Testing Procedures Testing Coordination Testing requires coordination with the Caterpillar DICE team Testing can be performed without Caterpillar DICE Team assistance Testing Comments During the documentation of this interface, an issue was identified with the download. The Equipment Type does not populate (always empty) to the download file during testing and there is always an additional empty field before Customer Number. Caterpillar: Confidential Green 29 Who To Contact For the scheduling of your testing needs, please contact your local dealer IT Representative to coordinate the needed testing with the DICE Team. If you are not sure who your IT Representative is, visit the Caterpillar website listed below for this information: https://dealer.cat.com/cda/alias/DealerITServices Test Configuration Server QA Server: https://qadealername.rd .cat.com Sample URL https://qadealername.rd.cat.com/DSFUnbundled/servlet/DSF CentralServlet?appName=EquipmentData Sample Test Data Example Record structure: "Equipment ID","Serial Number”,"Product Model","Manufacturer","Ownership Status","Equipment Type",”Customer Account" Example File format: |TEST|QALO341|Z11R|CATERPILLAR INC|Owned|||001562| |LENZ|38S07839|3412|CATERPILLAR INC|Owned|||000867| Production Information Production Comments As stated in the testing comments, during the documentation of this interface, an issue was identified with the download. The Equipment Type does not populate (always empty) to the download file during testing and there is always an additional empty field before Customer Number. Production Configuration Server Production Server: https://dealername.cat.com Application URL https://dealername.cat.com/DSFUnbundled/servlet/DSFCe ntralServlet?appName=EquipmentData Caterpillar: Confidential Green 30