equipmentData.pdf

Equipment Data (ED) Interface

Last 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.

Caterpillar: Confidential Green 2

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




Array Sizes 17



Layouts ....................................................................................................................... 17

Layout Comments 17

Layout Types 18

Equipment Information Record Fields Updating 18

Equipment XML record layout 18





Testing Comments 19

Who To Contact 19


Sample Test Data 20




DMS Automatic Download .......................................................................................... 21




Array Sizes 23



Layouts ....................................................................................................................... 24

Layout Comments 24

Layout Types 24

Equipment XML record layout 24




Testing Comments 25

Who To Contact 25


Sample Test Data 26




Download Equipment Information from Search Results – Text File ....................... 27




Array Sizes 28



Layouts ....................................................................................................................... 29

Layout Comments 29

Layout Types 29

Equipment Information File FLAT FILE record layout 29




Testing Comments 29

Who To Contact 30


Sample Test Data 30





Application URL ......................................................................................................... 30


Modification History

Date Author Description of Change 29 Mar 2010 Deanna Sundell Transition documentation into new template.

1 Nov 2010 Deanna Sundell Document reviewed in compliance with semi-annual review process to insure current information. No issues found. Updated last reviewed date.

23 Feb 2011 Deanna Sundell Updated the field 'Ownership Status' to required.

2 Mar 2011 Deanna Sundell Updated the field ‘Product Status’ to have ‘U’ for Used instead of ‘US’.

18 Mar 2011 Debra Lammers Added two new options DMS Download function in Equipment Data Web site (requires dealer setup) and DMS Automatic Download (requires dealer setup)

31 July 2012 Jim Eilts Added Business rules as provided by Earlene “Sha” Williams in the overview section

25 August 2012

Jim Eilts Fixed broken links by pointing to dealer.cat.com

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/Dealer-Facing%20Interface%20Standard%20v3.0.doc


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.


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.


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)


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. Manually entered into the Equipment Data Website 2. File Upload 3. DMS Download function in Equipment Data Web site (requires dealer setup) 4. 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


The following list provides the references to field types that will be used in this document. Reference Description Example

Alpha Composed of only letters and spaces, with no numbers or punctuation.

example

Alpha-Numeric Composed of only letters, punctuation, and the numbers 0-9 represented as characters.

D11R

Date Field containing only a date. 01082004

Numeric Composed of only numbers. 1234

Upload Equipment Information – 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.

Author 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.


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


Layouts

Layout Comments

N/A

Layout Types

Equipment Information Record FLAT FILE record layout

Field Name

Type Length Description Required (Y/N/C)

Sample

Dealer Manufacturing Code

Alpha-Numeric

2 Dealer make code Y AA

Cat Manufacturing Code

Alpha-Numeric

3 Caterpillar corporate code signifying the manufacturer of the equipment

Y CAT

Serial Number Alpha-Numeric

20 Serial Number of the equipment. Y 7XM99999

Equipment Type Alpha 1 Type of the equipment. M=Machine, E=Engine, A=Attachment.

Y M

Model Number Alpha-Numeric

50 Model of the equipment N D11R

Equipment ID (previously known as Nickname)

Alpha-Numeric

50 Dealer or customer description of the equipment.

N ZACKTEST

Product Status Alpha-Numeric

1 Status of the product. (N) New, (U) Used, (X)-Unknown

N N

Ownership Status Alpha-Numeric

1 Owned, Rented, Leased, Unknown Y O

Year Made Date yyyy Year of manufacture. Y 1966

Purchase Date Date ddmmyyyy

Date equipment was acquired. Also called acquisition date.

Y 10011992

Engine Arrangement Number

Alpha-Numeric

50 Free form N engarr

PWC Code Alpha 3 A Caterpillar code signifying the principal work code. In Equipment Data, this is labeled ‘Industry.’ DON’T USE, LEAVE BLANK.

N

Meter Reading Date Date ddmmyyyy

If no date specified, default to 01011901

Y 01082004

Meter Reading Value Numeric 6 Required if date is entered. Y 1234

Meter Reading Unit of Measure

Alpha 1 Required if date/value is entered. Valide Values are K=KiloMeters, M=Miles, H=Hours.

Y K

Transmission/Media Type

o Mailbox o Web service


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/DSFCentralServlet?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:


“AA”,”CAT”,”ZACHEQP”,”M”,”Z11R”,”ZACKTEST”,”N”,”O”,”2004”,”07012004”,”engarr”,””,30072004”,”1234”,”H”

Production Information

Production Comments

N/A

Production Configuration

Server Application URL

Production Server: https://dealername.cat.com

https://dealername.cat.com/DSFUnbundled/servlet/DSFCentralServlet?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.

Author Sha Williams




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.


• 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.


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.


If there is a problem connecting to your dealer system, the following error will be sent in email:


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


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.


N/A


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 Information Record Fields Updating

Field Name

Type Length Description Required (Y/N/C)

Sample

Equipment Type Alpha 1 Type of Equipment: M = Machine E = Engine A = Attachment

Y M


1-20 Unique identifier of the Equipment

Y AB00173

Dealer Make Code Alpha-Numeric

2 Make Code mapped in the Dealer Equipment Data to a specific Manufacturer Code

