Business Objects Reference, A - D

This page presents information about business objects and their properties, alphabetically from A to D.

Assignment Object

An Assignment object associates an engineer with a task, and it specifies a time interval when the engineer should perform the task.

A nonavailability assignment is an Assignment object that lacks a task. It defines a time interval when the engineer is not available for work.

Web Services that Use the Object

ScheduleService, LocateService

XML Representation

<Assignment>
  <Key>61440</Key>
  <Revision>2</Revision>
  <Stamp>...</Stamp>
  <Task>
    <CallID>WO42</CallID>
    <Number>1</Number>
  </Task>
  <Start>2009-03-15T09:30:00</Start>
  <Finish>2009-03-15T10:30:00</Finish>
  <Engineers>
    <Engineer>
      <ID>RB1-23-4567</ID>
      <District>Paddington</District>
    </Engineer>
  </Engineers>
  <Comment />
  <Latitude>51516314</Latitude>
  <Longitude>-175275</Longitude>
  <GISDataSource>1</GISDataSource>
  <AssignedEngineers>Russell Baker</AssignedEngineers>
  <LogicPolicy />
  <IsCrewAssignment>false</IsCrewAssignment>
  <CountryID/>
  <Street />
  <City />
  <State />
  <Postcode/>
  <NonAvailabilityType />
</Assignment>

In a nonavailability assignment, the Engineers, Start, and Stop properties must be assigned. The Task property must not be assigned. In the following example, the resource RB1-23-4567 is unavailable from March 15 at 08:00 until March 20 at 17:00.

<Assignment>
  <Key>61440</Key>
  <Revision>1</Revision>
  ...
  <Task />
  <Start>2009-03-15T08:00:00</Start>
  <Finish>2009-03-20T17:00:00</Finish>
  <Engineers>
    <Engineer>RB1-23-4567</Engineer>
  </Engineers>
  ...
</Assignment>

Properties

The following list describes the commonly used assignment properties. Certain additional properties are used only in special applications.

Key, Revision, Stamp

See Standard Properties of Business Objects.

Task

A reference to the assigned task.

Start, Finish

The start and finish times of the assignment. For the syntax of these properties, see the Date Parameter.

Engineers

References to the assigned engineers.

In a regular assignment, this property must contain exactly one engineer. The logic services do not support Assignment objects that contain multiple engineers. To implement assignments that require multiple engineers, see Multiresource Tasks and Teamwork and Configuring Crews in ClickSchedule.

In a nonavailability assignment, it is permitted for the the property to contain multiple engineers, indicating that all the engineers are unavailable during the same time interval.

Comment

A comment describing the assignment, such as the reason for a nonavailability assignment.

Latitude, Longitude

Assignment coordinates (integers in millionths of a degree).

These properties are read/write for non-availability assignments, signifying the location of an engineer when not available for work. For other assignments, the properties are effectively read-only. Their values are the coordinates of the the assigned task. If you attempt to write any other values to the properties, the system ignores the new values.

GISDataSource

The geographic dataset identifier that Service Edge uses to route the assignment. The property is provided for historical reasons. In Service Edge, the value of GISDataSource for a geocoded object is nearly always 1.

AssignedEngineers

A string representation of the Engineers property, containing the engineer names.

LogicPolicy
The name of a scheduling stage that created the assignment. The property is in use if the assignment was created by a logic service that uses scheduling stages, such as scheduling workflow or schedule-idle-resource.
IsCrewAssignment

True if a crew of engineers is assigned to the task.

CountryID

A reference to an item in the Country dictionary, identifying the country of the assignment. The property is meaningful only for non-availability assignments. For other assignments, assign the CountryID of the assigned task.

Street, City, State, Postcode

Address of the assignment. The property is meaningful only for non-availability assignments. For other assignments, assign the address properties of the assigned task.

NonAvailabilityType
The type of a nonavailability assignment. The value is the key of an item in the NonAvailabilityType dictionary, for example, Annual Leave or Medical Appointment.

SXP Identifier

By default, the identifier property of an assignment is its Task. The task, in turn, is identified by its CallID and Number. For example, the following reference identifies an assignment:

<Assignment>
  <Task>
    <CallID>WO42</CallID>
    <Number>1</Number>
  </Task>
</Assignment>

A nonavailability assignment does not have a task. You can reference a nonavailability assignment by its key:

<Assignment Key="61440" />

Calendar Object

