Parameters

As a connector developer, you almost always need some information from the administrator to be able to read and write data from the connected directory. With the parameters interface, you can configure how these pre-defined pages are rendered so you can get required data.

These pages appear at pre-defined locations in the UI. There is usually an interface with a similar name the page is closely associated with. These pages are as follows:

• Capabilities
• Connectivity
• Schema (available with GetConfigParametersEx)
• Global
• Partition
• RunStep

There are two functions for returning configurable parameters to the sync engine.

Function GetConfigParameters(configParameters, page) As ConfigParameterDefinition
Function GetConfigParametersEx(configParameters, page, pageNumber) As ConfigParameterDefinition

The latter, with Ex, is used when you need a dynamic number of pages for schema discovery in the UI. In all other cases, the first method can be used.

There are also two functions for validating the information.

Function ValidateConfigParameters(configParameters, page) As ParameterValidationResult
Function ValidateConfigParametersEx(configParameters, page, pageNumber) As ParameterValidationResult

Common scenarios would be to verify credentials and that required data is not empty.

Parameter pages

You don't need to have parameters on all pages and there is also some freedom for having a parameter on another page than the one with the same interface name. This freedom is mostly for the GetCapabilities interface. This is not called until after the Connectivity page. The reason is that in some cases you do not know what the remote directory can do until you have connected to it. In cases where you only need to ask the administrator for a single property, it might be better to put this on the connectivity page and not have a page with a single option. An example of this can be seen with the Generic SQL Connector.

Some pages have a special behavior.

The capabilities page only appears on connector creation. When editing or viewing an existing connector, this page is not visible.

The connectivity page appears when the connector needs to gather credentials in other places as well. As an example, when the administrator click refresh schema in the UI, the connectivity page appears to gather credentials.

Schema pages

The schema pages are different compared to the other pages. It is the only page that can appear as multiple pages. It is used when the configuration is complex, such as the Generic SQL connector. The Ex version of the interface was added to support the complexity of this connector.

When the connectivity page has completed, the GetConfigParametersEx is called for schema with the pageNumber 1. The method can then gather some information from the administrator, verify it, provide another page, and ask for more information. The number of pages is dynamic and one additional page is added until the method does not return any more parameters in a call.

Elements on a page

The method should return the elements it wants to be drawn in the sync engine UI in the correct order.

The following elements are available:

Name	Apperance
CheckBox
Divider
DropDown
EncryptedString
File
Label
String
Text

Most of these have an overloaded version so the default value can be passed in.

For string and encryptedstring, there is also a validation parameter. This allows for the sync engine being able to verify the format using the provided RegEx. This can be easy when you know the format for a field and the name of the field is obvious to the administrator. For example, a server name should not include special characters and port should only be numeric.

It is also common to just pass in empty in the validation parameter and do it all in the ValidateConfigParameters method instead. This would allow you to pass back a custom error message to the administrator.

Validate parameters

The validate parameters method allows you to verify the parameters provided by the administrator. If there is a problem with the data, then you set ErrorMessage on ParameterValidationResult. You can also set ErrorParameter indicating which parameter caused the problem, but that is optional. If everything is ok, then return success on the Code property.

Limitations with parameters

Some more advanced configuration options are not possible. You would have to work around these limitations or live with a non-optimal experience.

The most common feedback is that a page cannot be updated based on what the administrator selects. For example, in Generic LDAP there is a binding drop-down. If you select anonymous, then you should not provide any credentials, if you select basic, you need username and password, and if you select Kerberos, you also need to provide the realm. But the page always has all three parameters and you have to document which to use for different scenarios.

The elements are also a fixed list and you cannot add your own element to the sync engine UI. For example, in the built-in SQL connector there is a grid that allows attribute configuration. In the Generic SQL connector, the same configuration is instead a long list of drop-downs, one for each attribute.