Skip to content

Environment Set Up Guide

Some configuration options were included with this package to help it adapt to your development and analysis needs. Whether it is your first time working with the hdforce package, or starting over with a new project, you can choose how you want to use the package and customize your experience.

Event Logging

HDFORCE allows for event logging. This gives more detailed understanding of function processes and errors, to make development and debugging more efficient. Using the LoggerConfig.Configuration function, users can configure a couple of key settings to their project environment.

  1. Choose if the logs should be streamed to the stdout (default) or if you want a log file created to store logs.
  2. Choose the minimum level of log to be output. This is default to 'warning'.
  3. Provide a specific file path. This is default to 'root/hdforce.log'.
  4. Select a file mode to set whether the log file should append to itself, or overwrite with each session.

Authentication

Use the Refresh Token generated by https://cloud.hawkindynamics.com/integrations to get a valid Access Token. Only the organization administrator account has the ability to generate API tokens. Use this function to initiate access to your data in the cloud. All other HDFORCE functions will depend on the values returned from this function.

In HDFORCE, we can create and manage your authentication settings with the authManager function. The arguments passed will be used to handle authentication for the other functions used in the program. With this function you can control these settings:

  • region: Sets the url prefix of your cloud site
  • authMethod: Sets storage method of auth variables. One of env, file, or manual. Default to 'env'.
  • refreshToken_name: Provide or set name of refresh Token variable. Default to "HD_REFRESH_TOKEN".
  • refreshToken: Optionally provided to pass token for authentication when authMethod="manual". Otherwise sets refresh token value when provided.
  • env_file_name: Required when authManager="file". Directs storage location of variables.

The authentication manager allows the user to manage authentication with various development strategies. The 'env' method was designed to allow for simple authentication while developing in a local or contained environment, where the refresh token and variables are stored in system environment. The 'file' method can be used for more visible and dynamic interaction with the auth variables, as the refresh token and variables are stored with .env file. While the 'manual' method allows for use of the package without storing sensitive data, in so the refresh token is not stored and only used for authentication. This could be helpful in the scenario of developing a password protected application where the token can be used as a password.

Creating Environment Variables

For those working in less vulnerable or sensitive environments, the use of environment variables stored in your local system can be very helpful and efficient because you can use it from project to project without making changes. The process of storing environment variables will differ for Windows and Mac users.

It's important to note that authManager is set to look for the variable names of 'HD_REFRESH_TOKEN' and 'REGION'. These variable names should be used when storing environment variables

Windows

1. Open Environment Variables:

  • Right-click on the Start button and select 'System'.
  • Click on 'Advanced system settings' on the left sidebar.
  • In the System Properties window, click on the 'Environment Variables...' button.

2. Add New Environment Variables:

  • In the Environment Variables window, under the 'User variables' section, click 'New...'.
  • Enter the name of the variable (HD_REFRESH_TOKEN) and its value. Click 'OK' to close the dialog.
  • You can repeat this step to store the region.

3. Accessing Environment Variables in Python:

You can access these variables in your Python code using the os module:

import os
refreshToken = os.getenv('HD_REFRESH_TOKEN')

macOS

1. Open Terminal:

  • You can find the Terminal application in your 'Applications' folder under 'Utilities', or you can search for it using Spotlight.

2. Edit the Profile File:

  • In the Terminal, type open -e ~/.bash_profile if you are using Bash, or open -e ~/.zshrc if you are using Zsh, then press Enter. This opens your profile file in a text editor.

3. Add New Environment Variables:

  • Add a line at the end of the file for each variable you want to set, in the format export VARIABLE_NAME='value'. For example:
export HD_REFRESH_TOKEN='your_api_key_here'

4. Load the New Settings:

  • To make the changes take effect, type source ~/.bash_profile or source ~/.zshrc in the Terminal and press Enter.

5. Accessing Environment Variables in Python:

  • As with Windows, you can access these variables in your Python scripts:
import os
refreshToken = os.getenv('HD_REFRESH_TOKEN')

Verifying Environment Variables To ensure your environment variables are set correctly, you can print them in your Python script:

import os
print("Refresh Token:", os.getenv('HD_REFRESH_TOKEN'))

If the output shows your set value, the environment variables are correctly configured.

Environment File

In the case of the "file" method, the user will need to save a .env file in the source directory. When using this method, you will also need to pass the file name to the env_file_name argument as a string. It's most common to use something as simple as ".env", but you can name your file anything ending with .env.

Below is an example of what the .env file can look like. This can be used as a template, as the variable name "HD_REFRESH_TOKEN" is the default to what the authManager function will use for the refreshToken_name. If you want ot use a different variable name, simply pass the string through the refreshToken_name argument, along with the token to the refreshToken argument. The other values for ACCESS_TOKEN, TOKEN_EXPIRATION, and CLOUD_URL are defaults within the authManager function, and should be maintained.

Example .env file
HD_REFRESH_TOKEN=your_api_token     # Replace With Your Refresh Token
REGION=your_region                  # Replace With Your URL region
ACCESS_TOKEN=                       # Access token will be stored here
TOKEN_EXPIRATION=                   # Token Expiration will be stored here
CLOUD_URL=                          # Your region's URL here

Examples

With the variables stored, we can use it with our other functions without worrying about authentication for each call.

Authentication Examples
# Run authentication manager
AuthManager(authMethod="env", region= "Americas")

# Run authentication manager with file method
AuthManager(authMethod="file", env_file_name=".env", region= "Americas")

# Run authentication manager with manual method
AuthManager(authMethod="manual", region="Americas", refreshToken="your_refresh_token")