A Calendar object defines the time intervals when an engineer is available for work or when a task can be performed. Its representation can be lengthy because it contains lists of the time intervals. These include:

  • Yearly, weekly, and time-phased weekly activity intervals, which can have a status of Work, NonWork, OptionalWork, or Supervision
  • For an engineer calendar, yearly and weekly shift intervals, during which the engineer can be assigned only to a specified group of tasks

For a discussion, see Calendars.

 Web Services that Use the Object

ServiceOptimizationService, ScheduleService

 XML Representation

<Calendar>
  <Key>12345</Key>
  <Revision>2</Revision>
  <Stamp>...</Stamp>
  <Name>Maintenance Dept. Calendar</Name>
  <KeyOfBase Key="54321">
    <Name>Company Calendar</Name>
  </KeyOfBase>
  <TimeZone>Eastern Standard Time</TimeZone>
  <YearlyLevel>
    <YearlyInterval>
      <TimeInterval>...</TimeInterval>
      <Status>Work</Status>
      <OverwriteExisting>false</OverwriteExisting>
    </YearlyInterval>
    ...
  </YearlyLevel>
  <YearlyShiftLevel>
    <YearlyShiftInterval>
      <TimeInterval>...</TimeInterval>
      <Shift Key="23456">
        <Name>TaskGroup1</Name>
      </Shift>
      <OverwriteExisting>false</OverwriteExisting>
    </YearlyShiftInterval>
    ...
  </YearlyShiftLevel>
  <WeeklyLevel>
    <WeeklyInterval>
      <WeeklyIntervalStart>
        <Day>Monday</Day>
        <Time>08:00:00</Time>
      </WeeklyIntervalStart>
      <WeeklyIntervalFinish>
        <Day>Monday</Day>
        <Time>17:00:00</Time>
      </WeeklyIntervalFinish>
      <Status>Work</Status>
      <OverwriteExisting>false</OverwriteExisting>
    </WeeklyInterval>
    ...
  </WeeklyLevel>
  <WeeklyShiftLevel>
    <WeeklyShiftInterval>
      <WeeklyIntervalStart>
        <Day>Monday</Day>
        <Time>08:00:00</Time>
      </WeeklyIntervalStart>
      <WeeklyIntervalFinish>
        <Day>Monday</Day>
        <Time>12:00:00</Time>
      </WeeklyIntervalFinish>
      <Shift Key="1">
        <Name>TaskGroup2</Name>
      </Shift>
      <OverwriteExisting>false</OverwriteExisting>
    </WeeklyShiftInterval>
    ...
  </WeeklyShiftLevel>
  <TimePhasedWeeklyLevel>
    <TimePhasedWeeklyInterval>
      <WeeklyIntervalStart>
        <Day>Tuesday</Day>
        <Time>08:00:00</Time>
      </WeeklyIntervalStart>
      <WeeklyIntervalFinish>
        <Day>Tuesday</Day>
        <Time>12:00:00</Time>
      </WeeklyIntervalFinish>
      <Start>2011-01-01T00:00:00</Start>
      <Finish>2011-06-30T00:00:00</Finish>
      <Status>Work</Status>
      <OverwriteExisting>false</OverwriteExisting>
    </TimePhasedWeeklyInterval>
    ...
  </TimePhasedWeeklyLevel>
</Calendar>

Properties

Key, Revision, Stamp

See Standard Properties of Business Objects.

Name

The name of the calendar.

KeyOfBase

A reference to the base calendar.

TimeZone

This property is not in use. The system interprets the calendar in the local time zone of the engineer or task.


In the web-service and SXP APIs, the calendar intervals are represented by the following properties. In the .NET API, the intervals are accessed by methods rather than properties.

YearlyLevel, YearlyShiftLevel, WeeklyLevel, WeeklyShiftLevel

Yearly and weekly activity and shift intervals. For the syntax of these elements, see the TimeInterval Parameter.

The OverwriteExisting element is meaningful only in an UpdateCalendar Operation.

TimePhasedWeeklyLevel

Activity intervals that recur each week between specified dates. Note the following restrictions:

  • The nested WeeklyIntervalStart and WeeklyIntervalFinish must be on the same day of the week.
  • The Start and Finish dates must have a time of 00:00:00 (midnight).
  • The Start to Finish period must be at least 7 days.

Syntax Variations

In many web operations that use calendars, the Calendar parameter contains all the properties except the time intervals. The CalendarIntervals parameters contains the intervals:

<Calendar>
  <Key>12345</Key>
  ...
  <TimeZone>Eastern Standard Time</TimeZone>
