Know before you code
Here are facts you will need to know:
-
Each object can be used without the others.
-
Some objects can be used within other objects.
For example, the Stop object contains the property EarliestDate. There are two ways to use the property:
-
Use the Stop object (Stop.EarliestDate).
-
Use the Order object by defining a variable for the property Order.Stops, and then using the variable.EarliestDate.
-
-
Most updates can be done with the Order object because of its ability to access other objects.
For example, the Order object contains a Stops and a Notes property. These properties access the properties within the Stop object and the Note object.
The Reference Guide uses the following notation to show a list of properties in other objects:
Property Database Column Name
Data Type (in C#)
Name
Data Type
Modifiable
Comments
Stops
List<Stop>
Insert/ Update
Reference Stop Object in Stop table
The Stop hyperlink takes you to a list of properties in the Stop object. Similarly, the Stop object contains the property Freights, which accesses the properties in the Freight object.
. └── Order object ├── First property ├── Second property ├── ... ├── Stops property │ ├── First property │ ├── Second property │ ├── ... │ └── Freights property │ ├── First property │ ├── Second property │ ├── ... │ └── ReferenceNumbers property │ ├── First property │ ├── Second property │ └── ... └── Notes property ├── First property └── Second property
-
The properties required for updating a record are identified in the Reference Guide. See the comments for that property.
This is a sample table.
Property Database Column Name
Data Type (in C#)
Name
Data Type
Modifiable
Comments
MoveNumber
int
orderheader.mov_number
int
Read only
Required for update
Web Service Component Class definition
Each Component Class contains the following sub classes and properties:
These properties:
|
|
These properties identify the service properties that can be updated. Note: You must set UpdateableProperties to true to allow the service property to update. For example, to update the shipper on an order, you must:
An example of code written in VB.net: |
|
Criteria Class |
Identifies which properties can be used as criteria to retrieve records from the database |
Return Object Class |
All methods return an instance of the Return Object class. It contains the following properties:
|
Web Service method types
Most Service Components have the following types of methods.
| For more information on error return codes, see Error handling. |
New component
This method creates a component in memory, not in the database. It has the object’s default values.
Return Code:
-
0 = successful
-
1000 = errors occurred
New components
This method creates a list of components in memory (not in the database). The components in the list have the object’s default values.
Return Code:
-
0 = successful
-
1000 = errors occurred
Retrieve component
This method returns a list of components that meet the provided criteria. The returned component is stored within the Return Object. If a match cannot be found or the query results in an error, the default value is returned.
Return Code:
-
0 = successful
-
100 = no records found
-
1000 = errors occurred
Save component
This method creates new records for the passed-in components or updates existing ones in the database. The saved components are passed back in the Return Objects list.
Return Code:
-
0 = successful
-
100 = validation errors occurred and updates prevented
-
500 = update proceeded with warnings
-
1000 = error occurred and updates prevented
| If a passed-in object results in errors, its index is added to the Error Object Index List in the Return Object. |
To save a value in the database, both the service property being updated and the corresponding property in the Updateable Properties must be changed. The service property should be updated with the value that is to be saved to the database. The updateable property must be set to true.
In this example, a client is trying to save a driver’s last name to the database (Code in VB.net). If successful, the saved driver object is returned in the Reference Objects list in Return Object (retObj).
Dim svc As TMW_API_WCFServices.APIWCFServicesClient = Nothing
Dim retObj As TMW_API_WCFServices.Driver.ReturnObject = Nothing
Try
svc = New TMW_API_WCFServices.APIWCFServicesClient()
Dim retObj As TMW_API_WCFServices.Driver.ReturnObject = Nothing
Dim drvList As New List(Of TMW_API_WCFServices.Driver)
Dim drv As New SystemsLink.Driver()
drv.IsNew = True
drv.UpdateableProperties = New SystemsLink.Driver.DriverUpdateInfo()
drv.LastName = "MyLastName"
drv.UpdateableProperties.LastName = true
drvList.Add(drv)
retObj = svc.SaveDriver(drvList, True)
Dim drvSaved As TMW_API_WCFServices.Driver = retObject.ReferenceObjects(0)
Catch ex As Exception
Throw
Finally
'close svc after each call
If svc IsNot Nothing Then svc.Close()
End TryError handling
SystemsLink groups error codes into several ranges.
A code of zero (0) indicates successful completion. For example, the Save component documentation lists the following error codes:
Return Code:
-
0 = successful
-
100 = validation errors occurred and updates prevented
-
500 = update proceeded with warnings
-
1000 = error occurred and updates prevented
All other error codes are part of a range. The error code ranges are defined as:
-
100 to 499 are validation errors.
-
500 to 999 means the update occurred, but one or more warnings also occurred.
-
A code of 1000 or higher means that there was an error that prevented update.
| Make sure to include the entire range in your logic for error handling. |