Data object exchange web service

Omada Identity features a data object exchange web service. You can use this service to test and automate an Omada Identity implementation. The main purpose of the web service is to integrate with and automate smaller datasets.

• The web service can help you set up automation and handling of bulk imports and exports of data objects. It can also help you set up automated testing, with test processes that imply Create, Read, Update and Delete (CRUD) operations on data objects.

Overview

You can find the following features in the data object exchange web service:

• Support for importing reference property attribute values.
• The ability to specify to add or remove individual set- and reference-property values from a data object.
• Import and export of data objects for all data object types except Users, User Groups, Processes, and Activities.
• An XML-based interface that accepts data in XML format.
• Support of CRUD operations.
• An import file can contain data objects of more than one type.
• For exports, the data extracted is based on views. This means that only data visible in the view columns is exported. Omada recommends that you create views specifically for this purpose, but you can use existing views.

info

Instead of using the data object exchange web service, it is recommended to use the OData API. For more information, refer to the OData API section in the documentation.

Web service on-prem

The web service’s main purpose is to integrate with and automate smaller datasets.

The web service is installed automatically with the Enterprise Server installer under <web site root>/WebService/DataObjectExchangeWebService.asmx.

The web service supports a subset of the features of the command line utility. The web service exposes the following methods:

• InitializeExport (string viewUId, string mode)
• ExportDataObjects (Guid exportKey, int startIndex, int objectCount)
• ImportDataObjects (string XML, ObjectImporterSettings settings)

Web service security on-prem

The web service security is based on the standard Enterprise Server authentication and authorization model. You must authenticate and authorize the user who calls the web service to perform the operations. The web service works with HTTPS.

Web service usage on-prem

The service and command line utility support all Enterprise Server’s data object types with the exception of Users, User Groups, Processes, and Activities.

The XML format that you use when you import and export data objects is referred to as DataObjectExchangeML. Before you complete an import, the service validates that the XML data corresponds to a valid DataObjectExchangeML.

You can run an import or export of data objects either by using the command line utility or by calling the web service.

Using the data object exchange web service on-prem

Command line utility

The command line utility is named DataObjectImportUtil.exe. You can find it in the bin folder of the installation folder, C:\Program Files\Omada Identity Suite\Enterprise Server\website\bin in a default installation.

You can copy this .exe file to another computer. It does not have a dependency to other DLL files. To use it, you must install Microsoft.Net Framework version 4.6.1 in addition to have network access to the Enterprise Server’s web application.

You must run the command line utility with a number of command line parameters. To use the service through the command line, type and run:

DataObjectImportUtil.exe <command line arguments>

info

DataObjectImportUtil.exe client does not support the OAuth standard. However, the Data object exchange web service calls do support OAuth.

Required parameters:

• Set the mode of operation (-m), either import or export, for example:

  • -m import.

• You must base authentication against the (remote) Enterprise Server Web Service either on a user name (-u) and password (p) or n Windows Integrated Security, for example:

  • -u Administrator –p qwerty

• You must specify the URL to the (remote) Enterprise Server with -h, for example:

  • -h http://oisx

• You should provide a file name for the import/export XML file using -f.

  • -f C:\Data\Roles.xml

• When you run an export (-m export), you must provide a UID of a data object view using -v, for example:

  • -v 1193d8d0-8374-4589-9ded-f1685c8861ce

    info

    To find the UID of the view in the Omada Identity Portal, follow these steps:

    1. Open a data object view page in the Omada Identity Portal from Setup > Administration > User Interface… > Views.
    2. Inside the View detail page, use the combination CTRL+right-click and select FormDataUId in the popup menu. Click OK when you are asked to copy the UID.

To see the complete list of arguments in the command prompt, use the argument -?.

List of the available arguments