Y AA

Dealer Equipment Nickname [Equipment ID]

Alpha-Numeric

1-50 Identifier for the equipment that is specific to each dealer’s criteria

Y ZACKT

Model Number Alpha-Numeric

1-50 Model of the equipment N D11R

Model Year Numeric 4 Year of the model N 1999

Dealer Ownership Status

Alpha 1 Status of the product. (N) New, (U) Used, (X)-Unknown

N N

Dealer Customer Number [DCN]

1-50 The dealer customer number will be identified from the interface call.

Y

Ownership Start Date Date yyyy-mm-dd

Defines date ownership began from the dealer customer.

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 record layout

XML Tag Type Length Description Required (Y/N/C)

Sample

<ownershipDetail> N/A A container for single equipment ownership information.

<serialNumber> String 1-20 The serial number of the equipment (unique identifier within a manufacturer)

Y 5EK12345

<manufacturerCode> String 2 Mapped Dealer Make Code Y AA


<equipmentType> String 1 M for Machine, E for Engine, A for Attachment, Z

Y A

<model> String 1-50 Engineering model N 3406

<modelYear> Int 4 The model year of the equipment N 1994

<equipmentId> String 1-50 A free form identifier or nickname for the equipment

N MyEquipment

<ownershipType> String 1 O = Owned, L=Leased, N = New, R=Rented, X = Unknown

Y L

<dealerCustomerNumber> String 1-50 The dealer's customer identification. Must be mapped to a UCID in the UCID system.

Y ABC123

<ownershipStartDate> Date yyy-mm-dd

Defines date ownership began for the dealer customer.

2001-01-01


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 requires coordination with the Caterpillar DICE team Testing can be performed without Caterpillar DICE Team assistance

Testing Comments

Who To Contact



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 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/EquipmentDataIntegration" 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 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.



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.

Author Debra Lammers




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.


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.


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.


Only standard HTTP codes. The most common ones encounter includes: 404 – Couldn’t find the resource 403 – Forbidden 500 – Server error


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.


N/A



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 record layout

XML Tag Type

Length Description Required (Y/N/C)

Sample

<equipment-import> This is an equipment important document. A single import document can include multiple listings to add or update, and multiple equipment listings to delete.

<automaticDownloadEvents> N/A A list of ownership events consisting of <addOrUpdateEvent> or . <deleteEvent> elements.

Y N/A

<addOrUpdateEvent> N/A An event representing ownership addition or update.

- N/A

<deleteEvent> N/A An event representing ownership deletion.

- N/A

<ownershipDetail> N/A A container for single equipment ownership information.

- N/A

<serialNumber> String 1-20 The serial number of the equipment (unique identifier within a manufacturer)

Y 1JD02931

<manufacturerCode> String 2 Mapped Dealer Make Code Y AA

<equipmentType> String 1 M for Machine, E for Engine, A for Attachment,

Y M

<model> String 1-50 Engineering model 966C

<modelYear> Int 4 The model year of the equipment 1994

<equipmentId> String 1-50 A free form identifier or nickname for the equipment

N ABC123

<ownershipType> String 1 O = Owned, L=Leased, N = New, R=Rented, X = Unknown

Y O

<dealerCustomerNumber> String 1-50 The dealer's customer identification. Must be mapped to a UCID in the

Y C91916


UCID system.

<ownershipStartDate> Date Defines date ownership began for the dealer customer.

2001-01-01


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 requires coordination with the Caterpillar DICE team Testing can be performed without Caterpillar DICE Team assistance

Testing Comments

Who To Contact


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/equipmentOwnershipUpdate/


Sample Test Data

<?xml version="1.0" encoding="UTF-8"?> <equipmentDataInt:automaticDownloadEvents xmlns:equipmentDataInt="http://www.cat.com/equipmentdata/v1/EquipmentDataIntegration" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.cat.com/equipmentdata/v1/EquipmentDataIntegration 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 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.


URI

URI to push Web Service https://equipmentdataws.cat.com/EqData/rest/v1/equipmentOwnershipUpdate/


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.

Author 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.



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.


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.


N/A


N/A

Array Sizes

N/A


N/A


N/A


Layouts

Layout Comments

Layout Types

Equipment Information File FLAT FILE record layout

Field Name Type Length Description Sample

Equipment ID Alpha-Numeric

Dealer or customer description of the equipment.

LENZ


Serial Number of the equipment. 38S07839

Product Model Alpha-Numeric

Model of the equipment 3412

Manufacturer Alpha-Numeric

Caterpillar Inc.

Ownership Status

Alpha-Numeric

Owned, Rented, Leased, Unknown Owned

Equipment Type Alpha 1 Type of the equipment. M=Machine, E=Engine, A=Attachment.

E

Customer Account

This is the dealer customer number. 000001


o Mailbox o Web service o LU6.2 o XML o API � PC to Client o Web Download/SIFT o CD

Testing Procedures


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.


Who To Contact


Test Configuration

Server Sample URL



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 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.


Server Application URL

Production Server: https://dealername.cat.com

https://dealername.cat.com/DSFUnbundled/servlet/DSFCentralServlet?appName=EquipmentData

Documents

equipmentData.pdf