Installation

If the accounts in steps 2 and 4 both use Windows authentication, they MUST be the same account.

1.Record all necessary environmental details as you complete these steps. To keep track, you may want to print the Installation details checklist.

2.Identify or create a user account with read-only permissions to the target application database(s). The username(s) can be any valid name, but Ivanti recommends using Xtraction_RO for consistency. If this account uses Windows authentication, be sure to include the domain name (e.g., MYDOMAIN\myuser).

•For MS SQL, it should be sufficient to grant db_datareader access.

3.Manually create the Xtraction database on an MS SQL server to store the Xtraction data. The database name can be any valid name, but Ivanti recommends using Xtraction for consistency.

4.Identify or create a user account to enable Xtraction to connect to the Xtraction database with read, write, and owner permissions. The username can be any valid name, but Ivanti recommends using Xtraction for consistency. If the account uses Windows authentication, be sure to also include the domain name (e.g., MYDOMAIN\myuser).

•For MS SQL, it should be sufficient to grant db_owner, db_datareader, and db_datawriter permissions once the tables are created.

1.Run Setup.exe to start the install wizard. After reading the welcome message, click Continue.

2.After reading the license agreement, select I accept the terms in the License Agreement and click Continue.

3.The installation performs a prerequisite check and lists any missing prerequisites. If you want to see what those prerequisites are, click the Show all prerequisites check box. Follow the instructions in the install wizard to provide the missing components. If all prerequisites are met, the installation indicates that the prerequisites check has passed. Click Continue.

4.Designate the folder where Xtraction is to be installed. The default folder is C:\Program Files (x86)\Xtraction Software\Xtraction. Click Continue.

5.When you're ready to install the files, click Install. The installer will step through several tasks, such as registering components, copying files, and configuring Internet Information Server (IIS).

6.When the Configuring Xtraction installation task begins, the wizard will open the Xtraction Settings utility. You can complete the required configuration settings now or cancel and do so later—the installation will finish either way when you click Finish.

IMPORTANT: Note that even though the installation is complete, Xtraction will not work until the required settings are configured, as explained below.

You can find the Xtraction Settings utility with the other installed Xtraction files (by default at C:\Program Files (x86)\Xtraction Software\Xtraction\Tools).

Xtraction license files

To view your available licenses and verify that each one is valid, click the Licensing tab, then click the License status button. For more information about Xtraction licenses, see the "Pre-installation checklist" section above.

Database connection and setup

Note that Xtraction will fail without this next step.

To configure the connection settings to the Xtraction database that was created before installation, click the General tab, then click the Create/Update Database button. The Verify or Enter Connection Details dialog opens:

•Server: The name of the database server where the Xtraction database resides. If a non-standard port is used, place a comma (“,”) after the server name, followed by the port number.

•Database: The name of the Xtraction database created as part of the pre-installation steps.

•User ID: The User ID that Xtraction should use when connecting to this database. Leave this field empty if you’re using Integrated Security.

•Password: The password for the User ID specified above. The following special characters are NOT supported: single quote (‘), double quotes (“), semicolon (;), < >, &, and %. Leave this field empty if you’re using Integrated Security.

•Integrated Security: Select if the IIS application pool running Xtraction will connect to the Xtraction database using Windows Authentication.

If you’re using Integrated Security, the Test and Update Database buttons described below will use the Windows account that you’re currently using to run the Xtraction Settings utility, not the Windows account that is or will be configured in IIS. If you need to use the Windows account that is or will be configured in IIS, you must either re-run the Settings utility with the Run as a Different User option, or log back into the server with that Windows user account.

•Encrypt Connection: Not a mandatory field, but select to encrypt all traffic to and from the Xtraction database.

•Trust Server Certificate: Not a mandatory field, but select to encrypt the channel while bypassing the certificate chain to validate trust. Selecting indicates that you accept any certificate as valid.

After you’ve entered the details for your database, click Test to attempt a database connection and ensure that the provided details are correct.

When you click Update Database after completing and testing the connection settings, the Settings utility will automatically run the script to configure your Xtraction database. By default, this script is found at: <Xtraction installation path>\Tools\DatabaseScripts\Build.sql.

