Skip to main content

Schemas

Schemas specify the required format of XML configuration files. You can find the schema files for XML files in the folder C:\Program Files\Omada SDK\V14.0\schemas.

The Omada.SDK.Reference.chm file contains a reference for each schema where each element and attribute is explained.

FilenameDescription and Usage
SystemCategoryConfigurationML.xsdSchema for system onboarding configuration XML. Used to describe onboarding parameters.
DataObjectExchangeML.xsdSchema for data object exchange XML. Used to define default data objects during system onboarding.
OPSConnectorDataModel.xsdSchema for OPS connector data models. Used to describe the target system data model.
OPSTaskMappingConfigurationML.xsdSchema for OPS task mappings. Used to map data between Omada Identity and the target system data model.
OPSProvisioningConfigurationDefaultML.xsdThe provisioning default configuration schema is used to specify which task mappings to use, and for which resource type, when enabling provisioning.

System Onboarding configuration​

You can use the system onboarding configuration XML files to define the tasks and settings that you can configure for a given collector or connector, for example:

Schema fileSystemCategoryConfigurationML.xsd
Namespacehttp://schemas.omada.net/ois/2016/SystemCategoryConfigurationML

The following sample code shows the structure as well as an explanation of each of the elements:

<?xml version="1.0" encoding="utf-8"?>
<systemCategoryConfiguration
  xmlns="http://schemas.omada.net/ois/2016/SystemCategoryConfigurationML"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
 
  <configurationSections>
    <configurationSection name="sectionName" title="section title">
      <configurationParameters>
        <configurationParameter
            name="parameter" title="parameter name" scope="system">
          <selectValues>
            <selectValue title="Value 1" name="Value1" />
          </selectValues>
          <dependencies>
            <dependency
              parameter="" type="required" operator="equal" value="" />
          </dependencies>
          <defaultValue>
            <![CDATA[]]>
          </defaultValue>
        </configurationParameter>
      </configurationParameters>
    </configurationSection>
  </configurationSections>
  <settings>
    <trustSettings requireTrust="false" trustCategory=""/>
    <postActionHandler></postActionHandler>
  </settings>
  <defaultData></defaultData>
</systemCategoryConfiguration>
note

LDAP and REST -- the system onboarding configuration XML for template connectivity -- are also installed as part of the SDK, and you can use them as a base for inspiration to write new template base connectivity.

Using system onboarding configuration file​

To minimize the amount of manual configuration required when onboarding system it is possible to define values and set properties in system onboarding configuration file.

The SystemCategoryConfigurationML.xsd schema file can be installed with enterprise server and with the software developer kit (SDK). It contains information on allowed elements, defined values, and attributes.

The values are defined under <properties> element and supported format are text, integer, boolean, and date time.

note

Be aware that the specified systemName, must follow the naming rules, for example properties must be prefixed with the C_.

Example of system onboarding configuration file body:

<systemCategoryConfiguration xmlns="http://schemas.omada.net/ois/2016/SystemCategoryConfigurationML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <properties>
    <property name="Text value property" systemName="C_TEXT_VALUEPROP" type="value" dataType="text" description="Text value property"/>
    <property name="Set property" systemName="C_SETPROP" type="set">
      <setPropertyValues>
        <setPropertyValue name="value one"/>
        <setPropertyValue name="value two" description="description two"/>
      </setPropertyValues>
    </property>
  </properties>
</systemCategoryConfiguration>
info

If the property types match, the existing property is used. If there is already a property with the same system name but has different value from what is defined in the system onboarding configuration file, the system onboarding fails. If the value of the property corresponds with the one in the configuration file, the existing property is used.

Localization of configuration​

Because the system onboarding configuration appears in Enterprise Server, you may want to display the UI texts in the language of the user.

To display UI texts in the language of the user:

  1. For all title and description attributes in the configuration, you can specify a text or a constant pointing to the string resource in the user's local language.

If the value starts with S, the value is seen as a string resource rather than a string literal.

Writing a custom edit function​

Each defined parameter in a section is shown in a dialog box. If you want another type of dialog box to be shown, you can do it by writing a custom edit function in JavaScript.

The custom edit function must support editing of all parameters defined in a section.

