TcoreTypes Schema


This schema defines a set of standard type definitions for general use by other DAT Services/Transcore schema. It should normally be included in all other DAT schema to avoid multiple definitions or potential namespace conflicts.

Interface Overview


The majority of requests and responses supported by this system follow one of a series of general patterns. This overview briefly describes these patterns as well as the overall structure of requests and responses.

Requests
This interface supports a request/response protocol. Users of the interface construct requests and submit them to the system. The system processes the request, generates a response, and delivers the response to the requestor.

All requests follow a standard naming pattern, the request names are constructed by concatenating the type of request [create, update, cancel, lookup], the item affected by the request [alarm, asset, company, user, etc...], and appending the word 'Request'. So, the name of a request to create a new alarm is createAlarmRequest and the name of a request to update an existing company is updateCompanyRequest.

Each request contains one or more operations. The operations contain the information specific to the request. Operations are named in a similar way to the requests, with the word Operation appended instead of Request. So, the operation associated with a createAlarmRequest is the createAlarmOperation.

Responses
Every request has an associated response. The responses follow a naming pattern similar to requests, with the word Response appended instead of Request. So, the response to a createAlarmRequest is a createAlarmResponse.

Each response contains a Result. The results contain the outcome of the system's attempt to process a request. Results will contain either success data or error data.
  • SuccessData may contain warnings (code and message text) and/or other data indicating the request was successfully processed. The content of the success data varies depending on the nature of the request. The SuccessData component is named using a similar convention to requests, except the words SuccessData are appended instead of Request. So, the success data for a createAlarmRequest is called createAlarmSuccessData
  • ServiceError will contain a fault code, and a message describing the nature of the error.
The common request types, and their default behavior are described below:

Create/Setup
When creating a new item, the system will return the unique identifier of the item in the success data portion of the response. The requestor may also choose to receive a copy of the newly created item by setting the include element to true in the request.

For example: when making a CreateUser request, setting the includeUser element to true would cause the system assigned userId and a copy of the created user to be returned in the success data.

Update
When updating an item, the requestor must provide the unique identifier of the item to be updated. Except for the unique identifier, the elements in an update that are required will be updated with the data provided.

When requesting an update, optional components (i.e. where minOccurs = 0), will behave as follows:
  • If the optional component is present in the request, the corresponding data will be updated
  • If the optional component is present and is empty, the corresponding data will be removed
  • If the optional component is excluded from the request, no changes will be made to the corresponding data
When updating an item, the requestor may receive a copy of the updated item by setting the include element to true in the request. If the include element is not set to true, a successful update will return an empty success data component.

Cancel/Delete
When canceling or deleting an item, the requestor must provide the unique identifier of the item to be removed. A successful request will return an empty success data component.

Lookup
There are two general methods for looking up information:
  1. looking up a specific item using a unique identifier, this will always return a single result (or an error)
  2. querying with search criteria, this may return multiple results (one, or more)
When querying by a unique identifier:
If a match is found, the requestor will receive success data that contains the item requested. In addition, when making the request the requestor may be able to specify optional components to be returned in the success data. These are specified by setting the corresponding include elements to true in the request.

For example, when making a LookupCompanyRequest, the requestor might choose to set includeUsers to true. This will cause the system to include the list of users associated with the company in the success data of the response. If no matching item is found, the system will return error data.

When querying using search criteria:
If one or more matches are found, the requestor will receive success data that has one or more of the items they were looking for. If a match is not found, the system will return empty success data.



Published: August, 2004
Version : 1.1.0

Copyright (C) 2004-2008, TransCore LP, All Rights Reserved.