Note that the Update Database button modifies the schema, requiring the account to have the db_owner role on the Xtraction database. If needed, you can remove the db_owner role after the database has been configured. In this case, the account will require db_datareader and db_datawriter roles on the database.

Trusted sites

Use the Trusted Sites tab to include all site addresses of your Xtraction server that users may use to connect to Xtraction. This includes the hostname, FQDN, DNS Alias, and IP address. Enter all items in lowercase, as the list is case sensitive.

By default, the localhost is automatically added as a trusted site, which enables you to open Xtraction locally on the Xtraction server.

After an upgrade to version 2022.3, you will not be able to log in remotely to Xtraction until your trusted site addresses are added to this tab.

When using trusted sites, Strong Cryptography (TLS 1.2) needs to be enabled on the Xtraction server; otherwise, end users may get an error message that authentication has failed when connecting to Xtraction over https.

To enable TLS 1.2 on the Xtraction server, run the following PowerShell commands. A reboot will be necessary after:

Set-ItemProperty -Path 'HKLM:\SOFTWARE\Wow6432Node\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord

Set-ItemProperty -Path 'HKLM:\SOFTWARE\Microsoft\.NetFramework\v4.0.30319' -Name 'SchUseStrongCrypto' -Value '1' -Type DWord

Authentication

You MUST specify an authentication provider for Xtraction to function correctly. A single instance of Xtraction supports one or more of these methods of authentication:

•Windows: The Xtraction user accounts are tied to the corresponding Windows user accounts. User passwords are not maintained within Xtraction. Xtraction verifies the user’s identity via IIS. For details about configuring enhanced Active Directory integration with Windows authentication, see Integrating with Active Directory

•Xtraction Local: The Xtraction user accounts are created and maintained within Xtraction. All account information, including passwords, are maintained in Xtraction. Note that any administrator account using local authentication will always have access to an analyst license to perform administrative functions even if all available Xtraction licenses are in use by others.

•Custom: The Xtraction user accounts are tied to the corresponding user accounts in an external system. User passwords are not maintained within Xtraction. One example of a custom option is using the Ivanti Identity Broker web application to broker authentication via Okta or Microsoft Entra ID. For details, see Integrating with Ivanti Identity Broker.

Note that brokered authentication via Identity Broker is being deprecated, because native authentication using Okta and Entra ID is available as of Xtraction 2023.2.

•Okta: The Xtraction user accounts are tied to the corresponding Okta user accounts. User passwords are not maintained within Xtraction. For details about configuring authentication via Okta, see Authenticating with Microsoft Entra ID or Okta.

•Micosoft Entra ID: The Xtraction user accounts are tied to the corresponding Entra ID user accounts. User passwords are not maintained within Xtraction. For details about configuring authentication via Entra ID, see Authenticating with Microsoft Entra ID or Okta.

To add an authentication method, click Click here to add a new row. The Edit dialog opens with the following settings:

•Active: Select to make this authentication provider active within Xtraction. If you clear this check box to deactivate this authentication method at a later date, the settings will continue to be saved.

•ID: A unique ID for this authentication provider instance. Enter the ID any way you like.

•Type: The type of authentication provider this instance refers to. If you select Okta or Entra ID, additional settings will display. For details, see Authenticating with Microsoft Entra ID or Okta.

•Provider: The provider name that will display on the Xtraction login page.

•URL: The URL that unauthenticated users should be redirected to for authentication.

•Auto Create Users: Select if Xtraction should automatically create a user who has been authenticated by the provider but doesn’t exist within Xtraction. These users are automatically assigned the default user role(s) that you can set up under the Features tab of this utility. It's recommended that you enable this option.

At any time after setup, you can edit permissions for individual users via the Administration link > User Administration tab at the bottom of the Xtraction web client.

•Token Key: The key to use for encrypted, secure communication between Xtraction and the different authentication providers; it must match the key stored at the authentication provider.

WARNING: Xtraction is installed with a default key. This key MUST be changed during the installation in order to protect yourself from a potential security vulnerability.

