Using the ServiceNow Adapter Console Application

The ServiceNow Adapter Console Application is a command-line tool that provides various commands for running background and configuration tasks to extract, process, and load data from the Open iT database to the ServiceNow instance.

Displaying the ServiceNow Adapter Console Application Tasks

To show the available tasks, follow these instructions:

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe

   This will display the available options.

   Output

   ServiceNow Adapter for Open iT Integration, 1.0.0. Copyright 2023 Open iT, Inc. All rights reserved. 
   
   Sql Database: ServiceNow @ WIN-HOST01\SQL2019E
   
   ...
   
   Usage: OpeniT.Adapter.Console <subcommand> [args]
   Type 'OpeniT.Adapter.Console help <subcommand>' for help on a specific subcommand.
   
   Available subcommands:
   
   DeploySchema    Deploy SQL database schema to either the latest or a specific version.
   ProcessData     Process Open iT Datatypes and load to staging tables for integration.
   Configure       Configure ServiceNow-required details
   PushData        Fetch data from Open iT Database and push to ServiceNow instance.
   TestConnection  Test connection to ServiceNow instance.
   RunAdapter      Run all processing jobs

   To show the available parameters for each command, add a help parameter before the command:

   Example

   OpeniT.Adapter.Console.exe help deployschema

   This command displays the available options.

   Output

   ServiceNow Adapter for Open iT Integration, 1.0.0. Copyright 2023 Open iT, Inc. All rights reserved.
   
   Sql Database: ServiceNow @ WIN-HOST01\SQL2019E
   
   ...
   
   Deploy SQL database schema to either the latest or a specific version.
   usage: OpeniT.Adapter.Console DeploySchema [/version:value] [/trace]
       [/version:value]  Specific version to migrate to
       [/trace]          Enable tracing of SQL statements.

Deploying the Database Schema in SQL Server (DeploySchema)

This command creates all the necessary SQL objects for data processing, including tables, stored procedures, and predefined static data for specific tables.

Instructions

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe DeploySchema

   To further customize the command, use the optional parameters.

   Syntax

   OpeniT.Adapter.Console.exe DeploySchema /version:<migration_version> /trace

   Optional Parameters

   /version:<migration_version>
   This parameter limits the migration of the database to the specified version. The migration version format is YYYYMMDDHHMMSS.

   Example

   OpeniT.Adapter.Console.exe DeploySchema /version:20220101143000

   /trace
   This parameter triggers the command to display SQL statements.

   Example

   OpeniT.Adapter.Console.exe DeploySchema /trace

   Combine or use optional parameters at the same time to achieve necessary capabilities.

   Example

   OpeniT.Adapter.Console.exe DeploySchema /version:20220101143000 /trace

3. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

Processing Data from the Open iT SQL Database (ProcessData)

This command fetches data from specific data types in the Analysis Server database, transforms, and loads it to the staging tables.

Instructions

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe ProcessData

   To further customize the command, use the optional parameters.

   Syntax

   OpeniT.Adapter.Console.exe ProcessData /fullwipe /appScope:<application>

   Optional Parameters

   /fullwipe
   This parameter triggers the command to delete all processed and cached data.

   Example

   OpeniT.Adapter.Console.exe ProcessData /fullwipe

   /appScope:<application>
   This parameter specifies the application and limits job execution to the selected application. Accepted values are la for OpeniT LicenseAnalyzer or lm for OpeniT LicenseMonitor.

   Example

   OpeniT.Adapter.Console.exe ProcessData /appScope:la

   Combine or use optional parameters at the same time to achieve necessary capabilities.

   Example

   OpeniT.Adapter.Console.exe ProcessData /fullwipe /appScope:lm

3. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

note

The ProcessData and PushData commands use the stored procedure configuration files installed with the ServiceNow Adapter. For advanced configuration and customization options, see Stored Procedure Configuration.

Configuring the ServiceNow Settings (Configure)

This command contains various subcommands to configure necessary ServiceNow settings for a successful API connection.