Fault codes which enumerate the type of error or warning which resulted in a TcoreFault being generated.
  • RequiredFieldMissing - A data field required to fulfill this request was missing. Corrective action: Provide all required fields and resubmit the request.
  • InvalidData - The request could not be processed due to invalid data. For example, a request was made to create a company with a company name which already exists. Corrective action: Change the company name and resubmit the request.
  • ValueOutOfRange - Not currently used.
  • EntityNotFound - The requested object could not be found.
  • NoCapability - The current user was not authorized to perform the requested operation. Corrective action: Contact your system administrator to receive the proper authorization.
  • ConcurrentModification - An update was made by another process to the same object(s) as those being modified by this request. Corrective action: resubmit the request.
  • InvalidSession - Not currently used.
  • SessionTimeout - The session certificate provided with this request has timed out. Corrective action: The user must reauthenticate before any requests can be processed.
  • InvalidDocument - There was a syntactical error in the format of the request document and it could not be read correctly.
  • InvalidAuthentication - The session certificate provided with a request was not valid. Corrective action: The user must reauthenticate before any requests can be processed.
  • DatabaseException - An error occurred in the database during the processing of this request and it could not be completed. Corrective action: The request should be resubmitted.
  • ServiceNotAvailable - A service required to process the request successfully was temporarily unavailable. Corrective action: The request should be resubmitted.
  • ServiceException - An unexpected error occurred while processing this request. Some form of intervention may be required by DAT to resolve the issue.
  • IgnoredField - Data was provided in a field that is not needed to fulfill a request. This is only a warning and does not affect the completion of a request.
 Monotonically increasing sequencer. Useful for concurrency tracking. The base type for an operation The base type for a result The base type for data Message provides a detailed description of the fault. It is intended to clarify the more general information indicated by the code In some cases, a successful result will be returned with warnings, indicating non-fatal issues such as fields which were ignored or modified in processing. Message provides a detailed description of the fault. It is intended to clarify the more general information indicated by the code Examples might be: hyperbus, ftp, http, etc Describes/classifies the relationship of an organization with respect to DAT. Normally, the application a request is coming from, may also represent the source of an asset. ID of a Private Network (in the freight matching sense).
This is only used by TFMI... be warned... don't touch it unless you know exactly what you're doing. TFMI is an external public ZAPI with an SDK. Reference ID of a Private Network (in the freight matching sense). This is used by the general CSB interface for postings and searches. See "PrivateNetwork" (above) for TFMI usage.
Note that CSB makes no distinction between whether a private network is at the "office" or "group" (user-level) level. They are all just handles to a private network.
2021.08.12: the Association System is using 32-char private network references. The 100-char cap (below) is just to provide some protection against bad behavior. All Companies fall into one or more of these general classifications. Standard Carrier Alpha Code.
Each carrier has a unique SCAC code assigned/maintained by the National Motor Freight Association, and is an ANSI standard. The use of SCACs is very common, and even mandated by some governmental agencies on their forms/communications. The Id of a company, to which Users belong. All Users must belong to only one Company. This Id is unique among all companies across all of DAT. ID of an office, to which Users belong. All Users must belong to only one Office. All Offices must belong to only one Company. This Id is unique among all offices of a company. This means that multiple companies may have the same office Ids (although it would be much smarter if office Ids were unique across DAT). ID used to identified offices in the Customer Directory / Registry. Also carried in freight matching entities.
Typical pattern is [A-Z]\.* but we don't restrict it. A universal ID for a user.
  1. It represents a single user, not an office or company.
  2. It is, and must be, unique across all of DAT.
 A universal ID for a group. A user can belong to one and only one group. The encoded capabilities information. The registry lookup Id is a customer unique handle used to retrieve profiles and other information from the DAT Registry. The combined office ID is a special, synthesized ID that agglutinates different company offices that are in the same geographic location. This is especially useful for office filtering, such as done in Apollo for preferred/blocked customer filtering. Hyperbus agent ID. Hyperbus location in the format, "hbus://{address}:{port}" The customer directory Id is a customer unique handle used to retrieve profiles and other information from the DAT Customer Directory. CSB login Id. Must be between 4 and 16 characters long and consist entirely of lower or upper case letters, digits, and/or the underscore character. Assuming MD5 hash algorithm which produces a 32 digit hexadecimal number Price class associated with transactional orders. A unique identifier for a file stored in the CSB datastore. Represents the Latitude portion of a coordinate.
NOTE: Coordinate values are limited to North America. Represents the Longitude portion of a coordinate.
NOTE: Coordinate values are limited to North America.

