Data Transfer Facility (DTF) Interface
DTF (Data Transfer Facility) is an API for John Deere DBS to provide a secure possibility for file exchange between John Deere systems and John Deere DBS. In plain terms, DTF consists of a John Deere side and a John Deere DBS side. That means, files are not stored on a drive or server in a classical sense but embedded on the DTF server in a so-called BLOB storage (Binary Large OBject). As long as the files are in the BLOB storage, they are compressed in the DTZ file format and will only be decompressed when they are downloaded to the local machine.
In this chapter, you can find the following sections:
Setup
Test
User Guide
Support
Setup
This section shows all pages related to the DTF Interface and the individual steps to set up a working DTF environment.
In this section, you can find the following subsections:
'DTF Service' page for DTF Interface
The DTF Service page is the starting point for all DTF service actions.
In the following subsections, you find an explanation for all menu items of the DTF Service page.
To open the DTF Service page, proceed as follows:
- Open John Deere DBS.
- Navigate to Departments > TRASER > John Deere and click on the DTF Service list item.
- Here, you are presented with the DTF Service menu.
Files (DTF)
This subsection describes the Files (DTF) page related to the DTF Interface.
Warning!
This page is intended for Test and troubleshooting purposes only and must not be used to bypass the automatic upload or download functionality in the live system.
| Column | Description |
|---|---|
| Name | Shows the name of the file. Values will only be displayed after clicking on the Refresh button and only if DTF files are available on John Deere side. |
| Size | Shows the size of the file which. Values will only be displayed after clicking on the Request Details button and only if DTF files are available on John Deere side. |
| File Status | Shows the status of the file. The following options are available: Available = file is on John Deere side and available for transfer to John Deere DBS side |
| Last Accessed | Shows when the file was accessed the last time. |
| Transfer Status | Shows the status of the file transfer. The following options are available: emtpy = file is available on John Deere side and not yet transferred to John Deere DBS side Downloaded = file was downloaded from John Deere side to John Deere DBS side |
Note
This page is only temporary, i.e., when re-opening or refreshing the page, all columns will be emptied, and the corresponding actions must be repeated, if needed.
Uploaded or downloaded files might not be available in the list anymore after refreshing.
The buttons in the Process pane of the HOME tab of this page have the following functionalities:
| Button | Description |
|---|---|
| Refresh | Manually retrieves a list of files available on John Deere DBS side to download to the local machine. This functionality corresponds to the automatic LIST service. |
| Request Details | Manually requests details regarding Size, File Status, and Last Accessed value of the files retrieved via the Refresh button. This functionality corresponds to the automatic DETAIL service. |
| Upload | Manually uploads a file from the local machine to the John Deere side. There is no possibility for John Deere DBS to see which files were manually uploaded. This functionality corresponds to the automatic UPLOAD service. There is no file type or file size restriction. |
| Download | Manually downloads a file retrieved beforehand via the Refresh button from the John Deere side to the local machine. The file may have the DTZ file extension which will be resolved upon saving it to the local machine via the Save to Disk button. The Transfer Status value is changed after download, and the entry will not be available anymore upon refresh. |
| Save to Disk | Manually downloads a file from the John Deere DBS side to the local machine. This functionality corresponds to the automatic DOWNLOAD service. |
Note
Any actions manually triggered on this page will not be available on the DTF File Processing Log page.
DTF File Processing Log
This subsection describes the DTF File Processing Log page related to the DTF Interface.
| Column | Description |
|---|---|
| Entry No. | Shows the consecutive number of the entry in ascending order. |
| DTF Service Code | Shows from which DTF service the entry was created. This value corresponds to the Code field set up on the DTF Service Setups page. |
| Service Endpoint Code | Shows from which DTF service endpoint the entry was created. The following options are available: UPLOAD = file was uploaded from John Deere DBS side to John Deere side DOWNLOAD = file was downloaded from John Deere DBS side to the directory defined in the DTF Service Setup Card section |
| Filename | Shows the name of the file which was uploaded or downloaded. |
| Status | Shows the status of the processed file. The following options are available: Uploaded = file was uploaded to John Deere side Downloaded = file was downloaded to John Deere DBS side Decompressed = file was decompressed in the directory defined in the DTF Service Setup Card section to be processed by John Deere DBS Error = an error occurred, please check the Error Code and Error Message columns Renamed = file with the same name was already available in the target directory and thus was renamed with the DUP prefix and the corresponding timestamp |
| Error Code | Optional Shows the error code, if Status = Error. For more information about error codes, please see the Error Codes section. |
| Error Message | Optional Shows the error message related to the Error Code column. For more information about error codes, please see the Error Codes section. |
DTF Service Setups
This subsection describes the DTF Service Setups page related to the DTF Interface.
| Column | Description |
|---|---|
| Code | Shows the code of the DTF service. This value is set up when processing the Prepare and set up the DTF Interface section. |
| Description | Shows the description of the DTF service. This value is set up when processing the Prepare and set up the DTF Interface section. |
| Active | If this checkbox is selected, the corresponding DTF service is enabled. Otherwise, the DTF service is disabled, and no files are exchanged. |
Note
The DTF Service Setup Card is also part of this page and is described in a separate section.
Service Endpoints
This subsection describes the Service Endpoints page related to the DTF Interface. It also contains the Error Codes subsection. The service endpoint paths will be appended to the Host value set up on the DTF Service Setup Card.
Note
The service endpoints are set up automatically when setting John Deere DBS up according to the Prepare and set up the DTF Interface section, so the overview below is only for your quick reference.
Important
DO NOT CHANGE ANY OF THESE VALUES.
| Column | Description |
|---|---|
| Code | Shows the code of the service endpoint. The following options are available: DETAIL = used to receive file details DOWNLOAD = used to download files from John Deere side to John Deere DBS LIST = used to receive a list of files available on John Deere side UPLOAD = used to upload files from John Deere DBS side to John Deere side |
| Description | Shows the description of the service endpoint. |
| HTTP Method | Shows the type of the file transfer request. The following options are available: GET = data is retrieved from John Deere PUT = data is sent to John Deere |
| Endpoint Path | Shows the path of the DTF service endpoint which is appended to the Host value described in the DTF Service Setup Card section. The following values are required: DETAIL code = /dtfapi/dbs/dealer/%1/files/%2/detailsDOWNLOAD code = /dtfapi/dbs/dealer/%1/files/%2LIST code = /dtfapi/dbs/dealer/%1/filesUPLOAD code = /dtfapi/dbs/dealer/%1/files%1 = 'Main Dealer No.' value from 'General' FastTab of 'John Deere Setup' page %2 = file name |
| Content Type | Shows the type of content which is used to send and process the data. The following values are required: DETAIL code = application/jsonDOWNLOAD code = application/jsonLIST code = application/jsonUPLOAD code = multipart/form-data |
| Scope | Shows the type of permissions which are needed to send and process the data. The following values are required: DETAIL code = dtf:dbs:file:readDOWNLOAD code = dtf:dbs:file:readLIST code = dtf:dbs:file:readUPLOAD code = dtf:dbs:file:write |
Error Codes
This subsection shows a list of all Error Codes available for the DTF Interface. The Error Codes page is opened via clicking on the HOME > Error Codes button on the Service Endpoints page.
Note
The error codes are set up automatically when setting John Deere DBS up according to the Prepare and set up the DTF Interface section, so the overview below is only for your quick reference.
The screenshot below shows the error codes for the UPLOAD service endpoint as an example.
Important
DO NOT CHANGE ANY OF THESE VALUES.
| HTTP Code | HTTP Status | Error Code | Error Message | Affected Service Endpoints |
|---|---|---|---|---|
| 200 | OK | n.a. | n.a. | DETAIL, DOWNLOAD, LIST |
| 204 | No Content | n.a. | n.a. | UPLOAD |
| 400 | Bad Request | FileAttachmentMissing | File Attachment not found | UPLOAD |
| 401 | InternalServerError | Unauthorized | The requested client is not authorized to receive or send files to this dealer. | DOWNLOAD |
| 403 | Forbidden | insufficient_scope | Insufficient scope for this resource. | DETAIL, DOWNLOAD, LIST, UPLOAD |
| 403 | Forbidden | NotReadable | Unable to read the file. | DETAIL, DOWNLOAD |
| 404 | NotFound | DealerPathNotFound | The specified dealer path does not exist. | UPLOAD |
| 404 | NotFound | DealerSetupNotFound | Dealer's Setup does not exist. | DETAIL, DOWNLOAD, LIST |
| 404 | NotFound | FileNotFound | Specified File does not exist. | DETAIL, DOWNLOAD, LIST |
| 404 | NotFound | NotFound | No message available. | UPLOAD |
| 409 | Conflict | FileAlreadyExists | The specified file already exist. | DETAIL, UPLOAD |
| 500 | InternalServerError | FileIOException | The specified file not able to write to the specified resource path. | DOWNLOAD, UPLOAD |
| 500 | InternalServerError | ServiceUnavailable | Unable to process your request. | DETAIL, LIST |
Prepare and set up the DTF Interface
This section describes how to set up the DTF Interface. Please follow the instructions in the subsections below in consecutive order.
Okta Setup
In order to make the interface communication work, please proceed as follows:
- Open the DTF Service Setup List page in John Deere DBS and click on HOME > Edit.
- From the General > Authorization Method Code dropdown list, select the interface code used for Client Credentials.
Information about how to create a new Okta entry can be found under Okta Authentication.
Note
In case John Deere requires a different Okta authentication, the Okta Setup has to be extended by an additional entry. Information on how to create a new Okta entry can be found under Okta Authentication.
In this new Okta entry, fill in the following values with the data given to you from your contact at John Deere.
| Column | Description |
|---|---|
| Interface Code | Please enter DTF_P. |
| Description | Please add a description for which interface this Okta authentication is needed, e.g., DTF Productive, or DTF File Transfer, etc. |
| Authorization Type | Please select the value Client Credentials. |
| Client ID | Shows your individual client ID for the corresponding John Deere resource. This value is provided to you by John Deere. |
| Client Secret | Shows your individual client password for the corresponding John Deere resource. This value is provided to you by John Deere. |
| Redirect URL | Shows the URL where Okta will validate the credentials you entered in the Client ID and Client Secret fields. This value is provided to you by John Deere. |
| Auth Server | Shows the authentication server where Okta redirects to in order to validate the credentials. This value is provided to you by John Deere. |
| Session Token Request URL | Shows the URL where Okta retrieves a session token upon successful validation of your credentials. Not needed for DTF. |
| AuthCode Token Request URL | Shows the URL where Okta retrieves an authentication code token upon successful validation of your credentials. Not needed for DTF. |
| Access Token Request URL | Shows the URL where Okta applies the tokens created to log in to the John Deere resources, so that the interface can be used without needing to enter the login credentials upon each login (Single Sign-On). This value is provided to you by John Deere. |
- Afterwards, open the John Deere Setup page and check whether the Main Dealer No. value on the General FastTab is filled. Otherwise, the DTF service will not work.
Please proceed with the next setup step.
DTF Service Setup Card
To finalize the setup of the DTF Interface, please follow below instructions.
- Open the DTF Service Setups page in John Deere DBS.
- Click on HOME > New to create a new DTF service.
- The DTF Service Setup Card opens.
- In the General > Code field, please enter
DTF_P. - In the page header, click on the HOME > Initialize Service Endpoints button and confirm the dialog by clicking on Yes. The values will be automatically created on the Service Endpoints page and filled in the Endpoints FastTab of the DTF Service Setup Card.
This option can also be used to reset the settings in case a misconfiguration was made. - Please fill in the other fields as per the table below to set up the productive DTF service environment.
| FastTab | Field | Description |
|---|---|---|
| General | Code | Enter the code for the DTF service. Please use the following value: DTF_P |
| Description | Enter a unique and meaningful description for the DTF service, e.g., DTF API Client (Prod), or DTF Service Productive, etc. |
|
| Scheme | Select the transfer protocol which is used to access the DTF API. Please use the following value: https |
|
| Host | Enter the host address to access the DTF API. Please use the following value: servicesext.deere.com |
|
| Port | Optional If required, enter a specific port to access the DTF API. This value will be automatically appended to the URL. | |
| Authorization Method Code | Select the Okta Interface Code which was created beforehand when processing the Okta Setup section. Please use the value: DTF_P |
|
| Active | Select this checkbox to enable the current DTF service. Only one DTF service must be active at a time! |
|
| Endpoints | Endpoint for File Lists | Automatically filled via the HOME > Initialize Service Endpoints button Specifies the DTF API service endpoint which is needed to retrieve the file list. This field must hold the following value: LIST |
| Endpoint for File Details | Automatically filled via the HOME > Initialize Service Endpoints button Specifies the DTF API service endpoint which is needed to retrieve details for the retrieved file list. This field must hold the following value: DETAIL |
|
| Endpoint for Downloads | Automatically filled via the HOME > Initialize Service Endpoints button Specifies the DTF API service endpoint which is needed to download the files from John Deere side to John Deere DBS side. This field must hold the following value: DOWNLOAD |
|
| Endpoint for Uploads | Automatically filled via the HOME > Initialize Service Endpoints button Specifies the DTF API service endpoint which is needed to upload the files from John Deere DBS side to John Deere side. This field must hold the following value: UPLOAD |
|
| Directories | Target Directory for Downloads | Enter the directory which will be used to save the files downloaded from John Deere side as per the corresponding 'DTF Download' job queue. These files will be loaded and processed by John Deere DBS. Local as well as server-based directories can be selected. It is required that the John Deere DBS service account has full read/write access to that directory. |
| Source Directory for Uploads | Enter the directory which will be used to buffer the files to upload to John Deere side as per the corresponding 'DTF Upload' job queue. After upload, the files will be transferred to the Archive Directory for Uploads. Local as well as server-based directories can be selected. It is required that the John Deere DBS service account has full read/write access to that directory. |
|
| Archive Directory for Uploads | Enter the directory which will be used to archive the files uploaded to John Deere side. Local as well as server-based directories can be selected. It is required that the John Deere DBS service account has full read/write access to that directory. |
Please proceed with the next setup step.
Job queue setup
Job queues are used to trigger the DTF services on a regular basis. To enable the automatic DTF service execution, create two new job queues as follows (leave all fields not described below empty):
- Open the Job Queue Entries page in John Deere DBS.
- Click on the HOME > New button to create a new job queue entry.
- Enter the values in the 2 job queues as per below tables:
(01) Upload
| FastTab | Field | Value |
|---|---|---|
| General | Object Type to Run | Codeunit |
| Object ID to Run | 5446083 |
|
| Description | Enter a unique job queue description, e.g., DTF Upload via Job Queue |
|
| Earliest Start Date/Time | Optional Enter the date and time the job queue should run the next time. If no value is selected, the job queue will run as soon as the status is In Process. | |
| Recurrence | Run on... | Select the checkboxes for all weekdays. |
| Starting Time | Optional Enter the time the job queue first runs on the days selected beforehand: 04:00:00(Please note that the upload must take place at 06:00:00 at the very latest as the data is then required by John Deere in the USA.) |
|
| Ending Time | Optional Enter the time the job queue runs the last time on the days selected beforehand: leave empty; upload should run only once before the working hours |
|
| No. of Minutes between Runs | Optional Enter the number of minutes after which the job queue runs the next time within the timeframe specified in the Starting Time and Ending Time fields: leave empty; upload should run only once before the working hours |
(02) Download
| FastTab | Field | Value |
|---|---|---|
| General | Object Type to Run | Codeunit |
| Object ID to Run | 5446082 |
|
| Description | Enter a unique job queue description, e.g., DTF Download via Job Queue |
|
| Earliest Start Date/Time | Optional Enter the date and time the job queue should run the next time. If no value is selected, the job queue will run as soon as the status is In Process. | |
| Recurrence | Run on... | Select the checkboxes for all weekdays. |
| Starting Time | Optional Enter the time the job queue first runs on the days selected beforehand: Select a starting time which covers your company's usual working hours in order to keep John Deere DBS up to date. | |
| Ending Time | Optional Enter the time the job queue runs the last time on the days selected beforehand: Select an end date which covers your company's usual working hours in order to keep John Deere DBS up to date. Any files which are changed after the ending time will only be synchronized the next day the job queue runs. |
|
| No. of Minutes between Runs | Optional Enter the number of minutes after which the job queue runs the next time within the timeframe specified in the Starting Time and Ending Time fields: 5Select a duration which leaves enough time to upload the files to John Deere side. This largely depends on the speed of the corresponding internet connections! |
- Confirm the settings by clicking on the OK button.
- Enable the job queues as per your standard process.
The job queues will now run as defined and exchange data between the John Deere side and the John Deere DBS side on a regular basis. The transmissions are logged in the DTF File Processing Log and on the Job Queue Log Entries page.
Congratulations! The DTF Interface is set up and ready. You can now proceed with the Test or the User Guide section.
Test
DTF Interface Test
Note
Please note that no special test environment is required or intended by John Deere. You can safely use the productive environment for functionality test with your John Deere representative.
User Guide
This subsection describes how to use the DTF Interface after successful setup and test.
As soon as the DTF service is up and running, no further user interaction is needed. The service is running in the background to establish the basis for the DTF-dependent John Deere DBS interfaces. Information about the interfaces' use of the DTF Interface can be found in their corresponding documentation.
In case files are not transmitted as intended via the job queues, please check the DTF File Processing Log for transmission errors and fix them, if needed.
In this section, you can find the following subsections:
DTF-dependent John Deere DBS interfaces
The following John Deere DBS interfaces rely on the DTF service. Information about their use of the DTF Interface can be found in the corresponding documentation:
- Deere Parts Price List
- Deere Parts Substitution List
- DFA (Dealer Financial Analysis)
- DPM (Dealer Parts Management)
- Parts Locator
- Parts Receipt
DTF Interface updates
The DTF interface is regularly updated in sprints. Below, you find an overview of all corresponding tickets:
- [JDK-100] 1620 — DTF replacement: new data model (DTF Interface)
- [JDK-204] 1635 — DTF replacement: upload and download schedule (DTF Interface)
- [JDK-263] 1654 — DTF replacement: duplicate file name handling (DTF Interface)
- [JDK-413] Issue related to wrong captions on DTF Interface pages (DTF Interface)
- [JDK-432] Issue related to overwritten 'Dealer Account No.' value in DTF requests (DTF Interface)
Support
Note
The Support section is currently work in progress. Content will be updated as soon as it is available.
In the meantime, follow the processes in place to receive support from John Deere.