Agency Express Overview of File Structures and Data Synching
Purpose of this document
This document will provide an overview of the various file types used in Agency Express 3 with Ceres 5. It will explain what each file does, how it is generated, and how it cycles through the SyncV50 directory. Some optional auto-synch options are also explained.
Ceres Object release 6.00.00 is required for the functionality described in this document.
TABLE OF CONTENTS
AE3 Auto-Synch Options
A nightly synchronization of the Agencies and Shoppers & Items and Qualifiers is available, if desired. This option can be set up to run every day at a specified time. In addition you may select which components of the data you wish to have synchronized.
AE3 Auto-Synch Options can be accessed by selecting “Search” from the Dynamics 365 Business Central Banner and entering “AE3 Auto-Synch Options” in “Tell me what you want to do” then selecting “AE3 Auto-Synch Options” from the results in the Go to Pages and Tasks section OR by selecting the “AE3 Auto-Synch Options” menu action (if present) from your Role Center home page.
Coordination with Techbridge and/or your Ceres Solution provider is also necessary to set up this optional process.
The following screen is displayed. Toggle on the boxes for each type of record that will be affected by the auto-synch process. Auto-synchronization will not occur if the fields (Item & Qualifiers, Agencies, and Shoppers) are left blank.
Item & Qualifiers: Toggle on this box if Items and Qualifiers should be re-sent every day. This also includes item availability and item fees.
Agencies: Toggle on this box if Agencies should be re-sent every day.
Shoppers: Toggle on this box if Shoppers should be re-sent every day.
Last Auto-Synch Date: This field is updated automatically by Ceres and will reflect the last time the auto-synch process was executed.
Auto-Synch Scheduled Time: Enter the time of the day that you wish to have the auto-synch process begin each day. It is recommended that this is run after work hours, and that you confirm the time availability with [email protected] prior to executing this routine.
The “SyncV” Directory
The following screenshots depict the SyncV50 directory. The setup of this folder is universal for all food banks using Agency Express 3.0 with Ceres 5. For food banks using Agency Express 3.0 with Ceres 6 the directory would be named SyncV60.
The file types in each folder are described here:
Outbound Files
Org Files
Org files (also known as organizational files) are created as the result of updates to organizational entities such as agencies and shoppers. Org files are created by Ceres and immediately placed in the SyncV50\Out\Org folder. Once the TechbridgeFTP.exe has run to transmit the data to Agency Express, the file is removed from SyncV50\Out\Org and placed in SyncV50\Backup\Org.
ORAC: Parent Agency create/update file. This file is generated anytime an agency is updated or created.
ORPC: Agency create/update file. In previous versions of Ceres, this file was generated anytime a program was created or updated. Because programs do not exist in Ceres, this file is now sent when an agency record is created or updated. Though Ceres still labels it as an ORPC file, it’s basically an ORAC file from a Ceres perspective. Techbridge requires an ORPC file for Agency/Shopper activates because they support multiple releases of Ceres.
ORSC: Shopper create/update file. This file is generated anytime a shopper is updated or created.
Note: Ceres will attempt to combine ORAC/ORPC/ORSC information when it can. For example, if there are web queue entries for agency updates as well as shopper updates, Ceres will not create two separate files (i.e. an ORAC and an ORSC) rather it will simply create one file with the agency and shopper information in it. As a general rule of thumb, if two or more organizational entities need to be updated, Ceres will write the file relating to the highest level of Org data. In this example, because a shopper and an agency are being updated, Ceres wrote the ORAC file with the shopper information in it. If just a shopper needed to be updated, Ceres would just create an ORSC file.
Here is a sample ORSC file (note that this is just a sample, the actual file is much longer).
Catalog Files
Catalog files are created as the result of updates to item related information. Catalog files are created by Ceres and immediately placed in the Syncv50\Out\Catalog folder. Once the TechbridgeFTP.exe has run to transmit the data to Agency Express, the file is removed from Syncv50\Out\Catalog and placed in Syncv50\Backup\Catalog.
ITI: Item-agency information exchange. These files link information from agencies to items, such as Fee Group Code, Agency Group Code, etc. This file is also used for shopper updates. The ORSC file also handles shopper, but Techbridge only processes it once to handle the shopper create. Subsequent updates to shopper info (i.e. e-mail address, name, etc.) are all handled by the ITI version of the update. Activating/deactivating a shopper for web ordering is also handled through the ITI file.
Below is a sample ITI file:
ITQ: Item Availability - Transmits item availability information based on Agency Group Code.
Here is a sample ITQ file. Note that this is not a true .XML file, it is actually a .CSV (comma separated) file. The comma separated field values are as follows: Item No., Agency Group Code, and Available Quantity for that Group. A ‘D’ in the Quantity column indicates that zero available quantity is sent to AE for that Item and Agency Group.
Note: Due to the large number of item availability transaction files, they are not sent to the backup directory upon successful transmission. Instead they are retained in the original folder for a period of 24 hours and subsequently deleted.
ITM: Item Master. Transmits critical information found on the item card to Agency Express.
Below is a sample ITM file:
ITF: Item Fees. This file transmits item fee information if you are using Agency Fees functionality in Ceres.
Here is a sample ITF file. Note that this is not a true .XML file, it is actually a .CSV (comma separated) file. The comma separated field values are as follows: Agency Fee Group Code, Item No., Unit Fee.
ISD: Delivery Fees. Transmits delivery fee information.
Here is a sample ISD file. Note that this is not a true .XML file, it is actually a .CSV (comma separated) file. The comma separated field values are as follows: Delivery Zone Code, Type, Tier Pounds, Rate, and Unique Record Identifier. The Unique Record Identifier is used by Techbridge only and is generated in Ceres based upon the UNC FB ID and a Line No. which increments by 10000 for every record.
Outbound Schedule Files
Sched files (also known as schedule files) are created as the result of updates to Agency scheduling information. Sched files are created by Ceres and immediately placed in the SyncV50\Out\Sched folder. Once the TechbridgeFTP.exe has run and the files are transmitted to Agency Express, the file is removed from Syncv50\Out\Sched and placed in Syncv50\Backup\Sched.
ISM: Schedule Master. Transmits master calendar data to Agency Express.
Below is a sample ISM file:
ISQ: Appointment. Transmits appointment information to Agency Express.
Here is a sample ISQ file. Note that this is not a true .XML file, it is actually a .CSV (comma separated) file. The comma separated field values are as follows: Agency Express Entry No., UNC FB ID + Agency No., Order No. The Agency Express Entry No. is used only by Techbridge and is derived from the Appointment Line table. It links the appointment from this file to an Appointment Line in Ceres. If a record in the file represents a standing appointment, then the Order No. column will be blank. If a record represents a scheduled appointment, the Order No. column will show the order the appointment is associated with.
Outbound Transaction Files
Outbound Trans files (also known as transaction files) are created as the result of Agency Order activity in Ceres. Trans files created by Ceres are immediately placed in the Syncv50\Out\Trans folder. Once the TechbridgeFTP.exe has run and the files have been transmitted to Agency Express, the file is removed from Syncv50\Out\Trans and placed in Syncv50\Backup\Trans.
PO: Purchase Order. An outbound PO file represents a non-web order that has been created for an agency/shopper permitted for ordering on the web (“Permit Web Orders” = Yes). This type of PO file is generated when an agency order is picked.
PA: Purchase Acceptance. Depending upon the “Send ASN” setting in Agencies & Receivables Setup, this file will be created when an order is 1) Accepted, 2) Processed, or 3) Released for Pick. This indicates acceptance by the food bank and causes the Agency Express order status to update accordingly in Order Management online.
PR: There are two scenarios which result in the generation of a PR file. 1) A PR file is generated once an order is set to Foodbank Only Processing if you allow editing of web orders. Upon transmission to Agency Express, Order Management will be updated with a status of Released and the order will no longer be editable online. 2) A PR file is also generated when an order is rejected in Ceres. Upon transmission to Agency Express, Order Management will be updated with a status of Rejected and the order will no longer be editable online.
PI: Purchase Invoice. Notifies Agency Express that the order has been invoiced in Ceres.
On the next page is a sample PO/PA/PR/PI file. The format is actually the same for all files, the primary difference being the Status field which controls what the order does online.
Order statuses work as follows:
File Type Status Description
PO ORD Regular, non-web order
PO ALC Allocated order
PA ACK Accepted web order
PR REL Released web order
PR REJ Rejected web order
PI INV Invoiced web order
Note: All allocated orders start out as non-web orders. If a user decides to transmit an allocated order to the web, it goes up with a non-web status (ALC). When it is accepted by the shopper online, it becomes a web order in Ceres and is treated as such for the life of the order.
In the following examples, we are looking at a PA file, specifically, as noted by the Status of ACK and a PI file, noted by the Status of INV:
Inbound Files
Catalog Files
The only inbound catalog file is the ITS file. When this file arrives from Techbridge, it is immediately placed in the Syncv50\In\Catalog folder. Once Ceres executes its Inbox Processing routines, the file is permanently removed from the Syncv50 directory.
ITS: Semaphore. This is an Agency Express response file. It alerts Ceres that it is okay transmit additional Item Availability information via the ITQ file. No information is actually contained in the ITS file. This file is only in use if the FTP script is set to use the ITS (determined during FTP Setup).
Here is what the ITS file looks like in the Syncv50 directory (it is displayed as ITS_xxxx (where xxxx is your four digit (including zero’s) Food Bank ID number):
Inbound Schedule Files
The only inbound Sched file is the ISQ file. When the file arrives from Techbridge, it is immediately placed in the Syncv50\In\Sched folder. Once Ceres executes its Inbox Processing routines, the file is removed from Syncv50\In\Sched and placed in Syncv50\Backup\Sched
ISQ: Appointment updates from the web. This file is received when a shopper pre-reserves an appointment online (if the Pre-reservation Schedule model was selected). The inbound version of the ISQ file is exactly the same as the outbound version of the file. Here is an example. Please refer to outbound ISQ files for structure information.
Inbound Transaction Files
Inbound Trans files (also known as transaction files) are created as the result of Agency Order activity on Agency Express. Trans files created on Agency Express are imported and placed in the Syncv50\In\Trans folder. Once Ceres executes its Inbox Processing routines, the file is removed from Syncv50\In\Trans and placed in Syncv50\Backup\Trans. Subsequent submissions of the order from Agency Express will be incremented with and underscore and revision # (_#) when stored in the Syncv50\Backup\Trans directory. This will provide an audit trail of the order’s history from Agency Express.
PO: Purchase order. This is an Agency web order placed online. The inbound version of this file is the same as an outbound PO file except the Status field is blank. Please refer to the section on outbound PO files for an example.
Was this article helpful?
That’s Great!
Thank you for your feedback
Sorry! We couldn't be helpful
Thank you for your feedback
Feedback sent
We appreciate your effort and will try to fix the article