Skip to main content

Data import

Connection details​

ParameterDescription
BaseUrlHere, you can specify the Base URL of the service.When you specify the Base URL, this URL will be used for all defined queries if these do not specify a full URL of their own.The Base URL is a part of the data connection data, and the Base URL should not be transported between environments
AuthenticationTypeChoose the type of authentication to use for the ServiceNow system.The available options are: Basic OAuth2 Password OAuth2 Client Credentials Depending on the type of authentication that you choose to use with the system, you may see more or fewer settings appear in the dialog box.
UserType the user name for the user to authenticate with the service.
PasswordType the password for the user to authenticate with the service.Each time you make a change to any of the settings in the Connection details dialog box, you must enter your password again.
DomainThis field is optional.Here, you can specify the domain name for the user.
Token endpointThis field applies only to OAuth2 authentication options.Enter the URL used to exchange an authorization grant for an access token.
Client IDThis field applies only to OAuth2 authentication options.Enter the ID if the client registered with the service.
Client secretThis field applies only to OAuth2 authentication options.Enter the generated secret for the Client ID.
ResourceThis field is optional.Here, you can specify the Resource for which authorization will be granted.
Test connectionThis field is optional.You can check this field to force the collector to test the defined connection before moving froward.

Queries and mappings​

You can create your own queries, use predefined ones, or do both. The predefined queries are the following:

  • Users – Accounts
  • Groups – Resources
  • Roles – Resources
  • Group memberships – Resource assignments
  • Role assignments – Resource assignments

This collector supports any number of queries and has the following query parameters which should be specified when creating of editing a query.

  1. In the URL is a DynamicExpresso expression field, you can specify whether the URL is generated from a DynamicExpresso expression (if Yes is selected) or interpreted directly (if No is selected).

  2. In the URL field, enter the URL for the resource. If “No” is selected in URL is a DynamicExpresso expression, you can specify a full URL or the part of the URL which should be appended to the Base URL. If “Yes” is selected in URL is a DynamicExpresso expression, the URL enables the user to specify a DynamicExpresso expression, which is used to generate the URL dynamically.

  3. Optionally, in the Nested URL field, you can provide any attribute returned from the URL and use it as a nested query. The attribute must be enclosed in brackets, for example, /groups/{PARENT_id}/members?roles=MEMBER.

    important
    • If the URL returns a collection (multi-value), the Nested URL will only be called using the first element of each collection.
    • Moreover, as the Nested URL is called for the number of rows returned from the URL, employing this feature causes a performance penalty.
    • The Nested URL field doesn't allow special characters.

  4. Optionally, in the Append field, enter some query parameters which should be appended.

  5. Optionally, in the Distinct field, specify if the collector should remove possible duplicate rows.

  6. Optionally, in the Filter field under the Parameters heading, you can provide a Dynamic Expresso expression that is used for filtering the data imported into Omada Identity. It returns a TRUE/FALSE result for each imported data row. If the expression returns “FALSE” for the given row that row is skipped during import.

  7. The filter can be supplied with special functions #MinRow() or #MaxRow(). The #MinRow()/#MaxRow() are custom functions that can be combined with regular DynamicExpresso expressions thanks to the # prefix. For example, in

#MinRow(col1, col2)#col=="active"

the custom function is encapsulated with # at the start and end.

The MinRow()/MaxRow() functions take two parameters. The intention is similar to a "Group by function" in SQL server that allow you to eliminate duplicates and to take the lowest or highest [order by column] for each [unique column] row, i.e., MinRow([unique column], [order by column]).

  1. Optionally, in the Description field, enter a description for what this query is doing.

Defining your own query​

  1. In the URL field, enter the URL for the resource. You can specify a full URL or the part of the URL that should be appended to the Base URL.
  2. Optionally, in the Append field, enter some query parameters that should be appended on all calls to the service. This is relevant when the service offers paging.
  3. Optionally, in the Distinct field, specify if the collector should remove possible duplicate rows.
  4. Optionally, in the Collection field, enter the JSON field name of the collection where data is placed. This is relevant if the response returns more than one collection. If you do not specify a field, data from the first collection will be used.
  5. Optionally, in the Filter field under the Parameters heading, you can provide a Dynamic Expresso expression that is used for filtering the data imported into Omada Identity. It returns a TRUE/FALSE result for each imported data row. If the expression returns “FALSE” for the given row that row is skipped during import.
  6. Optionally, in the Description field, enter a description for what this query is doing.

