EDI via FTP / FTPS

EDI files can be transfered via this protocol.
FTP access has to be enabled by us, you have to ask us (sorry).
As soon as we activated the FTP subsystem you will see submenu Backoffice->Settings->FTP User Management.

Via FTP you can transfer EDI files to- and from cargooffice. Files you would like to upload to cargooffice typically include orders, status updates and trips. Files you would like to download from cargooffice typically include EDI files for your own TMS system, status updates, electronic signatures and invoice data.

Apart from your own EDI files you can also allow customers to transfer EDI files to- and from your cargooffice.

It is possible to instruct cargooffice to automatically PUSH or GET files. See the paragraph Automated transfers below.

Note: FTPES is the secure variant of FTP. Transfers are SSL/TLS encrypted. You can choose either for FTP, FTPS, FTPES (ftp://ftp.cargooffice.com or ftps://ftp.cargooffice.com or ftpes://ftp.cargooffice.com) or SFTP.

Note2: If you use Filezilla and encounter errors saying ECONNABORTED, then please downgrade the minimum TLS version in Filezilla: edit -> settings -> Minimum allowed TLS version
Downgrading the TLS version might be a little less secure.

Contents:

Access to your files (upload and download)

If FTP access to your cargooffice is enabled, EDI files can be transfered via this protocol. The FTP subsystem is active if the submenu Backoffice->Settings->FTP User Management is visible. If there is no such item available in the Backoffice, please contact Loginet via the bug tracking system in your cargooffice, via email or phone.

Master FTP EDI account for your cargooffice

You can access the master FTP account of your cargooffice via the username on top of the list in the submenu 'FTP User Management' as mentioned above. Usualy the username will have the format edi@yourcarriername.cargooffice.com. The password for this account can be set via this interface.

The servername for this account (and possible customer accounts) is ftp://ftp.cargooffice.com. With SSL/TLS certificate: ftpes://ftp.cargooffice.com.

Structure of the Master FTP EDI account

The directory structure of the master FTP account for your cargooffice mainly consist of an upload directory for EDI files, that will then be processed by cargooffice, a download directory where cargooffice places the output files it produces (e.g as for your TMS system to process), and one or more subdirectories for your customers, basically containing upload and dowload subdirectories of their own.

Data directory: /data

Files placed in this directory can be called or linked from different parts of Cargo Office aplications.

• attachments: additional files often connected to the bookingdetails.
• invoices: invoices generated out of the billing system.
• signatures: collected signatures from end users of pda's, smartphones and tablets.
• templates: some cargo office administrators have the ability to maintain some of their templates (at own risk).
• warehousepix: pictures from warehouse products.

Upload directory: /out

Files placed in this directory will be processed by the cargooffice EDI system according to their extension. All standard EDI file formats as described in the EDI section will be processed by default.

successfully processed files will be archived in /out/done for 7 days after processing

In case of errors during processing, files causing errors will be archived in /out/error and error output messages will be mailed to the address as set in parameter Backoffice->Settings(Instellingen)->Paramaters->OrderEntry(Zendinginvoer)->ErrorMailAddress.
Depending on the type of error the content of the message varies. It's not possible to sent messages for all errors, because the range of possible errors is bigger then we can imagine, but by time we add new error messages.

Download directory: /in

Orders processed by cargooffice (via EDI uploads or via webentry) generally produce digital out files ( e.g. as to be processed by your local TMS system. Cargooffice places such output files in /in, filenames depending on the chosen output format (via parameter Backoffice->Settings(Instellingen)->Paramaters->OrderEntry(Zendinginvoer)->OrderOutputType).

If a mail address is set for output (via parameter Backoffice->Settings(Instellingen)->Paramaters->OrderEntry(Zendinginvoer)->OrderOutputEmailAddress), such files we be mailed to this address. In case of success the output file will be archived in /in/done, in case of failure in /in/error.

If the parameter 'OrderOutputEmailAddress' is set to 'ftp', no mail will be sent out and the file will remain in root/in for download via FTP.
The best thing when downloading your files from this root/in directory is to put a copy in the done-directory when downloading the file. This way you keep better control over former processed files.

Customer FTP accounts and subdirectories

NEVER give your master FTP account to customers or third parties, use this procedure in stead.

Via the 'FTP User Management' menu, you can create FTP accounts for your customers to upload EDI files to be processed automatically. You can create such an account by clicking on 'Add User'. Cargooffice will automatically create the necessary directory structure (see bellow) and username and will prompt you to set the corresponding password.

Your customers will 'see' a directory structure similar to the above described: a /out directory for uploads and a /in directory for possible downloads (note that no TMS output will be placed here, all such output is categorically ment for the holder of a cargooffice, not his/her customers.

Furthermore such customer accounts will be accessible via the mast ftp account as subdirectories.

Example

Carrier 1234 ( showcase.cargooffice.com )

Master FTP Account:

server ftp.cargooffice.com
user edi@showcase.cargooffice.com
passwd somepass

visible directory structure:

/data
/data/attachments
/data/img
/data/invoices
/data/signatures
/data/templates
/data/templates/mobile
/data/warehousepix
/out
/out/done
/out/error
/in
/in/done
/in/error
/101/out
/101/out/done
/101/out/error
/101/in/done
/101//in/error

Customer Account:

(customer 101)

server ftp.cargooffice.com
user edi+101@showcase.cargooffice.com
passwd somepass101

visible directory structure:

/out
/out/done
/out/error
/in
/in/done
/in/error

whereby these directories are in fact the content of subdirectory 101 in the master account.

Automated transfers

FTP PUSH (automated transfer from cargooffice to your customers, subcontractors or your own systems)

It is possible to have files PUSHed to another FTP location automatically from Cargooffice. The pushspooler runs every few seconds. To configure this, you need to carry out the instructions below.

Note: For calling a webservice to transfer data please read: ApiCalls

First, a param 'orderOutputFTP' needs to be created. This param contains details of where the files will be pushed to. If you provide the param with a customerID, an outputfolder will be created for this customerID. If you omit the customerID, a general outputfolder will be created.

Before creating a new param please test the transfer from your own PC or server by using an FTP client. If you can't transfer the file using the given credentials, then cargooffice certainly will not do better.

Example of an orderOutputFTP param:

host=123.456.789.10
user=me@remoteserver
pass=password@remoteserver
dir=put/in/somefolder
log=1
tempExtension=.tmp
erroremail=youremail@yourdomain.com

Explanation:

• host: the ftp server you are pushing to
• user: the user ID needed to log into this server
• pass: the password needed to log into this server
• dir: the folder on the remote server you wish to push to
• log: whether the ftp actions should be made visible under 'EDI log' in your Cargooffice, set to 0 for no logging, set to 1 for logging.
• tempExtension: (optional) a temporary extension while uploading the file, the file is renamed when the upload is complete.
• errormail: (optional) an email is sent to this email address if something goes wrong trying to upload a file

SFTP push

SFTP connection will use same parameters as above plus these:

proto=sftp
port=22
key=id_rsa_intergamma

Explanation:

• proto: set pushspooler into secure ftp mode.
• port: necessary if ftp server use different port than 22.
• key: (optional) use this parameter only if the other side uses authentication with a public key. (Note: the key pair needs to be created by us and the public key will be made available to the other party by us, please contact us if you need this).

Next:

Param 'orderOutputEmailaddress' must be set to 'ftppush' for the chosen customerID. Please note that the use of capitals is different from the standard Cargooffice parameter: it must be orderOutputEmailaddress.

Only a combination of orderOutputFTP and orderOutputEmailaddress with the same customerID will create a working solution. So either both the params must have no customerID, or the customerID must be the same. You can obviously create numerous param pairs in this manner.

After having set these two parameters, files placed in the spool folders will be pushed to the defined remote locations.

Spool folders:

For every orderOutputFTP param, a spool folder is created. The spool folders are:

ftproot/in/ftpoutspool

ftproot/in/ftpoutspool<customerID>

The first is the general spool folder, the second is a customer specific spool folder.

You will need to save the file you want to transfer into the outspool folder. This can be done manually by using an ftp client (well, useless solution but hey) or automatically from a doAction script.

Troubleshooting

If the outspoolfolder is not created in ftproot/in, go back to the orderOutputFTP and orderOutputEmailaddress parameters and simple re-confirm them. Pay attention to the capitalised characters in the parameter names as they tend to break things. orderOutputEmailaddress must be spelled exactly as shown here with a small a for address!!!

FTP GET (automated transfer from customers or subcontractors to your cargooffice)

To use automated FTP GET instructions you need to be familiar with the cargooffice scheduler. If you are not familiar with the scheduler then it is best to drop us a mail or enter a request in the bug tracking system and we will do it for you.

You can find the scheduler here: Backoffice->Backoffice settings->scheduler.

Before entering a new scheduler entry please test the transfer to your own PC or server by using a FTP client. If you can't get the file then cargooffice certainly can't get it.

Example of a FTP GET scheduler entry:

7,8,9,10,11,12,13,14,15,16,17,18 * * * ftpget.php -C12345 -cCUSTID -hftp.server.com -uUSERID -pPASS -dDIR -mTEST.*\.xml -sunique -exml -rARCHIVE --proto=FTP

Explanation:

• -C12345: replace 12345 by your carrier number
• -cCUSTID (optional): replace CUSTID by the customerID if the file needs to placed in the customers FTP directory
• -hftp.server.com: replace ftp.server.com by the IP or URL of the remote system
• -uUSERID: replace USERID by the userID required by the remote system
• -pPASS: replace PASS by the password required by the remote system
• -dDIR (optional): replace DIR by the remote directory name if the file is in a subdirectory at the remote system
• -tDIR (optional): replace DIR by the target directory name if the file must be placed in a special subdirectory at the receiving system (see: Note3).
• -mTEST.*\.xml (optional): replace TEST.*\.xml by a file mask (regular expression) if only certain files need to be downloaded
• -sunique (optional): suffix, an optional text that will be added to the final filename, 'unique' creates a unique datetime stamp, other texts are just added to the filename (but before the extension)
• -exml (optional): replace xml by the extension cargooffice requires to start the right parser (e.g. xml, ttm, xls, xlsx, csv)
• -rDIR (optional rename): replace DIR by the directory name at the remote server where the file needs to be moved to after download (see: Note2)
• --proto=FTP (optional): the type of protocol to use, possible values are: FTP, FTPS or SFTP (FTP is the default)
• -S (deprecated) use SFTP (overruled by --proto=)
  
  

Note1: Cargooffice places the file in your /out directory for automatic pick-up by the EDI parser (also see Note3).
Note2: if option -r is given then Cargooffice will move the file on the remote server to the directory given by this option (e.g. -rARCHIVE). Otherwise Cargooffice will remove the file from the remote system when the transfer is complete.
Note3: The only valid parameter for argument -t is 'signatures' (-tsignatures). This places the file in data/signatures in stead of the default /out directory.