To use the custom edit function:

  1. With a text editor or Visual Studio, on the configurationSection element, using the customEditFunction attribute, specify the name of the function. You can specify the name of the JavaScript file in the attribute customEditFunctionFile.

    The following code sample shows how you can specify the name of the function and the file:

    <configurationSection
    customEditFunction="QueriesAndMappingsAD" customEditFunctionFile="OIM.SystemOnboarding.DataMapping.AD.js">
    info

    Some attributes have been omitted for the sake of keeping the example short.

    In the code sample, the name of the called function is "QueriesAndMappingsAD" and the function is in a file named OIM.SystemOnboarding.DataMapping.AD.js.

  2. Copy the OIM.SystemOnboarding.DataMapping.AD.js file to the folder C:\Program Files\Omada Identity Suite\Website\Jsinc.

  3. Ensure that the function has the following interface:

    function QueriesAndMappingsAD(options)

    The options object contains the following variables and functions:

    VariableTypeDescription
    CaptionstringThis is equal to the title attribute on the configurationSection element for which the custom edit function is defined.
    categoryWideBooleanIf you set this variable to True, the settings are relevant for the entire system category and not only for the individual system.
    PropertiesArrayThe list of the parameters in the section and their current value. Each entry in the array is equal to a quickform property.
    SuccessfunctionThis is the callback function. You must call this function from the custom edit function when the function is done.

Create data objects in the default data element​

To make created data objects system-specific, the following macros are available by default:

MacroDescription
#!SYSTEMCATEGORY_NAME!#The name of the system category where the system is registered.
#!SYSTEMCATEGORY_SC_IDENT!#The If (SC_IDENT) of the system category where the system is registered.
#!SYSTEM_ID!#The data object ID of the new system.
#!SYSTEM_NAME!#The name of the new system.
#!SYSTEM_SYSTEMID!#The ID (SYSTEMID) of the new system.

Data object exchange​

Schema file - DataObjectExchangeML.xsd

Namespace - http://schemas.omada.net/ois/2012/DataObjectExchangeML

Enterprise Server features a data object exchange web service with a command line utility that is included in the standard installation.

The feature consists of a web service as well as a command line utility that imports/exports data objects into and out of an Enterprise Server installation.

Connector data model​

Schema file - OPSConnectorDataModel.xsd

Namespace - http://schemas.omada.net/ops/2015/ConnectorDataModelML

A provisioning connector has a data model, which you can use to describe the objects that it can provision and update in the target system. The data model is defined as XML.

Namespaces​

To avoid potential name clashes in the connector data model, you can specify a namespace where you can copy the properties to. This is only relevant for properties that in the namespace, not the object type names.

The namespace is specified as an attribute named modelNamespace in the dataModel root element, for example:

<connectorDataModel xmlns="http://schemas.omada.net/ops/2015/ConnectorDataModelML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" modelNamespace="somenamespace">

The property element​

Properties are described by using the property element, which has the following attributes:

AttributeDescription
DatatypeDescribes the type of value to expect. You can use one of the following values:

* stringType
* datetimeType
* booleanType
* referenceType
* intType
* secureStringType.
* Default value

When you use Default value, or if you do not specify any attributes, the value stringType is used.
RequiredDescribes whether the property is required. The value can be True or False.

If you do not specify this attribute, the default value is False.
MultivaluedDescribes whether the property can contain multiple values. The value can be True or False.

If you do not specify this attribute, the default value is False.

You can also use the object element to describe connector objects. This element only has the attribute name, which is the name of the object.

The object properties are defined in a list of objectProperty elements in which the text in the element points to a property via the name attribute.

The object element has the following optional attributes:

AttributeDescription
isKeyA Boolean attribute that defines the key properties. You can specify multiple key properties.
referenceObjectA string attribute that indicates to which object type a referenceType property refers. You do not have to define the reference object in the connector model itself, and it is not validated.
referenceKeyPropertyA string property that indicates the key property on the referenced object. You do not have to define the reference object in the connector model itself, and it is not validated.
referenceLookupPropertyA string property that indicates the property in the referenced object to make a lookup against to find the reference object from the task property value. You do not have to define the reference object in the connector model itself, and it is not validated.

Object type details​

If you have to locate, create or update an object, some connectors need more information about the object. In such cases, you can specify a list of objectDetails for each object.

In the following example, the object type User specifies the schema as dbo and template as a CDATA object (content left out for brevity):

  <objects>
    <object name=”User”>
      <objectDetails>
        <objectDetail name=”schema” value=”dbo” />
        <objectDetail name=”template”>
          <largeDataField><![CDATA[]]></largeDataField>
        </objectDetail>
      </objectDetails>
      <objectProperties/>
    </object>
  </objects>
