Jobs are the stops you schedule your vehicles to make on a route. These can be deliveries, stops where your drivers perform tasks, locations where your vehicles make scheduled pick-ups, and so on. Each job can be configured with a name, a physical location (specified by providing a marker or a geographical location and a territory id), job type id, delivery date and time, and other attributes. If you create jobs by specifying geographical locations, make sure that you reuse the same job name for subsequent jobs that are at the same location - this results in the marker that was created for the first job being reused for subsequent jobs, and avoids the duplication of markers that would have a negative impact on reporting and other features.

The following key concepts define how jobs work:

Job types

Job types identify the types of tasks drivers perform on a job. Like Category for markers, job types have associated colors that make them easy to distinguish in charts, list views, reports, and clusters on the map. If a job has a Linked Stop, the linked job can have its own job type.

Markers

A marker represents a physical location. Each job must have a marker, which you can specify by providing data for any of the following column sets:

• MarkerId
• TerritoryId, Lat, Lon
• TerritoryId, StreetNumber, StreetName, City, Region, PostalCode, Country

When you create a new job, you must provide the data for at least one of these column sets.

If a MarkerId is not available, TDE uses the other column sets provided to try to find a nearby existing marker to use for the job. If an existing marker is found within one meter of the location specified, and that marker also has the same name as the job being created, then it is used as the marker for the job. This is the best case scenario, as it prevents duplicate markers. If there are no markers with the same name as the job within one meter of the location specified, a new marker is created and given the same name as the job. Note that this can result in a collection of duplicate markers over time, negatively affecting the function of other features, such as reports.

To prevent duplicate markers, ensure that you follow all of these guidelines:

• If possible, use the MarkerId of an existing marker to identify the location for a job. If this is not possible, use the same Lat/Lon or address for every job at the same location.
• Use the same job name for all jobs at the same location (for example, use the customer id or customer name as the job name, since these values will stay the same for multiple deliveries to the same customer at the same location).
• Use values that can vary, like delivery date or order number, in job names only if the location is specified by a MarkerId.

This same logic is applied for updates.

Note
If the Marker address data is updated, the changes are reflected in the Job table.

Depots

Depots are special types of markers. They represent the home base for a set of jobs. Depots are located within a territory. Drivers belong to the territory of their assigned base depot. If the driver is assigned to a vehicle, the vehicle must also be based at a depot in the territory.

The depot location is also the start and end point for a job route, or the location where materials are picked up or deposited.

Territories

A territory is a geographical area that can contain groups of customers, depots, drivers, and vehicles. A job cannot be directly assigned to a territory. Instead, a job inherits its territory based on either the assigned marker (MarkerId) or the assigned route (RouteId).

If you provide a TerritoryId on Create or Update, the way that Id is used depends on the other available data:

• On Create, if a MarkerId is not provided, then the TerritoryId is used with other location information provided to either select an existing marker for the job or create a new one. See the Markers section above for details.
• If the marker assigned to the job already has a territory assigned to it, then the TerritoryId provided is ignored.
• If the marker assigned to the job does not have a territory assigned to it, then the way the TerritoryId is used depends on whether the job is assigned to a route or not, as shown in the following table.

  RouteId	TerritoryId	Outcome
  X	X	The marker assigned to the job is given the route's territory, and the TerritoryId provided is ignored.
  	X	The marker assigned to the job is given that TerritoryId.
  X		The marker assigned to the job is given the route's territory.

When you Retrieve the TerritoryId for a job, the value returned can vary based on the following rules:

• If the job is already assigned to a route (RouteId), then the retrieved TerritoryId represents the route’s territory.
• If the job is not assigned to a route (RouteId), then the retrieved TerritoryId represents the marker’s territory.

When you create a job, you must provide the following information:

• JobTypeId
• Physical location of the job specified by MarkerId or Territory data.

When you write templates that access this table, follow these requirements:

1. Specify the Symbolic Name for the table version to use:

   Copy

   TableID = Job-1.0

2. Specify an Intent that this table supports:

   • Retrieve
   • Create
   • Update
   • CreateOrUpdate
   • Delete

