Overview

This document describes the DTN TABS™ ADMLOD 2.4 protocol. This protocol consists of a series of commands to give a user the ability to add, modify, and delete data in the DTN TABS system via a batch file.

ADMLOD commands can be submitted as a text file in ASCII through FTP. The same file can be submitted through the ADMLOD Upload within DTN TABS.

The ADMLOD Upload page provides Excel templates that can be populated with batch commands and submitted on the page.

Purpose

This document provides instructions for constructing load files that can be used to build and update DTN TABS.

It covers the key components and database tables within DTN TABS, including:

  • Terminals
  • Consignees
  • Marketer Consignees
  • Terminal Groups
  • Consignee Groups
  • Products
  • Product Groups
  • Forecasts
  • SoldTos
  • ShipTos
  • Channels
  • Carriers
  • Third Parties
  • Credit Allocations
  • Product Allocations
  • Global Product Override
  • Destination

 

General Protocol Guidelines

The DTN TABS ADMLOD protocol is a text line oriented protocol, described by commands and fields that are delimited (separated) by a semicolon (;) character. The fields are fixed positioned, which means they must be entered and transmitted in a prescribed order. Defaulted fields are designated with two semicolons.

All commands use the following format:

cmd;entity;field1;field2;…..

Where:
Cmd The command type, such as add, modify and delete.
Entity The type of entity of element to process such as terminal, consignee, transaction.
Field1  

The field value for the associated command.

 
Numeric Protocols

Unless specified under the individual field remarks, all numeric data must be rounded to the nearest whole number.

Alpha Protocols

On alpha fields, you may use both upper and lower case letters; however, you should be aware that searches on these fields aren’t case sensitive.

Seller Log On

The login and password of the sign on establishes the seller association with each data load. All the data that is processed by the ADMLOD is applied at this Seller ID level.

Commands

Below are the commands associated with each DTN TABS entity.

  • ADD
  • MODIFY
  • DELETE
  • ASSIGN
  • REMOVE
  • EXPORT
  • MERGE
Email Response

You can forward the response file to one or more email addresses with the Email Response command. This helps you monitor the ADMLOD process.

The command format is:

EMAIL;RESPONSE;TOADDRESSES

The command should be placed in the second line of the ADMLOD transmission after the VERSION tag.

No Field Type Size Required Remarks
1 EMAIL COMMAND
2 RESPONSE       ENTITY
3 TOADDRESSES AN Required Email address to which the response file must be sent

 

The following example shows a change to an allocation with email response notification:

VERSION;2.0;

EMAIL;RESPONSE;[email protected],[email protected];

BEGIN;ALLOCATION;T;255555000;C;123456;

MODIFY;ALLOCHEADER;Allocation;N;;N;N;AST;N;

END;ALLOCATION;

Transactions

ADMLOD 2.0 introduced the concept of transactions to the protocol. This provided the capability to group a series of ADMLOD commands into a single transactional process. All commands within the transaction block are treated as an atomic or single update to the system. If any single command within the block fails, then all of the commands of the block fail, and none of the commands are entered or committed to the DTN TABS system.

Begin Transaction

The Begin Transaction command is the first command in the set of commands for a transaction block. Before you can send a Begin Transaction command, you must have closed or ended any previous transactions with the End Transaction command. If not, an error occurs.

Note: Currently, DTN supports transactions at one level only. No nested transactions are allowed.

The command format is:

BEGIN;TRANSACTION;

Note: Allocation commands have their own Begin and End Statements. Therefore, Allocation commands are not allowed within the Transaction BEGIN/END block.

End Transaction

The End Transaction command signals that the transaction is complete. When DTN TABS encounters an End Transaction command, it commits or updates the system with any transactions that were transmitted between the Begin Transaction and End Transaction commands for that transaction block.

Note: If an error occurs at any point within the transaction block, the whole transaction block fails or is uncommitted.

The command format is:

END;TRANSACTION;

Note: Allocation commands have their own Begin and End Statements. Therefore, Allocation commands are not allowed within the Transaction BEGIN/END block.

 

Export/Merge Commands

Introduced in September 2016, the Export and Merge ADMLOD commands allow users to export DTN TABS data into a format that can then be reloaded back into DTN TABS using the Merge command.

Export

The Export command will produce an output that contains the entity as a merge command so the requester can then use to modify and upload changes into DTN TABS.

The command format is:

EXPORT;ENTITY;

Merge

The Export command acts as an insert where if the entity does not exist, it will act like an ADD command and if the entity does exist, it will act like a Modify command.

Uploading Files

ADMLOD commands can be submitted as a text file in ASCII through FTP. The same file can be submitted by the ADMLOD Upload within the DTN TABS website user interface. Additionally, the ADMLOD Upload page provides Excel templates that can be populated with batch commands and submitted on the page.

FTP Upload

Address:         Production – ftptabs.dtn.com

               Test – catftptabs.dtn.com

FTP Directory: IMPORT

Here’s how to upload the ADMLOD commands through FTP:

  1. Login to TABS FTP System – OPEN ftptabs.dtn.com
  2. Send User name = TABSN_[Seller Number]X[Login]
  3. Send Password
  4. Send ADMLOD file to IMPORT Directory = Put <Your local file name> ./IMPORT/<File name>
  5. Process ADMLOD file and get response file = get ./IMPORT//<File name> /<Response File name>
  6. End Session = QUIT

Sample Script:

OPEN ftpTABS.DTN.COM

TABSN_999XTEST1234

TEST8547

put ADMCON.txt ./IMPORT/ADMCONS1105.txt

get ./IMPORT ADMCONS1105.txt ADMCONS1105RESPONSE.txt

Quit

DTN TABS UI Upload

There is a file validation feature that proofs the formatting of the file prior to uploading.

Note: Excel file uploads do not require the Begin Transaction and End Transaction commands. The Begin Allocations and End Allocations, and the Begin Product Allocations and End Product Allocations are still required.

Here’s how to validate your files:

  1. From the ADMLOD Upload page, enter or click to find and select your ADMLOD Excel file.
  2. Click .

Here’s how to upload and process your file:

  1. From the ADMLOD Upload page, enter or use Browse to find and select your ADMLOD Excel file.
  2. Click .

 

Category: Getting Started