•Think of this key as a password and change it to something unique for your organization. Set it to a character string of 10–20 characters. The only requirement is that the same password needs to be set at each authentication provider.

•If you're using Windows authentication, you also need to change this value in the web.config file of the WinAuth web application, under secretKey. For details, see Integrating with Active Directory.

•During a fresh installation (not an upgrade), the Token Key is randomly generated. Therefore, if you're intending to use an existing Xtraction database or reuse your WinAuth\web.config file—for example, for testing purposes or if migrating Xtraction to a new server—you may get an error when logging in. For instructions on how to fix this, see this Xtraction community article: Xtraction Authentication Failed. Invalid signature.

•Token Timeout (mins): The number of minutes a token from an authentication provider is valid for. Any token received by Xtraction that is older than this value will be rejected.

This section describes the settings that are not required for Xtraction to work but are highly recommended. You can find the Xtraction Settings utility with the other installed Xtraction files (by default at C:\Program Files (x86)\Xtraction Software\Xtraction\Tools).

General

•Default Time Zone: Xtraction adjusts date/time values to the appropriate time zone. This default time zone used here will be the default time zone applied to all users, unless their accounts have been individually updated to reflect a different time zone. Xtraction automatically adjusts for daylight savings if the selected time zone observes daylight savings.

Features

•Session Timeout (mins): A user’s session will time out if the user hasn’t contacted the Xtraction server in this time period. The user will need to log back into Xtraction to continue. Note that a session timeout is required, so you cannot set the number to zero.

•Default Roles: When the Auto Create Users option is selected for an authentication provider, any newly created users will get the roles selected here by default.

•Default Features: When the Auto Create Users option is selected for an authentication provider, any newly created users will get the designer features selected here by default.

•Import Out of the Box Content: Used to import out-of-the-box (OOTB) content packs into Xtraction. Select Overwrite or Append, navigate to the OOTB zip file, and click Import to save the content to Shared Folders within Xtraction.

Email

If you want the Xtraction Task Scheduler and Alert services to send email, use the Email tab to set up the email settings. You have two options for sending email: SMTP (displayed by default) or Microsoft 365 (if you want to integrate Xtraction with Azure Active Directory).

SMTP settings:

•Server: The name of the email server.

•Port: The port to use when sending email to the email server.

•Username: The username to use to connect to the email server.

•Password: The password to use to connect to the email server.

•Sender: The sender to use when sending email from Xtraction. This must be a valid email address.

•Subject Prefix: Text entered here will display on the email subject line before the document name.

•Use SSL: Select if the connection to the email server needs to be made via SSL.

•Test Email: If you want to test the settings provided, enter an email address and then click Test Email.

Microsoft 365 settings:

These settings use your Entra ID account to send email via Microsoft 365.

Note that you'll need to add the Microsoft Graph Mail.Send application permission to the App Registration in your Entra ID account for email to work. For details, see this Xtraction community article: How to set up Microsoft 365 App Registration for sending Xtraction emails.

•Client ID: The client ID associated with your instance of Microsoft 365. A mandatory field.

•Client Secret Value: The client secret associated with the client ID. A mandatory field.

•Tenant ID: The tenant ID (also known as the tenant URL) you created in Azure Active Directory. A mandatory field.

•Sender: The sender to use when sending email from Xtraction. This must be a valid email address. A mandatory field.

•Subject Prefix: Text entered here will display on the email subject line before the document name.

•Test Email: If you want to test the settings provided, enter an email address and then click Test Email.

The Microsoft 365 fields are saved in the Xtraction database in the Settings table as: SenderEmail, SubjectPrefixEmail, TenantIdBinary, ClientIdBinary, SecretBinary, and TenantIdBinary. ClientIdBinary and SecretBinary are encrypted.

Alerts

Use the Alerts tab is to configure the Xtraction Alerts service. This service shares email configurations with the Xtraction Task Scheduler service, so the settings on the Email tab will be used with both services.