Argument	Description
-c <customer name>	The customer name used for logon. The argument can be empty for Windows Integrated Authentication.
-u <user name>	The user name used for authentication towards the Enterprise Server Web Service. This argument can be empty for Windows Integrated Authentication.
-p <password>	The password used for authentication towards the Enterprise Server Web Service. This argument can be empty for Windows Integrated Authentication.
-h <web service url>	The URL for the Enterprise Server Website, for example, http://ois. This argument is mandatory to fill in.
-f <file name>	The XML file from which to import or to which to export. This argument is mandatory to fill in.
-a <true or false>	Accept partial import. If set to false, the provided data will be imported in a single transaction. By default, the value is true where the data is imported and committed in chunks.
-e <number of allowed errors>	Import mode only. The number of allowed (non-fatal) import errors. When the number is exceeded, the import terminates. If you set this argument to 0 (default), the import terminates on the first encountered error. If you allow import errors and the import of an object fails, the import skips the failing object and proceed with the next object. Note that schema validation errors and deserialization errors are considered fatal and always causes an import to fail, regardless of this setting.
-i <start index>	Import mode only. Use the start index to skip over the first items in the file. Use this to restart a failed import at a given point. The default value is 0.
-v <view uid>	Export mode only. The UID of a DataObject View found in the Enterprise Server configuration. All data objects in the view are exported with the properties that are included in the view columns. This is a required argument in export mode.
-m <import or export>	The mode of operation is either import for reading a file into Enterprise Server or export for reading the content of a view into a file.
-o <timeout>	Timeout in seconds for the Web Service call to Enterprise Server. The default value is 90 seconds.
-n <chunk size>	The number of objects transferred to Enterprise Server in each Web Service call. The default value is 100.
-t	Import mode only. Run in test mode (import) where the Web Service analyzes the XML file, but no objects are persisted in Enterprise Server.
-r	Import mode only. Run an initial schema validation of the XML file before the import begins.
-x <ForUpdate or ForCreation>	Export mode only. ForUpdate generates an XML structure with object update actions that is suitable for reimporting into the same Enterprise Server database. ForCreation generates an XML structure with object create actions that is suitable for one-time importing into another Enterprise Server database.

Chunk size and index

When you run an import, objects are read from the XML file and sent to the web service in chunks.

Each chunk of objects is committed to the Enterprise Server database. Should an import fail in the middle of a file, you can resume an import at the last committed index. The last committed index is printed to the console.

On following imports, you can type in the start index to the import program, for example, –i 78400.

XML Document specification on-prem

Use the DataObjectExchangeML format to create a data exchange to import and export data objects with Enterprise Server.

The root element is called exchangeData and contains a collection of objects. The root element states a language which the system uses globally to look up stated values in multi-language fields, specifically data object type names and set property value names.

Base entities

The basic entities represented in the XML input file are:

• exchangeData
• object
• objects
• property
• properties
• propertyValue
• propertyValues
• attributeValue
• attributeValues

Object

The Object entity contains an operation to decide whether to create, update or delete the object. The following operations are supported:

• create: a new object is created.
• update: an existing object is updated. An error is given if no object can be found to update.
• updateOrCreate: if an existing object is found, it is updated - if not a new is created.
• delete: an existing object is deleted. An error is given if no object can be found to delete.
• none: the object is ignored by the import module.

When the operation is either update, updateOrCreate or delete, the import process is configured to try to locate an existing object in the system.

When the import process tries to locate an existing object, it first checks if the XML object has an Id. If it does have one, the ID helps locating the object in the system. If the XML object does not have an Id, the update looks at the properties that have isKey set to True. If more than one object is located in the system that matches the key properties, an error appears.

• A type specifying the system name of a data object type.
• An ID which identifies the object uniquely.
• A number, displayName, createdTime and changedTime which are only used when exporting data. They are ignored when importing data.
• A collection of properties.

XML Property

The property entity contains:

• A name. The system name of the property.

• An isKey which indicates if the property value should be used to identify the object in the system.

  • Only Value properties of the datatype Text can be a key.
  • You can specify zero, one or more properties typing isKey=true when you import data.
  • If you specify multiple properties with isKey=true then all the properties' values are combined into a single key.
  • An import ignores the isKey indicator if:
    • The XML object has an id
    • The XML object's operation is create.

• A collection of property values. propertyValues collection contains:

  • A clearExistingValues indicates if existing values(s) should be cleared for the property.

propertyValue

A propertyValue represents a value for a property. It contains:

• An action indicating whether the value should be added, removed, or modified on the property.

  • For Set- and Reference-properties, the action must be either add or remove.
  • For Value-properties, the action must be modify.

• Seven attributes for holding the value of the property:

  • valueText, valueInteger, valueBoolean, valueDateTime, valueTimeSpan, valueDecimal, and valueGuid.

• If the property is a Set- or Reference-property, there are three ways of identifying the value to be added/removed:

  • A guid id (valueGuid) which you can use to identify the value if the id of the Set property value or referred data object is known.

  • An integer id (valueInteger) which you can use to identify the value if the id of the Set property value or referred data object is known.

  • A value (valueText) which must be either:

    • the name of a set property value in the specified language (not case sensitive), or
    • the value of the key property on the referred data object (not case sensitive).

    The key property of a data object is specified on the data object type and is always a value property of data type Text or the DisplayName.

    If the import finds zero or multiple objects with the specified key value, an error is given.

• In the case of a multi-lingual value property, you can specify a text value together with the language for which it is.

• A property value for a reference property can have one or more attribute value.

• If the reference property is valid for two or more Data Object Type's (for example, users and user groups), it is not possible to specify a valueText (key value). Only valueInt and valueGuid are supported.

