OTWeb SVC

OMNITRACKER
The OMNINET
Problem and Request Tracking System
OMNITRACKER Web Service Manual
Version 10.3 (build 6274)

(C) Copyright 1996-2014 by OMNINET GmbH

2014 OMNINET GmbH
Information in this document is subject to change without notice and does not represent a commitment on the part
of OMNINET GmbH. The software described in this document is furnished under the software license agreement
distributed with the product. The software may be used or copied only in accordance with the terms of the license.
The purchaser may make one copy of the software for a backup, but no part of this user manual may be reproduced,
stored in a retrieval system, or transmitted in any form or by any means electronic or mechanical, including
photocopying and recording for any purpose other than the purchaser?s personal use, without prior written
permission from OMNINET GmbH.
Printed: Oktober 2014 in Germany
(C) Copyright 1996-2014 by OMNINET GmbH

All Rights Reserved.
OMNITRACKER and OMNINET are registered trademarks of OMNINET GmbH.
Microsoft, Windows, Win32, Windows NT, Windows 95, Visual Basic , Visual C++ are registered trademarks of
Microsoft Corporation.
Other brand and product names are either trademarks or registered trademarks of their respective holders.
Contents
Table of Contents
Foreword
Part I Introduction
Part II Frequently Asked Questions
10
Part III Reference
14
1 The
...................................................................................................................................
configuration file Web.config
14
2 Authentication
................................................................................................................................... 15
3 Session
...................................................................................................................................
Pooling
17
4 Cache
...................................................................................................................................
settings
18
5 Data
...................................................................................................................................
Types in OMNITRACKER
19
6 Methods
................................................................................................................................... 20
AddObject......................................................................................................................................................... 20
GetObjectList
......................................................................................................................................................... 21
InvokeScript
......................................................................................................................................................... 22
ModifyObject
......................................................................................................................................................... 23
Rem oveObject
......................................................................................................................................................... 24
7 Objects
................................................................................................................................... 25
AddedAttachm
.........................................................................................................................................................
ent
25
AddedAttachm
.........................................................................................................................................................
entsVal
26
AddObjectData
......................................................................................................................................................... 27
AddObjectResult
......................................................................................................................................................... 29
Attachm ent
......................................................................................................................................................... 29
Attachm entModificationsVal
......................................................................................................................................................... 31
Attachm entsVal
......................................................................................................................................................... 32
BoolVal ......................................................................................................................................................... 33
ByteVal ......................................................................................................................................................... 34
CurrencyVal
......................................................................................................................................................... 35
DateTim eVal
......................................................................................................................................................... 35
DoubleVal......................................................................................................................................................... 36
Filter
......................................................................................................................................................... 37
Get
......................................................................................................................................................... 38
GetObjectListData
......................................................................................................................................................... 38
GetObjectListResult
......................................................................................................................................................... 41
HistoryItem
......................................................................................................................................................... 42
HistoryVal......................................................................................................................................................... 43
ID
......................................................................................................................................................... 44
InvokeScriptParam
.........................................................................................................................................................
eters
45
InvokeScriptResult
......................................................................................................................................................... 46
LongIntVal......................................................................................................................................................... 47
ModifiedAttachm
.........................................................................................................................................................
ent
47
ModifyObjectData
......................................................................................................................................................... 49
ModifyObjectResult
......................................................................................................................................................... 50
NullVal
......................................................................................................................................................... 51
Object
......................................................................................................................................................... 52
2014 OMNINET GmbH

ObjectData......................................................................................................................................................... 52
ObjectIDs ......................................................................................................................................................... 53
ReferenceListModificationsVal
......................................................................................................................................................... 54
ReferenceListVal
......................................................................................................................................................... 55
ReferenceToUserVal
......................................................................................................................................................... 55
ReferenceVal
......................................................................................................................................................... 56
Rem oveObjectResult
......................................................................................................................................................... 57
RequiredField
......................................................................................................................................................... 58
ScriptParam
.........................................................................................................................................................
eters
59
Section ......................................................................................................................................................... 59
ShortIntVal
......................................................................................................................................................... 60
SingleVal ......................................................................................................................................................... 61
StringVal ......................................................................................................................................................... 62
Tim eStam.........................................................................................................................................................
pedMem oVal
63
66
Part IV Examples
1 A sample
...................................................................................................................................
client with Visual Studio
66
2 A sample
...................................................................................................................................
client without VS
71
3 GetObjectList
...................................................................................................................................
with Filter
75
4 GetObjectList
...................................................................................................................................
by IDs
77
5 AddObject
...................................................................................................................................
simple values
80
6 AddObject
...................................................................................................................................
complex values
81
7 RemoveObject
................................................................................................................................... 83
8 ModifyObject
...................................................................................................................................
simple values
85
9 ModifyObject
...................................................................................................................................
complex values
86
10 InvokeScript
................................................................................................................................... 88
11 Asynchronous
...................................................................................................................................
Calls
91
Index
93
2014 OMNINET GmbH
Part
Introduction
The OMNITRACKER Web Service provides a programming interface to OMNITRACKER in addition
to the COM-based "Automation Interface" and the COM-plugins. Since the COM technology is
supported only in the Windows world, this Web service extends OMNITRACKER, such that
applications running under other operating systems also can access OMNITRACKER.
Therefore it makes available five methods.
AddObject - adds a new object to a folder of the OMNITRACKER database
RemoveObject - removes one object from the database
ModifyObject - changes the content of one object
GetObjectList - retrieves a list of objects according to a filter or by identifier
InvokeScript - calls a server-global script
Each method can also be called asynchronous. See Asynchronous Calls for detail.
Architecture of the OMNITRACKER Web Service

The Web service takes usage of the serialization via XML and transports objects capsuled in SOAP
messages. Thus the reference uses following conventions.
Namespace - XML Namespaces provide a method to avoid element name conflicts. It may
contain elements and attributes.
Element - XML elements structure an XML document and have relationships.
Attribute - Attributes provide further information about elements.
Text - Text is contained by elements and is not bound to any structure or format.
<element xmlns:xyz="namespace definition">
2014 OMNINET GmbH
Introduction
<namespace:element attribute="value">text</element>
...
2014 OMNINET GmbH
Part
II
10
Frequently Asked Questions

Q: What are the software requirements for the Webservice to work?
A: The .NET Framework has to be installed on the computer where the web service will run.
use the .NET Framework version that is specified in the System Requirements document. At
client installation of OMNITRACKER including the Automation Interface must be present
same computer, since the Webservice accesses OMNITRACKER through the OtAut.
requirements only apply to the machine hosting the web service. Clients accessing the web
just need to be able establishing an HTTP connection to the hosting device.
Please
least a
on the
These
service
Q: I have installed the Webservice and called it from my browser. There I got an error
message "Server error in application / Configuration error".
A: The Webservice is probably not configured as application, but as virtual directory. This is an issue
with the setup, which occurs on some machines, but not on every machine. Up to date, we could
not determine the responsible dependency. Nevertheless, manually configuring the Webservice as
application will solve this. Open the IIS Administration Console, right click on the OTWS virtual
directory (the icon is folder like), select Properties. On the "Virtual Directory" tab click "Create" in
order to make this directory an application.
Q: How to call the WSDL page?
A: Use the following url: http://<server>/OTWS/v1.asmx?wsdl
Note: "<server>" must be replaced by the name of the server, where the WebService is installed
on.
Q: I got an error message "The value is outside the expected range" if I try to add/modify
an object using saveEx flags.
A: Depending on the authentication method this error can appear. Open the IIS Administration
Console, open the ApplicationPool which is used by the OTWS and set the managed pipeline mode
to "classic".
Q: When configuring Basic authentication, can I allow specific users unknown to the
domain to gain Webservice access?
A: No. Basic authentication in IIS requires the requesting user to be in member of the domain. Other
users credentials will not pass the IIS barrier.
Q: How can I set a time-out for my request?
A: When using Visual Studio you can set the Timeout attribute from the OTWebService class to set
the time-out in milliseconds.
OTWebService webSvc = new OTWebService();
webSvc.Timeout = 5000; // 5 seconds
When not using Visual Studio you will pass your SOAP query by using some web request object
(the name depends on the utilized language). This object will also allow to set the time-out.
Q: What will happen, if the network connection is severed while querying the web service?
A: Your request will run into a time-out. Even if not set manually, there is a preset time-out normally 10 seconds. Thus, your application will not hang if the web service does not respond in
2014 OMNINET GmbH
11
time.
There might be scenarios, where it is not necessary to wait for the web services response, or where
the response is not needed right after querying (which is the synchronous way). In those situations
you should consider using asynchronous calls of the web services methods.
Q: I got an error message "system.web.services.protocols.soapexception server was unable
to process request" If I try to add large attachments
A: The maxRequestLength was exceeded. In the web.config file the attribute "maxRequestLength"
must be enlarged. If the "httpRuntime" section is comment out, the preceding "" must be removed!
<system.web>
<httpRuntime maxRequestLength="20000"/>
Q: Is there a way to get all fields of objects using the GetObjectList method?
A: If you leave the RequiredFields section empty all fields will be returned, except those of type
Attachment and Memo.
Q: The response from the GetObjectList method is too large as there are many objects
returned. The query takes a very long time to be processed. Can I limit the size of the result
set?
A: The reason for the long processing time is the natural limitation of XML DOM Parsers. For
complex XML documents they require a massive amount of memory. You may hard limit the number
of nodes in the returned XML document using the key OT_Response_Estimated_Nodes_Limit in the
Web.config file. If you do so, in case of a too large result set you will get an error message instead
of a list of objects. This is a global option and affects ALL calls of GetObjectList. Therefore the
option prevents any GetObjectList calls, which could blow up the XML Parsers memory usage.
As a second option you can limit the number of OMNITRACKER objects actually returned by the
GetObjectList method. Implement a pagewise retrieval of objects. See the per-request parameters of
the GetObjectListData object.
Q: How do I get all objects of a folder with the GetObjectList method?
A: Do not specify any Filter or ObjectIDs section. Those two elements are optional, while their
purpose is to delimit the result set of objects.
Q: Can i get the fields of referenced object using the GetObjectList method?
A: Use the character sequence \. to access a referenced objects field (see RequiredField). This
technique cannot be used when adding or modifying objects.
Q: When passing a string with new line characters ( \r\n ), those characters are displayed in
OMNITRACKER as unreadable signs. How do I pass them to be correctly displayed?
A: When dealing with items of the type StringVal, occurrences of the new line character CRLF
(carriage row + line feed, \r\n) have to be replaced by the escaping sequence

because XML-processors replace all occurrences of CRLF with LF. Otherwise your strings will not
be displayed correctly in the OMNITRACKER Windows Client, since Windows Applications expect
CRLF instead of LF.
Q: The method GetObjectList throws the error "There is an error in XML document", Stack:
2014 OMNINET GmbH
12

at System.Xml.Serialization.XmlSerializer.Deserialize(...)?
A: This error occurs if you try to receive fields of type "List of references", if the field of at least one
returned object is empty. This is a known problem of the XmlSerializer.Deserialize method.
Workarounds:
make sure that each reference list contains at least one object
or get reference list values using a custom InvokeScript
2014 OMNINET GmbH
Part
III
14
Reference
3.1
The configuration file Web.config

