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

You’re provided with two license files—one for Xtraction and one for the Data Model Editor. Under the General tab > Licenses group box, locate both license files using the ellipsis buttons. Click Test to verify that each license is valid.

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. In the Database Connection group box, 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.

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 you to have DBO permissions.

Authentication

You must specify at least one authentication provider for Xtraction to function correctly, though you can specify more than one. A single instance of Xtraction supports all three methods of authentication, which are:

•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.

•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, and users are authenticated by the external system.

•Authentication Providers: The list of the authentication providers set up within your Xtraction instance. You can add/edit/remove these entries via the right-click context menu or by double-clicking a listed provider.

•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. A default key is provided, but you should change it during installation.

•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 Enhanced Active Directory integration.

•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.

Provider details

•Active: Select if this authentication provider is active within Xtraction.

•ID: A unique ID for this authentication provider instance.

•Type: The type of authentication provider this instance refers to.

•Provider: A display name for the provider.

•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. It's recommended that you enable this option.

For information about configuring enhanced Active Directory integration, see Enhanced Active Directory integration.

This section describes the settings that are not required for Xtraction to work but are otherwise useful. 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

•Support URL: At the bottom of the Xtraction web client is a Support link that you can customize for your organization's support process. Setting this URL will control the action to be performed after a user clicks it. For example, you can send Xtraction users to an internal help desk. Both HTTP and HTTPS configurations are supported here.

When using MAILTO, the end-user’s default mail client will display, allowing an email to be sent to the correct location.

•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: 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 service to send email, use the Email tab to set up the email 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 be shown 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.

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 (new for version 2020.4), 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).

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).

5.Start the Xtraction Alerts service.