This page presents operations in the ServiceOptimization web service, alphabetically from S to Z.

SetReferencedObjects Operation

This operation imports a set of objects to the database.

The main use of the operation is for settings management. Use GetReferencedObjects to export settings objects from a Service Edge database, and use SetReferencedObjects to import the settings to another database. For more information, see the GetReferencedObjects Operation,

Partially Created Objects

When you import an object, the operation might encounter references to other objects that do not yet exist in the target database. For example, when you import a schedule policy, the domain might reference rules that that have not yet been imported.

When this happens, the operation instantiates the referenced objects and adds them to the target database. However, it cannot fully assign the properties of the referenced objects. The referenced objects are said to be partially created.

Later, when you import the referenced objects, the operation assigns their properties. The referenced objects are then fully created.

If you do not import the referenced objects, the partially created objects remain in the database. If any partially created objects remain at the end of the import, the operation returns a report. You can then import the objects, or you can configure their properties manually.

Alternatively, you can set the input parameters to process the entire import in a single transaction and to roll back the transaction if any partially created objects remain in the database. The import transaction is committed only if all objects are fully created.

Belongs To

ServiceOptimizationService

Request Syntax

<SetReferencedObjects>
  <ImportExportObjectReferenceInfos>
    ...
  </ImportExportObjectReferenceInfos>
  <OneTransact>...</OneTransact>
  <ValidateOnly>...</ValidateOnly>
  <RollBackIfPartiallyCreatedObjectsExist>
    ...
  </RollBackIfPartiallyCreatedObjectsExist>
</SetReferencedObjects>

Response Syntax

<SetReferencedObjectsResponse>
  <SetReferencedObjectsResult>...</SetReferencedObjectsResult>
</SetReferencedObjectsResponse>

Request Parameters

ImportExportObjectReferenceInfos

A list of the objects, in the format returned by the GetReferencedObjects Operation.

OneTransact

If true, the operation processes the entire import in a single transaction. If any object fails to be imported, the entire transaction is rolled back.
If false, each object is imported in an independent transaction. If an object fails, the response contains an error message about the specific failure.

ValidateOnly

If true, the operation validates the list of objects, but it does not perform the import.

RollBackIfPartiallyCreatedObjectsExist

This parameter controls the behavior if any partially created objects remain in the target database at the end of the import:

If OneTransact = true and RollBackIfPartiallyCreatedObjectsExist = true, the import transaction is rolled back.
If OneTransact = false or RollBackIfPartiallyCreatedObjectsExist = false, partially created objects do not cause the import to be rolled back. Instead, the response contains a report of the partially created objects.

Response Parameters

SetReferencedObjectsResult

The operation returns:

IsValid: true if the input is valid.
Failures: information about lines of the input that caused an import failure.

The keys of objects that were PartiallyCreated, Updated, or Created.

<SetReferencedObjectsResult>
  <IsValid>true</IsValid>
  <Failures>
    <FailureInfo>
      <Description>...</Description>
      <File>...</File>
      <Line>...</Line>
      <Source>...</Source>
    </FailureInfo>
    ...
  </Failures>
  <PartiallyCreated>
    <int>...</int>
    ...
  </PartiallyCreated>
  <Updated>
    <int>...</int>
    ...
  </Updated>
  <Created>
    <int>...</int>
    ...
  </Created>
</SetReferencedObjectsResult>

SetStatusFlow Operation

This web operation is not recommended for user programming.

StopAgent Operation

This operation stops the execution of a Service Edge agent.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPServerStopAgent

Request Syntax

<StopAgent>
  <AgentName>...</AgentName>
</StopAgent>

Response Syntax

<StopAgentResponse />

Request Parameters

AgentName

The name of the agent.

StopPolling Operation

This operation stops a computation that runs in an asynchronous thread.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPPollingStop

Request Syntax

<StopPolling>
  <PollingID>...</PollingID>
</StopPolling>

Response Syntax

<StopPollingResponse>
  <Status>...</Status>
</StopPollingResponse>

Response Parameters

Status

The element has a value of true if the operation successfully updated the thread to stop, or if the thread was already stopped.

TestConnection Operation

This operation tests a connection to the Service Edge server.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPServerConnectionTest

Request Syntax

<TestConnection>
  <Connection>...</Connection>
</TestConnection>

Response Syntax

<TestConnectionResponse>
  <Valid>...</Valid>
</TestConnectionResponse>

Request Parameters

Connection

A reference to the connection object.

<Connection Key="12345">
  <Name>...</Name>
</Connection>

Response Parameters

Valid

If true, the connection is active.

UpdateCalendar Operation

This operation updates an existing calendar.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPCalendarUpdate

Request Syntax

<UpdateCalendar>
  <UseCalendarTimeZone>...</UseCalendarTimeZone>
  <Calendar>...</Calendar>
  <CalendarIntervals>...</CalendarIntervals>
  <OverwriteExisting>...</OverwriteExisting>
</UpdateCalendar>

Response Syntax

<UpdateCalendarResponse>
  <Calendar>...</Calendar>
  <OverlappingWeeklyIntervals>...</OverlappingWeeklyIntervals>
</UpdateCalendarResponse>

Request Parameters

UseCalendarTimeZone

If true, the system uses the calendar time zone to convert yearly intervals. If false, the system uses the server time zone for conversions.

Calendar

The Calendar object, including the updated property values. See the Calendar Object.
To reference the existing calendar, you must supply its key and/or identifier properties. If you specify additional properties, the operation updates the property values. If you omit a property, the existing value is retained.
Do not include the calendar time intervals in this parameter.

CalendarIntevals

A list of the calendar time intervals. For the syntax of the nested elements, see the Calendar Object.

<CalendarIntervals>
  <YearlyLevel>...</YearlyLevel>
  <YearlyShiftLevel>...</YearlyShiftLevel>
  <WeeklyLevel>...</WeeklyLevel>
  <WeeklyShiftLevel>...</WeeklyShiftLevel>
  <TimePhasedWeeklyLevel>...</TimePhasedWeeklyLevel>
</CalendarIntervals>

To delete an existing interval from a calendar, update it with a Status value of Undefined. To delete an existing shift interval, update it with a null Shift value.

OverwriteExisting

This parameter controls the behavior when the operation detects a conflict between a new interval and existing intervals. You can assign the parameter at the top level, and you can override its value in the individual intervals.
The operation detects a conflict under the following circumstances:

A new yearly interval is on the same day as one or more existing yearly intervals.
If OverwriteExisting = true, the operation deletes the existing intervals on that day and adds the new interval.
If OverwriteExisting = false, the operation adds the new interval and combines it with the existing intervals. For example, if there is an existing work interval of Jan 10 09:00-17:00, and you add a nonwork interval of Jan 10 12:00-13:00, then 09:00-12:00 and 13:00-17:00 are still defined as work intervals.
A new weekly interval is on the same day as one or more existing weekly intervals.
If OverwriteExisting = true, the operation deletes the existing intervals on that day and adds the new interval.
If OverwriteExisting = false, the operation adds the new interval and combines it with the existing intervals. For example, if there is an existing work interval of Tuesday 09:00-17:00, and you add a nonwork interval of Tuesday 12:00-13:00, then 09:00-12:00 and 13:00-17:00 are still defined as work intervals.
A new time-phased weekly interval has start and finish dates that overlap an existing time-phased weekly interval.
If OverwriteExisting = true, and the new interval coincides with the existing interval, the operation replaces the existing interval. Coincides means that the two intervals have the same Start, Finish, WeeklyIntervalStart, and WeeklyIntervalFinish.
Otherwise, the operation rejects the new interval.

Response Parameters

Calendar

This parameter contains the updated calendar object. See the Calendar Object.

OverlappingWeeklyIntervals

A list of time-phased weekly intervals that were rejected because they conflict with other time-phased weekly intervals. See the OverlappingWeeklyIntervals Parameter.

Example

The following request adds a yearly activity interval to Calendar1:

<UpdateCalendar>
  <Calendar>
    <Name>Calendar1</Name>
  </Calendar>
  <CalendarIntervals>
    <YearlyLevel>
      <YearlyInterval>
        <TimeInterval>
          <Start>2009-07-04T00:00:00</Start>
          <Finish>2009-07-05T00:00:00</Finish>
          <OverwriteExisting>false</OverwriteExisting>
        </TimeInterval>
        <Status>NonWork</Status>
      </YearlyInterval>
    </YearlyLevel>
  </CalendarIntervals>
  <OverwriteExisting>false</OverwriteExisting>
</UpdateCalendar>

UpdateCalendars Operation

This web operation is not recommended for user programming.

UpdateDictionaryItem Operation

This operation updates an existing dictionary item.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPDictionaryItemUpdate

Request Syntax

<UpdateDictionaryItem>
  <Object xsi:type="...">...</Object>
  <RequestedProperties>...</RequestedProperties>
</UpdateDictionaryItem>

Response Syntax

<UpdateDictionaryItemResponse>
  <Object>...</Object>
</UpdateDictionaryItemResponse>

Request Parameters

Object

The dictionary item object, including the updated property values. See the Object Parameter.
To reference the existing dictionary item, you must supply its key and/or identifier properties. 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.
Use the xsi:type attribute to specify the dictionary name:

<Object xsi:type="TaskType">
  <Key>12345</Key>
  <Name>Cabling</Name>
