Importing users

You can import users, with related filters and groups, from Excel files, LDAP sources, or a combination of both.

We recommend that you have one import task per set of users, groups, and filters. You can have different sources for the same entities. For example: one Excel file for managers and one Excel file for vendors, where both files have a common group or filter. Both of these sources should be attached to the same import task. You can change the path of your Excel and LDAP sources when needed.

Tip: You can update Qlik NPrinting group, user, and filter information nightly into a file with the same name, and load it to the same recipient import task path location.

Limitations

There are some limitations when importing:

  • You cannot import filters using LDAP. You must use an Excel file.
  • If you need to create or delete security roles, you must do so manually in the Qlik NPrinting web console. See: Managing roles
  • You can import from LDAP forests, trees, and domains that are different from the Qlik NPrinting server. However, cross-memberships between forests is not supported.
  • When importing users from LDAP, locale and time zone values are not available. Users imported this way will default to English and UTC. You can set different locale and time zone values by importing users from an Excel file, or changing them manually. Importing the same users again via LDAP will not overwrite locale and time zone values.

There are some limitations when importing users via Excel:

  • If groups, roles, or filters added in the row do not exist, they will be ignored.
  • If the name of a filter, user, or role contains commas, use double quotes as delimiters. Example: "Jeremy Martinson, Jr."

  • If a field value contains double quotes, leading/trailing spaces, or "{", "}" you must start and end the string with double quotes. Double quote characters must be inserted twice in order to differentiate them from escape quotes.

    Example:

    • [Country]={" Italy, France ", "Germany",Spain} => " Italy, France ","Germany","Spain"
    • [Country]={"""Italy"""} => ""Italy""
    • [Country]={"{Sweden}"} => {Sweden}
  • In order to import a field with leading/trailing spaces, you must start and end the string with square brackets.

    Example: [ Country ]={Italy}, CountryBorn ={Italy} => " Country "={Italy}, "CountryBorn"={Italy}

  • You cannot insert "[", "]" as field names.

  • You can delete existing filter fields by adding fields (values, numeric values, or formula columns) with a valid name and an empty values list. The Update filters if modified check box must be selected.

    Example:

    • [Country] => input ignored
    • [Country]={} => filter field with name country removed

 

Import syntax in Excel documents

You must create an Excel file with the following exact names on the worksheets and columns. You cannot re-order or remove columns. You cannot re-arrange or remove worksheets.

If you want an Excel file with sample users for testing: visit Sample files, download Examples.zip, and open Recipients.xls.

Import filter syntax

The first worksheet contains filter definitions. If a value or formula contains commas, use double quotes as delimiters. For example: [SalesmanName]={"Jeremy Martinson, Jr.", Tom Lindwall}.