3. Input templates: In your [Output] section, be sure to map an input value to every table column that is flagged as being a primary key or required.

   Note
   If you change the values for the ExpectedArrivalTime, ExpectedDepartureTime, or RouteId columns for a job, the JobStatus flag is reset to "OK".

4. Retrieve templates: This table requires the use of a fetcher. The following fetchers are available and are listed from most efficient to least:
   1. Id (Equals/In)
      Copy

      [Filter]
      Id(ExtId) = Equals(Id1)   # You can filter on literals or on variables from the [User] or [Calculated] sections.

      Copy

      [Filter]
      Id(ExtId) = In(["Id1","Id2","Id3"])

   2. UnitId (Equals) AND RouteStartTime (Between)
      Copy

      [Filter]
      UnitId(ExternalIdName) = Equals("ABC123")         # or use Telogis Id: UnitId = Equals("123456...")
      RouteStartTime = Between(TimeStart,TimeEnd)

   3. RouteId (Equals/In)
      Copy

      [Filter]
      RouteId(ExternalIdName) = Equals("RST456") # or use Telogis Id: RouteId = Equals("123456...")
                                                 # You can either use the Equals function as shown
                                                 # or use the In function: In([RouteId1,RouteId2,RouteId3])
                                                 # to test whether the key value matches any in the set.

   4. RouteStartTime (Between)
      Copy

      [Filter]
      RouteStartTime = Between(TimeStart,TimeEnd)

   5. ExpectedArrivalTime (Between/GreaterThan)

      When filtering by ExpectedArrivalTime, you can improve search performance by adding one or more of the following optional filters: Code(Equals/In), DriverId(Equals/In), JobTypeId(Equals/In), LastUpdateTime(Between/GreaterThan), or TerritoryId(Equals/In).

      For Id values, you can specify a value or use Telogis Id.

      Copy

      [Filter]
      ExpectedArrivalTime = GreaterThan(TimeStart)   # Use either a GreaterThan or Between function
                                                     # such as Between(TimeStart,TimeEnd)
      # Optional filters:
      LastUpdateTime = GreaterThan(UpdateTimeStart) # GreaterThan or Between
      TerritoryId(ExtId) = Equals("USA123")         # Equals or In   
      Code = Equals("MyCode1")                      # Equals or In  
      DriverId(ExternalIdName) = Equals("DEF123")   # Equals or In
      JobTypeId(ExternalId) = Equals("Depot")       # Equal or In

This table supports the following option, which can be set in the [TableOptions] section.

• EnableRouteStatusUpdate - When set to True, this table option allows the updating of the route status when the JobStatus is updated. The following table describes the behavior of this option for the Update intent.

  Note
  Using this table option is only recommended if your account has the Driver Initiated Job Status feature enabled. Otherwise, updates to the route status via the job status updates might be overridden by TDE’s automated systems.

  Update Intent

  Value	Description
  False (default)	Route status is set via TDE's automated systems.
  True	The behavior of enabling this option is as follows: OnSite - If the job status is being updated to OnSite and the job is not at the start depot, update the route status to InProgress. Complete - If the job status is being updated to Complete and the job is at the end depot, update the route status to Complete. Complete - If the job status is being updated to Complete and the job is not at the end depot, update the route status to InProgress.

  Example Template

  Copy

  [Template]
  TemplateVersion = 1.0
  TableID = Unit-1.0
  TemplateName = JobStatusUpdate
  Intent = Update
  
  
  [TableOptions]
  EnableRouteStatusUpdate=True
  
  
  [Output]
  Id = Input.Id
  JobStatus = Input.JobStatus
  ActualArrivalTime = Input.ActualArrival
  ActualDepartureTime = Input.ActualDeparture

This list includes each column's name, which you use in expressions to retrieve or create data, and data type, which defines how the data is retrieved and set.

Note
If a column of data type Id is a primary key OR if it refers to other tables (Id <OtherTable>), then you can map it to an external key or, in some cases, a Telogis key.

Additional columns: