What you need to know before using SystemsLink

SystemsLink is a Windows Communication Foundation (WCF) application deployed on a customer’s web server. It is recommended to use SOAP to communicate. When two separate web services communicate, Internal SystemsLink allows data transfer to and from the database. External SystemsLink invokes security measures that allow or deny a third party to communicate with Internal SystemsLink. Some methods are restricted from use by External SystemsLink. If you are a third party, when given the option, follow instructions for external use. All parties should follow instructions that are marked as neither internal nor external.

SystemsLink creates usable objects, properties, and methods for retrieving and updating information that originated in a database. Developers use this information to create custom code that maps SystemsLink properties to another database. He or she will also create logic to retrieve and update information.

The overall process is as follows:

  1. Install SystemsLink.

  2. Test the connection.

  3. Map SystemsLink properties to another database.

  4. Translate proprietary terms and abbreviations.

  5. Create logic for data retrieval and update.

You decide the information you want to retrieve and how often to retrieve or update it.

The illustration below shows the basic architecture for communication from other systems to the database.

SystemsLinkOverview

External SystemsLink: Security implementation

First available V.15.1.0

External SystemsLink uses validation tokens to protect service calls made to SystemsLink. These tokens maintain credentials. This allows customers to expose the web service for external use without risk. Best practice is for third parties to retrieve a new token for each session. They should release the token at the end of the session.

Prerequisites for using External SystemsLink

Take steps at both ends of the pipe to ensure External SystemsLink works properly. The steps below provide a high-level look at what each party must do.

These steps apply to both fuel and non-fuel customers.

Location: Web server housing External SystemsLink

  1. Install SystemsLink following the instructions.

  2. Create External SystemsLink user accounts.

  3. Configure the web server to allow external access.

  4. Write business rules.

  5. Provide the following to the third party needing access to SystemsLink:

    • External SystemsLink user name and password

    • Endpoint for External SystemsLink

    • Order header number for testing

    • Business rules

    • Documentation

Location: Third-party web server connecting to External SystemsLink

The third party performs these steps.

  1. Gather the mapping information for the database used by your application.

  2. Review the following information:

    • External SystemsLink username and password

    • Endpoint for External SystemsLink

    • Order header number for testing

    • Business rules

    • Documentation

  3. Verify that web-server firewalls, ports, etc., are configured to allow access to the endpoint. One way to test is to use the following format:

    http://ServerName/NameSpaceForSystemsLink/EndPoint.svc

  4. Test your connection to External SystemsLink by calling the following methods.
    Methods are documented in the form: Method [parameter1] [parameter2].

    • GetToken [SystemsLinkUserName] [SystemsLinkPassword]

    • TestConnection [tokenValue]

    • GetOrder [tokenValue] [orderHeaderNumber]

    • ReleaseToken [tokenValue]

    Notes:

    1. It is recommended to use SOAP for communication.

    2. A return code of 0 means the method was successful. Any other return code means an error occurred. For more information see Error handling.

    3. Use the mapping information for the application database to map SystemsLink properties to your database.

      Note: The SystemsLink Reference guide contains information on each property that can be mapped to your database.

    4. Use business rules and the SystemsLink Reference guide to create custom code for data retrieval and update.

How to map user-defined properties

Some SystemsLink properties map to user-definable fields that are stored in the database. These fields are not all stored in the same database table. The table below shows revenue types stored in the orderheader table. Revenue types are user-definable. Business rules determine the type of information stored by each user-definable field. For example, Order.RevType1 could store terminal locations. If that is the case, updating the Order.RevType1 property would change the terminal selected for an order. It would not change the list of terminals that can be selected.

Property Trimble Transportation Database

Object.Property

