Background processes

The SecuritySqlImport worker exports users, groups, and their dependencies to an XML file. This file can then be used to import the exported entities into the user management system of the 446 Plattform. However, the worker itself does not perform any import functions. Rather, it starts a preconfigured user import for a specific group. This means that the import for the respective group must be configured and activated. Additionally, the name of the XML file generated by the worker should match the name specified in the group's import configuration.

After the worker writes the XML file and selects the option to start the import immediately, the system checks if there is an active XML import group and if the import file name matches the output file name.

All listed properties can be configured directly in the 446 Plattform interface under Settings > Administration > Background processes.

Select the SecuritySqlImport worker from the list of installed workers. This will open the settings. All of the properties listed here can be found on the Properties tab.

• ProviderForGroups:

Here, you specify which database provider should be used to access the database from which the groups will be retrieved. This depends on whether you are using a Microsoft SQL Server, an Oracle Server, or a different product.

Note:

Possible provider are:

• System.Data.SqlClient

• System.Data.OleDb

• System.Data.Odbc

• System.Data.OracleClient

These also apply to the following two properties.

• ProviderForMembership:

Here, you specify which database provider should be used to access the database from which the memberships will be retrieved. This depends on whether you are using a Microsoft SQL Server, an Oracle Server, or a different product.

• ProviderForUsers:

Here, you specify which database provider should be used to access the database from which users will be retrieved. This depends on whether you are using a Microsoft SQL Server, an Oracle Server, or another product.

• ConnectionStringForGroups:

The connection string for connecting to the database from which the groups are to be retrieved.

• ConnectionStringForMembership:

This is the connection string used to connect to the database from which the membership properties are retrieved. These properties include hierarchical connections between groups and users, as well as between groups themselves.

• ConnectionStringForUsers:

The connection string for connecting to the database from which the users are to be retrieved.

• StatementForGroups:

The SQL statement that retrieves the groups is specified here.

• StatementForMembership:

The SQL statement that retrieves the memberships is specified here.

• StatementForUsers:

The SQL statement that retrieves the users is specified here.

• SqlCommandTimeoutInSeconds:

This specifies how long to wait for a response from the database before registering a timeout. The default value is 30 seconds. If the response is not registered within this time frame, a timeout is returned.

• PasswordsForNewUsers_Generate:

Specifies whether a password should be generated for new users. Possible values are True and False.

Note:

If new users are imported from an XML file, they will not be able to log in unless a password is generated.

If XML import is used to update existing users, this option should be set to False. This will retain the user's current password.

If this option is set to True, a new password will be generated during import. However, this only applies to new users. No new password is generated for existing users; only their user properties are updated. If new passwords are to be generated, care should be taken to ensure that passwords are not retrieved when querying users (see StatementForUsers). All queried fields from the source are stored as properties in the XML. This means that passwords would be written to the XML in plain text, as they are stored in the data source.

If this option is set to False, the password must be requested from the data source for each user. The password is then stored in encrypted form in the XML and transferred to the user database during import. To ensure the importer knows which field contains the password, specify the field name in the PropertyNameForNewUserBehavior property.

• PasswordsForNewUsers_FieldName:

This option is only required if the PasswordsForNewUsers_FieldName option is set to False. If this is the case, the name of the field containing the password must be specified here.

Example:

If the result of the SQL query contains the columns First_name, Last_name, Email, Address, Password, then the column name “Password” must be entered here.

• IdentifierColumnForGroups:

Here, you specify the name of the column (field) that contains the unique ID for the groups.

• IdentifierColumnForMembership:

Here, you specify the name of the column (field) that contains the unique parent ID for the membership. This parent ID must exist as an ID in the table with the groups.

• IdentifierColumnForUsers:

Here, you specify the name of the column (field) that contains the unique ID for the users.

• InvokeImporterAfterWritingXml:

This specifies whether the worker should automatically start the group/user import after writing the XML file. Possible values are True and False.

• OutputFile:

