Powershell API Module

[JJ Fullmer]

Due to current global pandemic conditions I find myself with some extra time to work on this. I do also have an infant, so not a ton of time, but more than I usually have to work on these kinds of projects.

I am currently thinking I will focus on the following things in the module but would love input on any features people would like in an API module out of the box.

• Creating a readthedocs or github pages based webpage for help files integrated with powershell’s get-help {function-Name} -online functionality. i.e. https://github.com/darksidemilk/FogApi is a rough draft
• Moving the api to its own repo following best practices for powershell modules. https://github.com/darksidemilk/FogApi.
• Update the build script to utilize the new structure and documentation needs
• Make sure each existing function has documentation, especially including examples
• Make it compatible with Powershell 7 (ideally without losing powershell 5 compatibility)
• Once compatible with powershell 7, add more cross platform compatibility for linux and mac (though I don’t have a way to test mac functionality) on all existing functions
• Add Functions for more common fog tasks (Hoping to get some requests to know where focus is best spent)
• Make it so the return object will work with the small api changes in fog 1.6 by making it just return just the content as the count is automatically included in a powershell object or changing the return object in some way that isn’t a breaking change. i.e. it currently returns something like

count: 100
hosts: {hostJsonContent}

in 1.6 I understand it will change to

count: 100
data: {hostJsonContent}

So I may utilize some method to make it so everything returns an object with count and data or just data or something based on what fog version you have. May also add additional 1.6 options if time permits (I understand there are join functions, and options to return just a specific parameter/member of an object or objects, or at least those were the plans 2 years ago)

• Make it so there’s more pipeable commands. i.e. you put some host in a variable and then just pipe it to actions

Get-FogHost -hostname computername | Add-FogHostMac -macaddress "12:34:56:78:90"

This would probably take quite some time to add

We’ll see how much of this I’m able to do in the undetermined amount of time this pandemic has me at home all day.

[JJ Fullmer]

A new version has been published!

I haven’t yet completed all my goals. But about half or more of the functions have at least one example in their help file and there is now an online home for the documentation.

You can find the published listing here
https://www.powershellgallery.com/packages/FogApi/2002.2.1.2

The documentation is now at https://fogapi.readthedocs.io/en/latest/
and the module’s code is now in its own repository at https://github.com/darksidemilk/FogApi

Hopefully more updating still to come in the near future.
I have thoughts and plans on creating a custom class for ‘fogObjects’ returned from the api to make things more universal throughout and make creating pipeline functions easier. Want to make it so most functions have 3 parameter sets that include performing the operation by id, name, or by object. We’ll see when I get to that.

[JJ Fullmer]

This module appears to have gained some popularity…

Maybe I need to find some time to do more updating.

[JJ Fullmer]

Sadly that 27k downloads was a glitch on the psgallery site.
But I still did do some updating to fix a couple bugs I just found. Nothing major, just a couple tweaks to fix pending mac address handling

Released Version 2004.2.2.4

https://www.powershellgallery.com/packages/FogApi/2004.2.2.4
Release notes - https://fogapi.readthedocs.io/en/latest/ReleaseNotes/ (see versions 2004.2.2.1 - 2004.2.2.4 for changes)

[JJ Fullmer]

See also this post if you’re searching for how to create scheduled tasks via the api
https://forums.fogproject.org/post/139328

[Jamaal]

@jj-fullmer

Hello, jj,

Thanks for the fog api notes, appreciate you helping us out. I’m not sure if you remembered me, but have a few questions.

I’m trying to do 2 things. One to assign a group to a machine one created in fog via powershell. I tried get-foggroupbyname, but says the parameter is not recognized.

It then told me to go to c:\program files… until I got to fogapi.psm1

I copied and pasted the command for cmdletBinding.

It didn’t error out, but didn’t return anything. Ex; , I know I created a Sales group in the Fog Gui with snapins assigned to it, so I wanted the machine to be assigned to that group to make it more dynamic. Please see attached pics. I’ll keep trying as well on my side. I’m so so on Powershell, but came a long way.

[JJ Fullmer]

