Argos API/EDI Import Tool

Argos API/EDI Import Tool

This document outlines how to use the Argos API Import tool to import new Bailment Accounts from an external file through the Argos API Server. Also how raise Credit Returns and Price Adjustments.

Prerequisites

API Server

The API Import tool requires a working instance of the Argos API Server. See the API Server Installation document for details on installing this.

.NET Framework 4.8

The .NET framework 4.8 must be installed for the API Import tool to run.

Microsoft Access Database Engine 2010 Redistributable

This can be downloaded from https://www.microsoft.com/enin/download/details.aspx?id=13255

Configuration

AppSettings.config

The API Import tool requires an appSettings.config.

In the installation folder:
  1. Rename the appSettings.config.example to appSettings.config 
  2. Edit the file to point to the server you wish to connect to.

<?xml version="1.0" encoding="utf-8"?>
<appSettings> 
<add key="ApiUrl" value="https://example-server.com/webapi/"/>
<add key="LoanModelMapFile" value="loanModels.xlsx"/>
<add key="SecurityMakeMapFile" value="securityMakes.xlsx"/>
<add key="DealerCodeFile" value="dealerCodeFile.xlsx"/>
</appSettings>

The LoanModelMapFile, SecurityMakeMapFile and DealerCodeFile values can edited if desired

ConnectionSettings.config

To import an EDI file, the API Import tool requires a connection to the Argos database.

In the installation folder:
  1. Rename the ConnectionSettings.config.example to ConnectionSettings.config
  2. Edit the file to point to the database you wish to connect to.

<?xml version="1.0" encoding="utf-8"?>
<connectionStrings>
  <clear/>
  <add name="ApiServer" connectionString="Data Source=server_name;Initial Catalog=database_name;Integrated Security=True" providerName="System.Data.SqlClient" />
</connectionStrings>

Replace server_name and database_name with the appropriated values.

Security Map File – EDI Only

To import an EDI file, the API Import tool requires a mapping from the third-party security make code to the Argos Security Make Code.

In the installation folder there is a securityMakes.xlsx spreadsheet. This contains the mapping data as follows:

Column Header
Format
Mandatory
Comment
EDISecurityMake
General
Y
The third-party security code
ArgosSecurityMake
General
Y
The Argos Security Make code

Other columns can be present but will be ignored. The API Import tool will look at the first sheet in the workbook.

Note: The columns must be formatted as “Text” or they will not import correctly

Loan Model Map File – EDI Only

To import an EDI file, the API Import tool requires a mapping from the third-party floor plan code to the Argos Bailment Loan Model Code.

In the installation folder there is a loanModels.xlsx spreadsheet. This contains the mapping data as follows:

Column HeaderFormatMandatoryComment
FreeFloorPlanEDICodeGeneralYThe third-party floor plan code
DivisionGeneralYThe Division Code/First Analysis code associated with this floor plan
LoanModelCode
General
Y
The Argos Loan Model Code
Condition
General
Y
One of NEW, USED, DEMO, RACE, RENTAL or IMPORT

Other columns can be present but will be ignored. The API Import tool will look at the first sheet in the workbook.

Note: The columns must be formatted as “Text” or they will not import correctly

Dealer Code Map File – EDI Only

To import an EDI file, the API Import tool requires a mapping from the third-party dealer code to the Argos Dealer Code.

In the installation folder there is a dealerCodeFile.xlsx spreadsheet. This contains the mapping data as follows:

Column HeaderFormatMandatoryComment
ThirdPartyCodeGeneralYThe third-party Dealer code
ArgosDealerCodeGeneralYThe Argos Dealer code

Other columns can be present but will be ignored. The API Import tool will look at the first sheet in the workbook.

Note: The columns must be formatted as “Text” or they will not import correctly

The Third Party Code column must not contain duplicate codes

SQL Scripts for Argos Staff User Access – API V4, V5 & V6

For an Argos Staff User to login to create accounts across many Distributors a series of scripts must be run by Argos Support for this to happen. Contact Argos Support if this is required.

Note: Scripts are located in Zoho Learn – SQL Scripts – Flag to Create Invoice using Distributor Code with Staff User Login via API

SQL Scripts for Payment Reference Transaction – API V6

For the Payment Transaction Reference to be added to an account a series of scripts must be run by Argos Support for this to happen. Contact Argos Support if this is required.

Note: Scripts are located in Zoho Learn – SQL Scripts – Flag to Enable "Payment Transaction Ref" field in bailment account.

Data Source

Excel File  - API and EDI

The API Import tool reads the Bailment Account details from an excel spreadsheet. An example file is provided with the tool.

The sheet can be named anything, but the tool will default to looking for a sheet called “Argos Imports”

The sheet must have following columns (order is not important):

Column HeaderFormatMandatoryComment
Bailment Dealer CodeGeneralYThe Argos Bailment Dealer Code
Invoice NumberGeneralYThe Invoice Number for the Account
Invoice Date
Date
Y
The Invoice Date
Loan Model Code
General
Y
The Argos Loan Model Code
Division/First Analysis Code
General
Y
The Argos First Analysis Code
Gross Amount
General
Y
The Gross Amount on the Invoice
Tax Amount
General
Y
The Tax Amount on the Invoice
Asset Condition
General
Y
One of NEW, USED, DEMO, RACE, IMPORT or RENTAL