DAT uses the international convention of negative longitude values west of the Greenwich Prime Meridian. This may cause nominal conversion hassle for some DAT legacy programs.

DAT list of recognized state/provinces codes for the United States, Canada, and Mexico.

The United States and Canada abbreviations are those used by the United States Postal Service and Canada Post, with the exception that we still use pre-2002 codes for Quebec and Newfoundland, for consistency with certain current DAT products and to avoid conflicts with Mexican codes.

NOTE: Mexican state codes do not have an official standard. We use those codes that are in the preponderance of use by North American businesses.

Zones are geographic areas represented as a collection of states or provinces.
The following zones are currently defined:
  • "New England" [Legacy code "Z0"] = CT,ME,MA,NH,NJ,RI,VT
  • "NorthEast" [Legacy code "Z1"] = DE,NY,PA
  • "Mid-Atlantic" [Legacy code "Z2"] = DC,MD,NC,SC,VA,WV
  • "SouthEast" [Legacy code "Z3"] = AL,FL,GA,MS,TN
  • "Mid-West" [Legacy code "Z4"] = IN,KY,MI,OH
  • "North Central" [Legacy code "Z5"] = IA,MN,MT,ND,SD,WI
  • "Central" [Legacy code "Z6"] = IL,KS,MO,NE
  • "South" [Legacy code "Z7"] = AR,LA,OK,TX
  • "Mountain" [Legacy code "Z8"] = AZ,CO,ID,NV,NM,UT,WY
  • "West" [Legacy code "Z9"] = AK,CA,HI,OR,WA
  • "Canada" [No Legacy code] = All of Canada / ON,PQ,NB,NF,NS,PE,AB,BC,MB,SK,NT,YT
  • "Central Canada" [Legacy code "ZC"] = ON,PQ
  • "Eastern Canada" [Legacy code "ZE"] = NB,NF,NS,PE
  • "Western Canada" [Legacy code "ZW"] = AB,BC,MB,SK,NT,YT
  • "Mexico" [Legacy code "ZM"] = All of Mexico / AG,BJ,BS,CH,CI,CL,CP,CU,DF,DG,EM,GJ,GR,HG,JA,MH, MR,NA,NL,OA,PU,QA,QR,SI,SL,SO,TA,TL,TM,VL,YC,ZT
  • "Northern Mexico" [Legacy code "ZB"] = Mexican US Border States / BJ,BS,CL,CU,NL,SO,TM
  • "Contiguous USA" [No Legacy code] = Lower 48 + DC
 Indicates if a city name is recognized by the United States Postal Service for a particular postal code. In the case where more than one city name is associated with a particular postal code, the primary city name (Point) will have a status of Primary and alternate city names will have a status of Acceptable. If a city name is known to DAT but is not recognized by the USPS, then it will have a status of Unacceptable, and the postal code assigned to it is DAT's best guess (usually based on proximity to the nearest place with a valid postal code).

NOTE:ZipcodeStatus is only applicable to US cities. All Canadian postal codes are considered Primary and currently DAT does not store Mexican postal codes. Abstract base class defined to support substitution groups. In some instances .NET tools generate better code if they have a common base type. This provides a common base type for all the geographic location types. A MinimalPoint is a named place that is located in a state/province and has latitude and longitude coordinates.
MinimalPoints encompass the notion of a city, a USGS placename, or a waypoint. County represents the county, parrish, department, district, or borough in which this place is located. This can be particularly important when a state or province has multiple points with the same name. Although the latitude and longitude values will be unique, people generally need a more useful hint, such as a county name.

If the point does not have an applicable notion of county, or it is not known, then this item is omitted. A Point is a KnownMinimalPoint with additional information. The shortened version of cityName. This is commonly used in situations where space is at a premium, such as Truck Stop Monitors and faxback search results.

If the point does not have a short name, then this item is omitted. The internal DAT unique ID for this place. This is used as a key to uniquely identify a specific point within the standard DAT set of points.

If this point is not known to DAT, this element will be set to zero (0). These are the Primary Metropolitan Statistical Area (MSA) codes as defined, and assigned, by the US Office of Management and Budget.