</Calendar>
<CalendarIntervals>
  <YearlyLevel>...</YearlyLevel>
  ...
  <TimePhasedWeeklyLevel>...</TimePhasedWeeklyLevel>
</CalendarIntervals>

In operations such as GetCalendarIntervals, the TimePhasedWeeklyInterval element has the following syntax:

<TimePhasedWeeklyInterval>
  <SingleOccurrenceInterval>
    <Start>2011-02-15T08:00:00</Start>
    <Finish>2011-02-15T12:00:00</Finish>
  </SingleOccurrenceInterval
  <Status>Work</Status>
  <TimePhasedWeeklyInterval>
    <WeeklyIntervalStart>
      <Day>Tuesday</Day>
      <Time>08:00:00</Time>
    </WeeklyIntervalStart>
    <WeeklyIntervalFinish>
      <Day>Tuesday</Day>
      <Time>12:00:00</Time>
    </WeeklyIntervalFinish>
    <Start>2011-01-01T00:00:00</Start>
    <Finish>2011-06-30T00:00:00</Finish>
    <Status>Work</Status>
  </TimePhasedWeeklyInterval>
</TimePhasedWeeklyInterval>

The SingleOccurrenceInterval and its sibling Status represent a single instance of a time-phased weekly interval, resolved to a yearly interval. The nested TimePhasedWeeklyInterval defines the recurring interval.

Operations such as CreateCalendar and UpdateCalendar omit the SingleOccurrenceInterval and its sibling Status.

SXP Identifier

By default, the identifier property of a calendar is Name.

ContractorCapacity Object

A contractor capacity object defines the working capacity of a resource.

You can use ContractorCapacity objects to define the capacity of a contractor organization that employs multiple engineers. For a discussion, see Configuring Contractors in ClickSchedule.

 Web Services that Use the Object

ScheduleService

 XML Representation

<ContractorCapacity>
  <Key>45678</Key>
  <Revision>2</Revision>
  <Stamp>...</Stamp>
  <Engineer>
    <ID>Contractor 1234</ID>
    <District>New York</District>
  </Engineer>
  <StartTime>2016-07-01T00:00:00</StartTime>
  <TimeResolution />
  <Capacity>1500000</Capacity>
  <NumberOfTasks>1000</NumberOfTasks>
  <UsedCapacity_SO>903660</UsedCapacity_SO>
  <UsedTasks_SO>297</UsedTasks_SO>
  <ContractorTimeResolution_SO>Week</ContractorTimeResolution_SO>
</ContractorCapacity>

Properties

Key, Revision, Stamp

See Standard Properties of Business Objects.

Engineer

A reference to the Engineer object representing the contractor.

StartTime
The start of the time interval during which a crew allocation or a contractor capacity is defined. The ContractorCapacity object applies to the time interval from StartTime until the end of the time resolution unit, which is defined in the Engineer.ContractorTimeResolution_SO property.

The value of StartTime must be the start of a time-resolution unit. For example, if Resource.ContractorTimeResolution_SO is Week and Central Settings/Parameters/Factors And Units/FirstDayOfWeek is 2, StartTime must be on a Monday at 00:00.

TimeResolution

This property is no longer in use. For more information about setting the contractor time resolution, see Configuring Contractors in ClickSchedule.

Capacity
The maximum working time of a contractor, in seconds, during the time interval of the ContractorCapacity object. For example, a Capacity of 3,600,000 seconds means that the contractor can supply up to 1000 hours of work during the time interval.

Optionally, the Capacity can include travel time, overhead time, or idle time. You can use the engineer AvailabilityFactor property to correct the Capacity to the actual time available for work.

NumberOfTasks
The maximum number of tasks that can be assigned to a contractor during the time interval of the ContractorCapacity object. A 0 value, which is the default, means that any number of tasks can be assigned to the contractor.
UsedCapacity_SO

(Read-only) The capacity that has already been assigned to the contractor during the time interval, in seconds. The system updates this property automatically as the assignments are created or modified. The value includes:

  • The total Task.Duration of the assigned tasks.
  • If the Resource.FixedTravel property is assigned, the total fixed travel associated with the assigned tasks.
UsedTasks_SO

(Read-only) The number of tasks that have already been assigned to the contractor during the time interval. The system updates this property automatically as the assignments are created or modified.

ContractorTimeResolution_SO

(Read-only) The length of the time interval during which the capacity is defined. The supported values are Day, Week, and Month.