In order to work properly the web service requires some information about the connection to the
dedicated OMNITRACKER server.
The host name and port number of the OMNITRACKER server, as well as the OMNITRACKER user
name and password are retrieved are stored in the services Web.config file. It is located in the top
folder of the web service. The following format is used:
<appSettings>
<add key="OT_Hostname" value="localhost"/>
<add key="OT_Port" value="5085"/>
<add key="OT_User" value="superuser"/>
<add key="OT_Password" value="superuser"/>
<add key="use_HTTP_authentication" value="false"/>
<add key="use_IWA_authentication" value="false"/>
<add key="OT_Session_Timeout" value="1"/>
<add key="OT_Session_Timeout_Units" value="hour"/>
<add key="OT_SessionPool" value="3" />
<add key="OT_Response_Estimated_Node_Limit" value="2000" />
<add key="DefaultScriptExecutionSite" value="Client" />
<add key="Caching_Enable_xxx" value="true"/>
<add key="Caching_Timeout_xxx" value="30"/>
<add key="Caching_Timeout_Units_xxx" value="min"/>
<add key="Caching_Scope_xxx" value="user"/>
</appSettings>
The service connects to the OMNITRACKER server reachable at OT_Hostname:OTPort, in this case
localhost:5085, and identifies itself as the user OT_User with the password OT_Password, user
"superuser" with password "superuser" (please note: if the Web Service runs on a node in a loadbalancing cluster, then the DNS name of the cluster must be instead of "localhost").
With this settings the service will not use HTTP basic authentication. It may use the Integrated
Windows authentication or Anonymous Login; see Authentication for more detail. Sessions on this
server will be terminated after 1 hour of idle-time. A value of 0 means, sessions do not time-out.
Furthermore a service with such a configuration uses a session pool with a maximum of 3 sessions
at the OMNITRACKER server; see Session Pooling for detail information.
Scripts called by the InvokeScript method will by default be executed on client side. The default
behaviour can be overwritten at request level. Possible values are "Client" and "Server". The default
value here is "Server".
The caching-parameters, which apply to the invocation of scripts, are described in the topic Cache
settings.
The OT_Response_Estimated_Node_Limit settings limits the output size of the GetObjectList
method. Large XML documents have a noticable impact on the XML DOM parsers performance.
When documents get too large, the ASP.NET worker process might even run out of memory.
Therefore the GetObjectList method can be enabled to estimate the number of XML nodes of
response. It may then reject the request in case of an expectedly large document. The estimated
number of nodes is never greater than the actual number of nodes.
2014 OMNINET GmbH
Reference
15
If login information is set to an invalid configuration, the web service will respond to every request
with the following message:
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:
xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<AddObjectResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<AddObjectResult success="false" objectId="0"
errorMsg="Could not get a session object from the
OMNITRACKER server. Please check your appSettings in the
Web.config." />
</AddObjectResponse>
</soap:Body>
</soap:Envelope>
Since OMNITRACKER version 8.5.100 the webservice will not store any data in HTTP-sessions
anymore, as they can consume a large amount of memory. The disabling of HTTP-sessions is
completely independent from the OMNITRACKER-sessions. As result of this change the Web.config
file contains a new line of code:
...
<sessionState mode="Off" />
...
Note: If you are migrating from an earlier version of OMNITRACKER, you should add this line to your
existing Web.config file at the end of the <system.web> XML node. You may alternatively disable
HTTP-session state inside the IIS management console, which will add this line automatically.
3.2
Authentication
The OMNITRACKER Web Service allows three different ways of authentication.
Anonymous Login: The Web Service logs on to the OMNITRACKER using an account
predefined in the appSettings of the Web.config file. Use the following settings:
o allow Anonymous Login in IIS
o Web.config: set a value to the fields: OT_User and OT_Password, set
use_HTTP_authentication to false
<appSettings>
<add key="OT_User" value="someDefaultUser"/>
<add key="OT_Password" value="thePassword"/>
2014 OMNINET GmbH
16

</appSettings>
Integrated Windows Authentication: The Web Service logs on by using the credentials
provided by the client application. The credentials are encrypted. Can only be in a Windows
environment. Use the following settings:
o In the Internet Information Services set the authentication for the Web Service to
Integrated Windows Authentication, uncheck the Anonymous Login.
o Web.config-file: Set use_HTTP_authentication to false and use_IWA_authentication to
true. Set authentication mode to Windows and identity impersonate to true. Please
refer to the ASP.NET documentation for further information. You may provide a
standard user and a password. If so, then all users passing the Basic Authentication
get mapped to that standard user
<appSettings>
<add key="OT_User" value="optional"/>
<add key="OT_Password" value="optional"/>
<add key="use_IWA_authentication" value="true"/>
</appSettings>
<system.web>
<authentication mode="Windows" />
<identity impersonate="true" />
<authorization>
...
</authorization>
</system.web>
o Configure your client application to support this kind of authentication
o In order to let IIS support identity impersonation set the application pool of the web
service application inside IIS to "Classic .NET AppPool".
o Add to your OMNITRACKER database a login account with authentication type set to
Windows.
Basic Authentication (HTTP): The Web Service logs on by using the credentials provided by the
client application. The credentials are NOT encrypted. Therefore in addition to this steps a
secure connection over SSL or HTTPS should be established. Use the following settings:
o Configure IIS to support Basic Authentication
o Web.Config-file: Set use_HTTP_authentication to true and use_IWA_authentication to
false. You may provide a standard user and a password. If so, then all users passing
the Basic Authentication get mapped to that standard user.
<appSettings>
2014 OMNINET GmbH
Reference
17

<add key="OT_User" value="optional"/>
<add key="OT_Password" value="optional"/>
<add key="use_HTTP_authentication" value="true"/>
</appSettings>
<system.web>
<authentication mode="None" />
<identity impersonate="false" />
<authorization>
...
</authorization>
</system.web>
o Configure your client application to support this kind of authentication
If it is undesired to have the standard credentials stored in the Web.config-file ASP.NET provides a
method to read them from the registry. (look for aspnet_setreg.exe)
Note: A simultaneous use of Basic and Integrated Windows Authentication is currently not
supported.
3.3
Session Pooling
The OMNITRACKER Web Service supports session Pooling, which means that clients share a
limited set of sessions to the OMNITRACKER Server. In the example there are three sessions
shared by all connected clients:
<appSettings>
<add key="OT_User" value="superuser"/>
<add key="OT_Password" value="superuser"/>
</appSettings>
When a client sends a request to the web service, then all of the existing sessions are checked, if
they already process the request of another client and if the requesting user equals the user owning
the session. A session already processing a request is marked active as long as it is occupied by
that task. It becomes inactive afterwards. An active session cannot serve the actual clients request.
When no inactive session is available, then a new session is created up to the limit of three
2014 OMNINET GmbH
18

sessions in a whole, because the maximum number of sessions is limited by [OT_SessionPool]. If
there is no inactive session and no space left to create a new one, the client has to wait until any of
the sessions becomes inactive. Each of these sessions times out after [OT_Session_Timeout]
[OT_Session_Timeout_Units] of inactivity. In this case after one hour.
The OT_SessionPool can be set to any number greater or equal zero. A value of 0 means that no
pool is used. Instead each client gets its own session. If the value is set too high, probably each
client will get its own session as well.
The OT_Session_Timeout_Units key can have one of the values:
day
hour
min
sec
If a standard users credentials are provided in the Web.config file, then all sessions in the pool will
be owned by that standard user. See Authentication for more detail.
3.4
Cache settings
Optionally, the results of script calls can be cached in the web service. Subsequent calls of the
same script with the same input parameters will immediately return the result from the cache,
without any communication with the OMNITRACKER server.
The cached results can be configured such that they are removed from the cache after a specified
timeout.
Caching can be configured by the following keys in the <appSettings> element of the Web.config
file:
<add
<add
<add
<add
key="Caching_Enable_xxx" value="true"/>
key="Caching_Timeout_xxx" value="30"/>
key="Caching_Timeout_Units_xxx" value="min"/>
key="Caching_Scope_xxx" value="user"/>
These keys have the following meaning:

Caching_Enable_xxx: can be true or false. Caching is enabled only if the value is true. If the
Caching_Enable_xxx key is missing, caching is disabled.
Caching_Timeout_xxx: specifies the timeout of the cached result (in the units specified by
Caching_Timeout_Units_xxx). If Cach-ing_Timeout_xxx is missing, or if its value is 0, the
cached re-sults never are removed from the cache.
Caching_Timeout_Units_xxx: specifies the units for the Caching_Timeout_xxx key. The possible
values are sec (seconds), min (minutes), hour (hours), or day (days). If
Caching_Timeout_Units_xxx is missing and Caching_Timeout_xxx is present and not 0, an error
message must be logged to the Windows event log. An error message also must be logged, if
Caching_Timeout_Units_xxx contains an invalid value.
Caching_Scope_xxx: indicates whether the cache is user-specific (user) or global (global). If
the cache is user specific, the results cached for user A cannot be seen by user B. If the cache is
global, the results are shared among all users.
If the suffix _xxx is missing, the setting specified by the Web.config key refers to all scripts. If
_xxx is present, the setting refers to the script named xxx only. It shall be possible to mix
settings with and without _xxx; e.g.:
2014 OMNINET GmbH
Reference
19
<add key="Caching_Enable" value="true"/>

<add key="Caching_Enable_GetTime" value="false"/>
<add key="Caching_Enable_GetNumUsers" value="false"/>
means that caching is enabled for all scripts, except for the scripts named GetTime and
GetNumUsers.
3.5
Data Types in OMNITRACKER

The following table describes, which classes of the web service are compatible to which fields in
OMNITRACKER when executing the AddObject or ModifyObject methods. Furthermore it lists the
classes returned by the GetObjectList method:
OMNITRACKER Can be assigned with

field data type
Is returned as
Attachments
AddedAttachmentsVal (AddObject),
AttachmentModificationsVal (ModifyObject)
NullVal, AttachmentsVal
Auto Number
ByteVal, LongIntVal, NullVal, ShortIntVal
LongIntVal, NullVal
Boolean
BoolVal
BoolVal
Byte
ByteVal, LongIntVal*, NullVal, ShortIntVal*
ByteVal, NullVal
Currency
CurrencyVal, NullVal
CurrencyVal, NullVal
Date/Time
DateTimeVal, NullVal
DateTimeVal, NullVal
Drop Down List
NullVal, StringVal*
NullVal, StringVal
Float Double
ByteVal, DoubleVal, LongIntVal, NullVal,

ShortIntVal, SingleVal
DoubleVal, NullVal
Float Single
ByteVal, DoubleVal*, LongIntVal*, NullVal,

ShortIntVal, SingleVal
NullVal, SingleVal
Integer long
ByteVal, LongIntVal, NullVal, ShortIntVal
LongIntVal, NullVal
Integer short
ByteVal, LongIntVal*, NullVal, ShortIntVal
NullVal, ShortIntVal
Memo
NullVal, StringVal
NullVal, StringVal
Memo Time
Stamped
StringVal**
TimeStampedMemoVal
Reference list of ReferenceListVal (AddObject),

objects
ReferencListModificationsVal (ModifyObject)
ReferenceListVal
Reference to
object
NullVal, ReferenceVal
NullVal, ReferenceVal
Reference to
user
NullVal, ReferenceToUserVal
NullVal, ReferenceToUserVal
2014 OMNINET GmbH
20
Schedule
You cannot assign values to fields of this

