Legacy Forum Q & A
Q: What should I be passing in Name tag when trying to list all networks?
A: It can be left blank. The Name parameter allows you to use the function to search for specific networks rather than a complete list.
Q: The time on the dates doesn't seem to have been updated to reflect the clock changes in Britain (forward 1 hr). I've just uploaded an Invalid message at 12:07 and the error report (parcelError) is reporting it was uploaded at 11:07.
A: All times in ECGrid are UTC/GMT. In future versions we may look into timezone support.
Q: What is the required access for MailboxList?
A: You need to be logged in and have a valid session to be able to do a mailbox list. Your user must also be linked to the mailbox that you are trying to do a listing for.
Q: Looking further into the API I do not see a method to change mailboxes (as a user action, not a setting or configuration), so perhaps I should have deduced that only a "network admin" would use such a function.
A: If you go through the API calls, there are many with an Ex suffix (e.g. MailboxList() and MailboxListEx()). The Ex APIs allow the NetworkID and MailboxID to be set, while the ones without the Ex default to the logged in user's NetworkID/Mailbox.
Q: I have the following code
Parcels = ecgridos.ParcelInBoxArchive(SessionID, LastTime, EndDate, 0, 0)
For Each Parcel As ParcelIDInfo In Parcels
Dim File As net.ecgridos.FileInfo
File = ecgridos.ParcelDownloadGZip(SessionID, Parcel.ParcelID)
'Store File Details into SQL Database Table
'File.Bytes
'File.Content
'File.ParcelID
'File.FileDate
NextWill the File.Bytes or File.Content hold the data? Thanks
A: This works just like ParcelDownload(), so Bytes is the size and Content is the actual data.
Q: I tested Interconnect Add successfully in test environment. I can receive PENDING status immediately. After one hour I received email of interconnect confirmation.
- Do you do something on your end to trigger interconnect so the email can be sent?
- In live scenario, will we receive confirmation immediately (except for special cases)? Who will complete the interconnect and send email to us?
A: InterconnectAdd() has an expert engine behind it that makes many decisions based on many parameters including Trading Partner VAN and previous interconnects.
Based on the information they system determines whether it can immediately confirm the interconnect or move it to pending status.
If the Interconnect Request is moved to Pending, then it is forwarded to NetOps for completion. Time to confirmation is dependent on the VAN and other factors. Normally, these are cleared in less than 24 hours.
The particular interconnect you set up today was to an ID on the ECGrid Test mailbox. When I saw the request come up on my dashboard, I moved it to Confirmed status.
Q: When a new trading partner wants to use AS2, I think we need to manually send you the AS2 connection request. However, if some trading Partner such as: Target...who had AS2 connection with you already. How can we do interconnect request? Which NetworkID should we use? Thanks
A: When setting up Interconnects on other Networks, regardless of their communications channel (e.g. ftp, smtp, AS2, etc.), they are all set up the same way using InterconnectAdd().
Specifically for Target, you only need to look up the ECGridID by Qualifier/ID using TPSearchEx() with NetworkID:=-1 and MailboxID:=-1, then use the ECGridID in InterconnectAdd().
Q: How can we cancel an interconnect? Should we just manually send email and receive confirmation manually?
A: There is a function called InterconnectCancel() just for this purpose.
Q: Is there a field on the ParcelInfo object that will let us know when a file was downloaded from the Inbox?
A: There is not, but it can be found in the ParcelManifest() API. We will look into that as a property of the ParcelIDInfo class object in a future update.
Q: How can we check the transaction status if we provide SenderID, ReceiverID and ISA Control Number?
A: Their are a few ways to locate a transaction:
-
InterchangeOutBox()
-
ParcelOutBoxArchive(): Does not use ICN.
-
If you were using ParcelUpload() rather than AS2, then you would receive a ParcelID as the return value which you could store off for future status checks using ParcelInfo() directly.
Q: I have some AS2 questions and forgive me if these are basic questions but I don't really know that much about it and like most things it became a necessity to learn quickly when a trading partner wanted to business with a company that does AS2.
A: First, AS2 is one of several communication paths into ECGrid which we call ECGridAS2. The native ECGridOS communication path is through the ParcelUpload() and ParcelDownload() set of APIs.
For every trading partner relationships there are two connections to ECGrid.
The first is for your side (you directly or your customer). If pure ECGridOS, then you can use the ParcelUpload()/ParcelDownload() or configure AS2 or FTP or whatever with our Networks Operations staff (netops@ecgrid.com).
The second connection if for your trading partner. If they already have a relationship with a VAN, then that is our preferred route. The data would route through our Interconnect with that VAN. If your partner does not use a VAN and needs to negotiate a direct connection with ECGrid the Networks Operations staff. We may already have a connection with that trading partner, so it is worth dropping a line to NetOps. Be sure to include your trading partners Qualifier/ID or GLN.
Q: AS2 uses certificates - Can this certificate be self signed?
A: ECGridAS2 accepts all certificates, including self-signed.
Q: I know that ECGridOS supports AS2 - Do I need to have AS2 setup on my system (which brings up many other questions) and then ECGrisOS forwards based on the AS2 url I provide?
A: AS2 is an option. You can also use the secure Upload/Download functions noted. ParcelUpload()/ParcelDownload()
Q: Does ECGridOS's support of AS2 mean I don't need an in-house solution. This would be the best case scenario in which AS2 connections would come to the mailbox ready for download much like the X12.56 Mailbag protocol works.
A: How your trading partner connects to us (VAN Interconnect, AS2, etc.) has no impact on how you connect to us. So if you use the native ECGridOS Upload/Download you need no additional communications software or configuration.
Q: TP - VAN, VAN - VAN, TP - TP - Are all of these options for AS2 connectivity or am I totally confused about how AS2 works?
A: AS2 is simply a communications protocol like FTP. It only appertains to the two points connecting to each other. ECGrid is a message routing hub, so each party that connects to it with its own protocols (VPN, VAN, AS2, FTP, HTTPS, etc.) and the data routes independently. You only need to worry about how you connect to ECGrid. One connection connects you to everyone.
Q: I sent a test file to myself which contained two different interchanges. The API for parcel_in_box specifies that I'll be receiving back a collection of InterchangeIDInfo objects. When I perform this request I actually got back two parcels, each with one InterchangeIDInfo object. Will ECGridOS be separating all inbound data as such and should I always only expect one InterchangeIDInfo in the parcel_in_box response?
A: The collection of InterchangeIDInfo objects is to accommodate systems that send us more than one interchange per mailbag/parcel. A number of the VANs and a few customers do this.
We recommend only sending on interchange per mailbag/parcel, but it is not a requirement. We will always send one interchange per parcel to your InBox.
The class object is set up to generically handle all InBox and OutBox possibilities, which is why it is set up as a collection for InterchangeIDInfo objects.
Q: If a new mailbox was created on, for example, GXS Tradanet which ECGrid did not know about. How would I be able to get ECGrid to know about it and assign it a partner ECGridID ?
I thought this might have been something to do with the interconnect requests, but the parameters to that require sender and receiver ECGrid IDs, which implies ECGrid already knows about the recipient.
Is this an admin task perhaps rather than something I can request through software?
A: Each Network attached to ECGrid maintains all its own internal Mailbox Routing. To ECGrid the connection to a Network (e.g. Sterling Commerce) is one large "trunk" connection.
On ECGrid it is only necessary that the Qualifier/ID or GLN is pointing to the right network. Once the interchange is delivered, that network will make sure it gets to the right place on their own system.
If the QID/GLN is not already registered on ECGrid, you can use the TPAddVAN() function. You will need to know which VAN they are on (if in doubt, contact NetOps).
Q: If you are designing an application that needs to poll all the In-Boxes on a an entire Network there is a way to do this without having to pull each individual Mailbox using ParcelInBox() or ParcelInBoxEx().
A: Using ParcelInboxEx() set MailboxID=-1 and it will check all Mailboxes simultaneously. You will need at least NetworkUser authorization to use this functionality.
Q: Most of the large VANs and many of the small VANs use the X12.56 Interconnect Mailbag Protocol (or X12.56 Mailbag or simply Mailbag) to help track transmissions between VANs.
While this is an X12 standard, X12.56 mailbags often contain X12, EDIFACT, TRADACOM and other standards. European X.400 networks do not typically support this standard.
A: While ECGrid treats Parcels and Mailbags as the same thing, only when the other VAN supports the X12.56 protocol, do we actually use the term Mailbag.
ECGrid fully supports X12.56. When this protocol is used, the Parcel.MailbagControlID property is populated. For Mailbags sent to VANs, this is the same as the ParcelID, left padded to nine digits.
The MailbagControlID is useful in tracking lost interchanges over Interconnects.
Q: I just want to ensure that we are picking up the correct information to display in the Mailbag field.
You sent us the following information previously. Which I think is for Outbound data (from our client)
ParcelUpload() -> ParcelID(1)
internally ParcelID(1) -> InterchangeID -> ParcelID(2)
ParcelID(2) is then sent to the VAN. The MailbagControlNo is ParcelID(2) not ParcelID(1)
So we need to use the MailbagControlNo on the 2nd Parcel for the Mailbag ID?
On inbound we can just use the Parcel ID of the parcel we down load is that correct?
Or is ir
Parcel(1) (Received from VAN) à InterchangeID à ParcelID(2) downloaded by our client.
So do we have to go from Parcel(2) back to Parcel(1) and use the ID of Parcel(1) for the inbound Mailbag ID – i.e. what you will have given to the 3rd party VAN.
A: Close. For outbound (to VAN) it is correct as the MailbagControlNo is Parcel(2).ParcelID, left padded with zeros to nine digits. This is only if the VAN mailbags. Check the Parcel(2).MailbagControlID to see the actual value. If it is blank, the VAN does not do mailbagging.
Inbound, it would be the Parcel(1).MailbagControlID, which will not match Parcel(1).ParcelID because the MailbagControlID for inbound (from VAN) is not assigned by us. If the property is blank, the VAN does not mailbag.
We need to develop new functions to permit users to check the interconnect status and traffic report to save our time and your time.
Q: I couldn’t find the way to view traffic report with : ClientQID, TradingPartnerIQD, and Date. Can you advise which function we should use? How can we download file by using ClientQID, TradingPartnerIQD, and/or ICN, and/or Date?
A: There are a few options depending on exactly what you are looking for. I suspect that you want is ParcelInBoxArchive(), you will also need to make calls to TPSearch() and TPSearchEx() for the ECGridIDs needed in that call. Once you have the ParcelID you can use ParcelManifest() to get even more information.
Once you find the ParcelID through the call above, you use ParcelDownload() or ParcelDownloadGZip() and then ParcelDownloadConfirm() to actually get the data.
Q: I'm kind of new to the EDI thing, I just added some code to upload a simple text file (not an EDI file) using some code that calls ParcelUploadEx() ... but I'm gettting an email that has the following:
ECGrid has encountered problems with the following mailbag due to one or more errors: ISAZZECGRIDOS ZZUPLOADEX 8402068616906 8502068616906 1205010542U999991565579040P| Status: (1105) INVALID ISA SYNTAX
A: The issue here is that X12 only allows a 2-digit Qualifier, but EDIFACT allows 3-digits. The test QIDs (Qualifier/IDs) you set up were 3-digit (840 and 850), so the system choked when trying to validate the ISA segment we use to wrap non-EDI data.
I will be putting in a validation check for ParcelUploadEx() so this is trapped in the future.
For now, just create test IDs using 2-digit qualifiers. If you look into X12, there is only a small set of valid 2-digit qualifiers; however, ECGrid will allow for any letter/number combination. For testing you can stick with something like XX which is not valid in the real world, so will make sure you don't interfere with any live QIDs.
Q: Is there a recommendation on when to use the GZip version of the methods vs. the regular ones? What is the advantage of using the GZip? is there a disadvantage to using it?
A: Good question. The short answer is that there is no recommondation.
GZip was included as EDI data, especially large EDI data files are very compressable. It seems like that would create a huge advantage whem moving very large transactions such as catalogs.
The tradeoff is processing power on both ends to compress/decompress. We have not done any studies. Perhaps you might want to try and let me know what you find.
Off hand at today's internet speeds, I would probably not consider worrying about compression until the file was at least 500K, maybe not even till 1MB.
Q: I was trying to use the ParcelInbox, and ParcelInboxArchive functions to see the complete mailbox (i.e. everything in there, both new and old), but for some reason those always return nothing for me when I use my stratecon.admin login to create a sessionid.
I had expected that calling the ParcelInbox would have shown me all items in all mailboxes for my account; but it must only show the parcels waiting for download.
Is that right? If so, what function do I use to list out all items in the mailbox (downloaded or not)?
A: There are a few issues going on here. First, ParcelInBox() is only pending as you suggest. ParcelInBoxArchive() is for all parcels.
Both of these ParcelInBox() and ParcelInBoxArchive() will only look in the current user’s NetworkID/MailboxID. If you want to log in as a Network Admin (assigned to “Root” MailboxID := 0), then you need to use the ParcelInBoxEx() and ParcelInBoxArchiveEx() where you specify the NetworkID (you only have access to your own) and the MailboxID on your system you wish to check. By using MailboxID := –1 it will check across all your system mailboxes.
Q: Our current system is using separate Mailbox and User for Parcel Management and Trading Partner Management for each of our customers. We want to rewrite our app to use one master User (with MailboxID of 0) to perform both Parcel Management and Trading Partner Management.
I understand that we need to create new Mailboxes for the new customers that come on-board with our company. My question is, do we need to create a new user for each of the Mailboxes? Can we have Mailboxes with no Users in them?
When we try to add the new customer to ECGrid as a new trading partner (by calling TPAddEx()), I understand that we need to pass in the NetworkID of our company. What about the MailboxID? Can we use 0 or should we use the new MailBoxID that we created for our customer? What's the downside of using 0 as the MailboxID? Will it defeat the purpose of creating new mailboxes for our customers if we use 0 as the MailboxID in TPAddEx()?
A: You do not need a separate user for each Mailbox. The NetworkAdmin or NetworkUser level user can access everything in every Mailbox, allowing you to do exactly what you want.
You can either assign the Qualifier/IDs (QIDs) to the Root (MailboxID:=0) or to separate customer Mailboxes, the data will route fine either way. Routing only occurs at the Network level, and then is sorted at the Mailbox level (confusing, I know).
However, I highly recommend that you assign customers their own Mailboxes and assign their QIDs to their mailboxes. This will allow you to produce all sorts of reports, alerts, etc. in the future with much less programming effort than if you were to just dump them all into MailboxID:=0.
If you are going to dump them all into MailboxID:=0, then there is no real reason to set up Mailboxes for all your customers as they will not contain any data.
A little history on this, that might help makes some sense of it. The original ECGrid did not have the concept of Mailboxes, it only had Networks (or Nodes as they were called at the time). All our customers routed all their data through the single Network connection and then did all their own parsing by customers/QIDs.
When we created ECGridOS, we added the concept of Mailboxes. We needed to be backwards compatible with all our existing traffic, so we created this "Root" mailbox (MailboxID:=0) for every Network. This allowed current customers to tap into ECGridOS as their systems currently operated and new customers could use the power of Mailboxes.
Then our current customers wanted to use Mailboxing for reporting, but continue to use their single connection to upload/download all data. We then came up with the concept of Managed and Unmanaged Mailboxes, which allows for this if they were using an alternative communications channel (e.g. FTP, AS2, etc.) rather than ParcelUpload/ParcelDownload.
What we ended up with is a robust system that allows you to send/receive how you want and still retain the reporting aspects of Mailboxing.
Q: I'm trying to retrieve the list of mailboxes that a given user has access to. I'm logged into the API using a user with AuthLevel=MailboxAdmin. When I'm perform a WhoAmI call i get the user info and it only has MailBoxID associated with the response which I'm guessing is the default MailboxID.
Now in the API documentation I saw the two calls MailBoxList and MailBoxListEx however every time I use them I get a permissions access denied error.
Am i using the correct call to retrieve the list of mailboxes? and If yes why am i getting the access denied error.
A: Depends on who your are logged in as and what the Authorization level is.
To see other mailboxes other than the one you are assigned to, you must be NetworkAdmin or NetworkUser.
With that said, if the current user is assigned to the Root Mailbox (0), then using MailboxList() with a Name:="" should work. You can also use MailboxListEx() with NetworkID:=[your NetworkID] and Name:="".
Q:
- Call ParcelInfo() with the uploaded ParcelID from ParcelUpload()
- In that Object you will find an Interchanges property with a list of InterchangeIDInfo objects
- Call InterchangeInfo() with each of the InterchangeID value(s) from the InterchangeIDInfo object(s) above
- Within that structure you will find a Parcels property with a list of ParcelIDInfo objects
- One of these will be the original ParcelID you started with, the other is the Parcel sent to the VAN. It will have a Direction value of InBox (meaning it was sent to the VAN’s In Box).
- The Mailbag Number ECGrid sent to the VAN is in the MailbagControlID property.
NOTE: You cannot do this immediately after upload as it may take several minutes till the Parcel has been processed and forwarded to the VAN.
A: Always report the MailbagControlNumber sent to the other VAN. That also is our internal ParcelID of the file sent to the VAN, which is exactly what we need.
Q: I'm updating a code here about adding a trading partner, using TPAddEx. I would like to understand when I have to use each one of the Routing Groups. Example: Migration1 (This is used when there is a scenario like xyz, etc).. if possible, a short explanation for each one (Migration1, Migration2, NetOpsOnly1, NetOpsOnly2, ProductionA, ProductionB, SuperHub, Suspense1, Suspense2).
Or, if I can get this information from somewhere else to set when calling TPAddEx, like if it is already set to a user and I should use from there.
A: While we use Routing Groups for some internal functionality, for the most part they are a leftover from earlier functionality of ECGrid.
I suggest using only the two following groups:
- For production IDs, use ProductionA
- For test IDs use Test
Q: What's the difference Test/Production when we set the ID ? (So we can run tests with the TD until we are in production?)
A: The main purpose is if the Trading Partner has both a Test and Production AS2 configuration, but uses the same ID for both.
If you set your customer’s flag to Test, it will route to your trading partner’s Test AS2 system
If you set it to Production, it will route to your partner’s Production AS2 system.
Otherwise, it is purely informational.
Q: Based on your vast experience, what are the best practice in managing the services - recommended API calls (parcel management)?
A: Inbound:
ParcelInBox() and ParcelInBoxEx() are used to check for incoming. The Ex commands with an APIKey assigned to a Network level user allows you to check through all your customer mailboxes with MailboxID:=-1 meaning “all” mailboxes. The non Ex only checks the mailbox assigned to the APIKey used.
ParcelDownload() gets the data
ParcelDownloadConfirm() clears it from the InBox
Outbound:
ParcelUpload() and ParcelUploadExA() post the data to the APIKey or specified MailboxID. With both of these, a ParcelID will be returned that you can use to track the data through the system. A unique feature is if you upload to MailboxID:=0 for a data that is in an Unmanaged mailbox, the system will ultimately figure out which MailboxID to assign it to for you based on Sender QID. (Note that ParcelUploadEx() was a different functionality and is deprecated.)
All successful data goes through this process:
ParcelID for the uploaded data
InterchangeID(s) for the interchanges within the data (we highly recommend one interchange per file uploaded, but the system can handle multiple; however, by X12.56 rules if one interchange is corrupt/invalid in the file, we cancel them all).
ParcelID outbound for each InterchangeID for the file to be downloaded to the receiver’s system
Tracking requires looking at the ParcelIDInfo object for the ParcelID, examining the InterchangeIDInfo object within and then calling InterchangeInfo() for that InterchangeID to get the information on the final outbound ParcelIDInfo object.
All status codes are listed on forums.ecgrid.com
For parcels/interchanges that fail, there is an e-mail message and they can also be tracked through ParcelOutBoxError() and ParcelOutBoxErrorEx() calls.
The ParcelOutBoxArchive(), ParcelOutBoxArchiveEx(), ParcelInBoxArchive() and ParcelInBoxArchiveEx() are used to search for historical information.
ParcelUploadDirected() is used to send non-EDI data and requires the Sender and Receiver ECGridIDs to be used.
There are GZip variants that allow the data to be GZipped prior to uploading/downloading to reduce file size. I’m not sure anyone is using these, but they do work.
Q: Do we need to set mailbox per customer and set the Qualifier/ID per TT with this customer? (My understanding that we can either create MB per customer per TT with single ID or one MB with multiple IDs.)
A: Correct. My suggestion is as said, one mailbox per customer. If the customer has multiple IDs, then put them all in the same mailbox. There is one special mailbox on your network called Root – is is MailboxID := 0.
If you want to separate a customer’s data for reporting purpose, but route all the data to/from your Root mailbox (e.g. you are going to preprocess in the cloud, then forward to customer), then there is an API called MailboxManaged(). Setting Managed:=true means the data will go to the mailbox, setting Managed:=false means the data will go to Root.
Q: When we upload a document for a TT (810 in reply to 850)? do we need to create a mailbox for that or we load it to the same MB we created to get the 850 from the TT (issue not 100% clear for us)
A: Each Mailbox is for upload and download – so you would use the same mailbox for sending and receiving. So you would not set up a separate mailbox for each. One mailbox per ID, each ID is used to send and receive.
Q: Can we assumed that the MB/network ID are fixed after creation and will not changed?
A: NetworkIDs and MailboxIDs do not change. If a ISA ID (e.g. ZZ*TEST) is moved from one mailbox to another, it’s ECGridID will change as each ECGridID lives and dies in the mailbox it is originally assigned to.
Q: When provisioning a new customer mailbox, the following is an example work-flow:
A:
- Login() as a NetworkUser or NetworkAdmin
- MailboxAdd() Since this is for a new client, first create the Mailbox using the current user's UserID which you can get from WhoAmI(), save the returned MailboxID
- UserAdd() using the new MailboxID, save the returned UserID. Repeat if you have more than one user assigned to the Mailbox.
- Optionally assign the new user(s) with MailboxOwnerContact(), MailboxErrorsContact(), MailboxInterconnectsContact() and MailboxNoticesContact().
Q: Why did it automatically add the sender in my file as a trading partner?
A: The system receives "unknown" IDs from the VANs all the time, so it automatically registers them as "unknowns" but does register the ID. There is no name associated with them and they are suspect until confirmed.
Also, there is no guarantee that the data will go through due to all sorts of Interconnect requirements by the VANs.
Safer to always TPAdd() then InterconnectAdd() before sending data. However, we are working towards the day that this can all be automated by just sending data...
Q: Do I not need to set up a trading partner as long as a new QID is encountered in a file?
A: The problem is that this may generate an Interconnect Request to the other side, and if your ID is not labeled properly with your company name, there is a good chance that it will be rejected or delayed by the other side.
Overall, it is an automation we would like to see, but getting cooperation on the other end will be the biggest challenge.
Q: Does all in and outbound traffic happen in my mailbox, and I have to determine what is coming in to download?
A: All inbound and outbound happen in the same mailbox, but it is subdivided into In and Out. You can use the various ParcelInBox() functions to see what is pending and use ParcelDownload() selectively choose files to process in specific ways. In the class objects you can find trading partner and transaction information.
Q: Do I just have to push the response documents (855,865,810) to my mailbox via ParcelUpload? Do they delete automatically once they have been transferred?
A: Yes, just push the response using ParcelUpload(), they are then processed and there is no delete function; however, with ParcelDownload() you do need to run ParcelDownloadConfirm() to remove them from the active queue.
Q: Starting with v3.1.113 - 3/11/2014, you no longer should use Login() to create a SessionID and Logout() to end your session.
A: Now when a new User is created, an APIKey is generated which can be substituted for the SessionID in all API calls for that user.
To expire that APIKey and create a new one, use the GenerateAPIKey() API.
Keep your APIKeys safe as they have all access to ECGridOS for that user.
Getting Started
- Getting Started - Basics
- Getting Started - Extended Capabilities
- HTTP Connections
- Visual Studio SOAP Connections
- About ECGridOS and Loren Data Corp.
- Documentation & Nomenclature
- Using Web Services
- Networks & Mailboxes
- Users & Authorization Levels
- API Keys & Sessions
- Trading Partners & ECGridIDs
- Interconnects
- Parcels, Interchanges & Mailbags
- Carbon Copies
ECGridOS API Calls
- API Calls - Full Definitions Available
- Asynchronous API Calls - Events
- Asynchronous API Calls - Task\Async\Await