attributeValue

An attributeValue represents an attribute value for a reference property value. It contains:

• A name, which is the system name of the attribute-defining property, which can be either a single-valued set property or a value property.
• Seven attributes for holding the value of the attribute:
  • valueText, valueInteger, valueBoolean, valueDateTime, valueTimeSpan, valueDecimal, and valueGuid.

limitations

You cannot exchange value properties with the data type hyperlink.

You cannot exchange multiple values for value properties.

Schema definition

The following lists the complete DataObjectExchangeML XML schema.

The schema is available in this location on the web server: http://<Enterprise server address>/Schema/DataObjectExchangeML.xsd.

<?xml version="1.0" encoding="utf-8"?>
<xs:schema xmlns="http://schemas.omada.net/ois/2012/DataObjectExchangeML" xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://schemas.omada.net/ois/2012/DataObjectExchangeML" elementFormDefault="qualified" id="DataObjectExchangeML">
  <xs:simpleType name="guid">
    <xs:restriction base="xs:string">
      <xs:pattern value="([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})|(\{[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}\})"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:element name="exchangeData">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="objects" minOccurs="0" maxOccurs="1"/>
      </xs:sequence>
      <xs:attribute name="language" type="xs:string" use="optional"/>
      <!-- language: must state the name of an active language in the system. Language is used to interpret the value of a multi-language attribute, such as the type of an object -->
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="operation">
    <xs:restriction base="xs:string">
      <xs:enumeration value="create"/>
      <xs:enumeration value="update"/>
      <xs:enumeration value="updateOrCreate"/>
      <xs:enumeration value="delete"/>
    </xs:restriction>
  </xs:simpleType>
  <xs:element name="object">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="properties" minOccurs="0" maxOccurs="1"/>
      </xs:sequence>
      <xs:attribute name="operation" type="operation" use="required"/>
      <xs:attribute name="type" type="xs:string" use="optional"/>
      <xs:attribute name="id" type="guid" use="optional"/>
      <xs:attribute name="number" type="xs:integer" use="optional"/>
      <xs:attribute name="displayName" type="xs:string" use="optional"/>
      <xs:attribute name="createdTime" type="xs:dateTime" use="optional"/>
      <xs:attribute name="changedTime" type="xs:dateTime" use="optional"/>
<!-- type: system name of the data object type. -->
<!-- id: is required when operation=delete. id is not used when operation=modify -->
<!-- number, displayName, createdTime and changedTime are ignored when importing data -->
    </xs:complexType>
  </xs:element>
  <xs:element name="objects">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="object" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="property">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="propertyValues" minOccurs="1" maxOccurs="1"/>
      </xs:sequence>
      <xs:attribute name="name" type="xs:string" use="required"/>
      <xs:attribute name="isKey" type="xs:boolean" use="optional"/>
<!-- propertyValues: holds the value(s) of the property -->
<!-- name: system name of the property. Is used to identify the property -->
<!-- isKey: exactly one property for an object must have isKey set to true. Only value properties of data type "Text" can be set as key. A key value is considered case-insensitive. -->
    </xs:complexType>
  </xs:element>
  <xs:element name="properties">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="property" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:simpleType name="action">
    <xs:restriction base="xs:string">
      <xs:enumeration value="add"/>
      <xs:enumeration value="remove"/>
      <xs:enumeration value="modify"/>
    </xs:restriction>
  </xs:simpleType>
<!-- A propertyValue represents either a Set-property value, a referred data object in a Reference-property or a text value for a multi-lingual Value property. 
   In case of a Set- or Reference-property a propertyValue can be identified either by an id or by a value. -->
  <xs:element name="propertyValue">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="attributeValues" minOccurs="0" maxOccurs="1"/>
      </xs:sequence>
      <xs:attribute name="action" type="action" use="required"/>
      <xs:attribute name="valueText" type="xs:string" use="optional"/>
      <xs:attribute name="valueInteger" type="xs:integer" use="optional"/>
      <xs:attribute name="valueBoolean" type="xs:boolean" use="optional"/>
      <xs:attribute name="valueDateTime" type="xs:dateTime" use="optional"/>
      <xs:attribute name="valueTimeSpan" type="xs:integer" use="optional"/>
      <xs:attribute name="valueDecimal" type="xs:decimal" use="optional"/>
      <xs:attribute name="valueGuid" type="guid" use="optional"/>
      <xs:attribute name="language" type="xs:string" use="optional"/>