NullVal, StringVal
type; supported by the GetObjectList method
only
Text
NullVal, StringVal
NullVal, StringVal
Workflow
NullVal, StringVal*
NullVal, StringVal
* The assigned value has to be element of the fields co-domain. Otherwise an error will
occur, e.g. the value 300 is about to be assigned to a field of the type Byte, which allows
values between 0 and 255.
** Setting a time stamped memo with a string value adds a new section to the field.
3.6
Methods
3.6.1
AddObject
The AddObject web method adds a new object to an OMNITRACKER folder.
Syntax:
<AddObject xmlns="http://www.omninet.de/OtWebSvc/v1">
<Object folderPath="ServiceDesk\Incidents">
<StringVal name="Title">This is a sample incident</StringVal>
...
</Object>
</AddObject>
Response:
<AddObjectResult success="true" objectId="4711"/>
OR
If an error occurred during the execution, which resulted in cancelling the request.
<AddObjectResult success="false" errorMsg="A description of the
error."/>
2014 OMNINET GmbH
Reference
21
Elements:
AddObjectData, describes the object to be added.
See AddObjectResult for information about the response.
Example 1 (simple), Example 2 (complex)
3.6.2
GetObjectList
The GetObjectList web method returns a list of objects from OMNITRACKER. The selection of
objects can be performed by providing the name of an existing filter for a folder, a list of object
identifiers or just a folder. For all matching objects the methods response will show the fields
specified as RequiredField. While these fields can be retrieved by the field name or alias, in the
response the alias is displayed. If there is no alias for a field, then its name will be returned.
Not specifying any RequiredField elements returns all fields of the object, except fields of type
Attachment or Memo. Time-stamped memos are returned.
It is also possible to retrieve the history of OMNITRACKER objects via this method. To do so, the
optional parameter getHistory has to be set to true.
Syntax:
<GetObjectList xmlns="http://www.omninet.de/OtWebSvc/v1">
<Get folderPath="ServiceDesk\Incidents" recursive="true">
<Filter>MyFilter</Filter>
<RequiredField>Title</RequiredField>
<RequiredField>CreationDate</RequiredField>
...
</Get>
</GetObjectList>
Response:
<GetObjectListResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<GetObjectListResult success="true">
<Object id="4711">
...
</Object>
<Object id="4712">
...
</Object>
...
</GetObjectListResult>
</GetObjectListResponse>
2014 OMNINET GmbH
22
OR
If an error occurred during the execution, which resulted in cancelling the request.
<GetObjectListResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<GetObjectListResult success="false" errorMsg="A description for
the error." />
Elements:
GetObjectListData, named Get, describes which objects shall be retrieved, and what object
fields shall be returned.
See GetObjectListResult for information about the response.
Example 1 (by filter), Example 2 (by IDs)
3.6.3
InvokeScript
The InvokeScript method calls a server-global script on the OMNITRACKER server.
Syntax:
<InvokeScript xmlns="http://www.omninet.de/OtWebSvc/v1">
<Script name="GetFolderInfo">
<Parameters>
<StringVal name="para_in_1">a value</StringVal>
...
</Parameters>
</Script>
</InvokeScript>
Response:
<InvokeScriptResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<InvokeScriptResult success="true">
<Parameters>
<LongIntVal name="para_out_1">21312</LongIntVal>
<StringVal name="para_out_2">John</StringVal>
...
</Parameters>
</InvokeScriptResult>
</InvokeScriptResponse>
2014 OMNINET GmbH
Reference
23
OR
If an error occurred during the execution, which resulting in cancelling the request.
<InvokeScriptResult success="false"
errorMsg="A description for the error occurred."/>
Elements:
The parameter Script contains the script name and the input parameters for the script. The
return value contains the output parameters of the script. Those parameters can be of the
following types: NullVal, BoolVal, ByteVal, ShortIntVal, LongIntVal, SingleVal, DoubleVal,
DateTimeVal, StringVal, CurrencyVal.
Example 1
3.6.4
ModifyObject
The ModifyObject web method modifies attributes of an already existing object.
Syntax:
<ModifyObject xmlns="http://www.omninet.de/OtWebSvc/v1">
<Object objectId="4711">
<StringVal name="Title">This is a modified title</StringVal>
...
</Object>
</ModifyObject>
Response:
<ModifyObjectResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<ModifyObjectResult success="true" />
</ModifyObjectResponse>
OR
An error occurred during the processing, which resulted in cancelling the web request.
<ModifyObjectResult success="false"
2014 OMNINET GmbH
24

errorMsg="A description for the error."/>
Elements:
ModifyObjectData describes the modifications that shall be made to an Object.
See ModifyObjectResult for information about the response.
Example 1 (simple), Example 2 (complex)
3.6.5
RemoveObject
The RemoveObject web method removes a single object from an OMNITRACKER folder.
Syntax:
<RemoveObject xmlns="http://www.omninet.de/OtWebSvc/v1">
<ObjectID>4711</ObjectID>
<IgnoreReferences>true</IgnoreReferences>
</RemoveObject>
Response:
<RemoveObjectResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<RemoveObjectResult success="true"/>
</RemoveObjectResponse>
OR
If an error occurred during the execution, which resulting in cancelling the request.
<RemoveObjectResponse xmlns="http://www.omninet.de/OtWebSvc/v1">
<RemoveObjectResult success="false"
errorMsg="A description for the occurred error."/>
Elements:
The parameter ObjectID contains the unique ID of the object that shall be deleted.
The optional parameter UseTrashBin is of type Boolean. If the value is true, then the deleted
object is moved to the trashbin instead of completely removing it from the OMNITRACKER
database. The default is false.
The optional parameter IgnoreReferences is of type Boolean. If the value is true, then the
object can be deleted although it is referenced by other objects. The default is false.
See RemoveObjectResult for information about the response.
2014 OMNINET GmbH
Reference
25
Example 1
3.7
Objects
3.7.1
AddedAttachment
AddedAttachment describes an attachment that shall be added to a field of an OMNITRACKER
object. Can only be used as child element of the Attachments element in the AddedAttachmentsVal
object or of the AddedAttachments element in the AttachmentModificationsVal object.
XML serialized
Syntax:
A link is added to the list of attachments.
<AddedAttachment description="something useful" link="true"

name="foo.bar" url="c:\tests\foo.bar" />
OR
The binary data of a file is stored in the attachments list under the provided name.
<AddedAttachment link="false" name="email.msg">SGVsbG8gd29ybGQh</

AddedAttachment>
Attributes:
link Indicates whether the attachment is a link (true) or a file (false).
name Name of the attachment.
description Description of the attachment.
url If link is true, then url must contain the URL of the link, e.g. http://www.omninet.de.
Text:
data If link is false, then data must contain the binary data (a string in base64 encoding) of
the attachment.
C# - Definition
public class AddedAttachment
2014 OMNINET GmbH
26

{
[XmlAttribute]
public bool link;
[XmlAttribute]
public string name;
[XmlAttribute]
public string description;
[XmlAttribute]
public string url;
[XmlText]
public byte[] data;
}
3.7.2
AddedAttachmentsVal
AddedAttachmentsVal indicates that one or more attachments shall be assigned to a field name.
The use of this class is valid in the context of the AddObject method only.
XML serialized
Syntax:
A link as well as a file are added to the attachments.

<AddedAttachmentsVal name="attachments">
<Attachments>
name="foo.bar" url="c:\tests\foo.bar" />
<AddedAttachment link="false"
name="email.msg">SGVsbG8gd29ybGQh</AddedAttachment>
...
</Attachments>
</AddedAttachmentsVal>
Attributes:
name Name of the field; this can be the field alias or the field name in server language. While
for a request the name can be the alias or name, in a response the alias is shown. If there
exists no alias for a field, then its name will be returned.
Elements:
2014 OMNINET GmbH
Reference
27
Attachments List containing any number of attachments of the type AddedAttachment.
C# - Definition
public class AddedAttachmentsVal

{
[XmlAttribute]
public string name;
public AddedAttachment[] Attachments;
}
3.7.3
AddObjectData
AddObjectData specifies an object that shall be added to the OMNITRACKER database. It specifies
the necessary data for the AddObject method.
XML serialized
Syntax:
A new object is added to the database, where it is declared by the element Object.
<Object folderPath="ServiceDesk\Incidents" fieldMapping="myMapping"
saveExFlags="23" username="carl" password="carlsPassword">
<any number of elements from the value types, which define the
objects properties/>
</Object>
Attributes:
folderPath Folder to which the object shall be added. \ characters are used to separate the
folder name. E.g.: ServiceDesk\Incidents means: add the object to the folder Incidents,
which is a subfolder of the top-level folder ServiceDesk.
fieldMapping A field mapping which shall be used to fill in default values in the fields of the
created object. This parameter is optional, leaving it blank or not specifying it all, causes the
web service to use no field mapping.
saveExFlags By default the new object is created using the standard Save method of the
OtRequest object. This optional parameter allows to set the flags of the SaveEx method,
which will be used instead of Save. (See Automation Interface Help for details on SaveEx
flags). Due to security reasons, the saveExFlags parameter is always ignored unless one of
the following conditions is met:
.1.The user is authenticated via Integrated Windows Logon (NTLM) and the user is a superuser
in OMNITRACKER
2014 OMNINET GmbH
28

.2.The user is authenticated via HTTP Basic Authentication, the user is a superuser in
OMNITRACKER and the connection to the webservice has been established using HTTPS
.3.the parameter username equals the parameter OT_User in the Web.config, the parameter
password equals the parameter OT_Password in the Web.config and the connection to the
webservice has been established using HTTPS
username An optional parameter to use in combination with saveExFlags.
password An optional parameter to use in combination with saveExFlags.
Elements:
properties List of name-value pairs that contains the values that shall be assigned to the
fields of the newly created object. At least one property has to be specified, even if it is one of
the type NullVal, otherwise the web service will not process this request.
C# - Definition
public class AddObjectData

{
[XmlAttribute("folderPath")]
public string strFolderPath;
[XmlAttribute("fieldMapping")]
public string strFieldMapping;
[XmlAttribute("saveExFlags")]
public int saveExFlags;
[XmlAttribute("username")]
public string strUsername;
[XmlAttribute("password")]
public string strPassword;
[XmlElement(typeof(NullVal))]
[XmlElement(typeof(BoolVal))]
[XmlElement(typeof(ByteVal))]
[XmlElement(typeof(ShortIntVal))]
[XmlElement(typeof(LongIntVal))]
[XmlElement(typeof(SingleVal))]
[XmlElement(typeof(DoubleVal))]
[XmlElement(typeof(DateTimeVal))]
[XmlElement(typeof(StringVal))]
[XmlElement(typeof(CurrencyVal))]
[XmlElement(typeof(AddedAttachmentsVal))]
[XmlElement(typeof(ReferenceVal))]
[XmlElement(typeof(ReferenceListVal))]
[XmlElement(typeof(ReferenceToUserVal))]
public object[] properties;
}
2014 OMNINET GmbH
Reference
3.7.4
29
AddObjectResult
AddObjectResult indicates the result of the AddObject web method.
XML serialized
Syntax:
<AddObjectResult success="true" objectId="4711" errorMsg="if error
occurred" />
Attributes:
success is true if the operation succeeded; is false if the operation failed. In the latter case,
errorMsg contains an error message.
errorMsg contains an error message if success is false.
objectId contains the unique ID of the newly added object.
C# - Definition
public class AddObjectResult

{
[XmlAttribute]
public bool success;
[XmlAttribute]
public int objectId;
public string errorMsg;
}
3.7.5
Attachment
This element describes a single attachment in a field of attachments. It is only available as
descendant of the Attachments element in the AttachmentsVal object.
XML serialized
Syntax:
A link is retrieved from the list of attachments.
2014 OMNINET GmbH
30
<Attachment attachmentId="71" description="something useful"

link="true" name="c:\tests\foo.bar" creationDate="2007-0509T08:12:01" lastModification="2007-05-09T08:13:13" />
OR
The binary data of a file from the attachments list.
<Attachment attachmentId="72" link="false" name="email.msg"
creationDate="2007-05-09T08:12:01" lastModification="2007-0509T08:13:13" >SGVsbG8gd29ybGQh</Attachment>
Attributes:
url If link is true, then url contains the URL of the link, e.g. http://www.omninet.de.
Text:
data If link is false, then data contains the binary data (a string in base64 encoding) of the
attachment.
C# - Definition
public class Attachment

{
[XmlAttribute]
public Int32 attachmentId;
[XmlAttribute]
public bool link;
[XmlAttribute]
public string name;
[XmlAttribute]
public string url;
[XmlAttribute]
[XmlAttribute]
public DateTime creationDate;
2014 OMNINET GmbH
Reference
31
[XmlAttribute]
public DateTime lastModification;
[XmlText]
public byte[] data;
};
3.7.6
AttachmentModificationsVal
AttachmentModificationsVal describes the modifications that shall be applied to an attachment field
during a ModifyObject operation. The use of this class is valid in context of the that method only.
XML serialized
Syntax:
<AttachmentModificationsVal name="attachments">
<DeletedAttachments>
<ID>75</ID>
<ID>76</ID>
...
</DeletedAttachments>
<ModifiedAttachments>
<ModifiedAttachment attachmentId="78" description="modified
link" link="true" name="test.foo" url="tests\foo1.bar" />
<ModifiedAttachment attachmentId="79" description="modified
file" link="false" name="mod.mehl">SGVsbG8gd29ybGQh</
ModifiedAttachment>
...
</ModifiedAttachments>
<AddedAttachments>
name="foo.bar" url="c:\tests\foo2.bar" />
name="email.msg">SGVsbG8gd29ybGQh</AddedAttachment>
...
</AddedAttachments>
</AttachmentModificationsVal>
Attributes:
name - Name of the attachment field; this can be the field alias or the field name in server
language. While for a request the name can be the alias or name, in a response the alias is
shown. If there exists no alias for a field, then its name will be returned.
Elements:
2014 OMNINET GmbH
32