Instructions

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe Configure

   The console application will display the available options.

   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
   [1]: Set ServiceNow instance URI
   [2]: Set Application Scope
   [3]: Set Authentication
   [4]: Test Connection
   [5]: Save configuration
   [0]: Exit
   
   Select:

3. Select from options 1 to 5, then press Enter.

4. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

Setting the ServiceNow Instance URI

This Configure subcommand updates the value of the ServiceNow instance URI. The initial value is the one provided during installation.

Instructions

1. Follow the instructions in the Configure section.

2. Select option 1.

3. Provide a valid ServiceNow instance URI.

   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
       [1]: Set ServiceNow instance URI
       [2]: Set Application Scope
       [3]: Set Authentication
       [4]: Test Connection
       [5]: Save configuration
       [0]: Exit
   
   Select: 1
   
   ServiceNow instance URI [https://test-instance.service-now.com/]:

   The current ServiceNow instance URI is displayed inside the square brackets.

   Press Enter to use the value.

   note

   Test the newly provided ServiceNow instance URI with the configured authentication using the Test Connection subcommand.

4. Select option 5 to save the changes.

   The application will test the connection using the provided configuration. If the connection fails, a prompt will be displayed.

   Type y (or press Enter) to continue saving. Let the process run until it completes.

note

After configuring the new ServiceNow instance URI, follow the ServiceNow Adapter Post-Installation Configuration steps.

Setting the Application Scope

This Configure subcommand updates the value of the Application Scope.

Instructions

1. Follow the instructions in the Configure section.

2. Select option 2.

3. Choose between the available Application Scope:

   • 1 for OpeniT LicenseAnalyzer
   • 2 for OpeniT LicenseMonitor
   
   
   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
       [1]: Set ServiceNow instance URI
       [2]: Set Application Scope
       [3]: Set Authentication
       [4]: Test Connection
       [5]: Save configuration
       [0]: Exit   
   
   Select: 2
   
   Set Default Application Scope
       [1]: LicenseAnalyzer
       [2]: LicenseMonitor
       [0]: Exit
   
   Select: 2

   Press Enter to proceed with new value.

   note

   Test the newly provided application scope with the configured ServiceNow settings using the Test Connection subcommand.

4. Select option 5 to save the changes.

5. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

Setting Authentication to Basic Authentication

This Configure subcommand updates the Authentication Type to Basic Authentication and the credentials to connect to the ServiceNow instance.

Instructions

1. Follow the instructions in the Configure section.

2. Select option 3.

3. The available Authentication Types will be displayed. Select 1.

   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
       [1]: Set ServiceNow instance URI
       [2]: Set Application Scope
       [3]: Set Authentication
       [4]: Test Connection
       [5]: Save configuration
       [0]: Exit
   
   Select: 3
   
   Set ServiceNow Authentication Type
       [1]: Basic Authentication
       [2]: Bearer Authentication
       [3]: Oauth2 Authentication
       [0]: Exit
   
   Select [1][basic]: 1

   The current authentication type is displayed inside the square brackets.

   Press Enter to proceed with new value.

4. Provide the credentials.

   Example

   Basic Authentication Details
   Username: john_doe
   Password: ************

   note

   Test the newly provided authentication with the configured ServiceNow instance URI using the Test Connection subcommand.

5. Select option 5 to save the changes.

   The application will test the connection using the provided configuration. If the connection fails, a prompt will be displayed.

   Type y (or press Enter) to continue saving. Let the process run until it completes.

Setting Authentication to Bearer Authentication

This Configure subcommand updates the Authentication Type to Bearer Authentication and the credentials to connect to the ServiceNow instance.

Instructions

1. Follow the instructions in the Configure section.

2. Select option 3.

3. The available Authentication Types will be displayed. Select 2.

   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
       [1]: Set ServiceNow instance URI
       [2]: Set Application Scope
       [3]: Set Authentication
       [4]: Test Connection
       [5]: Save configuration
       [0]: Exit
   
   Select: 3
   
   Set ServiceNow Authentication Type
       [1]: Basic Authentication
       [2]: Bearer Authentication
       [3]: Oauth2 Authentication
       [0]: Exit
   
   Select [2][bearer]: 2

   The current authentication type is displayed inside square brackets.

   Press Enter to proceed with new value.

4. Provide the Bearer Token.

   Example

   Bearer Authentication Details
   Bearer Token: ************

   note

   Test the newly provided authentication with the configured ServiceNow instance URI using the Test Connection subcommand.

5. Select option 5 to save the changes.

   The application will test the connection using the provided configuration. If the connection fails, a prompt will be displayed.

   Type y (or press Enter) to continue saving. Let the process run until it completes.

Setting Authentication to OAuth2 Authentication

This Configure subcommand updates the Authentication Type to OAuth2 Authentication and the credentials to connect to the ServiceNow instance.

Instructions

1. Follow the instructions in the Configure section.

2. Select option 3.

3. The available Authentication Types will be displayed. Select 3.

   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
       [1]: Set ServiceNow instance URI
       [2]: Set Application Scope
       [3]: Set Authentication
       [4]: Test Connection
       [5]: Save configuration
       [0]: Exit
   
   Select: 3
   
   Set ServiceNow Authentication Type
       [1]: Basic Authentication
       [2]: Bearer Authentication
       [3]: Oauth2 Authentication
       [0]: Exit
   
   Select [3][oauth2]: 3

   The current authentication type is displayed inside the square brackets.

   Press Enter to proceed with new value.

4. Provide the credentials.

   Example

   Oauth2 Authentication Details
   Username: john_doe
   Password: ************
   Client Id: companyID
   Client Secret: ************************

   note

   Test the newly provided authentication with the configured ServiceNow instance URI using the Test Connection subcommand.

5. Select option 5 to save the changes.

   The application will test the connection using the provided configuration. If the connection fails, a prompt will be displayed.

   Type y (or press Enter) to continue saving. Let the process run until it completes.

Testing the Connection

This Configure subcommand triggers a test connection to the ServiceNow instance using the current session’s configuration. This is useful for verifying the settings before saving them.

Instructions

1. Follow the instructions in the Configure section.

2. Select option 4.

   Example

   ...
   Current ServiceNow Configurations
   
   ServiceNow Instance URI: https://test-instance.service-now.com/
   Default Application Scope: <application>
   Authentication Type: basic
   Username: user1
   
       [1]: Set ServiceNow instance URI
       [2]: Set Application Scope
       [3]: Set Authentication
       [4]: Test Connection
       [5]: Save configuration
       [0]: Exit
   
   Select: 4

   The application tests the connection using the ServiceNow instance URI and authentication details from the current session. If no values are set in the session, it uses the existing configuration.

   On success, it displays Connection Successful. On failure, it shows Connection Failed along with details about the error.

Testing the Connection to the ServiceNow Instance

This command triggers a connection test to the configured ServiceNow instance.

note

Make sure that all ServiceNow configurations (i.e., Instance URI, Authentication Type, and Credentials) are properly configured.

Instructions

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe TestConnection

   To further customize the command, use the optional parameter.

   Syntax

   OpeniT.Adapter.Console.exe TestConnection /appScope:<application>

   Optional Parameter

   /appScope:<application>
   This parameter specifies the application and limits job execution to the selected application. Accepted values are la for OpeniT LicenseAnalyzer or lm for OpeniT LicenseMonitor.

   Example

   OpeniT.Adapter.Console.exe TestConnection /appScope:la

3. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

Sending Processed Data to the ServiceNow Instance (PushData)

This command connects then sends processed data to the ServiceNow instance.

note

Make sure that all ServiceNow configurations (i.e., Instance URI, Authentication Type, and Credentials) are properly configured.

Instructions

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe PushData

   To further customize the command, use the optional parameter.

   Syntax

   OpeniT.Adapter.Console.exe PushData /appScope:<application>

   Optional Parameter

   /appScope:<application>
   This parameter specifies the application and limits job execution to the selected application. Accepted values are la for OpeniT LicenseAnalyzer or lm for OpeniT LicenseMonitor.

   Example

   OpeniT.Adapter.Console.exe PushData /appScope:la

3. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

note

The ProcessData and PushData commands use the stored procedure configuration files installed with the ServiceNow Adapter. For advanced configuration and customization options, see Stored Procedure Configuration.

Running All Adapter Processing Jobs (RunAdapter)

This command combines the data processing commands – ProcessData and PushData, enabling scheduling of background data processing and sending.

Instructions

1. Open a command prompt and run the following command to go to the installation directory of the ServiceNow Adapter, which is by default in C:\Program Files\OpeniT\ServiceNow Adapter\:

   Example

   cd "C:\Program Files\OpeniT\ServiceNow Adapter\"

2. Once in the directory, run the following command:

   Example

   OpeniT.Adapter.Console.exe RunAdapter

   To further customize the command, use the optional parameters.

   Syntax

   OpeniT.Adapter.Console.exe RunAdapter /fullwipe /appScope:<application>

   Optional Parameters

   /fullwipe
   This parameter triggers the command to wipe all processed and cached data before loading and processing data.

   note

   Use this parameter if you upgraded from a previous installation and changed the ServiceNow instance URI. This reprocesses and pushes all data to the new instance.

   Example

   OpeniT.Adapter.Console.exe RunAdapter /fullwipe

   /appScope:<application>
   This parameter specifies the application and limits job execution to the selected application. Accepted values are la for OpeniT LicenseAnalyzer or lm for OpeniT LicenseMonitor.

   Example

   OpeniT.Adapter.Console.exe RunAdapter /appScope:la

   Combine or use optional parameters at the same time to achieve necessary capabilities.

   Example

   OpeniT.Adapter.Console.exe RunAdapter /fullwipe /appScope:lm

3. The Console Application will display informational messages in the command prompt. Let the process run until it completes.

Miscellaneous Configurations

Use these procedures to configure how the ServiceNow Adapter extracts, processes, and retains data for the OpeniT LicenseAnalyzer store application.

Configuring the Data Extraction Range (Month Offset)

The ServiceNow Adapter extracts and processes 3 months of data by default, covering the current month and the previous two (2) months.

For example, if the current month is October, it will extract data from August to October.

To set the number of month offset, follow these instructions:

1. Log in to the Open iT Analysis Server web interface.

2. Go to Administration > Configuration.

3. Locate the configuration key Root.ServiceNow.MonthOffset.

4. Click the value to make it editable.

5. Set the value to the desired number of months to include in extraction and processing.

6. Click Save to apply the changes.

7. Click the Reset Session button at the bottom of the configuration table.

Configuring Data Retention (Keep Stale Record)

The ServiceNow Adapter keeps existing staging table records for 90 days by default. Records not discovered again within this period are considered stale and cleaned up.

To set the number of days to keep unseen data, follow these instructions:

1. Log in to the Open iT Analysis Server web interface.

2. Go to Administration > Configuration.

3. Locate the configuration key Root.ServiceNow.KeepStaleRecord.

4. Click the value to make it editable.

5. Set the value to the desired maximum number of days to keep stale data.

6. Click Save to apply the changes.

7. Click the Reset Session button at the bottom of the configuration table.

Configuring Inactive Usage Window (Inactive Usage Days)

The ServiceNow Adapter considers recent usage activity from the last 7 days by default when evaluating inactive license usage. Licenses with no usage within this period are marked as inactive.

To set the number of inactive usage days, follow these instructions:

1. Log in to the Open iT Analysis Server web interface.

2. Go to Administration > Configuration.

3. Locate the configuration key Root.ServiceNow.InactiveUsageDays.

4. Click the value to make it editable.

5. Set this value to the number of days a record can go missing before it is marked as inactive.

6. Click Save to apply the changes.

7. Click the Reset Session button at the bottom of the configuration table.