<!-- attributeValues: can only be specified for Reference properties that has attributes. -->
<!-- action: "add" and "remove" are valid for Set- or Reference-properties. "modify" is valid for a Value-property. -->
<!-- valueText: value of a Value Property w. data type "Text" OR key property value on referred data object (case insensitive) OR text value for a multi-lingual Value Property OR name of a Set Property value (in global language) -->
<!-- valueInteger: value of a Value Property w. data type "Integer" -->
<!-- valueBoolean: value of a Value Property w. data type "Boolean" -->
<!-- valueDateTime: value of a Value Property w. data type "DateTime" -->
<!-- valueTimeSpan: value of a Value Property w. data type "TimeSpan". A TimeSpan value is specified as a number of seconds. -->
<!-- valueDecimal: value of a Value Property w. data type "Decimal" -->
<!-- valueGuid: id of a Set-property value or a referred data object -->
<!-- language: must state the name of an active language in the system. Language is only used if the propertyValue is for a multi-lingual Value Property. -->
    </xs:complexType>
  </xs:element>
  <xs:element name="propertyValues">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="propertyValue" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
      <xs:attribute name="clearExistingValues" type="xs:boolean" use="optional"/>
<!-- clearExistingValues: Indicates if the current values should be cleared. -->
    </xs:complexType>
  </xs:element>
<!-- An attributeValue can be used for Reference property values only. -->
  <xs:element name="attributeValue">
    <xs:complexType>
      <xs:attribute name="name" type="xs:string" use="required"/>
      <xs:attribute name="valueText" type="xs:string" use="optional"/>
      <xs:attribute name="valueInteger" type="xs:integer" use="optional"/>
      <xs:attribute name="valueBoolean" type="xs:boolean" use="optional"/>
      <xs:attribute name="valueDateTime" type="xs:dateTime" use="optional"/>
      <xs:attribute name="valueTimeSpan" type="xs:integer" use="optional"/>
      <xs:attribute name="valueDecimal" type="xs:decimal" use="optional"/>
      <xs:attribute name="valueGuid" type="guid" use="optional"/>
<!-- name: system name of the property that represents the attribute. Only single-valued Set properties and Value properties are allowed. -->
<!-- valueText: must be specified if the property is a Value Property w. data type "Text". Can be specified if the property is a Set property. -->
<!-- valueString: must be specified if the property is a Value Property w. data type "Integer" -->
<!-- valueBoolean: must be specified if the property is a Value Property w. data type "Boolean" -->
<!-- valueDateTime: must be specified if the property is a Value Property w. data type "DateTime" -->
<!-- valueTimeSpan: must be specified if the property is a Value Property w. data type "TimeSpan". A TimeSpan value is specified as a number of seconds. -->
<!-- valueDecimal: must be specified if the property is a Value Property w. data type "Decimal" -->
<!-- valueGuid: can be specified if the property is a Set property - must then specify the uid of a Set Property Value" -->
    </xs:complexType>
  </xs:element>
  <xs:element name="attributeValues">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="attributeValue" minOccurs="0" maxOccurs="unbounded"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

XML Example

<?xml version="1.0" encoding="UTF-8"?>
<exchangeData language="English" xmlns="http://schemas.omada.net/ois/2012/DataObjectExchangeML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <objects>
    <object operation="create" type="DataObjectExchangeTestObject">
      <properties>
        <property name="NAME">
          <propertyValues>
            <propertyValue action="modify" valueText="Test object 1"/>
          </propertyValues>
        </property>
        <property name="DESCRIPTION" >
          <propertyValues>
            <propertyValue action="modify" valueText="Some description"/>
          </propertyValues>
        </property>
        <property name="ACTUALWORK" >
          <propertyValues>
            <propertyValue action="modify" valueInteger="42"/>
          </propertyValues>
        </property>
        <property name="DEADLINE" >
          <propertyValues>
            <propertyValue action="modify" valueDateTime="2002-05-30T09:25:10+02:00"/>
          </propertyValues>
        </property>
        <property name="WORK" >
          <propertyValues>
            <propertyValue action="modify" valueDecimal="123.456"/>
          </propertyValues>
        </property>
        <property name="ESTIMATE" >
          <propertyValues>
            <propertyValue action="modify" valueTimeSpan="7200"/>
          </propertyValues>
        </property>
        <property name="HASMANAGER" >
          <propertyValues>
            <propertyValue action="modify" valueBoolean="true"/>
          </propertyValues>
        </property>
        <property name="RESPONSIBLE" >
          <propertyValues clearExistingValues="true">
            <!-- uid of the "administrator" user -->
            <propertyValue action="add" valueGuid="a3527a28-4365-4674-9797-939c995247f7"/>
          </propertyValues>
        </property>
        <property name="TASKSTATUS" >
          <propertyValues>
            <propertyValue action="add" valueText="Initiated"/>
          </propertyValues>
        </property>
      </properties>
    </object>
  </objects>
</exchangeData>