</connectorDataModel>

The individual connector defines the object details that you can specify.

The <largeDataField\> can be used when the value exceeds 200 characters.\

Task Mapping​

Schema file - OPSTaskMappingConfigurationML.xsd

Namespace - http://schemas.omada.net/ops/2015/TaskMappingConfigurationML

Task mapping is used to convert data from RoPE into data that the Omada Provisioning Service (OPS) can understand.

When RoPE calculates new, changed or deleted assignments, a provisioning task is sent to OPS using a predefined data model, called the RoPE model.

Because each connector has its own data model, you must configure how properties in the RoPE model are mapped to the properties in the connector data model. You can do this through task mapping.

The RoPE model​

The Account object has the following standard properties:

NameTypeDescription
ROPE_KeystringTypeThe UID of the calculated assignment.
ROPE_IdentitystringTypeThe display name of the identity.
ROPE_AccountNamestringTypeThe account name.
ROPE_DistinguisedNamestringTypeThe distinguished name of the account. The value is only available for calculated assignments with an Actual reason.
ROPE_AccountCBKstringTypeThe Omada Identity Data Warehouse’s composed businesskey for the account.
ROPE_AccountTypestringTypeThe account type name.
ROPE_AccountTypeIdstringTypeThe UID of the account type.
ROPE_ResourcestringTypeThe display name of the resource.
ROPE_ResourceTypestringTypeThe name of the resource type of the resource.
ROPE_SystemstringTypeThe name of the system to which the resource belongs.
ROPE_SystemKeystringTypeThe SYSTEMID of the system.
ROPE_SystemCBKstringTypeThe Omada Identity Data Warehouse’s composed businesskey for the system.
ROPE_DisabledbooleanTypeDisable or enable the account.

The Assignment object has the following standard properties:

NameTypeDescription
ROPE_KeystringTypeThe UID of the calculated assignment.
ROPE_SystemstringTypeThe name of the system to which the resource belongs.
ROPE_SystemKeystringTypeThe system’s System ID.
ROPE_SystemCBKstringTypeThe Omada Identity Data Warehouse’s composed business key for the system.
ROPE_AccountCBKstringTypeThe Omada Identity Data Warehouse’s composed business key for the account.
ROPE_AccountNamestringTypeThe account name.
ROPE_DistinguisedNamestringTypeThe distinguished name of the account. The value is only available for calculated assignments with an Actual reason.
ROPE_ResourceKeystringTypeThe ROLEID of the resource.
ROPE_ResourceCBKstringTypeThe Omada Identity Data Warehouse’s composed business key for the resource.
ROPE_ResourceTypestringTypeThe name of the resource type of the resource.
ROPE_ValidFromdatetimeTypeThe date/time from when the assignment should start.
ROPE_ValidTodatetimeTypeThe date/time from when the assignment should end.
ROPE_DisabledbooleanTypeShows if the assignment is disabled.
ROPE_AccountsstringType[]Multi-value property containing the account name. Usable for systems with the member attribute on the resource.
ROPE_ResourcesstringType[]Multi-value property containing the ROLEID. Usable for systems with the roles attribute on the user.

Using provisioning-relevant attributes​

In addition to the standard properties listed, provisioning-relevant attributes from the resource type are also added to the provisioning task.

If the resource type points to a provisioning-relevant attribute set with, for example, an attribute named FIRSTNAME, this attribute is added to the account or assignment object with the name ROPE_ATTR_FIRSTNAME.

Take note of the ATTR prefixing and the capitalization of the attribute name.

RoPE calculates provisioning-relevant attributes from either of the properties set on the resource type or from an extension.

The Constant mapper​

If you set the value of the mappingType to Constant, the value of the associated XML element is expected to be a constant value.

The SourceField mapper​

When the value of the mappingType is SourceField, the value of the associated XML element is expected to be the name of a field in the source object type.

The value of that field is then copied to the target field. This is useful for simple field renaming.

The Expression mapper​

When the value of the mappingType is Expression, the value of the associated XML element is expected to be an expression, which is evaluated to generate the output value for the target field.

Expressions are written in a C# subset. They are evaluated using the expression interpreter, DynamicExpresso. For more information, see the following link.