If a filter uses the Select excluded feature to exclude values, add <excluded> at the end. For example: [CategoryName]={Babywear, Men´s Wear, Women's Wear}<excluded>

Filters
Property Description Example
Name The name of the filter. Quarterly Sales
Description The purpose of the filter. (Optional) Sales from the current quarter.
App The name of the app associated with the filter. The app must exist on the server. SalesDemoApp
Enabled Set to TRUE if you want to create an active filter. Set to FALSE to create an inactive filter that will be ignored during report generation. TRUE
Connection The name of the connection. By specifying this, you can create different filters based on fields with the same names from different connections in the same app. The connection must exist on the server. SalesDemoConnection
Values Use to filter string values. List them in the form: [field name]={value1,value2,...}. To add values for more than one field, separate them with a comma. To exclude values, add <excluded> at the end. [Country]={Italy,Germany,Spain}, [CategoryName]={Babywear, Men´s Wear, Women's Wear}
Numeric Values Use to filter numeric values. List them in the form: [field name]={value1,value2,...}. CategoryID={1.0,"5",8.2}
Formulas Use to calculate values to filter by using QlikView formulas. List them in the form: [field name]={formula1,formula2,...}. Year={Year(now()), Year(now())-1,Year(now())-2}
Advanced Search Use to filter values by using QlikView or Qlik Sense advanced search expression. List them in the form: [field name]={advancedformula1,advancedformula2,...}. ProductName={=ProductName like '*Shoes*'}

Import user syntax

The second worksheet contains user definitions.

Users
Property Description Example
Email The user's unique email address. It will be used to log in. john_brown@qlik.com
Username The unique user name that is displayed in the interface to identify the user.

If you import a user with the same name as an existing user, the import will overwrite the existing user. If you import a user with the same name as an existing entity (group, role) that is not a user, you will get an error. The same error will happen if you import a group with the same name as an existing user.

John Brown
Password The password the user uses to log in to Qlik NPrinting. testpass
Domain Account The unique domain account assigned to the user. (Optional)

A user must have an associated domain account to use the following features:

  • Receive reports in Qlik Sense hub.
  • Create On-Demand reports in QlikView.

    The user's Windows Active Directory user account must be associated as the domain account.

JohnBrown33
Enabled Set to TRUE if you want to create an active user. Set to FALSE to create an inactive user that will be ignored during report generation. TRUE
Time Zone Report publishing is scheduled according to the time zone of the user. You must type the name as it appears in the Qlik NPrinting interface. Europe/Rome
Locale The display language of Qlik NPrinting. There are eight options: En (English), Es (Spanish), Fr (French), De (German), Pt (Portuguese), Ja (Japanese), It (Italian), Zh (simplified Chinese). It
Description The description of the user. (Optional) Account manager, Vicenza.
NickName The user's nickname. (Optional) JoBrown
Title The user's title. (Optional) Mr.
Company The user's company. (Optional) Qlik
Job Title The user's job title. (Optional) Account Manager
Department The user's department. (Optional) Sales
Office The user's office. (Optional) 1st floor, Vicenza
Folder Report destination folder that the user can assess. (Optional) C:\QlikReportingTraining\Output\
Sub Folder Report destination sub-folder that the user can assess. (Optional) John Brown
Read Password The password needed to open reports. Credential authentication will be disabled for the user if no password is specified. (Optional) password33
Write Password The password needed to edit reports. Credentials authentication will be disabled for the user if no password is specified. (Optional) password44
Filters The list of filters the user can access, separated by commas. (Optional) Quarterly Sales
Groups The list of groups the user is a member of, separated by commas. (Optional) Marketing Team, Sales Team
Roles The list of the user's security roles, separated by commas. (Optional) Developer, Administrator

Import group syntax

The third worksheet contains group definitions.

Groups
Property Description Example
Name The name of the group. Marketing Team
Description The purpose of the group. (Optional) Global Marketing Team
Enabled Set to TRUE if you want to create an active group. Set to FALSE to create an inactive group that will be ignored during report generation. TRUE

Import syntax in LDAP sources

Connection syntax

Connection
Property Description Default value
Connection path The URI used to connect to the directory server. To support SSL, specify the protocol as LDAPS instead. Currently, LDAPS is only supported for Active Directory. You can add a distinguished name (DN) to change the starting container: ldap[s]://[server address[:port]/][dn] ldap://company.domain.com
User name The user ID used to connect to the directory server. If this is empty, the user running the repository is used to log on to the directory server. (Optional) -
Password The password for the user. (Optional) -

User directory name

The name of the UDC instance (to be compared to the domain name of an Active Directory). If you leave this field empty, it will be populated with the correct domain name in Active Directory servers, or with the first DC component of the distinguished name. -

Entry attributes syntax

The entry attributes should reflect the attributes names of your LDAP server.

Entry attributes
Property Description Default value

Type

The types that can be imported are: users, groups, and roles. objectClass
User identification

The attribute value of the directory entry that identifies a user. A value that the attribute specified by Type can assume.

inetOrgPerson
Group identification The attribute value of the directory entry that identifies a group. A value that the attribute specified by Type can assume. group
Role identification The attribute value of the directory entry that identifies a role. A value that the attribute specified by Type can assume. group
Account name The attribute that specifies the unique name that the user uses to log in. sAMAccountName
Email The attribute name that holds the emails of a directory entry (user). mail
Display name The attribute that holds the full name of a directory entry (user, group, role). name
Group membership

The attribute that indicates the direct groups that a directory entry is a member of. Indirect group membership is resolved during user synchronization.

memberOf
Members of directory entry

The attribute name that holds a reference to the direct members of this directory entry.

member
Role membership The attribute that indicates the direct security roles that a directory entry holds. Indirect group roles are resolved during the user synchronization. memberOf

Advanced syntax (optional)

Advanced
Property Description Default value
Timeout (seconds) The timeout for reading data from the data source. 240
Page size of search

Determines the number of posts retrieved when reading data from the data source. When the specified number of posts have been found, search is stopped and the results are returned. When search is restarted, it continues where it left off.

Tip: If the user synchronization is unsuccessful, try setting the value to '0' (zero), which is equal to not doing a paged search.

2000

Alternative group path The distinguished name for using a different directory entry as staring point for group search. -
Alternative role path The distinguished name for using a different directory entry as staring point for role search. -
Additional user filters The LDAP query used to retrieve the users in the directory. -
Additional group filters The LDAP query used to retrieve groups in the directory. -
Additional role filters The LDAP query used to retrieve roles in the directory. -

Active directory

Active directory users should change the User identification value from inetOrgPerson to user or person. The default behavior is to import all groups. If you would like to import a specific group, use the Alternative group path or Additional group filters fields.

Merging import source data

Merge policy refers to the rules to apply when merging data from an import step with the results of previous steps. The synchronization in the Qlik NPrinting repository of import source data merge results do not use a merge policy. They are based on your import task settings. See: Creating an import task.

User merge key

This specifies the user field used to identify when a user retrieved from import sources is referring to an existing user. The algorithm used to merge the user data is based on entity and associations merge policies. In order to match the imported entities against the Qlik NPrinting repository, the Username is always used, so this merge key is not considered.

Entity merge policy

This specifies the algorithm used to merge the data retrieved from different import sources that are referring to the same entity (user, group or filter). It is not applied to fields that are mapping an association to another entity (user filters, roles and groups, and filter fields).

The supported values are Overwrite, Update missing, and Ignore. The data retrieved from a previous import source are:

  • Overwrite: removed and replaced by the most recent import. Columns that exist in a previous step, but not the latest step, are not changed.
  • Update missing: ignored, except for values not present in previous import tasks, which are added.
  • Ignore: ignored.

Association merge policy

This specifies the algorithm used to merge data retrieved from different import sources that are referring the same entity (user, group or filter). It is applied to fields that are mapping an association to another entity (user filters, roles and groups, and filter fields).

Supported values are Overwrite, Merge, and Ignore. The list of entities retrieved from a previous import steps are:

  • Overwrite: removed and replaced by the most recent import. Columns that exist in a previous step, but not the latest step, are not changed.
  • Merge: merged.
  • Ignore: ignored.

Assigning import rights to a security role

To import users, you must log into Qlik NPrinting web console as a user with Import task rights in at least one security role. Users with an Administrator role have Import task rights. If you apply the Administrator role to a user, they will also have all other administrative privileges.

You can also assign import rights to a security role, without giving it other administrative authority.

Do the following:

  1. Log into Qlik NPrinting web console as a user with the Administrator security role.
  2. In the Qlik NPrinting main menu, click the Admin drop-down menu.
  3. Click Security roles.
  4. Click on the role you want to give Import task rights.
  5. Click on the Apps tab.
  6. Scroll to the Import task rights check boxes.
  7. Select the check box to the left of Import task to assign all import task rights to the role.

    You can also select only specific rights by selecting the appropriate check boxes.

  8. Click Save.

Creating an import task

Do the following:

  1. In the Qlik NPrinting main menu, select Tasks, and then select Import Task.
  2. Click Create import task.
  3. Insert the Name of the task. For example: Import Users.

  4. Ensure the Enabled check box is selected. Otherwise, your task will be ignored by the Qlik NPrinting Engine.
  5. Under Sources, click Add Source. In the drop-down menu, select Import from Excel or Import from LDAP.
  6. The next steps will depend on the source type:
    1. Excel: Add the Import file path (on server) of the Qlik NPrinting Server where the Excel file is saved.

      For example: C:\ProgramData\NPrinting\Imports\NP_Web_Imports.xlsx. This is not the file path on your local computer.

      You can also use a remote computer network path. The Windows user that runs the Qlik NPrinting scheduler service must have access to the remote folder from the Qlik NPrinting Server.See: Import syntax in Excel documents.

    2. LDAP: Add the Connection path of the LDAP source.

      You can fill in the other fields as needed. See: Import syntax in LDAP sources.

  7. Ensure the Enabled check box is selected. Otherwise, your source will be ignored by the Qlik NPrinting Engine.
  8. Click Add Source to add another source.
  9. Click Delete, on the right, to delete a source. Click Duplicate to duplicate it.
  10. Under Settings, select the check boxes that specify how you want to handle merge conflicts:
    • Create users if not present
    • Update users if modified
    • Remove users not present in newest import sources

      Only users added in a previous run of the same import will be removed. Other users, like those added manually, will not be removed.

    • Replace existing user associations (filters, roles, and groups)

      Existing user associations will be removed if not present in the import file. They will be replaced with associations in new file.

    • Remove groups not present in newest import sources

      Only groups added in a previous run of the same import will be removed. Other groups, like those added manually, will not be removed.

    • Create filters if not present
    • Update filters if modified
    • Remove filters not present in newest import sources

      Filters added in a previous run of the same import will be removed. Other filters, like ones added manually, will not be removed.

    • Replace existing filter fields

      Existing filter fields will be removed if not present in the import file. They will be replaced with filter fields from the import file.

  11. Under Notifications, you can select Send task notifications. An email will be sent to the addresses specified under Settings > Tasks. See: Task execution notifications.
  12. Click Create.

Running the import task

The green bar at the top of the form confirms that the task was created successfully. There are different ways of running the task.

Do one of the following:

  • Click Run now to import users, filters, and groups immediately.
  • Click Test now to test the task. This runs a dummy import, and generates a .txt file with the results. This way you can check for merge conflicts before running an import.
  • Click the Triggers button to schedule the execution of the task. See: Creating a distribution schedule.

    NPrinting import task successfully created

Checking task status

On the Import filters and recipients task main page, you can see the status of your import tasks.

  • Last execution: shows the date and time of the last execution.
  • Last execution status: if a task ran successfully, it will show as Completed. Otherwise, it will show as Failed.
  • Last execution progress: shows how far an active task has progressed.
  • Last import log: click the Download link to see the latest logs associated with the task.

    If an error occurs during the import, the log file will show the error message in the current locale of the computer where the import was executed. The import for all users will halt at the first error, and the entire import is rolled back. The log file download contains a log line for each import action. The task execution logs only contain the main logs, such as errors and progress information.

  • Enabled: if this check box is not selected, your task will be ignored by the Qlik NPrinting Engine.
  • Actions: Click the Settings to edit, delete, run, or test the task.

Check the imported users on the Users page to see newly created users. You can check that associated filters were created by opening the Filters tab.

Did this information help you?

Thanks for letting us know. Is there anything you'd like to tell us about this topic?

Can you tell us why it did not help you and how we can improve it?