Parameters of Web Operations

This page explains some parameters that are used in numerous web operations.


The following parameters are used in many of the web operations documented on other pages of this reference.

In certain operations, the parameter syntax might differ from the syntax that is described here. We have commented about such cases in the individual web operations. An example is the TimeInterval Parameter. In most cases, this parameter has the syntax:

<TimeInterval>
  <Start>2009-01-01T00:00:00</Start>
  <Finish>2009-07-01T00:00:00</Finish>
</TimeInterval>

In the ConvertDates Operation, the parameter has an additional ID attribute:

<TimeInterval ID="1">
  <Start>2009-01-01T00:00:00</Start>
  <Finish>2009-07-01T00:00:00</Finish>
</TimeInterval>

Date Parameter

A date and time.

In XML, the dates are in the ISO 8601 format. If you use a language such as C#, Visual Basic, or Java to call the web services, the dates have the native date-time data type of the language.

Date parameters can have names such as Date, Start, or Finish.

Used In

All web services

Syntax

In the XML representation, dates have the following format:

yyyy-mm-ddThh:mm:ss

For example, the following date is March 7, 2009 at 3:25:00 pm:

<Date>2009-03-07T15:25:00</Date>

If you omit the time, then 00:00:00 is assumed. Thus

<Date>2000-03-07</Date>

is equivalent to

<Date>2000-03-07T00:00:00</Date>

Optionally, you can include decimal fractions of seconds and the time-zone offset from GMT:

<Date>2009-03-07T15:25:00.0000000-05:00</Date>

Dates Parameter

A list of dates and times.

Used In

ServiceOptimizationService

Syntax

<Dates>
  <Date>2009-02-05T09:15:00</Date>
  <Date>2009-02-05T16:30:00</Date>
  ...
</Dates>

Nested Parameters

Date

See the Date Parameter.

FailedOperations Parameter

This parameter records operations that a web operation failed to perform.

Used In

ServiceOptimizationService

Syntax

<FailedOperations>
  <Operation>
    <Action>...</Action>
    <Object>...</Object>
    <Error>
      <ErrorNumber>...</ErrorNumber>
      <ErrorDescription>...</ErrorDescription>
      <ErrorSource>...</ErrorSource>
    </Error>
  </Operation>
  ...
</FailedOperations>

Example

The DeleteObjects operation might return the following FailedOperations:

<FailedOperations> 
  <Operation>
    <Action>Delete</Action> 
    <Task>
      <CallID>AABB7676</CallID> 
      <Number>7776</Number> 
    </Task>
    <Error>...</Error> 
  </Operation> 
  ... 
</FailedOperations>

Indexes Parameter

This parameter defines lower and/or upper bounds on the properties of a business object. The web services use the parameter to select objects for processing.

There must be an index on the properties. To define indexes, use the Schema Editor.

Used In

ServiceOptimizationService, ScheduleService

Syntax

The generic syntax is:

<Indexes>
  <Index>
    <LowBound>
      <Property>
        <Name>...</Name>
        <Value>...</Value>
      </Property>
      <Property>
        ...
      </Property>
      ...
    </LowBound>
    <HighBound>
      <Property>
        <Name>...</Name>
        <Value>...</Value>
      </Property>
      <Property>
        ...
      </Property>
      ...
  </Index>
  <Index>
    ...
  </Index>
  ...
  <Distinct>...</Distinct>
</Indexes>

If you specify a single Index element, and Distinct is true, the Indexes parameter selects a single object per index value. If false (default), the parameter can select multiple objects per index value.

If you specify multiple Index elements, the parameter selects every object that lies between the bounds of any of the indexes. The Distinct element is ignored.

Example

The following example uses the Task_Status_DueDate index to select task objects. The Indexes parameters selects tasks having a status of Open and a DueDate between April 1 and April 3.

<Indexes>
  <Index>
    <LowBound>
      <Property>
        <Name>Status</Name>
        <Value>Open</Value>
      </Property>
      <Property>
        <Name>DueDate</Name>
        <Value>2009-04-01T00:00:00</Value>
      </Property>
    </LowBound>
    <HighBound>
      <Property>
        <Name>Status</Name>
        <Value>Open</Value>
      </Property>
      <Property>
        <Name>DueDate</Name>
        <Value>2009-04-04T00:00:00</Value>
      </Property>
    </HighBound>
  </Index>
  <Distinct>false</Distinct>
