jdempsey (Flexera Software)
Some customers may have a need to add custom contextual data to their IT Visibility devices (for example, you might want to associate the assigned user to each of your inventory devices) or to Software Products in Technopedia (for example, you might want to label specific applications as being "preferred" or "prohibited", etc.). To enable this, Flexera has a Contextual Data Store API. However, this may not be the easiest API to use, especially if you're just starting out. To try to make this easier to use, I have created a PowerShell script and a couple modules that wrap this API into simple cmdlets and a basic guided user experience. It can be run interactively with some basic UI or completely automated for scheduled uploads using command line parameters.
I'm still working on the comment-based help and some more detailed instructions, but I've had a few people asking for this, so I wanted to get it posted in its current state, so others can use it. I welcome feedback and contributions from the community, so please feel free to make suggestions for improvements. At some point, I hope to get this published in GitHub to make it easier to share updates and allow the community to contribute their own enhancements, but for now, here it is.
Instructions:
You'll need to download the attachments into a folder and modify the Upload-ContextData.config file with your own settings. Specifically, uncomment the appropriate RegionTLD setting (stands for Region Top Level Domain) that matches the region where your Flexera One org resides (com for North America, eu for EMEA, or au for APAC). Simply remove the # in front of the setting you want to use and make sure the other RegionTLD lines have the # in front of them. For example, if my Flexera One org resides in EMEA, my settings would look like this...
#RegionTLD=com
RegionTLD=eu
#RegionTLD=au
Next, make sure you update the OrgID to match your organization ID. This is the numeric value that appears in the address bar after /orgs/ like this...
https://app.flexera.au/orgs/12345/landing
All other settings in this config file are optional. Here is the full list:
- DebugLogging - not really implemented
- FileRetentionDays - Each run of the script creates a new log file. This setting controls how long to retain those logs. A negative value will retain all logs indefinitely. A value of 0 will remove all previous logs each time you run the script. A positive value will delete any previous logs older than the specified number of days each time you run the script.
- RegionTLD - already discussed above. Either com (North America), eu (EMEA), or au (APAC)
- OrgID - already discussed above. Needs to match your Flexera One org ID
- MaxRetries - specifies the number of times to retry an API call if it fails
- RetryIntervalSeconds - specifies how many seconds to wait in between retries if MaxRetries is greater than 0
- SmtpServer - specifies an SMTP relay server that can be used to send email messages
- SmtpPort - specifies the port number to be used for sending email through the SMTP relay server
- UseSSL - specifies if SMTP communication should enforce SSL (TLS) encryption
- MailFrom - specifies the sender email address
- MailTo - specifies one or more email addresses to send email messages to (semi-colon delimited)
- EnableFailureEmail - Boolean value specifying if an email message should be sent when a failure occurs
- EnableSuccessEmail - Boolean value specifying if an email message should be sent when the script runs successfully without errors
Note: the Send-Email function only works if you have an internal SMTP relay that supports basic authentication. However, the Send-Email function does not currently support M365/Exchange Online with its recent requirement for modern authentication.
After you've configured your settings, you can run the Upload-ContextData.ps1 script. Running it without any command line parameters will prompt you for the needed information and guide you through the process to create a new contextual data source or to upload a contextual data file. The first time you run the script, you'll also be prompted to enter your Refresh Token for authentication with Flexera One. If you don't already have a refresh token, you'll need to generate one. This token will be encrypted and stored in a file in the same folder with your script and will be used to automatically authenticate on subsequent runs of the script. This encrypted file is specific to the user running the script and the system on which the script is being run. It cannot be used or decrypted by any other user or on any other system.
Note: This PowerShell module was written to support either user-based Refresh Token authentication or service account-based Client Credential authentication; however, the API does not currently support the service account-based Client Credential authtentication. This is being worked on in Q1 2025, and once the API supports it, the script will be able to use it without modification. You'll just need to delete your CRED file and run the script again to choose the Client Credential option.
That's it for now. I hope you find this useful.