The complete path to the output file is specified here. If you want to start the import immediately after creating the file (property InvokeImporterAfterWritingXml set to True), the path should be the same as the one configured in the group import (see Configuring the Import for a User Group).

An assignment schema is still required to import the groups and users into the user management system. Here is an Example::

<AssignmentSchemes>
    <Scheme objectguid="60b7001199c54e8fb22b6525fbce841b" useOnlyCurrentUniqueId="false" friendlyName="Standard">
        <Group>
            <Alias>organizationalUnit</Alias>
            <Alias>group</Alias>
            <Alias>builtinDomain</Alias>
            <Alias>container</Alias>

            <Assignment source="name" destination="{Name}" />
            <Assignment source="description" destination="description" />
        </Group>
        <User>
            <Alias>user</Alias>
            <Alias>foreignSecurityPrincipal</Alias>

            <Assignment source="sAMAccountName" destination="{LoginName}" />
            <Assignment source="{Domain}+'\'+sAMAccountName" destination="{LoginName0}" />
            <Assignment source="userPrincipalName" destination="{LoginName1}" />
            <Assignment source="{Domain}+'\'+sAMAccountName" destination="{LoginName2}" >
                <Replace original="ADS-Name\" replaced="PreWindows2000Domain\" />
            </Assignment>

            <Assignment source="mail" destination="exchangealias" />
            <Assignment source="legacyExchangeDN" destination="legacyExchangeDN" />

            <Assignment source="givenName" destination="firstname" />
            <Assignment source="sn" destination="lastname" />
            <Assignment source="department" destination="department" />
            <Assignment source="telephoneNumber" destination="phonedirect" />
            <Assignment source="mobile" destination="phonemobile" />
            <Assignment source="mail" destination="email" />
            <Assignment source="company" destination="company" />
            <Assignment source="streetAddress" destination="street" />
            <Assignment source="postalCode" destination="zip" />
            
            <DefaultAttribute name="MessagingManager.DeliveryDisabled" value="false" />
            <DefaultAttribute name="MessagingManager.UnifiedEmailDelivery" value="True" />
            <DefaultAttribute name="MessagingManager.SmsDelivery" value="False" />
            <DefaultAttribute name="MessagingManager.PagerDelivery" value="False" />
        </User>
    </Scheme>
    
    <Scheme objectguid="2348001199c54e8fb22b6525fbce841b" useOnlyCurrentUniqueId="false" friendlyName="XML">
        <Group>
            <Assignment source="name" destination="{Name}" />
        </Group>
        <User>
            <Assignment source="ID" destination="{LoginName}" />

            <Assignment source="Firstname" destination="firstname" />
            <Assignment source="Lastname" destination="lastname" />
            <Assignment source="EMail" destination="email" />
        </User>
    </Scheme>    

</AssignmentSchemes>

The example shows two configured schemas. The first is the standard LDAP import schema, and the second is the XML import schema.

Further information on the assignment scheme can be found in the chapter Import.

This worker reads from a CSV file, and creates or updates tickets. One column of the CSV file has to be defined as the Identifier column. The worker searches for any non-deleted ticket that has that identifier, and will update the existing ticket. Otherwise, it will create a new ticket.

If there are multiple rows with the same identifier value in the CSV file, their field values are combined, if different from each other. Therefore, different combination types can be specified in the mapping. The worker uses the feature key EnableCsvToTicketImporter.

It is a scheduled worker (thus, not pausable) and has the following properties:

• ColumnDelimeter:

One character, which is used as the CSV column delimeter. Default is ';'.

• CsvFilePath:

Full path with filename to the CSV file.

• PauseInMillisecondsAfterNewTicket:

Whenever a new ticket is created by the importer, it waits the configured amount of time, before continuing with the next record. This is to avoid load spikes at the workflow manager. Default is 1000, means: one second.

• PauseInMillisecondsAfterUpdateTicket:

