This is the first of two tutorials that describe how to configure ZEDI so that it can exchange transactions with your CargoWise system. The topics covered are:
- Configuring ZEDI to exchange transactions with CargoWise
- Using metadata extracts to make life easier when handling CargoWise transactions
This tutorial deals with the first one.
We’re going to work through an example based on two CargoWise environments, one for live transactions and the other for test transactions.
CargoWise sends and receives transactions via an interface called eAdaptor. It’s useful to understand a little about how it works before we start.
In this example, our live CargoWise environment licence code is “ZBLWOKPRD” and the test environment licence is “ZBLWOKTST”.
Each of these has an eAdaptor interface attached to it. These interfaces have a URL like those shown here.
Your ZEDI environment also has an eAdaptor interface and again, it has a URL like this.
When one of your CargoWise environments has a transaction it needs ZEDI to process, it connects to the ZEDI URL and delivers the file.
Similarly, when ZEDI has a transaction for CargoWise, it will use the appropriate URL to deliver it.
The connections between CargoWise and ZEDI make use of the https: protocol, so the transactions are securely encrypted as they pass between the two systems.
If the eAdaptors in your CargoWise environments have not yet been configured, then this will need to be done as a first step.
Instructions for doing this can be found in the CargoWise document “Technical Guide – eAdapter SDK.pdf”, or you may choose to ask your CargoWise supplier to set it up for you. Either way, the things you need to determine are:
- The user ID that ZEDI will need to use in order to connect to your eAdaptor
- The password ZEDI will need to use.
- The URLs for the production and test eAdapters.
The first two are specified in the “eServices\eAdapter Inbound Authentications” section of the CargoWise registry. For this example, we’re going to say that the user ID will be “ZEDI” and the password will be “Car0Emer@ld”.
The URL is commonly in this format:
[Enterprise] is the first three characters of your CargoWise licence, and [origin] is the last three characters. In our case, the licence is “ZBLWOKPRD” so the URL for the production licence would be:
We’re going to set up ZEDI so that it will be able to deliver transactions into the two eAdaptors on CargoWise.
The first thing we need is a trading partner to represent CargoWise as a whole. It will look something like this:
Note that the default communications method is set to “eAdaptor”.
The details of the eAdaptors on your CargoWise environments are entered in the “Communications” section.
Set the communications method to “eAdapter” and complete the URL in the “Production” section.
The “recipient” is ZBLWOKPRD for our live environment, and the “sender” will be the user ID that was setup in the CargoWise registry.
Now enter the corresponding password in the “password” field
Do the same thing for the test CargoWise environment in the “Test” section using the test URL, recipient, sender and password.
Once this has been done, ZEDI has everything it needs to be able to send transactions into CargoWise, so save the changes.
We now need to configure ZEDI it so that it can receive transactions FROM CargoWise.
This is done on the “eAdaptor” section of the “Communications” page.
Invent a suitable password for the “CargoWise password” field. This will be the password that your CargoWise environments will need to provide in order to successfully deliver a transaction into ZEDI, so make a note of it.
Now use the “Add” row to add your production licence code to the list of IDs.
The ID Type will be “Internal” as this is an ID that is owned by your business. IDs can also be defined as “External”, these would be used when using ZEDI as an eAdaptor gateway, that’s the subject of another video.
We don’t need to provide a password for Internal IDs because ZEDI will expect the one entered at the top of the page to be used.
Since this is the live ID, we’ll set the mode to “PROD”. Now select the trading partner you created to represent CargoWise as a whole, and click the “Add” button.
Do the same thing for the test licence code, but this time set the mode to “TEST”.
You’ll now need to setup the outbound eAdaptor in CargoWise. Again, instructions for doing this can be found in the CargoWise document “Technical Guide – eAdapter SDK.pdf”, or you may choose to ask your CargoWise supplier to set it up for you.
Whoever does this will need the password, the one you just entered on the eAdapter settings screen in ZEDI, and the URL for your eAdaptor. The URL will be in this format:
So, if your service provider’s domain was “zirconblue.com”, and your environment code was “ZB”, the URL would be this:
Note that the URL begins with https:// rather than http://. This is important as it ensures that the transactions are sent securely between CargoWise and ZEDI.
In CargoWise, the eAdapter Outbound Messages service task needs to be enabled and running.
The password needs to be entered in the CargoWise registry under “eServices\eAdapter Outbound Password”.
The URL also needs to be entered in the CargoWise registry under “eServices\Outbound eAdapter Service URL”.
Within CargoWise, you can now trigger a test message by setting up a trigger which sends a Universal XML to the ZEDI eAdaptor. Once again, information on how to do this can be found in the CargoWise document “Technical Guide – eAdapter SDK.pdf”.
CargoWise will always use the nine-character licence code as the user ID to logon to the ZEDI eAdaptor.
ZEDI will validate that user ID by comparing it to the list of valid licence codes you setup in the “eAdaptor” section. If the user ID is not recognised, then the file will be rejected and it will appear in CargoWise as a “Transmission error” or something similar.
ZEDI will also check the password CargoWise provided to ensure it matches the one entered in the “Settings” section within ZEDI.
If everything is okay, then the file will be added to the list of transactions as a file from the partner you selected when you added the licence code in the “eAdaptor” section.
ZEDI can then perform whatever sequence of actions need to be done in order to process the transaction. Typically the first of these will be a “Metadata Extract” which will identify the final recipient of the transaction, the consignee for example, and the type of data the transaction contains such as “ForwardingConsol”.
This metadata will then allow the transaction to be accurately processed through ZEDI and is the subject of the next tutorial.
Transactions can be sent TO your CargoWise system by setting up a “Post transaction” action.
In this example, we’re going to send an inbound “AccountingInvoice” transaction from ACE Vegetables that has a condition of “Mapped”.
The action we’re using is called “Post transaction” and we’ve selected our CargoWise partner as the trading partner it will be sent to.
You may remember that we setup two CargoWise licence codes when we created this partner, once for the live system and the other for test. ZEDI will choose which to use based on the mode of the transaction. So live transactions go to the live licence, and test transactions go to the test licence.
We’ve left the communications method as [Partner default].
When we created the CargoWise partner we set the default communications type to eAdaptor, so the transaction will be delivered using the recipient, sender and password entered on the partner definition.
If we change this from [Partner default] to “eAdaptor”, then a button called “Additional settings” will appear. This allows us to override the recipient and sender This can be useful when you have multiple licences and need to ensure that the costs are assigned correctly within CargoWise.
The recipient and sender can either be set explicitly, or you can use fields from the metadata to set them. For example, if the transactions have an item of metadata called “CWRecipient” which contains the required recipient ID, then you can set the recipient to “[meta:CWRecipient]” rather than set it to a fixed value.
Once the action has been performed, the history of the transaction will record whether or not it was accepted by CargoWise.
If it was then an AED0002 entry will record the tracking ID that was used.
If the file could not be delivered then the history will record detailed information about the cause of the problem.