For livestock always select NEW
Description
General
Y
The Description for this asset
Model
General
Y
The Model for this asset

Not mandatory for API V5 - Livestock
VIN / HIN
General
Y
The VIN / HIN for this asset

Not mandatory for API V5 - Livestock
Colour
General
N
The Colour for this asset
Engine Number
General
Y
The Engine Number for this asset

Not mandatory for API V5 - Livestock
Registration 
General
N
The Registration Number for this asset
Year of Manufacture
General
Y
The Year of manufacture for this asset

Not mandatory for API V5 - Livestock
Security Make
General
Y
The Argos Security Make Code for this asset
Request Type
General
Y
Must contain the type of request, lowercase letters

ci - Create Invoice
cr - Credit Return
pa - Price Adjustment
cli - Create Livestock Invoice
Distributor Code
General
Y
API V4, V5 & V6

The Argos Distributor Code
Second Analysis Code
General
N
API V4, V5 & V6

The Argos Second Analysis Code for this asset
Original Livestock Count
General
Y
API V5 - Livestock only

The Original Stock Count
Payable Account
General
Y
API V5 - Livestock only

The Argos Payable Account for this account
Maturity Date
Date
N
API V5 - Livestock only

The Maturity Date
Approval Code
General
N
API V4 only

The Order Number for this account
Return Date
Date
See Comment
Mandatory for cr Request Type otherwise is blank
Adjustment Date
DateSee Comment
Mandatory for pa Request Type otherwise is blank
Payment Transaction Reference
General
Y
API V6 only

The Payment Transaction Reference for this account

Using the API Import tool

Run the Argos.ApiImport.exe file.

Logging in

At this point the main application form will load. Select File-> New Session


The login screen will appear



Enter the supplied Distributor External User username and password details.  If using V4 of the API, login with your Argos Staff Code username and password details.

Selecting a Data Source

Right click (or press F2) on the Import From browse box. Select the file you wish to import.

Excel Files

If the selected file is an excel file and has a sheet named “Argos Imports”, this will automatically be selected. If not, select the correct sheet from the dropdown.

EDI Files

If the selected file is an EDI file, the worksheet does not need to be selected.


Running the Import

Click the “Import” button, and the source data will be used to create requests for the API. The success or failure of each request is recorded in the results grid.

Credit Notes and Price Adjustments

These can only be run via a Distributor Login.

The amount on the spreadsheet must be a credit not a debit to allow for the credit note to process

Troubleshooting

Below is a list of error messages that may be presented if there is a configuration or set up issue.

The … may be either the Security Make, Dealer Code or Loan Model map file.

Error
Resolution
Could not find … File :
The location of the file has not been specified in the AppSettings config or there is a typo in the specified location 
Error Processing … File: ….xlsx

The given key was not present in the dictionary
There are codes contained in the import file, that have not been added to the spreadsheet for the system to recognise the required mapping

This error will also be presented if the columns are not formatted as text.

Note: If there has been excessive formatting on the spreadsheet (filters, fill colours etc), this can corrupt the spreadsheet for the import. Copying the import file data to a new worksheet may resolve this issue also. 
Error Processing … File: ….xlsx

An item with the same key has already been added
There are duplicate codes in the third party mapping column

These must be unique.

Error Handling

After running the import any errors will be logged in a “Log.txt” file in the same directory as the application. If any requests failed they will be saved to an excel spreadsheet called “Errors_<timestamp>.xlsx” (where <timestamp> is the current timestamp). This file will be in the users documents folder.


    • Related Articles

    • Import EDI File Setup

      Purpose Allow the setup of file paths for import and export of file relevant to distributors Access View | Distributor | account | Distributor Settings tab Dialog Details The following dialog will display: Details Specific Fields Field Explanation ...

    • Import EDI File Errors

      Purpose EDI Import allows the import of an externally created file of Bailment Assets, credit returns and price adjustments. Process Review the error, and correct Issue Solution File IO Exceptions or parsing errors If there is a problem reading the ...

    • EDI File Formats

      EDI File Format Field Position Num of Char Example Description Required Argos Data Not Used 1-3 3 DTL Record Type Y 4-5 2 IF Transaction Type IF - Invoice RF - Credit Return PA - Price Adjustment Y 6-8 3 1 Company Number N Y 9-20 12 IN1234567891 ...

    • Importing an EDI file

      Purpose To allow the import of asset details so that Bailment Accounts and Trust Receipts may be automatically created EDI File Import Rules All invoice amounts must be positive All Credit Return amounts must be negative and for the full amount of ...

    • Installing Argos Internal API

      The Argos Internal API is used to power the Vault and Bailment applications. Note, this is available from Argos v6.0 onwards Installation Types The installer can be used to install a production instance of the Argos Internal API. Instructions to ...