Node-locked and floating licenses for WbW-Pro

A purchase of WbW comes with an equal number of node-locked and floating licenses. For example, if you've purchased two seats, you will be able to register two node-locked licenses on two computers and you will also be able to check-out two silmutaneous floating licenses at any time from any computer.

When you register your WbW-Pro license, WbW writes information about your license on your computer, stored in a configuation file. This will allow you to use WbW on your computer at any time, even when you are not connected to the Internet. This is a so-called 'node-locked' license (i.e., it is tied to a specific computer). You can use your node-locked WbW-Pro license in the same way as we saw WbW used previously, except that you should now have access to the full set of tool functions:

sample_wbwpro_script.py

from whitebox_workflows import available_functions, WbEnvironment

# Checks for a valid node-locked WbW license stored locally
wbe = WbEnvironment()

available_functions(wbe) # You should now see more than 500 functions listed

# Do some processing here, including calling some WbW-Pro tool functions...

The code above uses a node-locked WbW license, i.e., the license is tied to the machine that it was registered on. Sometimes, you will want to use WbW in other computing environments, e.g. on different computers within a network, or on cloud-based computing platforms like Google Colab. When this is the case, you need to use a floating-license user ID. You will have been provided a unique floating license ID consisting of a three-word string (e.g. 'white-bolting-camel') in an email that was sent to you after registering your license activation code. This string connects your floating license with the WbW-Pro license server and allows you to use WbW-Pro on any computer or computing environment (e.g., Google Colab or Jupyter Notebooks).

Your floating-license user ID is unique to you and you should keep this string private. Sharing your user ID with other people will result in the early termination of your license.

Using your floating license is easy. Instead of using the usual means of intializing a WbEnvironment, you simply need to specify your floating-license user ID as an optional parameter, being sure to check-in the license when you have completed:

sample_wbwpro_script.py

from whitebox_workflows import available_functions, WbEnvironment

# Checks for a valid floating license stored on remote server
wbe = WbEnvironment('your-license-id') 
try:
    available_functions(wbe) # You should now see more than 500 functions listed

    # Do some processing here including calling some WbW-Pro tool functions...
except Exception as e:
  print("The error raised is: ", e)
finally:
    wbe.check_in_license('your-license-id')

Using the floating-license requires Internet access. If you are unable to access the Internet for a time, you should fall back on your node-locked license instead, assuming you are on the computer used to register the license.

A note on checking-in your license: Because the floating license uses a check-out/check-in model, you must remember to check-in your license after you have completed processing your script. The last thing you do in each script, therefore, should be to call the WbEnvironment.check_in_license method. There is no need to check-in your node-locked license.

When we specify our floating-license user ID in the WbEnvironment initializer, the program will communicate with the Whitebox Geospatial Inc. remote license server web app. It will check to see if there is an available seat associated with the specified user ID. Importantly, while your script is running, and until you check-in your license, it will not be available for use again. This means that it is very important that the last thing you successfully check-in the license at the end of the script, which is why we call check_in_license within the finally block of a try-finally construct in the script above. This way, if the script throws an error, we can still be sure that the license will be checked back in and we'll be able to use it again in the future.

If all of the existing 'seats' of a license are unavailable because they are either in use, or haven't yet been checked back in, you will receive an error indicating that 'All floating licenses are currently in use'. The number of 'users' that you specified when you purchased your WbW license will indicate how many silmutaneous floating license seats you have to work with.

Sometimes a script may panic, which is an unrecoverable type of error. This happens for example, if you provide an unexpected input parameter to a function. When this is the case, our checked-out license may not be checked back in correctly. What do we do in this case? Well, after a certain amount of time (usually two hours), an un-checked-in license will be returned to the pool of available licenses. But, of course, that leaves us in a difficult situation for those hours wihtout being able to run further WbW-Pro scripts. When this occurs, we can call the check_in_license function associated directly with the whitebox_workflows module, i.e. whitebox_workflows.check_in_license('your-license-id'). Note, you should always prefer using WbEnvironment.check_in_license('your-license-id) over whitebox_workflows.check_in_license('your-license-id') because the latter will throw an error if there is no unchecked-in license to check-in. However, in the event that a script panic results in a 'zombie' floating license seat, this method is a usable solution to get you up-and-running with WbW geoprocessing once again.

from whitebox_workflows import check_in_license

print(check_in_license('your-license-id')) # print to confirm the successful check-in