The definitions are often obscure, but an MSA usually includes one city with 50,000 or more inhabitants and the county that the city falls within. It can also include nearby counties if they are within commuting distance.

NOTE:Not all ZIP codes have an MSA code because many ZIPs are in rural areas.
DAT assigns 9999 to all Canadian locations.

DAT assigns 0 to all Mexican locations.

If a Point does not have an MSA, it is asigned 0. The primary postal code for this Point. It is possible for a large city to have more than a single postal code. If so, alternate postal codes will be listed in alternatePostalCode. If DAT does not have a postal code for this Point, this item is omitted. These are the postal codes assigned to this point in which the government (e.g., USPS or Canada Post) has classifed the assignment as "Acceptable". That means that another point is the "Primary" for the postal code, but if associated with a this point, the postal service will respect it as valid. In the case of multiple points having the same city name in the same state, this field is set true if this point is one that is preferred for freight matching. Typically, this is the point with the largest population. These are the postal codes assigned to this point in which the government (e.g., USPS or Canada Post) has classifed the assignment as "Primary". ID of the KMA (Key Market Area) in which this point resides. Not all points reside in a KMA. Key Market Area The geographic points which reference a particular postal code. The postal code being referenced. The point that is the "primary" location of the postal code (as assigned by the US Postal Service or Canada Post). Only one point will be the primary for any given postal code. The points that are alternate locations for the postal code (as assigned by the US Postal Service or Canada Post). In general, this means that postal addresses to this point's city, state, and this alternate postal code will be considered deliverable by USPS/CP.

Large cities may have many alternate points. A RangeCircle defines a circular area around a Point . An Area is a collection of states, provinces and/or zones. A list of states and/or provinces in the desired region. A list of one or more zones in the desired region. The Open type designates an empty geographic specification. Depending on context, this can represent either "nowhere" or "anywhere". The common name of a city, USGS place, or waypoint.

NOTE: most current DAT applications support just 14 character city names. The common name of a county, bourough, parrish

