Create code for daily operations

Now that the properties are mapped, you need to create custom code for daily operations.

Your code should do the following:

  1. If using External SystemsLink, use the GetToken [SystemsLinkUserName] [SystemsLinkPassword] method.

  2. Retrieve orders.

  3. Update orders.

  4. Set updatable properties to true so that values remain set.

  5. Use SaveOrder or another similar method.

    Note: The updateDB parameter must be set to true when executing save methods. Otherwise the information will not save in the database.

  6. If using External SystemsLink, use the method ReleaseToken [tokenValue].

  1. You control what data to retrieve and how often. You also control what to update and how often. Business rules will help you determine what is appropriate.

  2. External SystemsLink users must use the tokenValue as the first parameter for all methods except GetToken.

Retrieve orders

The first step in using the API is to retrieve orders. Orders can be retrieved based on several criteria. If you are a third party connecting to External SystemsLink, you would need to pull orders that are assigned to you. For example, if you are a carrier, you would retrieve orders assigned to your carrier ID.

Here is the current documentation for the RetrieveOrder method used by External SystemsLink:

Parameters

Method Name

Name

Data type (in C#)

Order.ReturnObject.
ReturnCode

Description

RetrieveOrder

tokenValue

string

0 = successful

100 = no records found

1000 = errors occurred

Returns all Order objects that meet the specified criteria

criteria

Order.Criteria
If you are using Internal SystemsLink, you do not need a tokenValue as a parameter.

To use the RetrieveOrder method, you will also need to know information about the criteria you can use to pull the orders. Below is the current documentation for the Carrier property in the Criteria object.

Name Table.Column Data Type (in C#) Comments

Carrier

Legheader.lgh_carrier

String

Join legheader table

For example, to retrieve all orders assigned to a carrier, you would do the following:

  1. If using External SystemsLink, use the method GetToken [SystemsLinkUserName] [SystemsLinkPassword].

  2. Set Order.Carrier to the appropriate carrier ID.

    Note: Business rules should provide the appropriate carrier IDs.

  3. Use the RetrieveOrder method to retrieve all orders assigned to that carrier ID.

  4. If using External SystemsLink, use the method ReleaseToken [tokenValue].

Update an order

Once you have retrieved the appropriate orders, you will need to update orders as information changes. The main three areas to update are:

  • Order information

  • Stop information

  • Freight information

The Order object’s ability to access Stop properties allows it to also access Freight properties. Most updates can be done using the Order object. For more information, see Hierarchy of properties in the Order object.

Some information is easier to update than others. For example, updating the status of an order is complex. It depends on what is driving the change. Updating freight volume is simple. It only requires you to set the value for the Freight.Volume property.

To access Stop and Freight properties directly, use Stop.property and Freight.property. The order object uses properties Stops and Freights (plural) to access those objects' property lists.

Simple example: Change freight volume

The example below uses the SaveOrder method for the Order object to update freight. To reduce overhead, you could use the UpdateFreight method instead. The example below uses the SaveOrder method because in most situations you would update more than just the volume on an order. Using the SaveOrder method object allows you to update Order, Stop, and Freight information.

The steps below use the Order object to change the freight volume.

  1. If using External SystemsLink, use the method
    GetToken [SystemsLinkUserName] [SystemsLinkPassword] to get a token.

  2. Call the GetOrder method.

    Note: GetOrder retrieves a specific order. You must know the order header number to use the GetOrder method. The RetrieveOrder method retrieves multiple orders based on criteria.

  3. Find the stop in the Order.Stops collection.

  4. Set Order.Stops to be a variable that includes the stop number.

    Note: The first stop on an order is stop 0.

  5. Find the freight in the Stop.Freights collection.

  6. Set StopVariable.Freights to be a variable that includes the freight number.

    Note: The first freight on a stop is freight 0.

  7. Set FreightVariable.Volume to the appropriate value.

  8. Set the FreightVariable.UpdatableProperties.Volume to true.

    Note: It will not update the property unless the appropriate UpdatableProperties is set to true.

  9. Use the SaveOrder method to re-save the order to the database.

    Note: The updateDB parameter must be set to true when executing save methods. Otherwise the information will not save in the database.

  10. If using External SystemsLink, use the method ReleaseToken [tokenValue] to release the token.

Complex example: Change order status

The order status is often derived from other actions taken on the order. For example, you would not change the order status to completed (CMP) using the Order.Status property. Instead, you would update the last stop on the order to show as completed. Do this with the Stop.Completed property. When saving the order, the Order.Status automatically changes to CMP. To fully understand when and where to update, you need to know the lifecycle of an order within the applications.

Lifecycle of an order

In its simplest form, data for a typical order follows these steps.

image1

The table below defines the most common actions to take during the lifecycle of an order. It only includes Order Entry and Dispatch. Most customers will not use SystemsLink for Invoicing or Settlements. The table does not include steps that are the same for all.

  1. There are multiple ways of updating the information below. The table only outlines one approach for each action.

  2. If you are using External SystemsLink, you will need the tokenValue parameter for each method except GetMethod.

  3. DateTime information is stored in the format and time zone of the server that hosts the SystemsLink API.
Action Steps Resulting Status

Order entry

Note: Use if creating an order. Usually SystemsLink is just used to retrieve orders.

Use the method NewOrder or NewOrders.

Order status:

Multi-order job (JOB) or a single available order (AVL)

Resource assignment

Note: This is only performed through SystemsLink if the Trimble Transportation system needs to store that information. Carriers may not need to perform this step. Check your business rules.

  1. Update Stop.Driver1.

  2. Update Stop.Tractor.

  3. Update Stop.Trailer.

  4. Set all three UpdatableProperties to true.

Order status:

Planned order (PLN)

Order dispatched to driver.

System automatically dispatches information once the order is planned.

Order status:

Dispatched (DSP)

Driver arrived at first stop.

  1. Update Stop.ArrivalDate.

  2. Set the Stop.Arrived value to true.

  3. Set both the UpdatableProperties to true.

Order status:

Started (STP)

Driver completed last stop.

  1. Update Stop.DepartureDate on the last stop.

  2. Set the Stop.Completed value to true.

  3. Set both the UpdatableProperties to true.

Order status:

Completed (CMP)

Below are two less-common actions that you may need to perform.

Action Steps Resulting status

Cancel an order

Change Order.Status to CAN.

Order status:

Cancelled (CAN)

Un-cancel an order

Use the UncancelOrder method.

Order status:

Available (AVL)