TECSYS Integration
Integration Data Flows
TECSYS and TrackAbout have built a generic integration that is in use with all of our mutual customers. The picture below shows the information that flows from one system to the other.
Integration Mechanism
At a high level:
- TrackAbout hosts webservices that are called by TECSYS/Elite
- Queue timers in Elite kick off calls to these webservices
- These queue timers can be run on whatever schedule you want to set in Elite. It is typical for the timers to run twice a day or so.
- You can also use "Execute Now" in Elite to kick off the queue timers manually at any time
- The programs triggered by the queue to send data to TrackAbout only send changes since the last time the timer ran
- The webservices exchange XML based text files between Elite and TrackAbout
- The XML is Archived on your TECSYS/Elite server
- Pushing data from Elite to TrackAbout is a one step process. A single queue timer can for instance push up changes to items.
- Pulling Asset Balances and Rental Invoics into Elite is a two step process.
- First one queue timer pulls the information into a staging table (dms_stg_asset_bal for balances and dms_stg_sale_b for rental invoices)
- Then another timer moves the data from the staging table into the Elite tables
Queue timers
Queue timers are setup in TECSYS. They are used to run a specific program at a specific time.
For you techies: This is analogous to 'cron jobs' in the Unix world or 'scheduled tasks' in the Microsoft world.
The basic idea is that you create a program then you schedule it to run every so often with the queue timer. For example you might schedule a program to run every hour at :15 after the hour. Or you might schedule a program to run at noon and 2am every day. Or you might schedule a program to run weekly at 3pm on Sunday afternoons.
This is how the integration works between TECSYS and TrackAbout. Various queue timers are run in TECSYS which push data to TrackAbout or ask TrackAbout if there is any data for them to pull down. All of the configuration of the schedule of integration happens in TECSYS. There is nothing to setup in TrackAbout (beyond setting up a 'Webservice' user - which will be done for you by TECSYS implementation staff).
Where are the Queue Timers?
There are two ways to get to the queue timers. Both are done inside of TECSYS/Elite:
- Navigate to: Home > System Administration > Messaging System> Queue Timer Master
- - or -
- Use the Quick Launch resource box in the upper right hand side corner. Go to meta_md_timer
I only want to see the TrackAbout queue timers
To limit the page to just the TrackAbout queue timers, search for ~*trackabout* in the "Queue Timer Description" field.
Note:
- ~ = Make the query case insensitive
- * = Wildcard character. So for example *at* will match on cat, cats or atlas.
A list of the integration Queue Timers
Timer Name | Queue Timer Description | Documentation |
---|---|---|
dms_trackabout_receive_asset | DMS - Trackabout - Receive Asset Balances | Pulls cylinder balances from TrackAbout into a staging table Elite. The staging table is used to store data temporarily until a validation process is run with a subsequent timer - In this case dms_trackabout_xfer_asset. |
dms_trackabout_receive_invoice | DMS - Trackabout - Receive Rental Invoices | Pulls rental invoices from TrackAbout into Elite. The staging table is used to store data temporarily until a validation process is run with a subsequent timer - In this case dms_trackabout_xfer_invoice. |
dms_trackabout_send_customer | DMS - TrackAbout - Send Customer Details | Sends all customer and ship-to information from Elite to TrackAbout. NOTE: All customers' Tax Region codes must be entered into TrackAbout before processing the Customer file or the entire file will fail. |
dms_trackabout_send_invoice | DMS - TrackAbout - Send Invoice Details | Sends all invoice adjustments to TrackAbout that involved cylinders. |
dms_trackabout_send_item | DMS - TrackAbout - Send Item Details | Sends all item information (Assets & Leases) from Elite to TrackAbout. This sends any items that were created or modified since this timer last ran. |
dms_trackabout_send_shipment | DMS - TrackAbout - Send Shipment Details | Send PPS information from Elite to TrackAbout. This sends any PPS that were created or modified since this timer last ran. |
dms_trackabout_send_tax | DMS - TrackAbout - Send Tax Details | Sends tax information from Elite to TrackAbout. This sends any tax region that were created or modified since this timer last ran. |
dms_trackabout_send_validation | DMS - TrackAbout - Send All Shipments From the Past 60 Days for Audit Purposes | This is currently under contruction - Will be used to run a data comparison between what was previously sent from Elite to TrackAbout |
dms_trackabout_xfer_asset | DMS TrackAbout Interface - Transfer stg_asset_bal to asset_bal | This timer transfers asset balances from the staging table to the final asset balance table in Elite. |
dms_trackabout_xfer_invoice | DMS - Transfer stg_sale_b to sale_b | This timer transfers rental invoices from the staging table to the final table in Elite (A/R Memo with Origin = 2 - External Application) |
Running a Queue Timer Manually
To run a queue timer manually, click on the downward facing arrow the the left of the queue timer. Click this "Execute Now" option in the list of action choices.
After you have run the "Execute Now" you should see this message "Queue: Successfully created"
How can I tell if the files were sent to TrackAbout?
Here are a couple of ways to check to see if the integration worked.
- 1) Check for errors. If you didn't get any errors then it probably worked.
- 2) Check to see if Elite archived the xml files it sent to TrackAbout.
- Go to the xmlFileOut directory on the EliteSeries application server.
- Sort the files by last modified date to find the one most recently created.
- New files end in ".xml"
- Once the sending is a success the extension is changed to ".xml.sent"
Queue Timer Errors - Troubleshooting
If one of the queue timers has not run in a while, it may be in error. A queue timer is put into an error state when it receives an error message from TrackAbout. There are many reasons that could cause an error. Some of these reasons are temporary. A good first trouble-shooting step is to take the queue out of error and let it run again normally. This may fix the issue.
To take a queue out of error: In Elite, go to "DMS Queue Message" with the following criteria.
Then change the "Is Error" status from Yes to No.
Resending All Data
Every time a queue timer runs it stores the last run date as an Attribute Value in Elite. The queue timers that send data from TECSYS to Trackabout only send info that has changed since the last time the queue timer ran. So for example the queue timer does not send every item to TrackAbout every time the queue timer runs. Instead it only sends items added or changed since the last time the queue timer ran.
Sometimes there will be an error or some testing or other reason that requires resending all of the info from TECSYS to TrackAbout. This is only common during the go-live and initial configuration of the systems.
To do this: Delete the queue attribute with the last time the file out queue was executed. In the Queue Master - Attribute view, you will see attributes the dms_xml_file_out queue as shown in the example below. Deleting the queue attribute for the view in question will cause it to resend all info the next time the queue is run.
How to See What Data is Transferred
Below are 3 ways to see what information is sent between TrackAbout and TECSYS:
- The "Views" in Elite
- The specification from TrackAbout
- Archived XML files created as the integration runs.
Elite Integration Views
TECSYS/Elite uses views to create the XML text files that are used for integration. These views can be altered like other Views in Elite, but this should only be done by TECSYS staff as it require coordination with TrackAbout so that TrackAbout expects the changes.
- "File Out" views
- Customers: dms_customer.trackabout
- Ship-Tos: dms_cust_shp.trackabout
- Tax: dms_tax.trackabout
- Items: dms_item.trackabout
- Shipments: dms_ship.trackabout, dms_ship_l.trackabout
- Invoiced Shipments: dms_inv_shp.trackabout, dms_inv_shp_l.trackabout
- "File In" views
- Asset Balances: dms_stg_asset_bal
- Rental Invoices: dms_stg_sale_b
TrackAbout Integration Specifications
The specifications for the integration are listed below. This is useful if you want to see exactly which fields are sent between TrackAbout and TECSYS.
Note that you can change the version (v=#.#.#) in the URL to see the specification for different versions of the interfaces.
- All data from TECSYS to TrackAbout is sent in this one interface:
- Asset Balances from TrackAbout to TECSYS
- Rental Invoices from TrackAbout to TECSYS
Integration File Archive
The XML files exchanged with TrackAbout are archived on your TECSYS/Elite server.
- By default they reside in the JBoss app server’s EAR directory
- Under the "data/xmlFileIn" subdirectory for import XML files
- Under the "data/xmlFileOut" subdirectory for export XML files
Create a Samba share in order that you may access these subdirectories from Windows
What Rental Data is Sent Back to Elite?
After you complete a rental run and print the bills, the final step is to send the rental numbers to Elite.
When we do this we can send a different code (Called the Accounting Code in TrackAbout) to Elite for each of these things:
- Each Rental Class
- Each Flat Fee
- Each type of Asset Agreement (these are your leases)
- A special code to use if we add a charge to make the bill equal to the minimum billable amount.
- A special code to use if we rolled forward any charges from a previous month that was below the minimum billable amount
These accounting codes are created as Add Charges in Elite.
For example: You might use "TACR" to stand for TrackAbout Cylinder Rental and use that for most of your rental classes. You might then also use "TAHZ" for a Flat Fee that is used for a Hazmat Charge. Then in Elite you can report on the cylinder rental and hazmat charge revenue separately.
Setting Customer Addresses
This is how addresses are set on customers for use on rental bills:
- For top level customer:
- Bill-to address and ship-to address are the same
- For the child department (ship-to)
- The bill-to is the address from the parent account
- The ship-to is the address of the department
Example:
Here is some raw data from Elite:
<DmsCustomerMasterTrackaboutInterface> <Customer>123456</Customer> <Name>ABC School Dist</Name> <Chargeto>55555</Chargeto> <Address1>100 Main St</Address1> ... </DmsCustomerMasterTrackaboutInterface>
<DmsCustomerShipToMasterTrackaboutInterface> <Customer>123456</Customer> <ShipTo>001</ShipTo> <Name>Maintenance Room</Name> <Address1>333 State St</Address1> ... </DmsCustomerShipToMasterTrackaboutInterface>
Parent Customer: 123456
- BillTo Address = 100 Main St
- ShipTo Address = 100 Main St
Child Department/Ship-to: 123456+001
- BillTo Address = 100 Main St
- ShipTo Address = 333 State St
Note that the "ChargeTo" field is not used at all by TrackAbout today.
How are Asset Balances Managed
- Asset balances are managed in TrackAbout. TrackAbout is the master system for asset balances.
- When the queue timers runs, TrackAbout sends all of the asset balances to Elite. (This is normally done nightly, but could be done as often as the queue timers run
- Elite process the TrackAbout file one row at a time and updates the customers balance table with the data from TrackAbout.
- Elite does not drop the table of balances and refresh it from TrackAbout each time it pulls in balances. Instead it updates the rows one at a time. This meas that if TrackAbout stops sending a balance for a given Bill-To/Ship-To/Item combo it is possible for the Elite data to become stale
- TrackAbout is supposed to remember every Bill-To/Ship-To/Item that was ever sent to Elite and continue to send down a zero balance for for any customer that no longer has a balance
- TrackAbout technical note. This data is stored in the HolderAssetTypesDelivered table which is updated by the asp_HolderAssetTypesDelivered_RefreshData stored procedure.
- If for some reason the balances fall out of sync, one way to fix them is to go into Elite and:
- Delete all records from dms_stg_asset_bal
- Delete all records from dms_asset_bal in
- This will flush the balances from Elite. The TrackAbout timers will rebuild the balances the next time the asset balance queue times run. You should probably manually run the queue timers so that the asset balances are not empty in Elite.
TECSYS Configuration
Configuration parameters are in a file named
Tecsys.Properties
somewhere on the TECSYS server. The location has moved with different versions, so search the server filesystem to find the true location.
Here are some of the configurations setup in TECSYS for the integration.
These should normally only be edited by TECSYS staff.
Messaging:
- msg.admin.email – The email to send a message to whenever an error occurs
- msg.admin.email.interval – The interval in minutes between email messages sent
TrackAbout connectivity parameters:
- dms.trackabout.interface.inbound_url
- dms.trackabout.interface.inbound_argument
- dms.trackabout.interface.outbound_url
- dms.trackabout.interface.username
- dms.trackabout.interface.password
- dms.trackabout.interface.enforce_valid_cert
Web service Urls
Following are the base urls in the TrackAbout environment for calling the web services. Additional parameters can be added to the utl to specify the version, compression options, etc.
Web Service | Production | Test |
---|---|---|
Inbound Data to TrackAbout | https://www.trackabout.com/ws/EliteSeries.asmx
Addtional info at: https://www.trackabout.com/ws/EliteSeries.asmx?meta |
https://test.trackabout.com/ws/EliteSeries.asmx
Addtional info at: https://test.trackabout.com/ws/EliteSeries.asmx?meta |
Asset Balance Export to EliteSeries | https://www.trackabout.com/ws/EliteSeries/AssetBalances.asmx
Addtional info at: https://www.trackabout.com/ws/EliteSeries/AssetBalances.asmx?meta |
https://test.trackabout.com/ws/EliteSeries/AssetBalances.asmx
Addtional info at: https://test.trackabout.com/ws/EliteSeries/AssetBalances.asmx?meta |
Rental Data Export to EliteSeries | https://www.trackabout.com/ws/EliteSeries/RentalInvoices.asmx
Addtional info at: https://www.trackabout.com/ws/EliteSeries/RentalInvoices.asmx?meta |
https://www.trackabout.com/ws/EliteSeries/RentalInvoices.asmx
Addtional info at: https://www.trackabout.com/ws/EliteSeries/RentalInvoices.asmx?meta |
Line Item Asset Transaction Types:
Elite Series sends an Asset Transaction Type for each line item when sending PPS information to TrackAbout. The following chart describes the different values for this field and how they are handled in TrackAbout.
Asset Transaction Type | Description |
---|---|
1 | Non asset transactions. Lines with this transaction type are ignored by Trackabout. |
2 | New Asset Rental. TrackAbout may create or update PPS information based on this data. |
3 | New Asset Lease: TrackAbout may create or update PPS information based on this data. |
4 | Asset Sale. TrackAbout will create or update Customer Owned Offsets based on this data. (Only should be used if Offsets are NOT created by Customer Owned leases). |
5 | Leased Asset Return. TrackAbout may create or update PPS information based on this data. |
6 | Rental Exchange. TrackAbout may create or update PPS information based on this data. |
7 | Owner Exchange. TrackAbout may create or update PPS information based on this data. Additionally, TrackAbout will create or update Customer Owned Offsets. |
8 | TrackAbout may create or update PPS information based on this data. |
9 | Cylinder Adjustments. TrackAbout may create or update PPS information based on this data. |
Some Specific Issues
Invoice Numbers
The TrackAbout Rental Invoice numbers must be lower than the range of invoice numbers that Elite is using for invoices.
Bill-to and Ship-to numbers
Today we're setup in TrackAbout like this:
- Bill-to: 007780 (We call this the "Parent")
- Ship-to: 0077801 (We call this the "Department")
TrackAbout requires that all bill-to and ship-to numbers be unique.
TECSYS is fundamentally setup like this:
- Bill-to: 007780
- Ship-to: 1
TECSYS requires that all bill-to customers be unique and that the ship-to numbers within a bill-to are unique. So many bill-to's can all have the same ship-to number. For instance many bill-to's can have a ship-to of "1".
To ensure that we don't have any problems in our integration, we will setup our TrackAbout numbers to have a Ship-to number that includes the TECSYS Bill-to number then a plus sign (+) then the TECSYS Ship-to number. This guarantees that all ship-to numbers are unique in TrackAbout. So the format is like this:
- TECSYS
- Bill-to: A
- Ship-to: B
- TECSYS
- Trackbout:
- Bill-to: A
- Ship-to: A+B
- Trackbout:
So if you wanted to keep the longer ship-to numbers in Elite for ease of training/conversion for your users then we'd set them up like this (This is what we've done at our other TECSYS/TrackAbout customers)
- TECSYS
- Bill-to: 007780
- Ship-to: 0077801
- TECSYS
- TrackAbout
- Bill-to: 007780
- Ship-to: 007780+0077801
- TrackAbout
Or if you wanted to switch to using short ship-to numbers in Elite you could do it like this:
- TECSYS
- Bill-to: 007780
- Ship-to: 1
- TECSYS
- TrackAbout
- Bill-to: 007780
- Ship-to: 007780+1
- TrackAbout
So one of the steps in your conversion to TECSYS is for us to convert your Bill-To (Department) numbers in TrackAbout to the new format.