Importing Users and Groups

Through the management of user and group imports, it is possible to synchronize users and groups from an external repository with the database of LumisXP.

It is executed in two stages: in the first, the XML generators are registered, which create the XML file with users and groups extracted from the external repository (an Active Directory, for example). The second stage registers the importers that insert the content of the XML (generated in the first stage) into the database of LumisXP.

Configuration Files

Through the administration of configuration files, it is possible to view and delete the XML files used to access a specific external repository. These files must be located in "lumisdata/config/importprincipal".

To save to the server, configuration files that are local or on other servers that are not the application server must click "Upload File" and inform:

File: In this field, the xml file located in a local directory or another server is assigned. Just locate it by clicking "Browse". Once confirmed, the file will be saved in "lumisdata/config/importprincipal" of the application server.

Example of a configuration file:

<?xml version="1.0" encoding="UTF-8"?>
		
		<config>
			<importgroups>true</importgroups>
			<readers>
				<reader type="ADReader">
					
					<groupShortId>${group.attributes.cn}@mydomain.com</groupShortId>
					
					
					<login>${user.attributes.sAMAccountName}@mydomain.com</login>
		
					
					
					<uris>
						<uri recursive="true">ldap://10.200.10.2:389/OU=Users,DC=MYDOMAIN,DC=COM</uri>
						<uri>ldap://10.200.10.2:389/OU=Groups,DC=MYDOMAIN,DC=COM</uri>
					</uris>
					<credential>
						<user>username@mydomain.com</user>
						<password encrypted="false">password</password>
					</credential>
					<user>
						<attributes>
							<attribute name="phoneNumber" />
						</attributes>
					</user>
				</reader>
			</readers>
		</config>

The configuration file to be created must contain the following tags:

`<importgroups>`	Can contain the values “true” to import the groups located in the directory; or “false” only to import users.
`<readers>`	Groups the various “reader”.
`<reader>`	Defines a reader for users/groups for each specified source.
`type`	The “type” attribute defines the type of reader. LumisXP comes with a reader of type “ADReader” that accesses the Active Directory to extract users and groups. Other readers can be implemented for other types of repositories. For that, just add an attribute named "className" and the qualified name of the custom class that implements the IPrincipalReader interface.
`<groupShortId>`	Expression language used to generate the shortId of groups.
`<login>`	Expression language used to generate user logins.
`<alternativeLogin>`	Expression language used to generate alternative logins for users.
`<uris>`	Groups various possible paths `<uri>` for the repository.
`<uri>`	Defines the path to the repository. In the case of Active Directory, which uses the LDAP protocol, the URI format follows: “ldap://host_name:port/CN=,OU=,DC=”
`recursive`	The “recursive” attribute can be defined with value "true" to traverse the uri recursively and not just at the initial level. By default, this value is false.
`<credential>`	Contains the `<user>` and `<password>` tags
`<user>`	Defines the name of the user who has access rights to the repository.
`<password>`	Defines the user's password to access the repository.
`encrypted`	The “encrypted” attribute must be defined with the value "true" if the password in the configuration file is encrypted. By default, this value is false. For more information on how to encrypt passwords see here
`<user>`	Defines the custom user attributes that should be read from the repository.
`<attributes>`	Contains the custom attributes that have been previously registered in user attributes, which should be read from the repository. The attributes must be keyword, String or text.
`<attribute>`	A custom attribute that should be read from the repository.
`name`	The name of the attribute to be read.

Generate XML

This is the first stage of the user and group import process. It refers to the registration of XML generators. It is necessary to specify a configuration file for access to an AD and an output file containing the extracted data to be imported into LumisXP.

To do this, you must click “add” in the administrative area of XML generators and fill in the following information:

Source: name of the external repository of users and groups;
Configuration file: name of the configuration file (along with the .xml extension) that contains information from the source repository. The file must be in “lumisdata/config/importprincipal ” (there's no need to provide the path);
Output file: name of the file that will contain the data (users and groups) extracted from the external repository. This file will be saved in “lumisdata/data/importprincipal”. If the directory does not exist, it will be created on the first execution for the data extraction.
Schedule automatic execution: indicates whether the generation of the XML will be performed automatically. If the automatic generation option is chosen, it will be done automatically once a day.

To extract data from a certain repository, you must select the corresponding XML generator and click “Run”. Thus, the user and group data will be extracted to the specified output file.

In generating the XML file, the user who does not have windows login, will have the netbios login used as the main LumisXP login. If the user does not have a netbios login, they will not be exported to this file.

As the identification of the user is based on the main LumisXP login, registering a windows login for a user who does not have it is equivalent to changing their main login, and thus, they will be identified as a different user during the import. The same would occur if the windows login were changed.

On the other hand, the netbios login is only taken into account if the netbiosDomain parameter is specified in the configuration file to generate the XML.

Import XML

This is the second stage of the process of importing users and groups from an external repository. In this stage, importers are configured that are responsible for reading the output file generated in the previous stage and writing the information to the LumisXP database.

To do this, you must click on “Add” in the importer manager and fill in the following information.

Source: name of the external repository of users and groups;
Input file: corresponds to the output file from the first stage that will be read by the importers. The name must be provided along with the extension;

The input file must have the following format:

The tags contain the following information:

`<origin>`	Defines the origin name of users and groups.
`<users>`	Contains the list of users.
`<user>`	Contains the properties of the user.
`<login>`	Login of the user.
`<alternativeLogins>`	Contains the list of alternative login for each user.
`<alternativeLogin>`	Defines the alternative login of the user.
`<name>`	Name of the user.
`<channelId>`	ID of the channel that the user will belong to. This field is only filled when the user is a local user of a channel.
`<attributes>`	Contains the custom attributes. The attributes need to be previously registered in the portal settings under User Attributes and must be of type keyword, string or text.
`<groups>`	Contains the list of groups.
`<group>`	Contains the properties of the group.
`<shortId>`	Nickname or short name of the group.
`<name>`	Full name of the group.
`<description>`	Description of the group.
`<channelId>`	ID of the channel that the group will belong to. This field is only filled when the group is local to a channel.
`<members>`	Contains the members of a group.
`<member>`	Login of the user who is a member of the group.

If it exists in the destination: allows to ignore or overwrite the user or group if they exist in the destination;
If it does not exist in the destination: allows to ignore or include the user or group if they do not exist in the destination;
If it does not exist in the source: Allows ignoring or removing groups and disabling users if they exist in the destination and do not exist in the source repository.

Schedule automatic execution: indicates whether the import of the XML will be executed automatically. If the automatic import option is chosen, the import will be performed automatically once a day.

To import into the LumisXP database, you must select the corresponding XML importer and click “Run”.

Thus, the user and group data will be imported into the database and can be accessed via the Users and Groups Manager.

XML Files

Through the administration of XML files, it is possible to view and delete the files that contain the users and groups extracted from a specific repository. They are the output files of the "Generate XML" process and are used as input files in the "Import XML" process. These files are located in "lumisdata/data/importprincipal".

To save to the server, XML files that are local or on other servers that are not the application server must click "Upload File" and inform:

File: In this field, the xml file located in a local directory or another server is assigned. Just locate it by clicking "Browse". Once confirmed, the file will be saved in "lumisdata/data/importprincipal" of the application server.