AddedAttachments List of added attachments.
ModifiedAttachments List of modified attachments.
DeletedAttachments List of unique IDs of the removed attachments.
Each of the three elements can be left blank or away; e.g.
<AttachmentModificationsVal name="attachments">
<ModifiedAttachments />
<AddedAttachments>
...
</AddedAttachments>
C# - Definition
public class AttachmentModificationsVal

{
[XmlAttribute]
public string name;
public AddedAttachment[] AddedAttachments;
public ModifiedAttachment[] ModifiedAttachments;
public ID[] DeletedAttachments;
}
3.7.7
AttachmentsVal
AttachmentsVal describes the contents of an OMNITRACKER field of the attachment type. This
class is only available in the context of the GetObjectList method.
XML serialized
Syntax:
A link as well as a file have been retrieved from the attachments.

<AttachmentsVal name="attachments">
<Attachments>
<Attachment attachmentId="71" description="something useful"
link="true" creationDate="2007-05-09T08:12:01"
lastModification="2007-05-09T08:13:13" name="foo.bar" url="c:
2014 OMNINET GmbH
Reference
33
\tests\foo.bar" />
<Attachment attachmentId="72" link="false" name="email.msg"
creationDate="2007-05-09T08:12:01" lastModification="2007-0509T08:13:13">SGVsbG8gd29ybGQh</Attachment>
...
</Attachments>
</AttachmentsVal>
Attributes:
name Name of the field; this can be the field alias or the field name in server language. While
Elements:
Attachments List containing any number of attachments of the type Attachment.
C# - Definition
public class AttachmentsVal

{
[XmlAttribute]
public string name;
public Attachment[] Attachments;
}
3.7.8
BoolVal
BoolVal describes a boolean value that shall be assigned to a field of an OMNITRACKER object.
Can be a descendant of either AddObjectData, Parameters (input and output of InvokeScript),
ObjectData or ModifyObjectData.
XML serialized
Syntax:
<BoolVal name="isReady">false</BoolVal>
Attributes:
name - Name of the field; this can be the field alias or the field name in server language. While
2014 OMNINET GmbH
34
Text:
Boolean value.
C# - Definition
public class BoolVal

{
[XmlAttribute]
public string name;
[XmlText]
public bool value;
}
3.7.9
ByteVal
ByteVal describes an unsigned byte value that shall be assigned to a field of an OMNITRACKER
object. Can be a descendant of either AddObjectData, Parameters (input and output of InvokeScript),
XML serialized
Syntax:
<ByteVal name="byte_field">31</ByteVal>
Attributes:
Text:
Unsigned byte value (range: 0 to 255).
C# - Definition
public class ByteVal

{
[XmlAttribute]
2014 OMNINET GmbH
Reference
35
public string name;

[XmlText]
public byte value;
}
3.7.10 CurrencyVal
CurrencyVal describes a currency value that shall be assigned to a field of an OMNITRACKER
XML serialized
Syntax:
<CurrencyVal name="costs">200.52</CurrencyVal>
Attributes:
Text:
Currency value.
C# - Definition
public class CurrencyVal

{
[XmlAttribute]
public string name;
[XmlText]
public decimal value;
}
3.7.11 DateTimeVal
DateTimeVal describes a date/time value that shall be assigned to a field of an OMNITRACKER
2014 OMNINET GmbH
36
XML serialized
Syntax:
<DateTimeVal name="first_occured">2006-04-18T19:30:10.7</DateTimeVal>
Attributes:
Text:
Date/time value.
C# - Definition
public class DateTimeVal

{
[XmlAttribute]
public string name;
[XmlText]
public DateTime value;
}
3.7.12 DoubleVal
DoubleVal describes a double-precision floating-point value that shall be assigned to a field of an
OMNITRACKER object. Can be a descendant of either AddObjectData, Parameters (input and
output of InvokeScript), ObjectData or ModifyObjectData.
XML serialized
Syntax:
<DoubleVal name="diameter">2.75647364539</DoubleVal>
Attributes:
2014 OMNINET GmbH
Reference
37
Text:
Double-precision floating-point value.
C# - Definition
public class DoubleVal

{
[XmlAttribute]
public string name;
[XmlText]
public double value;
}
3.7.13 Filter
Describes an existing filter in the context of an OMNITRACKER folder.
XML serialized
Syntax:
<Filter>New RFCs</Filter>
OR with parameters
<Filter>New RFCs<StringVal name="para1">Example*</StringVal></Filter>
OR filter name as attribute
<Filter name="New RFCs"><StringVal name="para1">Example*</
StringVal></Filter>
Elements:
parameters - Zero or more parameters for Ask user conditions of the filter. Not all parameters
have to be set.
Attributes:
2014 OMNINET GmbH
38

name - The name of the filter in server language. If the attribute name is set the XML-Text is
ignored. If the attribute name is null or empty the XML-Text is used instead.
Text:
The name of the filter in server language.
C# - Definition
public class Filter

{
[XmlText]
public string strFilterName;
[XmlAttribute]
public string name;
public object[] Parameter;
};
3.7.14 Get
See:
GetObjectListData
3.7.15 GetObjectListData
GetObjectListData describes which objects and fields shall be retrieved from the OMNITRACKER
database by the method GetObjectList.
XML serialized
2014 OMNINET GmbH
Reference
Syntax:
Retrieve a number of objects by utilizing a filter. In this case also include subfolders.
<Get folderPath="ServiceDesk\Incidents" recursive="true"
getHistory="false">
<Filter>New RFCs</Filter>
<RequiredField>Attachments</RequiredField>
<RequiredField>Stunden</RequiredField>
...
</Get>
OR
Select the object by their unique identifier.
<Get folderPath="" recursive="false">
<ObjectIDs objectIDs="4711 4712 ..." />
...
</Get>
OR
Select all objects from the folder with or without subfolders, in this case without.
<Get folderPath="ServiceDesk\Incidents" recursive="false">
...
</Get>
OR
Get at most 20 objects of a folder starting from index 100 and retreive all user fields.
<Get folderPath="ServiceDesk\Incidents" recursive="false"
minimumIndex="100" maximumRecords="20">
</Get>
OR
Get the unique identifers of all objects in a folder and do not retrieve any user fields.
2014 OMNINET GmbH
39
40

<Get folderPath="ServiceDesk\Incidents" recursive="false"
getNoFields="true">
</Get>
Attributes:
folderPath - Folder from which the objects shall be retrieved. \ characters are used to
separate the folder name. E.g.: ServiceDesk\Incidents means: retrieve the objects from the
folder Incidents, which is a subfolder of the top-level folder ServiceDesk.
recursive Indicates whether or not objects from subfolders shall be retrieved as well.
getHistory If true, then the history of retrieved objects will be returned, too.
getNoFields If true, then only the unique identifers of objects are returned.
minimumIndex This attribute can be used to retrieve subsets of the returned objects. For
example you can implement a pagewise retrieval of objects. the attribute specifies the index of
the first object to include in the result list. Indices are zero-based.
maximumRecords When set to a value other than 0, no more than the specified number of
objects will be returned.
selector Indicates which objects shall be retrieved:
If selector is missing, all objects of the folder (and optionally its subfolders) are retrieved.
If selector contains a Filter element, all objects matching the filter are retrieved.
If selector contains an ObjectIDs element, all objects with the specified ObjectID are
retrieved.
Elements:
RequiredField Contains the names of the fields whose values shall be returned for each
returned object.
C# - Definition
public class GetObjectListData

{
[XmlAttribute("folderPath")]
public string strFolderPath;
[XmlAttribute("recursive")]
public bool bRecursive;
[XmlAttribute("getHistory")]
public bool bGetHistory;
[XmlAttribute("getHistory")]
public bool bGetNoFields;
[XmlAttribute]
public int minimumIndex;
[XmlAttribute]
public int maximumRecords;
2014 OMNINET GmbH
Reference
41
[XmlElement(typeof(Filter))]
[XmlElement(typeof(ObjectIDs))]
public object selector;
[XmlElement("RequiredField")]
public RequiredField[] aRequiredFields;
}
3.7.16 GetObjectListResult
GetObjectListResult indicates the result of the GetObjectList web method.
XML serialized
Syntax:
<GetObjectListResult success="true" errorMsg="A description for an
occurred error" totalNumberResults="15">
<Object id="4711">
...
</Object>
<Object id="4712">
...
</Object>
...
Attributes:
totalNumberResults the total number of OMNITRACKER objects, which match the query.
Even if only a subset of records is requested using the parameters
GetObjectListData.minimumIndex
and
GetObjectListData.maximumRecords,
totalNumberResults shows the nuzmber of all matching objects.
Element:
Object A list of the returned objects.
C# - Definition
public class GetObjectListResult
2014 OMNINET GmbH
42

{
[XmlAttribute]
[XmlAttribute]
[XmlAttribute]
public int totalNumberResults;
[XmlElement("Object")]
public ObjectData[] aObjects;
}
3.7.17 HistoryItem
HistoryItem represents an entry in the history of an OMNITRACKER object. It is always a child
element of HistoryVal.
XML serialized
Syntax:
<Section action="10">
<Date>2008-04-18T19:25:50.3</Date>
<Description>Object created.</Description>
<NewValue/>
<OldValue/>
<State/>
<User>brian</User>
<UserField/>
</Section>
Attributes
action The type of action, which triggered the history entries creation. See Automation
Interface help "Action Property" of OtHistoryItem.
Elements:
Date - The creation date of the history entry.
Description - A textual description of the history entry.
NewValue - If applicable, holds the new value of the changed field.
OldValue - If applicable, contains the old value of the changed field.
State - The state the object was in.
User - The display name of the user, who caused the change.
UserField - The affected user field.
2014 OMNINET GmbH
Reference
43
C# - Definition
public class HistoryItem

{
[XmlAttribute("action")]
public int action;
[XmlElement("Date")]
public DateTime date;
[XmlElement("Description")]
[XmlElement("NewValue")]
public string newValue;
[XmlElement("OldValue")]
public string oldValue;
[XmlElement("State")]
public string state;
[XmlElement("User")]
public string user;
[XmlElement("UserField")]
public string userField;
}
3.7.18 HistoryVal
HistoryVal describes the history of an OMNITRACKER object. Can be a descendant of ObjectData
in scope of the GetObjectList method.
XML serialized
Syntax:
<HistoryVal>
<HistoryItem action="17">
...
</HistoryItem>
<HistoryItem action="14">
2014 OMNINET GmbH
44

...
</HistoryItem>
...
</HistoryVal>
Elements:
HistoryItem.
C# - Definition
public class HistoryVal

{
[XmlElement("HistoryItem")]
public HistoryItem[] aItems;
}
3.7.19 ID
ID describes a single ID of an OMNITRACKER object or attachment.
XML serialized
Syntax:
<ID>71</ID>
Text:
Unique ID.
C# - Definition
public class ID
{
[XmlText]
public Int32 UID;
}
2014 OMNINET GmbH
Reference
45
3.7.20 InvokeScriptParameters
InvokeScriptParameters describes which server-global script should be executed with a set of
parameters by the method InvokeScript.
XML serialized
Syntax:
<Script name="GetFolderInfo" runAt="Default">
<Parameters>
...
</Parameters>
</Script>
Attributes:
name - The name of a server-global script.
runAt - Scripts can be executed on "Client" or "Server" side. The option "Default" will execute
the script at the location specified in the Web.config.
Elements:
Parameters Contains the parameters passed to the script.
C# - Definition
public enum ScriptExecutionSite

{
Default = 0,
Server = 1,
Client = 2
}
public class InvokeScriptParameters
{
[XmlAttribute("name")]
public string name;
[XmlAttribute("runAt")]
public ScriptExecutionSite runAt;
[XmlElement("Parameters")]
2014 OMNINET GmbH
46

public RequiredField[] aRequiredFields;
}
3.7.21 InvokeScriptResult
InvokeScriptResult indicates the result of the InvokeScript web method.
XML serialized
Syntax:
<InvokeScriptResult success="true" errorMsg="">
<Parameters>
<LongIntVal name="para_out_1">21312</LongIntVal>
<StringVal name="para_out_2">John</StringVal>
...
</Parameters>
Attributes:
Element:
Parameters A list of the returned objects.
C# - Definition
public class InvokeScriptResult

