TECSYS Integration

<< Back to Rental Module

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:

1. The "Views" in Elite
2. The specification from TrackAbout
3. 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:
  • https://www.trackabout.com/ws/EliteSeries.asmx?Meta&v=2.0.0

• Asset Balances from TrackAbout to TECSYS
  • https://www.trackabout.com/ws/EliteSeries/AssetBalances.asmx?Meta&v=2.1.0

• Rental Invoices from TrackAbout to TECSYS
  • https://www.trackabout.com/ws/EliteSeries/RentalInvoices.asmx?Meta&v=1.1.0

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

Trackbout:

Bill-to: A

Ship-to: A+B

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

TrackAbout

Bill-to: 007780

Ship-to: 007780+0077801

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

TrackAbout

Bill-to: 007780

Ship-to: 007780+1

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.