</Object>

RequestedProperties

See the RequestedProperties Parameter.

Response Parameters

Object

The updated dictionary item. See the Object Parameter.

UpdateObjects Operation

This operation updates the property values of a set of business objects. You can use the operation to assign uniform property values to all objects in the set. For example, you can set the Active property of a set of engineers to False.

You can define the objects to update in one of the following ways:

You can list their keys.
You can specify a group containing the objects.
You can specify an index on the object type. The operation updates all objects whose properties lie between the lower and upper bounds of the index.

If you do not define a set of objects, the operation updates all objects of the specified type.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPServerUpdateObjects

Request Syntax

<UpdateObjects>
  <ObjectType>...</ObjectType>
  <Properties>...</Properties>
  <Indexes>...</Indexes>
  <Group>...</Group>
  <EnableGroupOnTheFly>...</EnableGroupOnTheFly>
  <KeySet>...</KeySet>
  <OneTransaction>...</OneTransaction>
  <ContinueOnError>...</ContinueOnError>
</UpdateObjects>

Response Syntax

<UpdateObjectsResponse>
  <FailedOperations>...</FailedOperations>
</UpdateObjectsResponse>

Request Parameters

ObjectType

The type of business object.

<ObjectType>Engineer</ObjectType>

Properties

A list of the properties and their values.

<Properties>
  <Property>
    <Name>Active</Name>
    <Value>False</Value>
  </Property>
  ...
</Properties>

Indexes

An index defining lower and upper bounds on properties of the objects. See the Indexes Parameter.

Group

A group object. See the Group Object.
If the group does not exist in the Service Edge database, specify its properties. You must set EnableGroupOnTheFly = true.
If you specify only the Key and/or identifier properties of the group (without any other properties), the operation uses a group object that exists in the database.

EnableGroupOnTheFly

If true, the Group parameter can contain the definition of a group that does not exist in the database.

KeySet

The keys of the objects to update. See the KeySet Parameter.

OneTransaction

If true, the server updates all the objects in a single transaction. If any update fails, the complete set is aborted and rolled back. If false, each update is a separate transaction.

ContinueOnError

Whether to continue after an update fails.
If OneTransaction is false and ContinueOnError is false, the server stops at the first failed update but does not roll back any preceding updates. If ContinueOnError is true, the server continues with the succeeding updates.
If OneTransaction is true, ContinueOnError has no effect.

Response Parameters

FailedOperations

If the updates succeed, the response contains an empty FailedOperations element.
If any of the updates fail and OneTransaction is false, the server returns a list of the objects that could not be updated and an explanation of the error.
If the updates fail and OneTransaction is true, the server returns an error response.
See the FailedOperations Parameter.

UpdateResource Operation

This operation updates an existing resource (engineer) object.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPEngineerUpdate

Request Syntax

<UpdateResource>
  <Resource>...</Resource>
  <RequestedProperties>...</RequestedProperties>
</UpdateResource>

Response Syntax

<UpdateResourceResponse>
  <Resource>...</Resource>
</UpdateResourceResponse>

Request Parameters

Resource

The resource object, including the updated property values. See the Resource Object.
To reference the existing resource, you must supply its key and/or identifier properties. 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.

RequestedProperties

See the RequestedProperties Parameter.

Response Parameters

Resource

The updated resource object. See the Resource Object.

UpdateSetting Operation

This operation updates an existing central setting.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPSettingUpdate

Request Syntax

<UpdateSetting>
  <Setting>...</Setting>
  <RequestedProperties>...</RequestedProperties>
</UpdateSetting>

Response Syntax

<UpdateSettingResponse>
  <Setting>...</Setting>
</UpdateSettingResponse>

Request Parameters

Setting

The setting object, including the updated property values. See the Setting Object.
To reference the existing setting, you must supply its key and/or identifier properties. 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.

RequestedProperties

See the RequestedProperties Parameter.

Response Parameters

Setting

The updated setting object. See the Setting Object.

UpdateUserSetting Operation

This operation updates an existing user setting, for example, the personal setting of a ClickSchedule user.

The operation is identical to UpdateSetting, , except that it updates a user setting rather than a central setting.

Belongs To

ServiceOptimizationService

Corresponding SXP Message

SXPUserSettingUpdate

Request Syntax

<UpdateUserSetting>
  <Setting>...</Setting>
  <RequestedProperties>...</RequestedProperties>
</UpdateUserSetting>

Response Syntax

<UpdateUserSettingResponse>
  <Setting>...</Setting>
</UpdateUserSettingResponse>

Request Parameters

Setting

The user-setting object, including the updated property values. See the Setting Object.
To reference the existing user setting, you must supply its key and/or identifier properties. 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.