Connectivity
Register Connectivity utility
The Omada.SDK.RegisterUtility.exe file is a command line utility that is installed as part of the Omada Connectivity SDK.
By default, the Register Connectivity utility is installed in the following folder C:\Program Files\Omada SDK\V14.0\utils\register connectivity.
The Register Connectivity utility makes it easy to set up all the needed configuration in Enterprise Server, so that the connectivity is available in the System onboarding process.
Authentication
You can configure the Registration utility to register and update connectivity only after authentication via Omada Identity OData service. The authentication can be performed by an integrated authentication, by using username and password, or by a token. The parameters required for configuration of the OData authentication are described in the Parameters section below.
Parameters
You can set the following parameters in the Register Connectivity utility:
| Parameter | Usage |
|---|---|
| -f (required) | Specifies the full path to the registration XML file. |
| -c (optional) | Specifies the full path to the folder where the files referenced in the registration file are located. If you do not specify the parameter, the files are read from the same folder as the registration file. |
| -url (optional) | Specifies the URL to the Omada Identity OData service in order to use of the OData authentication for the registration utility, for example, http://enterpriseserver/OData. |
| -user (optional) | Specifies the username for the OData authentication of the registration utility. |
| -pwd (optional) | Specifies the password for the OData authentication of the registration utility. |
| -token (optional) | Specifies the security token for the OData authentication of the registration utility. |
| -ssis (required if deploying SSIS packages) | SQL Server versions: * 13 for SQL Server 2016 |
| /unregister (optional) | Use this parameter to remove the registered objects again. You cannot unregister if an already registered system uses any of the registered objects. |
| /ignoreVersion (optional) | Use this parameter to ignore the version check. |
Registration file
The Register Connectivity utility requires that you include a registration file to define the content to register as well as the location where to find the content for the registered connectivity objects.
The registration file is an XML file that you must define according to this schema: http://schemas.omada.net/ois/2017/ConnectivityRegistrationML.
The schema file is installed together with the SDK and you can find it in the following path: C:\Program Files\Omada SDK\V14.0\schemas.
To ensure that the content of the file complies with the schema, it is recommended that you reference the schema file from your preferred XML editor.
The registration file defines which collector, connector and task mapping objects to create as part of the system registration, for example:
<?xml version="1.0" encoding="utf-8"?>
<connectivityRegistration
xmlns="http://schemas.omada.net/ois/2017/ConnectivityRegistrationML"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
version="14.0.6.45"
packageId="Id13"
packageName="TestPackage"
platformVersion="14.0.6.*">
<collectors>
<collector
name="Foo Collector"
collectorId="FooCollector"
onboardingFile="Onboarding configuration.xml"/>
</collectors>
<connectors>
<connector
name="Foo Provisioning Connector"
connectorId="FooConnector"
dataModelFile="Data model.xml"/>
</connectors>
<taskMappings>
<taskMapping name="Foo User" mappingFile="Task Mapping.xml"/>
</taskMappings>
<codeAssemblies>
<codeAssembly fileName="Foo.dll"/>
</codeAssemblies>
<ssisPackages>
<ssisPackage
packageFile="C:\temp\test\foo wrapper.dtsx"
dtsConfigFile="C:\Program Files\Omada Identity Suite\Datawarehouse\Common\Omada ODW ConnectionString.dtsConfig"
packagePassword="OmadaEncryptionKey"
executePackageTaskPassword="SuperSecretPassword"
server="localhost"
folder="OMADA\ODW\Collector"/>
<ssisPackage
packageFile="C:\temp\test\foo.dtsx"
dtsConfigFile="C:\Program Files\Omada Identity Suite\Datawarehouse\Common\Omada ODW ConnectionString.dtsConfig"
packagePassword="SuperSecretPassword"
executePackageTaskPassword="OmadaEncryptionKey"
server="localhost"
folder="OMADA\ODW\Collector"/>
</ssisPackages>
</connectivityRegistration>
Connectivity registration root
The connectivityRegistration root element requires some additional attributes that you need to specify. Values of these attributes are applied to the created data objects.
| Attribute | Description |
|---|---|
| version (required) | Use this attribute as a description of the version of the package. The version must be given as Major.Minor.Build.Revision or 1.0.0.0 |
| packageId (required) | The package ID is a unique value which is used to identify where a connectivity object stems from. It is registered in the Connectivity Repository CMDB. |
| packageUid (optional) | You can optionally use package UId to specify the data object UId. The value is only used when the object is created and it must adhere to the following format: {e6fdb43f-dd13-4f68-832d-5a9ae6c14eb9}. |
| packageName (required) | This is a friendly name of the package. Both the packageName and packakgeId are needed to create a new Connectivity package data object. |
| platformVersion (required) | You can use the platform version attribute to verify the version of Omada Identity if the connectivity is dedicated to a specific version. The platform version must be specified using the full version number, for example, 14.0.7.24. In such a case, Omada Identity 14.0.7.24 or later must be installed. To allow all revisions of an update, use 14.0.7.*. |
Code assemblies are not updated with version number and package id. The version check is performed against the Enterprise Server version.
Collectors
Under the <collectors> element, you can list all the collectors that you want to register and if necessary, you can also define more than one collector.
You must define each collector in the <collector> element. Each collector is created as a data object of type ODWCOLLECTOR in Omada Identity Enterprise Server.
The following table describes the attribute that you can set and what you can use it for:
| Attribute | Description |
|---|---|
| name (required) | This attribute must contain the name of the collector and includes the name that is displayed in the Enterprise Server. The name attribute is considered the key of the object. The Register Connectivity utility checks if there is already a collector defined with the same name. If a collector is already defined, this collector is updated. The name attribute is also used to identify the collector to unregister. |
| collectorId (required) | This must be the name of the SSIS package to call. This can either be your own collector that you can place in the _\\OMADA\\ODW\\Collector_ folder located in the MSDB database or you can use one of the template collectors. The recommended template collector is:* Omada ODW NET Query: uses the Omada ODW NET Query collector. Additionally, you can use also additional collectors listed below, however, these are not recommended, and will be deprecated in the future update. * Active Directory: uses the Active Directory collector. * Exchange: uses the Exchange collector. * Generic DB: uses the generic database collector. * SAP: uses the SAP collector. |
| onboardingFile (required) | This is the file name on the file which contains the system onboarding configuration template. The file is an XML file complying with the http://schemas.omada.net/ois/2016/SystemCategoryConfigurationML schema.The settings that you define in the onboardingFile attribute appear as tasks in the Definition section of the System onboarding page. |
| uid (optional) | You can optionally specify the data object UId. The value is only used when the object is created and it must adhere to the following format: _{e6fdb43f-dd13-4f68-832d-5a9ae6c14eb9}_. |
| description (optional) | Describe the collector and its purpose. |
Connectors
Optionally, under the <connectors> element, you can list all the provisioning connectors that you want to register and if necessary, you can define more than one connector.
If you want to register connectors, you must define each connector in the <connector> element. Each connector is created as a data object of the type OPSCONNECTOR in Omada Identity Enterprise Server.
The following table describes the attributes that you can set and what you can use them for:
| Attribute | Description |
|---|---|
| name (required) | This attribute must contain the name of the connector and includes the name that is displayed in the Enterprise Server. The name attribute is considered the key of the object. The Register Connectivity utility checks if there is already a connector defined with this name. If a connector is already defined, this connector is updated. The name is also used to identify the connector to unregister. |
| uid (optional) | You can optionally specify the data object UId. The value is only used when the object is created and it must adhere to the following format: {e6fdb43f-dd13-4f68-832d-5a9ae6c14eb9}. |
| connectorId (required) | This is the connector ID given to the connector through the ConnectorName attribute. This can either be your own connector, or you can use one of the following template connectors: * Generic database: uses the Generic database connector. * LDAP: uses the LDAP connector. * PowerShell: uses the PowerShell connector. * REST: uses the REST connector. * Salesforce: uses the Salesforce connector. * SCIM V2.0: uses the SCIM V2.0 connector. |
| dataModelFile (required) | This is the file name of the file which contains the connector data model. The file is an XML file that complies with the http://schemas.omada.net/ops/2015/ConnectorDataModelML schema. A connector data model defines the properties and objects that a connector knows. |
| isTemplate (optional) | Indicates if the connector is a template connector that can be used as a base for new connectivity. By default, this is set to True. |
| isRelayConnector (optional) | Indicates if the connector is a relay connector that relays provisioning jobs to an external provisioning mechanism. |
| template (optional) | The name of the template connector when the connector configuration is based on a template connector. |
| onboardingFile (optional) | Name of the file that contains the system onboarding configuration template for the connector. The file is an XML file complying with this schema: http://schemas.omada.net/ois/2016/SystemCategoryConfigurationML. Settings defined in this attribute appear as tasks in the Provisioning section of the System Onboarding page. |
| onboardingDefaultFile (optional) | Name of the file that contains default settings for system onboarding. The file is an XML file complying with this schema: http://schemas.omada.net/ops/2016/ProvisioningConfigurationDefaultML. Onboarding defaults are used when you enable provisioning for a system to bind a task mapping with a resource type. |
Task mappings
Under the <taskMappings> element, you can list task mappings that you can use for provisioning with connectors. You must define each task mapping in the <taskMapping> element.
In Enterprise Server, each task mapping is created as a data object of the type OPSTASKMAPPING. The following table describes the attributes that you can set and what you can use them for:
| Attribute | Description |
|---|---|
| name (required) | The name of the task mapping in Enterprise Server. The name attribute is considered the Key of the object. The Register Connectivity utility verifies if there is already a task mapping defined with this name. If there is already a task mapping with this name, this task mapping is updated. The name is also used to identify which connector to unregister. |
| uid (optional) | You can optionally specify the data object UId. The value is only used when the object is created and it must adhere to the following format: {e6fdb43f-dd13-4f68-832d-5a9ae6c14eb9}. |
| mappingFile (required) | This XML file contains the task mapping rules. The file complies with the following schema: http://schemas.omada.net/ops/2015/TaskMappingConfigurationML. |
| isTemplate (optional) | Indicates if the mapping is a template mapping that can be used as a base for new connectivity. By default, this is set to True. |
| template (optional) | The name of the template mapping when the mapping configuration is based on a template mapping. |
The value of PackageUid for Registration root as well as Uid for Collectors, Connectors, and Task mappings must be unique across all connectivity packages and objects. Values can be generated using, for example, this page.
The Uid is only used if a connectivity is registered using the OData service.
Code assemblies
Optionally, under the <codeAssemblies> element, you can list code assemblies that contain onboarding POST actions and/or code methods which are used by the connectivity.
Each assembly must be defined in a <codeAssembly> element. If you develop code assemblies, you must register them in Enterprise Server.
You must manually copy the assembly to the C:\Program Files\Omada Identity Suite\Enterprise Server 12\website\bin folder of your Omada Enterprise Server installation.
If you do not do this, the Omada Timer Service breaks and does not function.
This table describes the attribute that you can set and what you can use it for:
| Attribute | Description |
|---|---|
| filename (required) | The name of the code assembly, including the extension. |