Data Type (in C#)

Table.Column

Data Type

Modifiable

1

Order.RevType1

string

orderheader.ord_revtype1

varchar(6)

Insert/Update

2

Order.RevType2

string

orderheader.ord_revtype2

varchar(6)

Insert/Update

3

Order.RevType3

string

orderheader.ord_revtype3

varchar(6)

Insert/Update

4

Order.RevType4

string

orderheader.ord_revtype4

varchar(6)

Insert/Update

In the example above, to change the list of terminal that can be selected, use the LabelFile object.

The LabelFile object contains properties that map information about the field’s display name, its rank in drop-down menus, etc. The LabelFile object does not actually map to where the data entered for that field is stored. The data is located in the table associated with where the information is accessed within an application.

The list of terminals is user-defined. That information is stored in the labelfile table within a database. Below is an example of how terminal information may be stored.

image3

Here are the corresponding SystemsLink properties:

Property Trimble Transportation Database

Object.Property

Data Type (in C#)

Table.Column

Data Type

Modifiable

1

LabelFile.Abbr

string

labelfile.abbr

varchar(6)

Insert/Update

2

LabelFile.Code

int

labelfile.code

int

Insert/Update

3

LabelFile.LabelDefinition

string

labelfile.labeldefinition

varchar(20)

Insert/Update

4

LabelFile.Name

string

labelfile.name

varchar(20)

Insert/Update

5

LabelFile.UserLabelName

string

labelfile.userlabelname

varchar(20)

Insert/Update
External, third parties do not need to update label files. They need to know that, in this case, RevType1 corresponds to the terminal selected for an order. This should be clearly stated in the business rules. In this example, you would map the Order.RevType1 property to the table and column that stores terminal information for your application.

Terminology

As with any business, your company has its own "language." Applications are often customized to use the unique terms of the customer using the software. However, Trimble Transportation applications come with a few unique terms. To understand how the system works, you need to know how we use these terms:

  • Stop

  • Event

  • Order

  • Movement

  • Trip segment

What is a stop?

A stop occurs at a particular place during a driver’s route. A stop is defined by:

  • A physical location

  • An activity, called an "event"

  • The date and time of the event

Some stops are determined by a customer’s order; others are not. For example, suppose a customer wants cargo moved from company B to company C. To complete the order, the driver makes a trip that consists of these four stops:

Stop 1: Driver deadheads from his current location at company A.

Stop 2: Driver arrives at company B, the pickup location recorded on the customer’s order.

Stop 3: Driver refuels at Fuel Stop 1, as directed by his dispatcher.

Stop 4: Driver arrives at company C, the order destination.

Since Stops 1 and 3 were not specified by the customer, they are not associated with the order. As a result, the customer will not be billed for them. Stops 2 and 4 are billable because the customer requested the pickup and delivery.

In the trip described above, not all stops are associated with the order; however, all of them are part of the same movement.

What is an event?

An event is an activity that occurs at a stop location. Multiple events may occur at the same stop.

There are two types of events:

  • A primary event must occur in order for a trip to be completed. For example, if cargo must be moved from point A to point B, the trip consists of at least two primary events: a pickup and a delivery. A pickup is called a "load"; a delivery is called an "unload".

  • A secondary event is an ancillary activity that is to be performed in addition to the primary event. A driver check call and a post unload are examples of secondary events.

  • An event code is used to identify a type of activity that is to occur at a stop location. These codes are used by the system to determine:

  • Whether miles between the current stop and the previous stop are to be considered loaded miles or empty miles.

  • Whether the stop is billable to the customer and/or payable to the driver.

What is an order?

An order is a customer request for the movement of goods or materials. Such a request must be recorded before resources (i.e., driver(s), tractor/trailer/carrier) can be dispatched to move the load. Each order is assigned a unique ID number, called the order header number.

What is a movement?

A movement is the record of all of the activities performed by the resources (driver, tractor, trailer, carrier) assigned to execute a trip. A unique, system-assigned ID number is associated automatically with a movement at the time it is recorded in an application. This number can be considered the "blanket ID" for all activities that occur during a trip.

The SystemsLink property Order.MoveNumber is required for update.

What is a trip segment?

A trip segment is the portion of a movement that is executed by the same driver and tractor. Each time a new driver and/or tractor is assigned to a movement, a new segment is created. A system-assigned ID is associated automatically with each trip segment. When a driver’s settlement for a trip is prepared, he will be paid for the activities that he performed during his segment of the trip.

  1. Trip segments are also called legs or legheaders.

  2. A movement consisting of multiple trip segments is called a split trip.