</Indexes>

KeySet Parameter

This parameter is a list of business-object keys.

Used In

ServiceOptimizationService, ScheduleService

Syntax

<KeySet>
  <Key>12345</Key>
  <Key>23456</Key>
  ...
</KeySet>

Object Parameter

The Object parameter designates a business object or dictionary item.

In some operations, this parameter is called BaseObject.

Used In

ServiceOptimizationService

Syntax

Depending on the web operation where it is used, an Object parameter can contain:

  • A complete object with all its properties.
  • A complete object, but without the Key and Revision. This is the case for Create requests.
  • A partial object containing selected properties. This is the case for Update requests. Only the specified properties are updated.
  • A reference to an object, containing the Key, the identifier properties, or both.

Use the xsi:type attribute to identify the object type. The following example illustrates a Task Object:

<Operation>
  <Action>Create</Action>
  <Object>
    <Object
      xsi:type="Task" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <Key>...</Key>
      <Revision>...</Revision>
      <Stamp>...</Stamp>
      <CallID>...</CallID>
      <Number>...</Number>
      ...
    </Object>
  </Object>
</Operation>

Usage for Dictionary Items

In some web operations, the Object parameter can contain an item belonging to any dictionary. Use the xsi:type attribute to specify the dictionary name.

For example, the following Object is a dictionary item called Electrical, belonging to the TaskType dictionary.

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

For a discussion, see Dictionary Items. For an example, see the CreateDictionaryItem Operation.

Operation Parameter

This parameter defines an operation that a web service should perform.

Used In

ServiceOptimizationService

Syntax

<Operation>
  <Action>...</Action>
  <Object>
    <Object xsi:type="Task" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      ...
    </Object>
  </Object>
  <RequestedProperties>...</RequestedProperties>
</Object>

Nested Parameters

Action

The action that the web operation performs. The action value can be:

  • Create: Adds an object to the database.
  • Update: Updates an object that already exists in the database.
  • Delete: Deletes an object from the database.
    Some web operations support the following additional actions:
  • CreateOrUpdate: Updates the object if it already exists, or creates a new object if it does not yet exist.
  • CreateUnique: Creates the object only if it does not already exist.
  • PreviewCreate: Same as Create, but does not commit the result. Use this option to simulate the operation and view the effects of any events that the operation triggers.
  • Preview: Same as CreateOrUpdate, but does not commit the result. Use this option to simulate the operation and view the effects of any events that the operation triggers.
  • GetObject: Retrieves an object.
  • GetReference: Retrieves a reference to an object.
Object/Object

The object on which to perform the action. Use the xsi:type attribute to specify the object type. See the Object Parameter.
In a create operation, omit the Key, Revision, and Stamp properties. The server assigns these properties. For example, to create a Task object, you might specify:

<Operation>
  <Action>Create</Action>
  <Object>
    <Object
      xsi:type="Task" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
      <CallID>Job123</CallID>
      <Number>1</Number>
      <Region>London</Region>
      <District>Soho</District>
    </Object>
  </Object>
</Operation>

In an update operation, you must supply the Key and/or identifier properties of the object. If you specify additional properties, the operation updates the property values. If you supply a blank property value, the existing value is deleted. If you omit a property, the existing value is retained.
In a delete or get-object operation, you can provide a reference to the object rather than the complete object.

<Operation>
  <Action>Delete</Action>
    <Object Key="12345"
      xsi:type="Task" 
      xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" />
</Operation>
RequestedProperties

In a get-object operation, the properties to retrieve. See the RequestedProperties Parameter.

OverlappingWeeklyIntervals Parameter

This parameter contains a list of time-phased weekly intervals that were rejected because they conflict with other time-phased weekly intervals.

Used In

ServiceOptimizationService

Syntax