•Xtraction URL: When notification emails are sent, there’s an option to link to Xtraction content. Use the base URL of your Xtraction installation when building the URL to send in the notification email (for example, http://server1/xtraction/, where “server1” is the name of your Xtraction server). Note that the slash ( / ) at the end of the URL is required.

•Notification Subject Prefix: All notification emails are sent with this prefix in the email subject line.

•Maximum Alerts Allowed: The maximum number of alerts allowed to be defined in Xtraction. Once this number has been reached, no more alerts can be defined.

•Errors Before Alert Failure: The number of errors an alert can encounter before it’s flagged as failed.

•Worker Count: Once an alert is triggered to be checked, it’s placed in a queue for checking. This value defines the number of worker processes that pull alerts from the queue to perform alert checking and actioning if necessary.

•Shutdown Queue Size: The maximum number of entries allowed in the queue before the Alerts service shuts down and restarts. See Worker Count.

Xtraction dates

If you want to change the format for dates that are displayed in Xtraction, you can set them on the Xtraction Dates tab.

•Short Date Format: The short date format contained within the Xtraction configuration file Settings.dat is displayed here. If you change this value and click OK, the change is saved back to the Settings.dat file.

•Long Date Format: The long date format contained within the Xtraction configuration file Settings.dat is displayed here. If you change this value and click OK, the change is saved back to the Settings.dat file. The long date format affects the way the date is shown in most presentations.

•Test: Used to view today’s date and time in the format entered in the text boxes for short date or long date format.

•Format Help: This is a list of known formats for your locale.

Excel dates

Documents that are exported to Excel will format date columns in accordance with the Excel date format shown below. The Excel date format is separate from the Xtraction date formats, because Xtraction uses Windows operating system locale date/time formats, and not all of these formats are valid in Excel.

•Excel Date Format: The date format used for columns containing dates. The Settings utility doesn't validate the format you save, so it’s recommended that you test the format in Excel before exporting content to that application.

ADO.NET

If you're using Xtraction to report from a non-MS SQL database such as PostgresSQL, Informix, DB2, Teradata, or Sybase, add a connection to it from the ADO.NET tab after you install the desired .NET Data Providers.

Telemetry

On the Telemetry tab, the Send Telemetry Data option is selected by default. During upgrades, this feature enables Xtraction to upload certain usage information to Ivanti so that we can improve the product.

Currently, this data is limited to the following information:

• Computer name

• Xtraction current version and version upgraded from

•Information about templates

•Information about dashboards

1.Make sure the file is not blocked:

•Navigate to the Tools folder (by default, C:\Program Files (x86)\Xtraction Software\Xtraction\Tools).

•Locate the Xtraction.SchedulerService.exe file.

•Right-click Properties.

•Check to see if there’s an Unblock button on the General tab (Windows Server 2008 R2).

•Click Unblock, then Apply, then OK.

•Right-click Properties again to make sure it has disappeared.

2.Open the Services Manager.

3.Scroll to the bottom where you should see Xtraction Task Manager.

4.Set up the appropriate settings (Startup type and Logon). Important: If using Integrated Security, the service should run as the Active Directory account.

5.Start the Xtraction Task Manager service.

1.Make sure the file is not blocked:

•Navigate to the Tools folder (by default, C:\Program Files (x86)\Xtraction Software\Xtraction\Tools).

•Locate the Xtraction.AlertService.exe file.

•Right-click Properties.

•Check to see if there’s an Unblock button on the General tab (Windows Server 2008 R2).

•Click Unblock, then Apply, then OK.

•Right-click Properties again to make sure it has disappeared.

2.Open the Services Manager.

3.Scroll to the bottom where you should see Xtraction Alerts.

4.Set up the appropriate settings (Startup type and Logon). Important: If using Integrated Security, the service should run as the Active Directory account.

5.Start the Xtraction Alerts service.

1.In IIS, click the Default Web Site node on the Connections tree.

2.Select the Actions menu > Edit Site List > Bindings option.

3.Select HTTPS from the list of site bindings, then click the Edit button.

4.Next to the name of the SSL certificate, click the Select button to choose an alternate certificate.

5.Click OK.