Skip to main content

Configuring the Web API by Modifying Web.Config

The final step with configuring the Web API is to add/set your custom settings in Web.Config (main configuration file found in the main installation directory for Virtual Task Runner). 

There are a couple of ways to edit your Web.Config file. The first way is within IIS. It works like this (we're going to show you HOW to make changes, but NOT what to change just yet):

Click on site you want to modify, then double-click on Configuration Editor.

modify-web-config-via-iis-1.png

Click on Collection or Count=X. Click on three dots button.

modify-web-config-via-iis-2.png

Alternatively, you can click Edit in sub-menu on right side.

modify-web-config-via-iis-4-edit-items.png

Both ways will display the settings in the AppSettings group of Web.Config.

modify-web-config-via-iis-3.png

From there you can make your changes, close the window, and select Apply or Cancel to save or discard your changes.

modify-web-config-via-iis-5-apply-cancel.png

The second way to make changes is manually using a text editor. In our case, we have our Web.Config files configured to open with Notepad (if you do not, just right-click on it and choose the Notepad app to open these file types).

modify-web-config-manually-1.png

When you open it with Notepad, it will look like the following screenshot. Everything arrowed is what you can change. The two settings shown near the very bottom of screenshot should NOT be changed. This will complete break the application if you modify either of those two settings.

modify-web-config-manually-2.png

Next, let's go over each of these settings, what they are, and what you should set them to. We prefer editing the Web.Config file manually, because we can see the XML comments above each setting which explains what the setting is and how to set it.

		<!-- LICENSE issued to you from Known Keep to authorize usage of Virtual Task Runner (without an authorized license, the API will fail) -->
		<add key="VTR-LICENSE" value="NOT SET YET" />

		<!-- KEY/CODE/PASSWORD passed in API Call Header from mobile application (without a matching key, the API will fail) -->
		<add key="VTR-API-KEY" value="NOT SET YET" />

		<!-- ONLY return (INCLUDE) tasks which start with X (separate multiple values with a comma ... EX: YourCompanyName, Known_Keep, Jeff-Net, Simple, Report_Runner, YourCompanyName) -->
		<add key="VTR-INCLUDES-STARTSWITH-FILTERS" value="" />

		<!-- EXCLUDE ALL tasks which start with Y (separate multiple values with a comma ... EX: win-acme, Microsoft, Adobe, Google) -->
		<add key="VTR-EXCLUDES-STARTSWITH-FILTERS" value="" />

		<!-- TEST MODE IS ON by default (This will NOT allow schedules to run at all from mobile application) ... Set to "NO" to disable TEST MODE -->
		<add key="VTR-TEST-MODE-ON" value="YES" />

		<!-- LOGGING is ON by default (this logs all mobile connections to VTR.DB in the App_Data folder) ... Set to "NO" to disable LOGGING -->
		<add key="VTR-LOGGING-ON" value="YES" />

                <!-- HELLO is ON by default (this shows a "Hello" message with settings confirmations when root URL is entered in browser) ... Set to "NO" to disable HELLO -->
		<add key="VTR-HELLO-ON" value="YES" />

VTR-LICENSE: This is where you paste in your license issued to you from Known Keep. It will look something like "KK+yABmJN9996qXX8iM15x==". The application will not work with the mobile app if this is not entered and valid. The license you enter is validated by the Web API connecting to our licensing server. This is done on a random basis.

VTR-API-KEY: This is the key/access code that YOU configure for mobile devices to access YOUR installation of the Web API. Without this key, the mobile application can not access your server to read and/or execute tasks from the Windows Task Scheduler.

This unique key can be anything. It can be simple like "123456789", medium like "YourCompanyName1234567890!", or complex like a GUID "61d7e66b-f9b6-4a12-8e1a-5cdfed9997ca". Whatever you set it to, you will ALSO need to then set it in the mobile app when you configure the server settings there. Obviously someone is probably not going to type in a GUID-type code (they would probably need to copy and paste it from an email). 

VTR-INCLUDES-STARTSWITH-FILTERS: When you mobile app connects to the Web API, by default the API will return ALL tasks in the base Task Scheduler Library (not the ones in sub-folders like Microsoft). With this filter setting, you can instruct the Web API to ONLY return tasks which start with an ID or list of IDs (separated by a comma). 

task-scheduler-library.png

Setting a filter ensure your end users ONLY see tasks they are supposed to see and prevents them from seeing tasks they shouldn't. It adds a level of safety, too, ensuring critical tasks don't get run accidentally. Lastly, the fewer tasks returned to the mobile app, the faster it works/feels.

Note, this is a "Starts With" filter so it should never include the entire ID. You can include all but the last letter.

Our demo.virtualtaskrunner.com Web API uses this setting to ONLY show you the 10 specific "test" tasks that can be run/demoed.  

<add key="VTR-INCLUDES-STARTSWITH-FILTERS" value="VTR-TEST, Jeff-Net_f9f80eec-550d-4f17-a556-da, Jeff-Net_1333e8b9-61b6-4536-a7d7-31, Jeff-Net_b33818b5-0691-4be8-88e2-84, Jeff-Net_10cc1388-292c-400c-b6e9-a8, Jeff-Net_0dae6870-4f6f-4e9d-aa0d-57"/>

VTR-EXCLUDES-STARTSWITH-FILTERS: This filter is the opposite of the previous INCLUDES filter, but other than that, it works much the same. Anything in the EXCLUDES filter will ensure those tasks are never seen by the mobile app. 

Maybe you have some end of month and end of year tasks which should never be run from the mobile app, because they are critical accounting tasks which close out the month or year. Let's say they start with either "MONTHLY" OR "YEARLY". Your EXCLUDES setting might look like this:

<add key="VTR-EXCLUDES-STARTSWITH-FILTERS" value="MONTHLY, YEARLY" />

VTR-TEST-MODE-ON: This setting, when set to "YES", puts the entire Virtual Task Runner application in "test" mode. Test mode prevents tasks from being submitted/executed from the mobile app. The mobile app can still view the tasks it has access to, and see their status, but the mobile app is unable to run the task until test mode is disabled.

VTR-LOGGING-ON: This setting, when set to "YES", logs all Web API calls to VTR.DB (a SQLite database stored in the App_Data folder).

app-data-directory.png

Note, the license.json file shown has nothing to do with logging. It is a data file the Web API uses to track recent licensing checks (and data files are generally stored in the App_Data folder). You can ignore this file.

The log stores the date/time, IP address, and type of access (reading tasks or running a task). It will also log the user name entered into the mobile app. This could be a bogus name, but assuming your users (employees) enter their real name, when "Bob" or "Jenny" use the mobile app to access the Web API, that's exactly what you'll see in the log. 

Note, we recommend keeping this logging ON so you can both audit who's accessing the Web API and see the usage/benefit of who's using it and how much.

A couple log entries by user name "Bruce" might look like this:

Bruce          99.233.999.111 10/20/2024 2:50:57 PM    Read        Fetched 10 task(s)
Bruce          99.233.999.111 10/20/2024 2:50:55 PM    Run         VTR-TEST-E

You can use anything SQLite utility to read the VTR.DB database. We've include a simple console application in the same directory to display recent entries, or you can export them. The database will only save the most recent 50,000-100,000 entries. By our estimates, that would equate to 3-7 years worth of entries. When the database reaches 100,000 entries, it automatically trims itself back down to 50,000 by removing the oldest 50,000 records.

Lastly, to be clear, NOTHING from these logs is accessed by or shared to Known Keep (the creators of Virtual Task Runner). This logging feature is strictly for your use. We don't track usage/stats, exceptions, or anything else. The ONLY thing we track is whether you are licensed to use the app or not. There is a single licensing call made every now and then to our server. That's it. There are no other connections to Known Keep.

VTR-HELLO-ON: This setting, when set to "YES" shows you the "Hello" message we mentioned previously at the end of Configuring IIS to Run the Web API. Once you have everything configured and you call it again, it might look something like this:

demo-virtualtaskrunner-com-hello-2-later.png

This confirms the Web API is working, a license has been set, and API KEY has been set, and INCLUDES filter has been set, an EXCLUDES filter has NOT been set, test mode is OFF, logging is ON, and the whatever the current version is. 

Once everything is working, for extra security purposes, we recommend changing HELLO setting to "NO". Once you do that, whenever you call the base URL again, instead of showing you the screenshot above, it will give you a 404 error (this 404 is displayed differently depending on the browser you use). Either way, there is no indication there is a live Web API at the URL.

This is what the Edge browser shows when HELLO is disabled:

404-not-found-demo.png

Note, we keep our "demo" URL active just so you can see the HELLO call work from your browser.

Back to top