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.

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"

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

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

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

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.