NOTE: most current DAT applications support just 14 character county names. A unique DAT ID is assigned to all Points. Based on two-letter ISO 3166 country codes for countries supported by DAT. The two-letter ISO 3166 country code. The ISO 4217 three-letter IDs for the representation of international currencies. The number of milliseconds to add to UTC to get local time. Negative values are for locations west of the Greenwich Meridian, e.g., Pacific Standard Time is -28800000. 12 hours west of Greenwich, in milliseconds. 14 hours east of Greenwich, in milliseconds. This is effectively the same time zone as Hawaii, except "tomorrow", and is used by the Kiribati Islands, which span the international date line. This allows the entire nation to operate in the same date (except for the three hours as they cross midnight). 13 hours east of Greenwich is also used by New Zealand for Summer Time This allows them to have the US equivalent of Daylight Savings, but not deal with suddenly leaping into "tomorrow" when they go on DST. A Locale represents a specific geographical, political, or cultural region. Currently only "en" (English) is supported, with no specific support for variants (e.g., "en_US", "en_CA", "en_UK". If omitted, will default to "en" (English). If omitted, will default to "CountryCode.US". If omitted, will default to 0 (zero), which is equivalent to UTC/GMT/ZT If omitted, will default to "CurrentCode.USD". If omitted, will default to "MeasurementSystem.Standard". If omitted, will default to "$" (which covers USD, CAD, and MXN). If omitted, will default to ",". A language-localized string. The localized string value. The language for which the string is localized. Most commonly will be "en" or "en-US". The type requested and/or method used to compute a road mileage distance. DAT currently only supports a single road mileage provider (ALK PC*Miler). The 'RoadProMiles' and 'RoadAlk' options remain in place for backward compatibility, but we have no short-term plans to support other providers. We recommend using the 'Road' option, which will return mileages from the current mileage provider. Equatorial circumference of the Earth (kilometers). Since air miles really only needs half this distance as its maximum, hopefully this will be a large enough limit for anyone trying to travel by road and water half-way around the globe. A Distance value, and a description of how the distance was derived. Universal Coordinated Time representation.
DAT uses UTC exclusively, therefore ALL dateTime values must be in UTC format. Type UTC helps enforce this requirement with the legal dateTime pattern: "YYYY-MM-DDTHH:mm:ssZ". NOTE:
  • The seconds portion may optionally contain a decimal fraction
  • Timestamps in particular will make use of millisecond precision.
 Container for date/time and a time zone is which it is to be rendered. CSB does not support conversions to/from/between localized date/times! The ID of the time zone in which "when" is to be rendered. It is highly recommended that a recognized standard ID be used (e.g., IANA: http://en.wikipedia.org/wiki/IANA_time_zone_database for which the Beaverton installation of CSB operates in the "America/Los_Angeles" time zone). 4-digit year 2-digit month Credit card types recognized by DAT. The month and year in which a credit card expires. North American Postal Codes
  • Canada: LNL NLN
  • Mexico: NNNNN
  • US ZIP: NNNNN(-NNNN)
 Country code. ZIP or postal code. The hyphen in 9-digit US ZIP codes and the space in Canadian postal codes are optional. The postal code patterns
  • Canada: LNL NLN
  • Mexico: NNNNN
  • US ZIP: NNNNN(-NNNN)
 Partial North American Postal Codes.

These are typically only of use when looking up postal codes for a metropolitan area. A minimum of three leading characters of a postal code must be specified. It makes little sense to specify fewer (too broad a geographical area, and certainly larger than a metropolitan area).

Likewise, there is often little value to specifying more than three characters:
  • US: Digits 4 and 5 do not necessarily resolve to an area finer than a city (although large cities may have many postal codes), and in fact, there's no guarantee that all ZIPs with the same leading three digits are in the same metro area (and often are not).
  • Canada: While all urban postal codes with the same first triplet always resolve to the same city, the second triplet resolves to arbitrarily-sized small areas, typically neighborhoods, large buildings/campuses, etc. In rural areas, many small towns and villages can share the first triplet, and the second triplet may specify a very large area.
  • Mexico: Postal Codes obstensibly follow a pattern in which successive digits resolve to finer geographical areas, but there is no guarantee. Large cities often have postal codes within them that have differing third digits.
 Three-character partial postal codes. For US, aka "three digit ZIP", for Canada, aka "FSA" (Forward Sortation Area).

These are typically only of use when looking up postal codes for a metropolitan area. First, middle and last name of a person. First and last name of a person. The recognized types of telephony devices. The different classifications of phone numbers. Country codes are short alphabetic or numeric geographical codes (geocodes) developed to represent countries and dependent areas, for use in data processing and communications.
This field is a String that contains a numbers that's 1-3 digits long. A telephone number or phone number is a sequence of digits used to call from one telephone line to another in a public switched telephone network.
This field is a String that contains a numbers that's 10 digits long (changed from 8 to 10 in July 2016, to reflect that all US/CAN/MEX customers are 10 digits, and no plans to expand to other countries). An extension telephone is an additional telephone wired to the same telephone line as another. In middle 20th century telephone jargon, the first telephone on a line was a "Main Station" and subsequent ones "Extensions". Such extension phones allow making or receiving calls in different rooms, for example in a home. Some telephones intended for use as extensions have built in intercom features.
This field is a String that contains a numbers that's 1-5 digits long. Describes DAT's interpretation of phone numbers.

NOTE:
  • US and Canada are always 3-digit area code + 7-digit local code
  • Area codes should not begin with a zero or one, but there exists some legacy data containing such area codes. For the time being such numbers will continue to be accepted. Please note that this could change in the future and area codes beginning with a zero or one would then be rejected as invalid!
  • Mexico has 1-3 digit area code + 7-digit local code, except in Mexico City the local code is always 8 digits, where the first digit is always '5': 5nnnnnnn
  • International access from the United States and Canada is always "011", and the country code for Mexico from United States and Canada is always "52"
  • A country code is always a 3 digit code with leading zeros where needed
  • An extension consists of 1 to 5 numeric digits
 Country code. 1-3 digits. The primary number. 8-10 digits. Extension. 1-5 digits. Describes DAT's interpretation of phone numbers.

NOTE:
  • US and Canada are always 3-digit area code + 7-digit local code
  • Area codes should not begin with a zero or one, but there exists some legacy data containing such area codes. For the time being such numbers will continue to be accepted. Please note that this could change in the future and area codes beginning with a zero or one would then be rejected as invalid!
  • Mexico has 1-3 digit area code + 7-digit local code, except in Mexico City the local code is always 8 digits, where the first digit is always '5': 5nnnnnnn
  • International access from the United States and Canada is always "011", and the country code for Mexico from United States and Canada is always "52"
  • A country code is always a 3 digit code with leading zeros where needed
  • An extension consists of 1 to 5 numeric digits
 Country code The primary number Extension The information needed to contact a freight matching User. Requires that the person's initials be provided, as well as their poster state/province. n.n.n.n How the customer prefers to be contacted. How the customer heard of DAT. Day of the week. This type will be deprecated. Use Email type instead. This is used for multi-part emails. Dun and Bradstreet Universal Numbering System number. Motor Carrier (MC) number. Department Of Transportation (DOT) number. Federal tax identification number used by the IRS to identify an individual and/or business. DAT recognized business types for carriers. The short name of the user, primarily used for display on Truck Stop Network monitors. Types of freight matching assets. Broad classification of equipment. All equipment (trucks and their containers) belong to one or more of the following classes of equipment. DO NOT CHANGE THE ORDERING OF THESE VALUES!!!!!!! Legacy/shorthand code for equipment classes The following specific types of equipment are supported. DO NOT CHANGE THE ORDERING OF THESE VALUES!!!!!!! Legacy/shorthand code for equipment types. Standard name-value pair used for properties, attributes, etc. A very limited regular expression syntax.
Allows any character(s) and an optional trailing wildcard, '*'. If a trailing wildcard is found, the leading characters are considered a prefix and any name that begins with these characters is returned. Express a range value rule.
  • variable must be between min and max.
  • minInclusive and maxInclusive specify whether the ends of the range are open or closed.
 Express a relational rule.
variable must be related to value through the use of operator.. Expresses a set membership rule.
variable must be one of the values.
NOTE: it is possible to have an empty value set.

Applications can interpret empty value sets as they please, but usually the result is either:
  1. always false (i.e., "value" can never be a member of an empty set, or
  2. true' if "value" is has no value (is undefined), or if "value" is a string, it is empty.
 Represents a non-negative 32-bit int. Used often for Ids. Represents a positive 32-bit int. Relevance score based on closeness to a specified criteria. An exact match will always have a score of 1.0. JSON Web Token https://tools.ietf.org/html/rfc7519 Should contain 3 base64 encoded sections separated by periods, but the enforcement of format is left to code. Identifier of the application that is sending the request. Since a token is valid for multiple applications, the caller must specify their identity. This will be validated against a list of known sourceApps. The application's reported version number. Historically, this was reported in the "ApplicationHeader", but in the JWT world, it makes sense here. Encapsulation of a collection of Point. Typically used to allow convenient data transfer or persistence as XML text (especially the export of the geoascii.dat and all_points.xml files to clients). When a point is looked up by a service, the requestor typically wants to know how the point was found. Descriptor of how points were looked up. Exact match (lower cased) with the supplied criteria. No exact matches found. Matching points' names start (lower cased) with the supplied criteria. No exact or starts-with matches found. Matching points' names match (lower cased) with the supplied criteria after CSB/SB2 standard rules of abbreviation, punctuation, and spacing have been applied to the criteria. No exact, starts-with, or normalized matches found. Matching points' names are suggestions based on assumption that supplied criteria is a misspelling. The maximum size of an Oracle VARCHAR2 is 4000 bytes. A LatLongLocation is a place specified only by latitude and longitude coordinates. Used to send a file via XML. The content must populated using base 64 encoding and read using base 64 decoding. Used only for testing Used only for testing Used only for testing Used only for testing A mementoable MetaDomainObject