{
[XmlAttribute]
[XmlAttribute]
[XmlElement("Parameters")]
public ScriptParameters parameters;
}
2014 OMNINET GmbH
Reference
47
3.7.22 LongIntVal
LongIntVal describes a 4-byte signed integer value that shall be assigned to a field of an
XML serialized
Syntax:
<LongIntVal name="count">2000</LongIntVal>
Attributes:
Text:
4-byte signed integer value.
C# - Definition
public class LongIntVal

{
[XmlAttribute]
public string name;
[XmlText]
public Int32 value;
}
3.7.23 ModifiedAttachment
ModifiedAttachment describes an attachment that shall be modified during a ModifyObject operation.
XML serialized
Syntax:
2014 OMNINET GmbH
48

<ModifiedAttachment attachmentId="78" description="modified link"
link="true" name="test.xml" url="C:\test\foo3.bar" />
OR
<ModifiedAttachment attachmentId="79" description="modified file"
link="false" name="mod.mehl">AAUKDxQRHhsoLQ==</ModifiedAttachment>
Attributes:
attachmentId contains the unique ID of the attachment.
url If link is true, then url must contain the URL of the link, e.g. http://www.omninet.de.
Text:
data If link is false, then data must contain the binary data (a string in base64 encoding) of
the attachment.
C# - Definition
public class ModifiedAttachment

{
[XmlAttribute]
public Int32 attachmentId;
[XmlAttribute]
public bool link; //read-only in OT
[XmlAttribute]
public string name; //read-only in OT
[XmlAttribute]
[XmlAttribute]
public string url; //read-only in OT
[XmlText]
public byte[] data;
}
2014 OMNINET GmbH
Reference
49
3.7.24 ModifyObjectData
ModifyObjectData describes which fields of an object shall be modified.
XML serialized
Syntax:
<Object objectId="4711" saveExFlags="23" username="carl"
password="carlsPassword">
<StringVal name="Title">This is a modified title</StringVal>
...
</Object>
Attributes:
objectId unique ID of the object that shall be modified.
saveExFlags By default the new object is created using the standard Save method of the
OtRequest object. This optional parameter allows to set the flags of the SaveEx method,
which will be used instead of Save. (See Automation Interface Help for details on SaveEx
flags). Due to security reasons, the saveExFlags parameter is always ignored unless one of
the following conditions is met:
.1.The user is authenticated via Integrated Windows Logon (NTLM) and the user is a superuser
in OMNITRACKER
.2.The user is authenticated via HTTP Basic Authentication, the user is a superuser in
OMNITRACKER and the connection to the webservice has been established using HTTPS
.3.the parameter username equals the parameter OT_User in the Web.config, the parameter
password equals the parameter OT_Password in the Web.config and the connection to the
webservice has been established using HTTPS
username An optional parameter to use in combination with saveExFlags.
password An optional parameter to use in combination with saveExFlags.
Elements:
properties List of name-value pairs that contains the values that shall be assigned to the
fields of the modified object.
C# - Definition
public class ModifyObjectData

{
[XmlAttribute]
public Int32 objectId;
[XmlAttribute("saveExFlags")]
public int saveExFlags;
2014 OMNINET GmbH
50
[XmlAttribute("username")]
public string strUsername;
[XmlAttribute("password")]
public string strPassword;
[XmlElement(typeof(AttachmentModificationsVal))]
[XmlElement(typeof(ReferenceListModificationsVal))]
}
3.7.25 ModifyObjectResult
ModifyObjectResult indicates the result of the ModifyObject web method.
XML serialized
Syntax:
<ModifyObjectResult success="true" />
OR
<ModifyObjectResult success="false"
errorMsg="A description for the error."/>
Attributes:
2014 OMNINET GmbH
Reference
51
C# - Definition
public class ModifyObjectResult

{
[XmlAttribute]
[XmlAttribute]
}
3.7.26 NullVal
NullVal indicates that the value of a field shall be set to empty or that a field has no content. Can
be a descendant of either AddObjectData, Parameters (input and output of InvokeScript), ObjectData
or ModifyObjectData.
XML serialized
Syntax:
<NullVal name="Middle name" />
Attributes:
C# - Definition
public class NullVal

{
[XmlAttribute]
public string name;
}
2014 OMNINET GmbH
52
3.7.27 Object
Represents an object in the OMNITRACKER database.
XML serialized
See:
ObjectData in context of the GetObjectList method
AddObjectData in context of the AddObject method.
ModifyObjectData in context of the ModifyObject method.
C# - Definition
3.7.28 ObjectData
ObjectData describes a single object that is returned by the GetObjectList operation.
XML serialized
Syntax:
<Object id="4711">
... properties
</Object>
Attributes:
nID Unique ID of the object.
Elements:
properties list of name-value pairs that describes the values of the fields of the object.
properties contains only those fields that have been specified in the GetObjectListData/
RequiredField element.
C# - Definition
public class ObjectData
2014 OMNINET GmbH
Reference
{
[XmlAttribute("id")]
public Int32 nID;
[XmlElement(typeof(AttachmentsVal))]
[XmlElement(typeof(ReferenceListVal))]
[XmlElement(typeof(TimeStampedMemoVal))]
[XmlElement(typeof(HistoryVal))]
}
3.7.29 ObjectIDs
ObjectIDs describes a set of IDs of OMNITRACKER objects.
XML serialized
Syntax:
<ObjectIDs objectIDs="148" />
OR
<ObjectIDs objectIDs="148 230 ..." />
Attribute:
objectIDs - a list of unique IDs OMNITRACKER objects.
C# - Definition
2014 OMNINET GmbH
53
54

public class ObjectIDs
{
[XmlAttribute]
public Int32[] objectIDs;
};
3.7.30 ReferenceListModificationsVal
ReferenceListModificationsVal describes the modifications that shall be applied to a reference-list
field during a ModifyObject operation.
XML serialized
Syntax:
<ReferenceListModificationsVal name="reflob" removedObjectIds="80 81
82" addedObjectIds="81" />
Attributes:
name - Name of the reference-list field; this can be the field alias or the field name in server
language. While for a request the name can be the alias or name, in a response the alias is
shown. If there exists no alias for a field, then its name will be returned.
addedObjectIds Unique IDs of the objects that shall be added to the reference list.
removedObjectIds Unique IDs of the objects that shall be removed from the reference list.
C# - Definition
public class ReferenceListModificationsVal

{
[XmlAttribute]
public string name;
[XmlAttribute]
public Int32[] addedObjectIds;
[XmlAttribute]
public Int32[] removedObjectIds;
}
2014 OMNINET GmbH
Reference
55
3.7.31 ReferenceListVal
ReferenceListVal describes a reference list value that shall be assigned to a field of an
OMNITRACKER object. Can be a descendant of either AddObjectData or ObjectData.
XML serialized
Syntax:
<ReferenceListVal name="reflob" objectIds="80 81 82" />
Attributes:
objectIds a list of unique IDs that specifies the objects in the reference list.
C# - Definition
public class ReferenceListVal

{
[XmlAttribute]
public string name;
[XmlAttribute]
public Int32[] objectIds;
}
3.7.32 ReferenceToUserVal
ReferenceToUserVal describes a reference-to-user value that shall be assigned to a field of an
OMNITRACKER object. Can be a descendant of either AddObjectData, ObjectData or
ModifyObjectData.
XML serialized
Syntax:
<ReferenceToUserVal name="refus" type="groupname" Value="Email ReadWrite" />
2014 OMNINET GmbH
56
Attributes:
type Describes how the user or group is identified:
groupname - value contains a user group name.
userdisplayname value contains the display name of a user.
userloginname value contains a login name of a user.
Value Name of the user or group, according to type.
C# - Definition
public class ReferenceToUserVal

{
public enum ValueType {groupname, userdisplayname, userloginname};
[XmlAttribute]
public string name;
[XmlAttribute]
public ValueType type;
[XmlAttribute]
public string Value;
}
3.7.33 ReferenceVal
ReferenceListVal describes a reference value that shall be assigned to a field of an OMNITRACKER
object. Can be a descendant of either AddObjectData, ObjectData or ModifyObjectData.
XML serialized
Syntax:
<ReferenceVal name="refob" objectId="82" />
Attributes:
objectId a unique IDs that specifies the object that shall be assigned to the reference field.
2014 OMNINET GmbH
Reference
57
C# - Definition
public class ReferenceVal

{
[XmlAttribute]
public string name;
[XmlAttribute]
public Int32 objectId;
}
3.7.34 RemoveObjectResult
RemoveObjectResult indicates the result of the RemoveObject web method.
XML serialized
Syntax:
<RemoveObjectResult success="true"/>
OR
<RemoveObjectResult success="false"
errorMsg="A description for the error occurred."/>
Attributes:
C# - Definition
public class RemoveObjectResult

{
[XmlAttribute]
2014 OMNINET GmbH
58

[XmlAttribute]
}
3.7.35 RequiredField
RequiredField specifies the name of a field for which values shall be returned when executing
GetObjectList.
In case of a "reference-to-object" or "reference-to-user" field, the fields of the referenced object can
be retrieved, too. All that has to be done is appending \. and the referenced objects field name. Up to
two reference steps can be resolved, which means expressions like Field1\.Field2\.Field3 can be
resolved.
Note: Occurences of the character \ (backslash) in the required field name should be replaced by a
double backslash \\. For example: If the name of the field is "My\Field" in OMNITRACKER, then it
should be accessed by writing "My\\Field".
XML serialized
Syntax:
OR
<RequiredField>Category\.Title</RequiredField>
Text:
field name Alias of the field or name of the field in the server-default language. Fields of
referenced objects can be retrieved by adding \. followed by the referenced objects field name.
C# - Definition
public class RequiredField

{
[XmlText]
public string strFieldName;
}
2014 OMNINET GmbH
Reference
59
3.7.36 ScriptParameters
A list of name value pairs describing parameters of the InvokeScript function. Before calling the
script, the ScriptParameter object holds the input parameters. After the scripts execution it contains
its output parameters.
XML serialized
Syntax:
<Parameters>
...
</Parameters>
Elements:
Any number of objects of the following types: NullVal, BoolVal, ByteVal, ShortIntVal,
LongIntVal, SingleVal, DoubleVal, DateTimeVal, StringVal, CurrencyVal.
C# - Definition
public class ScriptParameters

{
public object[] Parameter;
}
3.7.37 Section
Section describes a single section in a time-stamped memo field. It is always a child node of
TimeStampedMemoVal.
2014 OMNINET GmbH
60
XML serialized
Syntax:
<Section date="2006-04-18T19:30:10.7" user="superuser"
state="state_1"></Section>
Attributes
date Date/time when the section was created.
user Display name of the user who created the section.
state Alias of the state in which the object was when the section was created. If no alias is
defined, the name of the state is returned. This attribute may be empty.
Text:
Text of the section.
C# - Definition
public class TimeStampedMemoSection

{
[XmlAttribute]
public DateTime date;
[XmlAttribute("user")]
public string strUser;
[XmlAttribute("state")]
public string strState;
[XmlText]
public string strText;
}
3.7.38 ShortIntVal
ShortIntVal describes a 2-byte signed integer value that shall be assigned to a field of an
XML serialized
2014 OMNINET GmbH
Reference
61
Syntax:
<ShortIntVal name="count">2000</ShortIntVal>
Attributes:
Text:
2-byte signed integer value.
C# - Definition
public class ShortIntVal

{
[XmlAttribute]
public string name;
[XmlText]
public Int16 value;
}
3.7.39 SingleVal
SingleVal describes a single-precision floating-point value that shall be assigned to a field of an
XML serialized
Syntax:
<SingleVal name="Hours">2.1</SingleVal>
Attributes:
2014 OMNINET GmbH
62

Text:
Single-precision floating-point value.
C# - Definition
public class SingleVal