Whenever an existing ticket is updated by the importer, it waits the configured amount of time, before continuing with the next record. This is to avoid load spikes at the workflow manager. Default is 100, means: one tenth of a second.

• MappingFileName:

Name of the mapping file, which defaults to FieldMapping.xml. The mapping file has to be located in the worker directory.

The FieldMapping XML file

<?xml version="1.0" encoding="utf-8" ?>
<Csv2TicketMapping
    client="default"
    ticketSchema="incident"
    identifierField="Opportunity_Id"
    identifierColumnWithTicketId=""
    creatorUser="login_name_admin"
    affectedUser="login_name_admin"
    workflowOnChange="0487c756-23c0-4fbf-b754-df391233a609"
    deleteFileAferImport="false"
    deleteFileFolderAfterImport="false">
    <ImportNotificationTicket enabled="False">
        <Identifier type="TicketDataId" location="DirectoryName" />
        <Workflow onSuccess="1563f478-459b-4d6c-9054-80392c7040c3" 
            onError="ab5dfd34-76f9-42f2-93f3-d904d256c9d9" />
    </ImportNotificationTicket>
    <TicketStates>
        <State value="Closed" />
    </TicketStates>
    <Fields>
        <Field source="Division" target="Division" />
        <Field source="Company" target="CompanyName" >
            <SpecialBehavior value="DoNotUpdate" logicalOperator="and">
                <Condition operator="notequals" value="NA" />
                <Condition operator="notequals" value="Dumb" />
            </SpecialBehavior>
        </Field>
        <Field source="Location" target="City">
            <SpecialBehavior value="CreateNoTicket">
                <Condition operator="equals" value="NA" />
                <Condition operator="equals" value="Dumb" />
            </SpecialBehavior>
        </Field>
        <Field source="Amount (gross)" target="Amount" combine="sum" />
        <Field source="Opportunity_Id" target="OpportunityId" />
        <Field source="CiField1" valueSource="CiField1Value" target="CiField1" />
        <Field source="KeyValueField1" valueSource="KeyValueField1Value" target="KeyValueField1" />
    </Fields>
    <Properties>
        <Property target="creatorUser">
            <PrincipalAttribute source="Opp. manager (First name)" target="firstname" />
            <PrincipalAttribute source="Opp. manager (Last name)" target="lastname" />
        </Property>
        <Property target="affectedUser">
            <PrincipalAttribute source="Customer (First name)" target="firstname" />
            <PrincipalAttribute source="Customer (Last name)" target="lastname" />
        </Property>
    </Properties>
</Csv2TicketMapping>

Configuration of the FieldMapping XML file

Attributes of the Document Element node Csv2TicketMapping:

• client:

Is either default (which makes the first client to be used), a client ObjectGUID, or a client name.

• ticketSchema:

FriendlyName or ObjectGUID of a ticket schema.

• identifierField:

This is the field which holds the identifier, by which an existing ticket is searched to update. If there is no ticket with that field found, a new ticket is created. This attribute has to point to one of the Field nodes in the mapping, and has to match the source attribute there. The identifierField attribute may be empty (not: missing). If empty, the importer won't look for existing tickets, but create exactly one ticket for every row of the CSV file.

• identifierColumnWithTicketId:

If the field specified here contains a ticket number in the CSV file, the importer will use it to find a ticket. If the field in the CSV is empty or no ticket with the specified ticket number is found, the importer will create a new ticket. Attention: This option cannot be used in conjunction with the identifierField option. Only one of the two options can be used.

• creatorUser:

Login name or ObjectGUID of a user to be used as the default creator user.

• affectedUser:

Login name or ObjectGUID of a user to be used as the default affected user.

• workflowOnChange:

Optional. If missing, empty or Guid.Empty, no workflow is started after an existing ticket has been updated. Otherwise, it has to contain the ObjectGUID of a workflow.

• deleteFileAfterImport:

Optional. If True, then the CSV file is deleted after it has been processed.

• deleteFileFolderAfterImport:

Optional. If True, then the parent folder of the CSV file is deleted after the file has been processed but only if it is empty. So, it can be really used only together with the deleteFileAfterImport setting.

Attributes of the individual ticket field mapping nodes (Field):

• source:

Name of the column in the CSV file to map.

• valueSource:

Optional. Name of the column in the CSV file to map for the ticket field VALUE. The attribute source maps only to the ticket field TEXT.

• target:

FriendlyName of the ticket field where the content should be written to.

• combine:

Optional attribute. If missing, it defaults to AppendIfDifferent. Meanings of the different combine types:

• Overwrite:

If the value is different from the previous value, the previous value is overwritten.

• AppendIfDifferent:

If the value is different from the previous value, the new value is appended to the existing value in a new line.

• AppendIfDifferentWithBrTag:

Same as AppendIfDifferent, but with an additional <br> tag for each new line character.

• Append:

This option just appends the values on a new line, ignoring if the value already exists or not.

• AppendWithBrTag:

This option works as the Append, but it also adds <br /> tags.

• Sum:

Requires that the values are integers, and adds the value of the previous and current value together, building the sum.

• Optional child nodes of the type SpecialBehavior:

• value:

• CreateNoTicket:

This prevents the worker from creating new a ticket, when the value of the field matches the underlying condition(s). Existing tickets will still be updated.

• DoNotUpdate:

This prevents the worker from updating an existing ticket, when the value of the field matches the underlying condition(s). If no existing ticket is found, new tickets will still be created.

• logicalOperator:

• or:

One of the conditions has to match. This is the default behavior if the logicalOperator attribute is missing.

• and:

All of the conditions have to match.

• Child nodes of the type Condition:

• operator:

• equals:

The imported value has to match the specified value attribute, the check is done case insensitive.

• notequals:

The imported value has to be different than the specified value attribute, the check is done case insensitive.

• value:

A given text to be matched.

Attributes of the ticket property mapping nodes (Property):

• target:

Name of the property. creatorUser and affectedUser are supported. Logic for the affected group: main group of the affected user. This way, these users can be set for each ticket according to the CSV file instead of using the default users.

• Child nodes of the type PrincipalAttribute:

• source:

Name of the column in the CSV file to map.

• target:

Name of the user attribute to which the content has to match.

Attributes of the optional ticket status white list mapping nodes (State):

• value:

FriendlyName or ObjectGUID of a ticket status. A ticket will be updated only when it has the given status (multiple status can be allowed using multiple nodes).

Attributes of the optional ImportNotificationTicket node (ImportNotificationTicket):

• enabled:

If set to True, then a ticket will be searched which will be modified after the CSV file has been processed: in case of an error, an error log file will be attached to that ticket. Plus, the ticket can be moved to certain workflows after the CSV file has been processed. If the node ImportNotificationTicket is missing, its functionality defaults to False. In case a notification ticket is available, all created tickets from the CSV file are created as successors of it.

• Child node Identifier attributes:

• type:

The only supported value is TicketDataId. Means: the value must match with the internal ticket data id.

• location:

The only supported value is DirectoryName: Means: the parent directory name of the CSV file contains the ticket identifier.

Example: C:/../<TicketDataId>/ImportFile.csv

• Child node Workflow attributes:

• onSuccess:

GUID of the workflow where the specified ticket will be moved to after the CSV import was successful.

• onError:

GUID of the workflow where the specified ticket will be moved to after the CSV import has failed for any reason.

The Worker Send and Receive are used to exchange and synchronize ticket information between different 446 platforms. Tickets that should be synchronized must be explicitly marked for this purpose (plug-in: MarkForSync).

For the synchronization of a ticket, the send worker writes all log entries of the ticket into a synchronization database. The Receive Worker running on the other side fetches these entries and processes them accordingly.

With the client config key Isonet.Synchronisation.IsEnabled the synchronization can be activated or deactivated.

The following ticket information can be transferred:

The license key EnableWorkerManagement makes the workers visible in Worker Management.