Naming convention for mapping and expressions​

The name used for mapping or expressions is converted into a name that is usable as a C# parameter. Names can contain the characters: _ (underscore), a‑z, A-Z, and 0‑9, but the first character of the name cannot be a digit (0-9). Furthermore, any illegal characters will be stripped from the name during the conversion.

For example, $somekey1 becomes somekey1 and 1another_key becomes another_key.

Mapping of resource owners​

If you create a query to import resource owners, it is possible to specify the resource's owner in two ways. You can do it either by directly importing the UID of the identity or by specifying the account from which the resolved owner is imported as a resource owner.

When mapping directly to the UID of identity, ensure that identities are already imported to Omada Identity.

When mapping to an owned account, it is possible to either specify the business key of the account or the composed business key. The former should be used if the account is in the same system as the resource; the latter should be used if the account is imported into any of the trusted systems.

When the account stems from another system, you should use a Lookup mapping.

Advanced configuration​

ParameterDescription
Perform unfoldingEnable this setting to unfold users’ access to resources assigned through group-level policies. Such resources will be visible as indirect assignments.
Append Url parameter(s)Contains the parameter(s) that is (are) appended to the query string.Useful if the paging URL returned by the service needs additional parameters.
SecurityProtocolThe protocol used for HTTPS handshake: TLS 1.2 or higher.
Timeout in secondsSpecify how long the collector should wait for a response of the AWS service.The default value is set to 3600 seconds (1 hour).
Row count per batchSet the number of objects that will be collected and staged as a batch when paging is implemented in the collector.The default value is 100000.

RoPE configuration​

Before moving to the ServiceNow connector configuration, changes in a Role and Policy Engine (RoPE) configuration file are needed.

  1. Navigate to the location: C:\Program Files\Omada Identity Suite\Role and Policy Engine\Service\ConfigFiles.
  2. Open the EngineConfiguration.config file for editing.
  3. Find the following two sections that are commented out. Uncomment the section marked in bold by deleting the lines with comment markers.
<!--Generic extension for mapping ODW attributes to OPS provisioning attributes.
The extension is typically used when a target system requires an internal identifier to modify or deprovision an account and this identifier is not represented in the ES. In that situation the extension can be used to fetch the identifier directly from the ODW and assign it to a RoPE attribute which can then be used by the OPS.
Default configuration presented below can be used for standard ServiceNow provisioning.
Any attribute to be mapped to RoPE needs to be specified using the following format:
<add key="**UNIQUE KEY (e.g. number)**" extraInfo="**RESOURCE TYPE DISPLAY NAME**" name="**ODW ATTRIBUTE NAME**" value="**ROPE PROVISIONING ATTRIBUTE NAME**" />
Alternatively, if we want to refer to the resource directly (e.g. due to ambiguous resource type names), use the following format:
<add key="**UNIQUE KEY (e.g. number)**" extraInfo="UID:**RESOURCE TYPE UID**" name="**ODW ATTRIBUTE NAME**" value="**ROPE PROVISIONING ATTRIBUTE NAME**" />
-->
<!--
<add type="Omada.RoPE.Controller.OISX.Extensions.MapAttributesFromActualDataExtension, Omada.RoPE.Controller.OISX">

<settings>

<add key="1" extraInfo="ServiceNow Group" name="snowAssignmentID" value="SERVICENOW_ASSIGNMENT_ID" />

<add key="2" extraInfo="ServiceNow Role" name="snowAssignmentID" value="SERVICENOW_ASSIGNMENT_ID" />

</settings>
</add>
-->

Configure thresholds​

The Configure thresholds function allows you to set the amount of changes that cannot be exceeded, relevant to the last import. In the** Configure import thresholds** view, type a number (integer) in percentage for New objects, Modified objects, and Deleted objects to enable thresholds for the import of objects from this system.

The value for each operation is by default set to 0, which means that no threshold calculations take place for the operations until you change the integer. For more information, see the Thresholds section.

important

For all .NET-based collectors, thresholds are calculated in the following relation:

  • If the system category is set to Identity data, the thresholds are calculated.
  • If the system category is set to Access data, the thresholds are calculated.
  • If the system category set to Both, the thresholds only apply to Access data, that is, Accounts, Resources, and ResourceAssignments.