Professional Documents
Culture Documents
Interface
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.
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
Cat Inspect tool is a mobile and web inspection application. This application contains several
inspection types including: Certified Rebuild inspection forms, Technical Analysis inspection forms
(TA-1), Preventive Maintenance Checklists (PM), and select Mining checklists. This easy-to-use
application will allow you to download and complete inspections as well as add pictures, comments,
and ratings. The PM checklists are serial number-specific to perform PM Service intervals as
recommended in the Caterpillar Operation and Maintenance Manual. Currently, Cat Inspect will be
available in English, Chinese (Simplified), French, German, Indonesian, Italian, Portuguese
(Brazilian), and Spanish (Latin American). The administration console is in English only.
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.
Dealer Management System. A bundled management information system containing software that
supports all aspects of running a dealership.
Element
Specifies the kind of information in the XSD Schema.
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).
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.
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
Process Overview
Cat Inspect tool is a mobile application that dealers can utilize to complete inspections electronically.
Inspections completed by the mobile application are stored in the Inspection database at Caterpillar.
This interface document describes a service that allows dealers to pull completed inspections from
the Inspection database via a RESTful Web Service. Basic authentication is required and it uses an
application logon id to get the dealer code so that only your dealer data is returned. The web service
is invoked with parameters including start date, end date and optionally serial number and inspector
id. A maximum of ten inspections at a time are returned in the response XML that can be used to
populate a dealer management system.
Related Interfaces
N/A
https://dealer.cat.com/cda/files/2789564/7/DICE+Team+Contats.xls
Comments
This solution provides a simple REST Web service that enables inspection information to be pulled
from a Caterpillar hosted database. Since we are using a pull service, the client will invoke the
service as needed to retrieve inspection information from the correct URI. The inspection data is
returned in UTF-8 encoding.
Opening a connection
Providing authentication
Executing the get 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 a Caterpillar non-expiring application id/password.
When accessing the production service, the application id/password must be present in the
Production Caterpillar Global Directory.
Example:
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);
An HTTP 200 is sent to the client when the batch has been successfully pulled from the inspection
database for processing. The connection is released.
Accept header
The Rest service can provide either XML or Json. This is triggered by adding, in the HTTP Accept
header, either application/inspections-v1+xml or application/inspections-v1+json.
Note The service is versioned in this way as well. If the Accept header is not set with one of these
values version 1 of the XML will be returned even though new versions may exist. It is best practice
to set the Accept header in order to ensure the most current version is returned.
Array Sizes
Inspection An array of unique inspections. This array is unbounded meaning it can be as many
occurrences however the web service is designed to return a maximum of 10 inspections at a time.
Currency Considerations
N/A
Regional Considerations
Layout Comments
Layout Types
GET cds/rest/inspect/inspection
Examples:
/cds/rest/inspect/inspection?startDate=19Nov2012&endDate=18Jul2013
/cds/rest/inspect/inspection?startDate=19Nov2012&endDate=18Jul2013&sn=2WS23456&page=2
/cds/rest/inspect/inspection?startDate=19Nov2012&endDate=18Jul2013inspector=lewisJ&sn=2WS23456&page=2
Response XML
The inspection service returns inspections 10 at a time. There is a nextUrl element provides the url
to get the next set of inspection data. When nextUrl is null, all inspections have been accessed.
NOTE Inspections are not deleted from the database when they are pulled. You may pull an
inspection an unlimited number of times.
1 = thumb
2 = full size
<dtaTyp> String 20 Type of file extension. Some possible Y JPG
values are:
JPG
GIF
PDF
<link> String 150 The URL of the attached image. Y http://www.cat.com/c
at/images/Cat_logo.gi
f
<isSignature> string Y/N Is this image a signature N Y
Sample Data
Transmission/Media Type
RESTful Web service
Testing Coordination
Testing requires coordination with the Caterpillar DICE team
Testing can be performed without Caterpillar DICE Team assistance
Testing Comments
Dealer sends an email to CatInspect@catsupport.com. You will need to supply the following items in
your email.
a) Subject should be Dealer Request for CAT Inspect Interface application Id
b) Main Store Dealer Code
c) Requester name
d) Requester CWS Id
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
No test environment is available for this interface.
Sample Data
N/A
Caterpillar: Confidential Green 16
Production Information
Production Comments
A generic application Id and password are available for testing in the production environment. These
credentials are tied to dealer TD00 and will pull back some test data if searched between
19Nov2012 and 18Jul2013.
Logon: CatInspect_Test
Password: Q7N7D6-s6b8p5
Production Configuration
URI
URI to pull Web Service https://dataserve.cat.com
Background
Inspections can contain image data including pictures taken of the equipment, signatures of one or
more individuals responsible for the inspection, and initials entered with answers to specific
questions.
This section explains how a dealers IT resource can set up a program to retrieve the images from
Salesforce using the technology of their choosing. (A working Java program is provided as an
example but the necessary steps can be performed using other languages and tools).
As shown in the examples, the images themselves are not available in the XML or JSON. Rather, a
link is provided that realistically looks more like:
https://cateca.my.salesforce.com/servlet/servlet.FileDownload?file=00Pd0000006e5zkEAI
Dealers already have downloaded inspection data with the first link.
To extend the image download feature to use API (using code) take the image ID from the end of the first link
(every character after the equal sign, =).
00Pd0000006e5zkEAI
/services/data/v20.0/sobjects/Attachment/
to get
/services/data/v20.0/sobjects/Attachment/00Pd0000006e5zkEAI
and append
/body
/services/data/v20.0/sobjects/Attachment/00Pd0000006e5zkEAI/body
Pre-requisites
Before the corrected links can be used, Salesforce security parameters need to be set up including a
special dealer user account. To get these, contact CatInspect@catsupport.com with an email. In the
subject line Please enter:
1. Dealer code.
2. Name of the technical contact at the dealer responsible for the image retrieval user account.
3. Email of the technical contact at the dealer responsible for the image retrieval user account.
As mentioned in previous steps, once the Image Retrieval Setup Request has been processed,
CatInspect@catsupport.com team will provide following information-
1. User details to retrieve image [Technical Contact person will receive necessary information to
set new password from Salesforce.com]
2. As per provided working java program, use above details to retrieve images.