@jamaal I see that you’re using the powershell ISE. While that is still a great tool, I would personally recommend giving vscode with the powershell extension a try. That’s what I use for all my development and find it faster and easier to use.

[Jamaal]

@jj-fullmer said in Powershell API Module:

vscode

Thanks jj,

I’ll install & try out.

[JJ Fullmer]

A new small bugfix and feature release has just been published.
This fixes issues related to getting fog groups and adds functions for creating fog hosts.

https://github.com/darksidemilk/FogApi/releases/tag/2103.2.12

https://www.powershellgallery.com/packages/FogApi/2103.2.12

[Chris Whiteley]

@JJ-Fullmer,

I had a feature request for the API. I am looking at trying to output the last time the computer was imaged so that when I scan the serial I can get that info direct out of PS. Have I just missed it or is that not in there?

Thanks!

[JJ Fullmer]

@chris-whiteley Sorry for the insanely delayed reply.
So you’re looking to find a host by the serial number? And then get the last time it was imaged?
I was coming here to post information on my recent update, but this sounded useful so I went ahead and implemented getting a foghost by the serialnumber in the inventory field and even a get-lastimagetime function that will default to prompting you to scan a serial number barcode
These will be published shortly.

-JJ

[JJ Fullmer]

@jj-fullmer
A new Major version has been released along with a quick feature revision shortly after

see
https://github.com/darksidemilk/FogApi/releases/tag/2208.3.0
and
https://github.com/darksidemilk/FogApi/releases/tag/2208.3.1

for details on what’s been added.

Some highlights include
Deploy-FogImage and Capture-FogImage functions to start deploy and capture tasks on fog hosts from powershell both instant and scheduled.
You could always do this, but it’s now simplified in helper functions.

[Chris Whiteley]

@jj-fullmer

I will check it out! Late is better than never! Appreciate your work on this.

[JJ Fullmer]

@JJ-Fullmer
A new version has been published!

Release notes here:

https://github.com/darksidemilk/FogApi/releases/tag/2303.5.26

[Chris Whiteley]

@JJ-Fullmer Thanks for your great work!

[JJ Fullmer]

A minor update has been released

Release notes: https://github.com/darksidemilk/FogApi/releases/tag/2303.5.33
PSgallery Listing: https://www.powershellgallery.com/packages/FogApi/2302.5.33

[JJ Fullmer]

A minor bugfix update has been released

Release notes: https://github.com/darksidemilk/FogApi/releases/tag/2304.5.41
PSgallery Listing: https://www.powershellgallery.com/packages/FogApi/2304.5.41

[JJ Fullmer]

A minor bugfix update has been released…and then something more was caught (aliases for functions weren’t being exported) and another version was released right after

Release notes: https://github.com/darksidemilk/FogApi/releases/tag/2310.6.3
PSGallery: https://www.powershellgallery.com/packages/FogApi/2310.6.3

[JJ Fullmer]

Another minor bugfix release, I left a random ‘a’ at the end of a line.
Also added a switch to set-fogsnapins for running the repair-fogsnapinassociations before attempting to add new ones

Release notes: https://github.com/darksidemilk/FogApi/releases/tag/2311.6.4
PSGallery: https://www.powershellgallery.com/packages/FogApi/2311.6.4

[JJ Fullmer]

A major version update has been released!
Added various functions and some new features. If you’re using fog 1.6 beta I added some tab complete of your server’s host names dynamically (the api in 1.6 is much faster, so there’s less overhead in making the call to list host names).
Also added a get-fogversion and various other requested features.

One big and often requested thing included is a Set-WinToBootToPxe function that attempts to find the pxe boot entry in a windows hosts bcedit /enum {fwbootmgr} and sets it as the first boot option. I’ve used it with much success in my environment but I need feedback from other environments to make it truly universal.

Another big update is pipeline support. It’s not quite yet as universal as I want, but I added things like get-foghost -hostname somename | add-foghostmac -macaddress 00:00:00:00:00:00

Release notes: https://github.com/darksidemilk/FogApi/releases/tag/2408.9.2
Full change log:
https://github.com/darksidemilk/FogApi/compare/2311.6.4...2408.9.2
PSGallery: https://www.powershellgallery.com/packages/FogApi/2408.9.2