<OverlappingWeeklyIntervals>
  <OverlappingWeeklyInterval>
    <RejectedInterval>
      <TimePhasedWeeklyInterval>
        <WeeklyIntervalStart>
          <Day>...</Day>
          <Time>...</Time>
        </WeeklyIntervalStart>
        <WeeklyIntervalFinish>
          <Day>...</Day>
          <Time>...</Time>
        </WeeklyIntervalFinish>
        <Start>...</Start>
        <Finish>...</Finish>
        <Status>...</Status>
      </TimePhasedWeeklyInterval>
    </RejectedInterval>
    <ExistingInterval>
      <TimePhasedWeeklyInterval>
        <Start>...</Start>
        <Finish>...</Finish>
        <Status>...</Status>
      </TimePhasedWeeklyInterval>
    </ExistingInterval>
  </OverlappingWeeklyInterval>
  ...
</OverlappingWeeklyIntervals>

Nested Parameters

RejectedInterval

An interval that was rejected. See the Calendar Object.

ExistingInterval

The conflicting interval.

Paths Parameter

This parameter specifies a list of navigation nodes.

Used In

ScheduleService

Syntax

<Paths>
  <Path>...</Path>
  <Path>...</Path>
  ...
</Paths>

RequestedProperties Parameter

A list of object properties to include in the response. If you do not specify RequestedProperties, the response contains the full set of properties.

If a web operation returns multiple objects, it can have multiple RequestedProperties parameters. For example, if an operation returns both an assignment and a task, it might have parameters called AssignmentRequestedProperties and TaskRequestedProperies.

Used In

All web services

Syntax

<RequestedProperties>
  <Item>Key</Item>
  <Item>Name</Item>
</RequestedProperties>

Nested Parameters

Item

The property name.

TimeInterval Parameter

A time interval.

Many web operations have time-interval parameters called Period, SchedulingHorizon, or other names. Some web operations have Start and Finish parameters that are not wrapped in a TimeInterval element. The syntax of these parameters is similar to that of TimeInterval.

Used In

All web services

Syntax

<TimeInterval>
  <Start>2009-04-01T00:00:00</Start>
  <Finish>2009-05-01T00:00:00</Finish>
</TimeInterval>

In the ConvertDates Operation, the parameter has an ID attribute:

<TimeInterval ID="1">
  <Start>2009-04-01T00:00:00</Start>
  <Finish>2009-05-01T00:00:00</Finish>
</TimeInterval>

Nested Parameters

For the syntax of Start and Finish, see the Date Parameter.

Interval Boundaries

Throughout the Service Edge system, a time is considered to lie within an interval if:

  • It is greater than or equal to the Start time, and
  • If is less than the Finish time

In the above example, the interval includes all times in April. It does not include any time in May.

The following XML, although syntactically correct, does not represent the same interval. It omits the last second of April.

<!-- Not recommended -->
<TimeInterval>
  <Start>2009-04-01T00:00:00</Start>
  <Finish>2009-04-30T23:59:59</Finish>
</TimeInterval>

In some cases that 23:59:59 format can cause errors. A sequence of daily intervals, written in this way, would not be consecutive because the intervals omit the last second of each day.

TimeIntervals Parameter

A list of time intervals.

Used In

ServiceOptimizationService, ScheduleService

Syntax

<TimeIntervals>
  <TimeInterval>...</TimeInterval>
</TimeIntervals>

Nested Parameter

See the TimeInterval Parameter.

TimeZone Parameter

This parameter specifies a time zone.

The valid time zone names are defined in the following registry key on the Service Edge server:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows NT\CurrentVersion\TimeZones

Click Field Service Edge supports the time-zone names that are assigned to the std registry parameters.

Used In

ServiceOptimizationService

Syntax

<TimeZone>Eastern Standard Time</TimeZone>

In some web operations, the TimeZone element contains nested elements such as the offset from GMT and a description.

Violations Parameter

A list of rule violations. The violation text is defined in the rule setting.

Used In

ScheduleService

Syntax

<Violations>
  <Violation>
    <ViolationText>...</ViolationText>
  </Violation>
  ...
</Violations>

Related Topics

ServiceOptimization Web Service, A - C

Business Objects Reference, A - D

Business Objects Reference, E - Z

Time Zones

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