{
[XmlAttribute]
public string name;
[XmlText]
public float value;
}
3.7.40 StringVal
StringVal describes a string value that shall be assigned to a field of an OMNITRACKER object. Can
be a descendant of either AddObjectData, Parameters (input and output of InvokeScript), ObjectData
or ModifyObjectData.
Important Note: Occurrences of the new line character CRLF (carriage row + line feed, \r\n) have to
be replaced by the escaping sequence
because XML-processors replace all
occurrences of CRLF with LF. Otherwise your strings will not be displayed correctly in the
OMNITRACKER Windows Client, since Windows Applications expect CRLF instead of LF.
XML serialized
Syntax:
<StringVal name="Memo">test2</StringVal>
Attributes:
Text:
String value.
C# - Definition
2014 OMNINET GmbH
Reference
63
public class StringVal

{
[XmlAttribute]
public string name;
[XmlText]
public string value;
}
3.7.41 TimeStampedMemoVal
TimeStampedMemoVal describes the contents of a time-stamped memo field. It is only available in
the context of the GetObjectList method.
XML serialized
Syntax:
<TimeStampedMemoVal name="">
<Section>
...
</Section>
...
<TimeStampedMemoVal>
Attributes:
Elements:
Sections a list of the memo sections, which are of the type Section.
C# - Definition
public class TimeStampedMemoVal

{
[XmlAttribute]
public string name;
[XmlElement("Section")]
public TimeStampedMemoSection[] aSections;
2014 OMNINET GmbH
64

}
2014 OMNINET GmbH
Part
IV
66
Examples
4.1
A sample client with Visual Studio

In Visual Studio it is rather simple to call methods provided by a web service and transmit objects.
All that has to be done is:
Create your project (e.g. a Console Application)
Add a web reference to your project, while the service is running; Visual Studio will read all
necessary information by processing the WSDL description of the service. It then creates
proxy classes in a namespace, which is "YourNamespace.NameOfTheWebReference"
NOTE:
The examples in this documentation refer to web service references added with "Advanced |
Compatibility | Add Web Reference" (see an example without compatibility mode at the end of this
page)
2014 OMNINET GmbH
Examples
67
Type in the URL of the Web Service and append the parameter "?wsdl" ( Example: http://localhost/
OTWS/v1.asmx?wsdl ).
The newly created namespace now must be included
2014 OMNINET GmbH
68
Now you can access the public methods and classes from the web service as if they were
included in your project.
NOTE:
When dealing with items of the type StringVal, occurrences of the new line character CRLF

be displayed correctly in the OMNITRACKER Windows Client, since Windows Applications
expect CRLF instead of LF.
The names of objects and members in the automatically generated proxy classes may differ from
the ones presented in the C#-Definition sections of the reference book. Take a closer look at these
proxy classes and their member names. You are free to rename them.
The example clients presented here send just a single request to the service, which means that
each call of the Main function will create a new OMNITRACKER session, which might be time
consuming. In order to take advantage of existing sessions, simply reuse the OTWebService object.
The following code retrieves a list of objects from the folder "ChangeMgmt\RFCs" that satisfy a
certain filter.
using System;
using ConsoleApplication1.WebReference1;
namespace ConsoleApplication1
{
class Program
{
static void Main(string[] args)
{
GetObjectListData gold=new GetObjectListData();
// Replace the following lines with your code that
// creates the request
2014 OMNINET GmbH
Examples
gold.folderPath = "ChangeMgmt\\RFCs";
gold.recursive = true;
gold.RequiredField = new RequiredField[5];
gold.RequiredField[0] = new RequiredField();
gold.RequiredField[0].Value="Title";
gold.RequiredField[1].Value="Attachments";
gold.RequiredField[2].Value="Last Change";
gold.RequiredField[3].Value="Priority";
gold.RequiredField[4].Value="Answers";
// Optional: use a filter
Filter flt = new Filter();
flt.name = "Open RFCs";
gold.Item = flt;
try
{
//simply call the proxy for the intended web method
GetObjectListResult golr = webSvc.GetObjectList(gold);
//Do something with the results
if (golr.success)
{
ObjectData[] myObjects = golr.Object;
for (int i = 0; i < myObjects.Length; i++)
{
foreach (object myItem in myObjects[i].Items)
{
if (myItem is NullVal)
{
string field = ((StringVal)myItem).name;
//do something...
}
else if (myItem is StringVal)
{
string val = ((StringVal)myItem).Value;
//do something...
}
else if (myItem is DateTimeVal)
{
string field = ((DateTimeVal)myItem).name;
DateTime dt = ((DateTimeVal)myItem).Value;
//do something...
}
else if (myItem is LongIntVal)
{
string field = ((LongIntVal)myItem).name;
int val = ((LongIntVal)myItem).Value;
//do something...
2014 OMNINET GmbH
69
70

}
else if (myItem is ShortIntVal)
{
//do something...
}
else if (myItem is TimeStampedMemoVal)
{
string field = ((TimeStampedMemoVal)myItem).name;
TimeStampedMemoSection[] sections =
((TimeStampedMemoVal)myItem).Section;
foreach (TimeStampedMemoSection sec in sections)
{
DateTime dt = sec.date;
string state = sec.state;
string user = sec.user;
string val
= sec.Value;
//do something...
}
}
else if (myItem is AttachmentsVal)
{
string field = ((AttachmentsVal)myItem).name;
Attachment[] att = ((AttachmentsVal)myItem)
.Attachments;
foreach (Attachment a in att)
{
string name = a.name;
DateTime dt = a.creationDate;
bool bIsLink = a.link;
byte[] val
= a.Value;
string descr = a.description;
DateTime mod = a.lastModification;
//do something...
}
}
else if (myItem is ReferenceListVal)
{
string field = ((ReferenceListVal)myItem).name;
int[] objects = ((ReferenceListVal)myItem)
.objectIds;
//do something...
}
}
}
}
else
{
string err = golr.errorMsg;
}
}
catch (Exception ex)
{
string err = ex.Message;
}
2014 OMNINET GmbH
Examples
71
}
}
}
Example without compatibility mode

If a service reference is added to your Visual Studio project without using the compatibility mode,
then the "OTWebService" object will not be available. "OTWebServiceSoapClient" can be used
instead:
using System;
using ConsoleApplication1.WebReference1;
namespace ConsoleApplication1
{
class Program
{
static void Main(string[] args)
{
OTWebServiceSoapClient webSvc = new OTWebServiceSoapClient();
GetObjectListData gold = new GetObjectListData();
// Replace the following lines with your code that
// creates the request
gold.recursive = true;
gold.RequiredField[2].Value="Last Change";
...
}
}
}
4.2
A sample client without VS

This sample code for a client defines a method, which uses the .NET framework to establish a
connection to the OMNITRACKER Web Service and transmit a web request. This might be for
example a call for the RemoveObject method as presented in the example. It then waits for the
server to respond and returns the received message.
When accessing the web service with such a client, you will have to define proxy classes for the
2014 OMNINET GmbH
72

server objects. Those classes are presented in the C#-Definition sections of chapters in the
reference book.
The example clients presented here send just a single request to the service, which means that
each call of the SendRequest function will create a new OMNITRACKER session, which might be
time consuming. In order to take advantage of existing sessions, simply reuse the WebRequest
object.
NOTE: When dealing with items of the type StringVal, occurrences of the new line character CRLF

be displayed correctly in the OMNITRACKER Windows Client, since Windows Applications expect
CRLF instead of LF.
C#
...
using System.Net;
using System.Text;
using OTWebSvc;
using System.Xml;
using System.Xml.Serialization;
...
namespace SomeTestClient
{
class TestClient
{
private string host;
private string soapIntro="<soap12:Envelope xmlns:xsi=\"http://
www.w3.org/2001/XMLSchema-instance\" xmlns:xsd=\"http://
www.w3.org/2001/XMLSchema\" xmlns:soap12=\"http://
www.w3.org/2003/05/soap-envelope\">
<soap12:Body>";
private string soapOutro="</soap12:Body></soap12:Envelope>";
...
/* Get the object which will be the input of the web method
* serialize it to a soap request
* get and process the services response
*
* beforehand: create an object of the type GetObjectListData,
* AddObjectListData, ModifyObjectData or Int32
*/
void ProcessRequest(object request)
{
string strRequest = CreateSoapRequest(request);
string strResponse = SendRequest(strRequest);
ProcessResponse(strResponse);
2014 OMNINET GmbH
Examples
}
/*
* Serialize the object to a soap request
*/
string CreateSoapRequest(object request)
{
XmlSerializer xser = new XmlSerializer(typeof
(GetObjectListData));
StringBuilder sb.= new StringBuilder();
StringWriter sw = new StringWriter(sb);
xser.Seserialize(sw,request);
sw.Flush();
sw.Close();
sb.Insert(0, soapIntro);
sb.Append(soapOutro);
return sb.ToString();
}
...
/*
* This methods sends a soap message to the web service
*/
string SendRequest(string strRequest)
{
WebRequest webRequest = WebRequest.Create(host);
webRequest.ContentType = "application/soap+xml;
charset=utf-8";
webRequest.Method = "POST";
Encoding encoding = Encoding.Default;
byte[] strContent=encoding.GetBytes(str);
Stream os = null;
try
{
webRequest.ContentLength = strContent.Length;
os = webRequest.GetRequestStream();
os.Write(strContent);
}
catch (WebException ex)
{
//handle this exception, for instance:
return null;
}
finally
{
if (os != null)
{
os.Close();
}
}
2014 OMNINET GmbH
73
74

string strReturn = "";
try
{
WebResponse webResponse = webRequest.GetResponse();
if (webResponse == null)
{ return null; }
StreamReader sr = new StreamReader
(webResponse.GetResponseStream());
strReturn=sr.ReadToEnd().Trim();
}
catch (WebException ex)
{
//handle this exception, for instance:
return null;
}
return strReturn;
}
void ProcessResponse(string strResponse)
{
XmlDocument xmlDoc = new XmlDocument();
xmlDoc.LoadXml(strXML);
// get rid of soap capsule
XmlElement xmlRoot = xmlDoc.DocumentElement;//soap:
Envelope
XmlNode soapBody=xmlRoot.FirstChild;//soap:Body
XmlNode methodResponse = soapBody.FirstChild;//
MethodsResponse
XmlNode methodResult = methodResponse.FirstChild;//
MethodResult
// read out the xml node and process the different types
// of results
XmlReader xread = new XmlNodeReader(methodResult);
if (methodResult.Name.Equals("GetObjectListResult"))
{
(GetObjectListResult));
GetObjectListResult golr = xser.Deserialize(xread)
as GetObjectListResult;
//...do something
}
else if (methodResult.Name.Equals("AddObjectResult"))
{
(AddObjectResult));
AddObjectResult aor = xser.Deserialize(xread) as
AddObjectResult;
//...do something
}
else if (methodResult.Name.Equals("ModifyObjectResult"))
2014 OMNINET GmbH
Examples
75
{
(ModifyObjectResult));
ModifyObjectResult mor = xser.Deserialize(xread) as
ModifyObjectResult;
//...do something
}
else if (methodResult.Name.Equals("RemoveObjectResult"))
{
(RemoveObjectResult));
RemoveObjectResult ror = xser.Deserialize(xread) as
RemoveObjectResult;
//...do something
}
}
}
}
4.3
GetObjectList with Filter

In this example a list of objects is retrieved from the folder "ChangeMgmt\RFCs" from the
OMNITRACKER ITIL demo database. Following fields are retrieved: Title, Description, LastChange
and Priority. The selection method here is a filter, which has to be defined in the context of the folder
"ChangeMgmt\RFCs" . In this case it is the predefined filter "Open RFCs", which has two
parameters "Priority at least" and "Due before (date)". The attribute recursive is set to "true". This
causes the filter to be applied to the given folder and all of its subfolders; and their descendants as
well (and so on).
XML SOAP message