This property is a copy of the Engineer.ContractorTimeResolution_SO property, enabling the Contractor Management view to display the time resolution . Internally, the contractor logic (such as the Contractor Capacity rule) uses only Engineer.ContractorTimeResolution_SO value. The logic ignores the ContractorCapacity.ContractorTimeResolution_SO value.

SXP Identifier

By default, the identifier of a contractor capacity is the combination of the Engineer, TimeResolution, and StartTime properties. For backwards compatibility, the default identifier includes the TimeResolution property even though the property value is no longer in use.

CrewAllocation Object

This object allocates an engineer to a crew. For a discussion, see Configuring Crews in ClickSchedule.

 Web Services that Use the Object

ScheduleService

 XML Representation

<CrewAllocation>
  <Key>12345</Key>
  <Revision>1</Revision>
  <Stamp>...</Stamp>
  <Crew Key="34567">
    <ID>InstallationCrew01</ID>
    <District>Paddington</District>
  </Crew>
  <StartTime>2009-03-02T00:00:00</StartTime>
  <FinishTime>2009-03-09T00:00:00</FinishTime>
  <AllocatedResource Key="24680">
    <ID>RB1-2345-67</ID>
    <District>Paddington</District>
  </AllocatedResource>
  <ContinueFromHomeBase>true</ContinueFromHomeBase>
  <Critical>true</Critical>
  <Relocation>true</Relocation>
</CrewAllocation>

Properties

Key, Revision, Stamp

See Standard Properties of Business Objects.

Crew

A reference to the Engineer object representing the crew.

StartTime, FinishTime

The time interval of the allocation. For the syntax of these properties, see the Date Parameter.

AllocatedResource

A reference to the Engineer object who is allocated to a crew.

ContinueFromHomeBase

If true, the logic services assume that the engineer returns to his or her home base when the crew allocation ends. If false, the engineer continues from the crew's home base.

For example, an engineer is allocated to a crew from 08:00 to 17:00. From 17:00 to 24:00 the engineer is on-call for emergency tasks. If the engineer is at his or her own home base during the on-call shift, you should set ContinueFromHomeBase to true. If the engineer stays at the crew's home base, you should set ContinueFromHomeBase to false.

If true, Service Edge allows time for travel from the engineer's home base to the crew's home base, and for travel from the crew's home base to the crew's first assignment of the day (and conversely for the last assignment of the day).

Critical

If true, and the allocated engineer is not available for assignment, the entire crew should not be assigned.

Relocation

True if the allocation is a relocation, and false if the allocation is to a crew.

SXP Identifier

By default, the identifier property of a crew allocation is Key.

Dictionary Items

Click Field Service Edge uses dictionaries to store strings that are used as the values of certain properties. For example, a task has properties called Region, District, and TaskType. The values of these properties are strings that are stored in the Region, District, and TaskType dictionaries, respectively.

The objects stored in dictionaries are called dictionary items. For example, the Region dictionary might contain items named London and New York.

 Web Services that Use the Object

All web services

Dictionary Identifiers

Each dictionary has a name, such as Region, District, or TaskType.

A dictionary also has a numerical ID. To ascertain the ID, right-click the dictionary in the Service Edge Structure tool, and click Properties. For example, the ID of the Region dictionary is 50.

Dictionary Properties

Dictionary items have the following properties:

Key, Revision

See Standard Properties of Business Objects.

Name

The string value of the item.

In some dictionaries, there are additional properties. For example, the District dictionary has a property called TimeZone, which you can use to store the time zone name of each district.

 XML Representation

In SXP messages and in web operations, dictionary items are represented in the following way:

<Region>
  <Key>34123456</Key>
  <Revision>1</Revision>
  <Name>London</Name>
</Region>

Here, London is the name of an item in the Region dictionary. The key of the item is 34123456, and this is the first revision of the item.

If the dictionary has additional properties, they are included in the web-service representation.

Elements Containing Items from Any Dictionary

In some web operations, a single element can contain an item from any dictionary. The operations use the following representation for dictionary items:

<Object 
  xsi:type="Region"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <Name>London</Name>
</Object>

The representation uses the xsi:type attribute to identify the dictionary. For an example, see the CreateDictionaryItem Operation.

SXP Identifier

By default, the identifier property of a dictionary item is its Name.

Related Topics

Standard Properties of Business Objects

Parameters of Web Operations

Multiresource Tasks and Teamwork

Configuring Crews in ClickSchedule

Calendars

Standard Properties of Business Objects

ServiceOptimization Web Service, S - Z

Configuring Contractors in ClickSchedule

Business Objects Reference, E - Z

For comments related to product functionality, please post your question in the ClickAccess Community.