For example, in the following task-mapping XML document, the expression mapper has been used for the target field name. If the Operation property value of the incoming object from the RoPE extension is Create, the value of the target property name becomes the value of the incoming object property Create.

Otherwise, null is set as the value. See the following code sample:

<fieldMapping name="name" dataType="stringType" action="modify" mappingType="Expression">Operation=="Create" ? ROPE_Identity :null</fieldMapping>

You can also use the C# method string.Format() in the Expression mapper.

In the following example, the value of the target property userPrincipalName is the value of the property ROPE_AccountName from the source object, followed by \@megamart.com. See the following code sample:

<fieldMapping name="userPrincipalName" dataType="stringType" action="modify" mappingType="Expression">string.Format("{0}@megamart.com", ROPE_AccountName)</fieldMapping>

The MultiValueExpression mapper​

The MultiValueExpression mapper builds on top of the Expression mapper and has all the same capabilities, as well as a set of multi-value operations and variables.

For example, if you have a multi-value property named members, you can perform expressions for each value that it contains. Use the operators “:” and “Value”.

In the following example, all values in the members property are set to <value>@megamart.com.

<fieldMapping name="members" multiValued="true" dataType="stringType" action="modify" mappingType="MultiValueExpression">members:string.Format("{0}@megamart.com", Value)</fieldMapping>

Expression operators and variables​

The following operators and variables are available when using the Expression mapper:

Operator/VariableDescription
ObjectTypeContains the value of the connector object type.
ObjectIdContains the value of the task object ID.
OperationThe task operation. The possible values are

* Create
* Update
* Delete
* CreateOrUpdate
* DeleteIfExists

The following additional variables are available when you use the MultiValueExpression mapper:

Operator/variableUsage
:To iterate all values and perform an expression. The value is available using the Value variable.
ValueThe value when iteration values using the operator : and action=add.
Value_RemoveThe value when iteration values using the operator : and the action=remove.
Value_ClearExistingUse this to specify if the ClearExisting value is True or False.

Extensions​

The expression mappers have a set of built-in functions, which can help you when writing task mappings. The following is a list of the variables that you can use:

Operator/variableUsage
NameValuePairExtensions.GetAttributeValue (object attributeProperty, string attributeName)Use this function to obtain a value from a name property containing name value pairs. For example, if the value for ATTRIBUTES is SIZE=500, you can use this extension to get the value 500: NameValuePairExtensions.GetAttributeValue(ATTRIBUTES, “SIZE”)
Extensions.ArrayContains (Array array, object searchValue)Use this function to check if a multi-value property contains a specific value.
Extensions.GetTokenValue (string value, char delimiter, int tokenNumber, string defaultValue)Use this function to extract a portion of a string. The function splits the string by the delimiter and then fetches the token value indicated by its placement. For example, if an account name is provided as follows: domain\accountname but you are only interested in the accountname, you must use the following function: Extensions.GetTokenValue(PROPERTY, ‘\’, 2, “”)
Extensions.GetSidFromCBK (string composedBusinessKey)This function creates an Active Directory object-sid from a Data Warehouse-composed business key.

Using connector configuration values in task mappings​

In some cases, you may want to use system-defined variables in your task mappings. Specify these variables as a connector configuration parameter.

You can also specify the configuration parameters during the System onboarding process, when you enable provisioning. You can find the values of these settings in the task mappings using The Expression mapper.

  1. To retrieve the value, use the following function:

    ConnectorConfiguration.GetValue("hostname")

  2. In the <connector setting name> section, enter the name of the connector setting.

  3. Save your changes.

Provisioning default configuration​

When enabling provisioning, you can use the provisioning default configuration to specify which task mappings to use for a given resource type.

Schema file - OPSProvisioningConfigurationDefaultML.xsd

Namespace http://schemas.omada.net/ois/2012/DataObjectExchangeML

Example of the default configuration:

<provisioningConfiguration xmlns="http://schemas.omada.net/ops/2016/ProvisioningConfigurationDefaultML" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <provisioning>
    <resourceTypes>
      <resourceType type="Foo Role" mapping="Foo Assignment" />
    </resourceTypes>
  </provisioning>
</provisioningConfiguration>

In the example, it is declared that when the user checks the Use default configuration checkbox while enabling provisioning, the system uses the task mapping named Foo Assignment for the resource type named Foo Role.