<soap12:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:
soap12="http://www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<Get folderPath="ChangeMgmt\RFCs" recursive="true">
<Filter>Open RFCs<StringVal name="Priority at
least">Medium</StringVal><DateTimeVal name="Due
before (date)">2007-06-01T12:00:00</DateTimeVal></
Filter>
<RequiredField>Description</RequiredField>
<RequiredField>LastChange</RequiredField>
<RequiredField>Priority</RequiredField>
</Get>
</GetObjectList>
2014 OMNINET GmbH
76

</soap12:Body>
</soap12:Envelope>
The response might look like:

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://
www.w3.org/2003/05/soap-envelope">
<soap12:Body>
<GetObjectListResponse xmlns="http://www.omninet.de/OtWebSvc/
v1">
<GetObjectListResult success="true" errorMsg="">
<Object id="44018">
<StringVal name="Title">Hub austauschen</
StringVal>
<StringVal name="Description">Einen defekten
Hub beim betroffenen Kunden vorort
austauschen.</StringVal>
<DateTimeVal name="LastChange">2007-0509T10:03:29</DateTimeVal>
<StringVal name="Priority">Medium</StringVal>
</Object>
<Object id="44052">
<StringVal name="Title">Benutzerumzug POM</
StringVal>
<StringVal name="Description">Umzug von POM</
StringVal>
<DateTimeVal name="LastChange">2007-0111T17:24:55</DateTimeVal>
<StringVal name="Priority">High</StringVal>
</Object>...
</soap:Body>
</soap:Envelope>
C#
GetObjectListData gold = new GetObjectListData();
/*
* Replace the following lines with your code that
* creates the request
*/
gold.recursive=true;
2014 OMNINET GmbH
Examples
77

gold.RequiredField[2].Value="LastChange";
// add the filter
Filter flt = new Filter();
flt.name = "Open RFCs";
gold.Item = flt;
// a filter with two parameters:
flt.Items = new object[2];
StringVal val1 = new StringVal();
val1.name = "Priority at least";
val1.Value = "Medium";
DateTimeVal val2 = new DateTimeVal();
val2.name = "Due before (date)";
val2.Value = new DateTime(2007, 06, 01);
flt.Items[0] = val1;
flt.Items[1] = val2;
/*
* simply call the proxy for the intended web method
*/
GetObjectListResult golr=webSvc.GetObjectList(gold);
/*
* Check for success; Do something with the results
*/
4.4
GetObjectList by IDs
In this example the fields Title, Priority and Attachments shall be retrieved from the ITIL demo
database of OMNITRACKER for three objects. The objects are retrieved by their unique identifier.
Therefore the folderPath attribute is unused and it can be left blank. Same is true for the recursive
attribute, but since a two valued boolean variable must have a state (true or false) it has to be set.
XML SOAP message

<soap12:Body>
2014 OMNINET GmbH
78

<Get folderPath="" recursive="false">
<ObjectIDs objectIDs="44018 44169 44052" />
<RequiredField>Priority</RequiredField>
</Get>
</GetObjectList>
</soap12:Body>
</soap12:Envelope>
The response might look as follows. Unlike the second and third object, the first contains three
attachments, two links and one binary stored file.
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://
www.w3.org/2003/05/soap-envelope">
<soap:Body>
<GetObjectListResponse xmlns="http://www.omninet.de/OtWebSvc/
v1">
<GetObjectListResult success="true" errorMsg="">
<Object id="44018">
<StringVal name="Title">Hub austauschen</
StringVal>
<AttachmentsVal name="Attachments">
<Attachments>
<Attachment attachmentId="1"
link="true" url="C:
\Programme\OMNITRACKER\ExampleDBs\ITI
L_1.0.300.demo.txt" description=""
creationDate="2007-05-09T08:13:13"
lastModification="2007-0509T08:13:13" />
link="true" url="C:
\Programme\OMNITRACKER\ExampleDBs\PjM
_1.2.0.demo.txt" description=""
creationDate="2007-05-09T08:13:13"
lastModification="2007-0509T08:13:13" />
link="false" name="foo.bar"
description="The work of Prof.
Stegritzki." creationDate="2007-0509T10:03:29.9"
lastModification="2007-0509T10:03:29.9">W2Jvb3QgbG9hZGVy...==<
/Attachment>
2014 OMNINET GmbH
Examples
</Attachments>
</AttachmentsVal>
</Object>
<Object id="44169">
<StringVal name="Title">SW-Versionsnummer
korrigieren</StringVal>
<NullVal name="Attachments" />
</Object>
<Object id="44052">
<StringVal name="Title">Benutzerumzug POM</
StringVal>
<NullVal name="Attachments" />
</Object>
</soap:Body>
</soap:Envelope>
C# (with Visual Studio)
...
GetObjectListData gold=new GetObjectListData();
/*
*/
ObjectIDs oids = new ObjectIDs();
oids.objectIDs = new int[3];
oids.objectIDs[0] = 44018;
gold.Item = oids;
/*
* call the proxy for the intended web method
*/
GetObjectListResult golr = webSvc.GetObjectList(gold);
...
/*
2014 OMNINET GmbH
79
80

* Check for success; Do something with the results
*/
4.5
AddObject simple values

A new request is added by using the AddObject method to the folder "ChangeMgmt\RFCs" of the
OMNITRACKER demo ITIL database. Whereas only the necessary fields are filled with values. Look
here for the compatibility of the Web service classes with the OMNITRACKER data types.
XML SOAP message

<soap12:Body>
<Object folderPath="ChangeMgmt\RFCs">
<StringVal name="Title">I need help</StringVal>
<ReferenceVal name="Reporting Person"
objectId="43715"/>
<StringVal name="Description">A new simple RFC</
StringVal>
</Object>
</AddObject>
</soap12:Body>
</soap12:Envelope>
The response tells that the new object was successfully added and that its unique identifier is
537843.
<soap:Body>
<AddObjectResult success="true" objectId="537843" />
</soap:Body>
</soap:Envelope>
C#
2014 OMNINET GmbH
Examples
81
...
AddObjectData aod = new AddObjectData();
/*
*/
aod.folderPath = "ChangeMgmt\\RFCs";
aod.Items = new object[3];
StringVal value0 = new StringVal();
value0.name = "Title";
value0.Value = "I need help";
aod.Items[0] = value0;
ReferenceVal value1 = new ReferenceVal();
value1.name = "Reporting Person";
value1.objectId = 43715;
value2.name = "Description";
value2.Value = "A new simple RFC";
/*
*/
AddObjectResult aor = webSvc.AddObject(aod);
...
/*
* Check for success
*/
4.6
AddObject complex values

This example shows how to add a new object with the more complex value types
AddedAttachmentsVal, ReferenceListVal and ReferenceToUserVal. Look here for the compatibility of
the Web service classes with the OMNITRACKER data types.
XML SOAP message

<soap12:Body>
<Object folderPath="ChangeMgmt\RFCs">
<StringVal name="Title">I need help</StringVal>
<ReferenceVal name="Reporting Person"
objectId="43715"/>
2014 OMNINET GmbH
82

<StringVal name="Description">A new simple RFC</
StringVal>
<AddedAttachmentsVal name="Attachments">
<Attachments>
<AddedAttachment description="my favorite
website" link="true" name="omninet"
url="http://omninet.de/index.php" />
name="email.mehl">AAUKDxQRHhsoLQ==</
AddedAttachment>
</Attachments>
</AddedAttachmentsVal>
<ReferenceListVal name="AffectedCMDBCIs"
objectIds="517561 517556 536562 536568"/>
<ReferenceToUserVal name="Responsible"
type="groupname" value="Tester" />
</Object>
</AddObject>
</soap12:Body>
</soap12:Envelope>
C#
...
/*
*/
aod.folderPath = "";
AddedAttachmentsVal value3=new AddedAttachmentsVal();
value3.name="Attachments";
value3.Attachments = new AddedAttachment[2];
value3.Attachments[0] = new AddedAttachment();
value3.Attachments[0].description="added a link";
2014 OMNINET GmbH
Examples
83
value3.Attachments[0].link = true;
value3.Attachments[0].name = "omninet site";
value3.Attachments[0].url = "http://www.omninet.de";
value3.Attachments[1] = new AddedAttachment();
value3.Attachments[1].description="added a file";
value3.Attachments[1].link=false;
value3.Attachments[1].name = "foo.bar";
value3.Attachments[1].Value = xyz;//put in the binary data of the
file here encoded in base64
ReferenceListVal value4 = new ReferenceListVal();
value4.name = "AffectedCMDBCIs";
value4.objectIds = new int[3];
value4.objectIds[0] = 517561;
ReferenceToUserVal value5 = new ReferenceToUserVal();
value5.name = "Responsible";
value5.type = ValueType.groupname;
value5.Value = "Tester";
/*
*/
AddObjectResult aor = webSvc.AddObject(aod);
...
/*
* Check for success
*/
4.7
RemoveObject
This example removes an object with the unique identifier 537842 from the OMNITRACKER
database.
XML SOAP message

<soap12:Body>
<RemoveObject xmlns="http://www.omninet.de/OtWebSvc/v1">
<ObjectID>537842</ObjectID>
</RemoveObject>
2014 OMNINET GmbH
84

</soap12:Body>
</soap12:Envelope>
The response is:

<soap:Body>
<RemoveObjectResponse xmlns="http://www.omninet.de/OtWebSvc/
v1">
<RemoveObjectResult success="true" errorMsg="" />
</soap:Body>
</soap:Envelope>
OR
If an error occurred, in this case the object did not exist in the database, the attribute success will
be false and the error is described in errorMsg.
<soap:Body>
<RemoveObjectResponse xmlns="http://www.omninet.de/OtWebSvc/
v1">
<RemoveObjectResult success="false" errorMsg="The object
cannot be found in the database (id=537842)" />
</soap:Body>
</soap:Envelope>
int objectID = 537842;
bool useTrashbin = true;
bool ignoreReferences = false;
RemoveObjectResult rolr = webSvc.RemoveObject(objectID, useTrashbin,
ignoreReferences);
/*
2014 OMNINET GmbH
Examples
85
* Check for success

*/
...
4.8
ModifyObject simple values

For the object with the unique identifier 44018 the fields DueDate, Priority and Description are
modified. DueDate is a field of type Date/Time, hence only a value of type DateTimeVal can be
applied here. Look here for the compatibility of the Web service classes with the OMNITRACKER
data types.
XML SOAP message

<soap12:Body>
<DateTimeVal name="DueDate">2006-04-18T19:30:10.7</
DateTimeVal>
<StringVal name="Description">Everything is not
fine</StringVal>
</Object>
</ModifyObject>
</soap12:Body>
</soap12:Envelope>
C#
...
ModifyObjectData mod = new ModifyObjectData();
/*
*/
mod.objectId = 44018;
mod.Items = new object[3];
DateTimeVal value0 = new DateTimeVal();
value0.name = "DueDate";
value0.Value = new DateTime(2006,4,18,19,30,10,7);
mod.Items[0] = value0;
2014 OMNINET GmbH
86

value1.name = "Priority";
value1.Value = "High";
value2.Value = "Everything is not fine";
/*
*/
ModifyObjectResult mor = webSvc.ModifyObject(mod);
/*
* Check for success
*/
4.9
ModifyObject complex values

The request with the unique identifier 44018 is modified. Two attachments, if they exist, are removed
from the attachments list. A third attachment is modified, while one link and one file are added to the
attachments field. Since the attributes "name" and "url" are read-only in OMNITRACKER they
cannot be changed in the ModifiedAttachments section. Due to this both fields can be left blank or
away.
Furthermore a field of the type "reference to user" and one of the type "reference list" are changed.
Look here for the compatibility of the Web service classes with the OMNITRACKER data types.
XML SOAP message

<soap12:Body>
<AttachmentModificationsVal name="Attachments">
<DeletedAttachments>
<ID>1</ID>
<ID>3</ID>
</DeletedAttachments>
<ModifiedAttachments>
<ModifiedAttachment attachmentId="2"
description="A new description for this
link" link="true" />
</ModifiedAttachments>
<AddedAttachments>
<AddedAttachment description="added a
2014 OMNINET GmbH
Examples
87
link" link="true" name="omninet site"

url="http://www.omninet.de" />
<AddedAttachment description="added a
file" link="false"
name="foo.bar">AAUKDxQRHhsoLQ==</
AddedAttachment>
</AddedAttachments>
<ReferenceToUserVal name="Responsible"
type="groupname" value="Tester" />
<ReferenceListModificationsVal
name="AffectedCMDBCIs" addedObjectIds="517561 517556
536562" removedObjectIds="521611" />
</Object>
</ModifyObject>
</soap12:Body>
</soap12:Envelope>
C#
...
ModifyObjectData mod=new ModifyObjectData();
/*
*/
mod.objectId = 44018;
mod.Items = new object[3];
AttachmentModificationsVal value0 = new AttachmentModificationsVal
();
value0.name = "Attachments";
value0.DeletedAttachments = new ID[2];
ID id_del0 = new ID();
id_del0.Value = 1;
value0.DeletedAttachments[0] = id_del0;
ID id_del1 = new ID();
id_del1.Value = 3;
value0.DeletedAttachments[1] = id_del1;
value0.ModifiedAttachments = new ModifiedAttachment[1];
value0.ModifiedAttachments[0] = new ModifiedAttachment();
value0.ModifiedAttachments[0].attachmentId = 2;
value0.ModifiedAttachments[0].description="A new description for
this link";
value0.ModifiedAttachments[0].link = true;
value0.AddedAttachments = new AddedAttachment[2];
value0.AddedAttachments[0] = new AddedAttachment();
value0.AddedAttachments[0].description = "added a link";
value0.AddedAttachments[0].link = true;
2014 OMNINET GmbH
88

value0.AddedAttachments[0].name="omninet site";
value0.AddedAttachments[0].url = "http://www.omninet.de";
value0.AddedAttachments[1] = new AddedAttachment();
value0.AddedAttachments[1].description = "added a file";
value0.AddedAttachments[1].link = false;
value0.AddedAttachments[1].name = "foo.bar";
value0.AddedAttachments[1].Value = xyz;//put in the binary data of
the file here encoded in base64
ReferenceToUserVal value1 = new ReferenceToUserVal();
value1.name = "Responsible";
value1.type = ValueType.groupname;
value1.Value = "Tester";
ReferenceListModificationsVal value2 = new
ReferenceListModificationsVal();
value2.name = "AffectedCMDBCIs";
value2.addedObjectIds = new int[3];
value2.addedObjectIds[0] = 517561;
value2.removedObjectIds = new int[1];
value2.removedObjectIds[0] = 521611;
/*
*/
ModifyObjectResult mor = webSvc.ModifyObject(mod);
...
/*
* Check for success
*/
4.10
InvokeScript
In the present example a server-global script with name "GetNewObjects" is called. This script is
intended to return the number of objects created in specific folder since a certain date. It also returns
the value of the field "title" of those objects. The example web request retrieves those objects in
folder "ServiceDesk", which have been created since "10.07.2007".
The response shows there are three those objects. Their titles are returned to the output parameters
"titleX", where X is the objects index.
XML SOAP message

2014 OMNINET GmbH
Examples
89
<soap12:Body>
<InvokeScript xmlns="http://www.omninet.de/OtWebSvc/v1">
<Script name="GetNewObjects">
<Parameters>
<StringVal name="folder">ServiceDesk</
StringVal>
<DateTimeVal name="created">2007-0719T00:00:00</DateTimeVal>
</Parameters>
</Script>
</InvokeScript>
</soap12:Body>
</soap12:Envelope>
The response may be:

<soap:Body>
<InvokeScriptResult success="true">
<Parameters>
<ShortIntVal name="number">3</ShortIntVal>
<StringVal name="title1">Spanish spellchecker is
not installed</StringVal>
<StringVal name="title2">Printer does not work
correctly</StringVal>
<StringVal name="title3">WTS server not
responding</StringVal>
</Parameters>
</soap:Body>
</soap:Envelope>

InvokeScriptParameters isp = new InvokeScriptParameters();
isp.name = "GetNewObjects";
isp.Parameters = new ScriptParameters();
isp.Parameters.Items = new object[2];
value1.name = "folder";
value1.Value = "ServiceDesk\\Incidents";
2014 OMNINET GmbH
90

isp.Parameters.Items[0] = value1;
DateTimeVal value2 = new DateTimeVal();
value2.name = "created";
value2.Value = new DateTime(2007, 7, 19);
isp.Parameters.Items[1] = value2;
try
{
InvokeScriptResult isr = webSvc.InvokeScript(isp);
if (isr.success)
{
ScriptParameters parameters = isr.Parameters;
for (int i = 0; i < parameters.Items.Length; i++)
{
object myItem = parameters.Items[i];
if (myItem is StringVal)
{
string val = ((StringVal)myItem).Value;
Console.WriteLine(field + ": " + val);
}
else if (...)
{
}
}
}
else
{
string err = isr.errorMsg;
}
}
catch (Exception ex)
{
string err = ex.Message;
}
Global serverside script (GetNewObjects)

Set actParas = ActiveParameters
path = actParas("folder")
dtCreated = actParas("created")
Set session = ActiveSession
Set folder=session.GetRequestFolderByPath(path)
Set reqs = folder.Requests
numberNew = 0
For i=0 to reqs.Count-1
Set req = reqs(i)
If req.CreationDate > dt Then
numberNew = numberNew+1
2014 OMNINET GmbH
Examples
91
title = req.UserFields("Title")
actParas("title" & CStr(numberNew)) = title
End If
Next
actParas("number") = numberNew
4.11
Asynchronous Calls
Each of the web service methods has an asynchronous version, which means the method will
immediately return and will fire an event, when the request is completed. This example is the
asynchronous counterpart of the AddObject simple values example.
If you are not using Visual Studio and .NET you will have some web request object, which allows
asynchronous calls, too. The name and usage of that object depends on the selected programming
language and cannot be covered here.
C#
/*
* Create the web service object and set the event handler
*/
webSvc.AddObjectCompleted += OnAddObjectCompleted;
...
/*
* create the new object and send the request
*/
aod.folderPath = "ChangeMgmt\\RFCs";
webSvc.AddObjectAsync(aod); //the program will go on immediately
...
2014 OMNINET GmbH
92

/*
* after the request was completed this event handler is called
*/
public void OnAddObjectCompleted(object sender,
AddObjectCompletedEventArgs args)
{
if (args.Cancelled)
{
//the request was cancelled
}
else
{
AddObjectResult aor = args.Result;
// do something with the result
...
}
}
2014 OMNINET GmbH
Index
Drop Down List
Index
ErrorMsg
exception
AddedAttachment
25, 26, 31, 86
AddedAttachments
25, 31
AddedAttachmentsVal
26
AddedObjectIds
54
AddObject
19, 20, 80
AddObjectData
27
AddObjectResponse
20, 80
AddObjectResult
20, 29, 80
Anonymous Login
15
AppSettings
14, 17
Asynchronous Calls
91
Attachment
10
AttachmentModificationsVal
31, 86
Attachments
19, 25, 26, 29, 31, 32, 77, 86
AttachmentsVal
32, 52, 77
Attribute - Attributes
6
Authentication
15
Auto Number
19
-B15
20, 21, 23, 24, 29, 41, 50, 57, 75, 77, 83
10
-FFAQ
10
Filter
6, 21, 37, 38, 75
Float Double
19
Float Single
19
Folder
6, 20, 21, 27, 37, 38, 75, 80
FolderPath
27, 38, 77
10
-GGet
21, 38, 75, 77
GetObjectList
19, 21, 75, 77
GetObjectListResponse
21, 75, 77
GetObjectListResult
21, 41, 75, 77
Groupname
55
-HHistoryItem
HistoryVal
42
43
-IID
24, 29, 44, 49, 53
Integrated Windows Authentication
InvokeScript
22, 45, 46, 88
-CCache
18
CurrencyVal
19
-E-
-A-
Basic Authentication
BoolVal
33, 52
Byte
19
ByteVal
34, 52
35, 52
-DData Types
19
Date/Time
19, 35
DateTimeVal
35, 52, 75, 85
DeletedAttachments
31, 86
Description
23, 25, 26, 29, 50
DoubleVal
36, 52
2014 OMNINET GmbH
93
-LLongIntVal
47, 52
-MmaxRequestLength
10
Memo Time Stamped
19
ModifiedAttachment
31, 47, 86
ModifiedAttachments
31
15
94
ModifyObject
19, 23, 47, 50, 85, 86
ModifyObjectData
49
ModifyObjectResponse
23, 50
ModifyObjectResult
23, 50
SingleVal
52, 61
soapexception
10
StringVal
20, 23, 49, 52, 62, 75, 77, 81, 85
-T-
-N-
TimeStampedMemoSection
59, 63
Name
23, 25, 26, 29, 31, 32, 33, 34, 35, 36, 47, 51, TimeStampedMemoVal
52, 63
55, 56, 58, 60, 61, 62, 63
Namespace
6
NullVal
27, 51, 52, 77
-U-
Unique ID
29, 44, 49, 52, 53
Url
25, 26, 29, 31, 32, 47, 77
Use_HTTP_authentication
15
Object
6, 19, 20, 21, 23, 24, 27, 38, 41, 49, 52, 53, Userdisplayname
55
55, 59, 75, 77, 80, 83, 85, 86
Userloginname
55
ObjectData
52
ObjectId
20, 29, 49, 56, 80, 81
ObjectIDs
38, 53, 55, 77, 83
OT_Hostname
14
Web.config
14, 15
OT_Password
14, 15
Workflow
19
OT_Port
14
WSDL
10
OT_SessionPool
17
OT_SessionTimeout_ms
17
OT_User
14, 15
-O-
-W-
-X-
-R-
XML
6, 71, 75, 77, 83
ReferenceListModificationsVal
54, 86
ReferenceListVal
52, 55, 56, 81
ReferenceToUserVal
52, 55, 81, 86
ReferenceVal
52, 56, 80, 81
RemovedObjectIds
54
RemoveObject
24, 83
RemoveObjectResponse
24, 83
RemoveObjectResult
24, 57, 83
RequiredField
38, 58, 66
-SScriptParameters
59
Section
59
SendRequest
71
server was unable to process request
Session Pooling
17
ShortIntVal
52, 60
10
2014 OMNINET GmbH

OTWeb SVC

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

OTWeb SVC

Uploaded by

Copyright:

Available Formats

OMNITRACKER

OMNITRACKER Web Service Manual

Version 10.3 (build 6274)

OMNITRACKER Web Service Manual

(C) Copyright 1996-2014 by OMNINET GmbH

OMNITRACKER and OMNINET are registered trademarks of OMNINET GmbH.

Part II Frequently Asked Questions

Part III Reference

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

Architecture of the OMNITRACKER Web Service

2014 OMNINET GmbH

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

Frequently Asked Questions

2014 OMNINET GmbH

Frequently Asked Questions

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

The configuration file Web.config

2014 OMNINET GmbH

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

2014 OMNINET GmbH

<add key="OT_Port" value="5085"/>

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

These keys have the following meaning:

2014 OMNINET GmbH

<add key="Caching_Enable" value="true"/>

Data Types in OMNITRACKER

OMNITRACKER Can be assigned with

ByteVal, LongIntVal, NullVal, ShortIntVal

ByteVal, LongIntVal*, NullVal, ShortIntVal*

Drop Down List

ByteVal, DoubleVal, LongIntVal, NullVal,

ByteVal, DoubleVal*, LongIntVal*, NullVal,

ByteVal, LongIntVal, NullVal, ShortIntVal

ByteVal, LongIntVal*, NullVal, ShortIntVal

Reference list of ReferenceListVal (AddObject),

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

You cannot assign values to fields of this

2014 OMNINET GmbH

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

2014 OMNINET GmbH

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

2014 OMNINET GmbH

A link is added to the list of attachments.

<AddedAttachment description="something useful" link="true"

<AddedAttachment link="false" name="email.msg">SGVsbG8gd29ybGQh</

public class AddedAttachment

2014 OMNINET GmbH

OMNITRACKER Web Service Manual

A link as well as a file are added to the attachments.

2014 OMNINET GmbH

Attachments List containing any number of attachments of the type AddedAttachment.

ByteVal, LongIntVal, NullVal, ShortIntVal

ByteVal, DoubleVal, LongIntVal, NullVal,