API

[theWizard]

@Tom-Elliott said in API:

fog-api-token

Hi Tom
Thanks you for the detailed response much appreciated, i feel rather stupid asking but i don’t suppose you have a couple of examples to follow do you ?
Say for instance if i wanted to list all active tasks or even add a snapin task.

[george1421]

@theWizard The API is RESTful based. You might want to do a quick read up on RESTful interfaces. https://www.tutorialspoint.com/restful/

Once the API is finished we will create guidance on using it. Actually what Tom posted below is the first time this information was made publicly available.

Please give us some time to get the documentation in line with the advances the developers are making in the code.

[Tom Elliott]

@theWizard

List all active tasks:

header('fog-api-token: <FOG Configuration Page->FOG Settings->API Settings->FOG_API_TOKEN>');
header('fog-user-token: <User management page->relevant user->API Settings->User API Token>');
http://fogserverip/fog/task/active

So let’s do this command line style:
Let’s just say your api token is abcde
Let’s just say your user token is fghij
List all current/active tasks is a GET request.
URL for now is just fogserver

curl -H 'fog-api-token: abcde' -H 'fog-user-token: fghij' -X GET http://fogserver/fog/task/current -o listalltasks.json

This will list all current/active tasks to a file in the current working directory named listalltasks.json

For creating a snapin task, this depends how you plan to do it. To be honest, while the option is available, it’s not something I’ve worked overly hard to get working “natively”. It was originally only designed to allow host and group, though I saw the appeal and added capabilities.

So let’s just say you have a snapin associated to a host.

The snapin ID is: 6
The host ID is: 1

This would be a POST request as per the earlier information.

The URL you would call would be:

http://fogserver/fog/host/1/task

The post requires some information, and luckily I kind of documented the “maximum” and “minimum” information for creating a tasking in this way.

The “data to send” would be, at minimum:

{
    "taskTypeID": <IDOFTASKTYPETOUSE>
}

For a “snapin” task, this is ID’s 12 or 13. important to remember which is a single snapin, vs. all snapin though.

The “full” information you could send for tasking in a manner as above is:

{
    "taskTypeID": <IDOFTASKTYPE>,
    "taskName": "NameToGiveTasking",
    "shutdown": <bool>true/false,
    "debug": <bool>true/false,
    "deploySnapins": <bool>/<IDOFSNAPIN or -1 for all>,
    "passreset": "what to change password if passreset task",
    "sessionjoin": "<SessionNameToJoin>",
    "wol": <bool>
}

In your case, with a specific known host and snapin to send you could do:

curl -H 'fog-api-token: abcde' -H 'fog-user-token: fghij' -H 'Content-Type: application/json' -X POST -d '{"taskTypeID":13,"deploySnapins":6}' http://fogserver/fog/host/1/task

This should create the tasking for you as you described. (Task Type ID 13 = Single Snapin Task, deploy Snapins is true/false/-1 = all/<IDOFSNAPIN>

[george1421]

#wiki worthy

[Tom Elliott]

This is just a quick means to represent how you could filter the tasks if you needed to as well.

Our “List all tasks” works without a body sent, but CAN be filtered to get specific information for active tasks. The example just shows how you might want to get active tasks for host ids of 5 and 6. I’m not trying to show actual payload right now. Just trying to show example use cases.

So let’s do this command line style:
Let’s just say your api token is abcde
Let’s just say your user token is fghij
List all current/active tasks is a GET request.
URL for now is just fogserver

curl -H 'fog-api-token: abcde' -H 'fog-user-token: fghij' -X GET http://fogserver/fog/task/current -o listalltasks.json -d '{"hostID":[5,6]}'

[theWizard]

@Tom-Elliott said in API:

curl -H ‘fog-api-token: abcde’ -H ‘fog-user-token: fghij’ -X GET http://fogserver/fog/task/current

Thankyou perhaps i will have to wait as anything i try results in
The requested URL /fog/task/current was not found on this server.

[Tom Elliott]

@theWizard I don’t follow.

What are you using as a test, exactly?

[theWizard]

@Tom-Elliott
I’m using powershell with Invoke-WebRequest which is alias for curl

[UWPVIOLATOR]

@theWizard

What did your Powershell command look like? I would like to see that example. I am most familiar with it and the one main thing I need to work on is a for each from a csv file with all of our old junked computers and laptops returned from lease. We no longer need them in fog.

[george1421]

@UWPVIOLATOR Not the answer you are looking for, but a bit more details that Wayne uses for FOG scripting. https://forums.fogproject.org/topic/9779/can-i-use-some-kind-of-script-to-create-image-and-ghost-my-lab-machines/15

[george1421]

@UWPVIOLATOR Warning: I’m not a programmer (or even know how to program in PS) and sometimes I even question if I know what I doing here…

But I think I was able to translate one of Wayne’s posts with a curl call into powershell.

curl --silent -k -H 'Content-Type: application/json' -H 'fog-user-token: ZjBkMmE3YmI5NmUzZDcxYTliYzNkZTc4MmJhNTFiYTQ3Mzc2MTg5MzYxMThmNjA5NDYyMjllMTA5YzE0NWUxMjFiNzkyMTc5OTMwZjFhZGM5NWIxMTc3YWZmNTU2MmMwYjFhNjg0NjVmMTkyMGZkNDQxYmY0MzI1NWNkMzQyM2M=' -H 'fog-api-token: MzI2NDY1NjY2NjM0MzUzMDMzMzA2MzM1MzEzNzYyMzg2NTYyNjQ2MjMxMzczMTM0NjY2NDM0NjUzOTM2NjIzNDM4MzQ2NDM3MzY2MzM2MzMzNjYyMzUzODY0MzUzNDYyMzgzMDY2NjQzNTMxMzI2MzM5NjYzNjYzMzMzMzM0MzA=' http://10.0.0.28/fog/host/testhost1/task -d '{"taskTypeID":1,"shutdown": true}'

would translate into something like this:

$headers = @{}
$headers.Add("fog-user-token", "ZjBkMmE3YmI5NmUzZDcxYTliYzNkZTc4MmJhNTFiYTQ3Mzc2MTg5MzYxMThmNjA5NDYyMjllMTA5YzE0NWUxMjFiNzkyMTc5OTMwZjFhZGM5NWIxMTc3YWZmNTU2MmMwYjFhNjg0NjVmMTkyMGZkNDQxYmY0MzI1NWNkMzQyM2M=")
$headers.Add("fog-api-token", "MzI2NDY1NjY2NjM0MzUzMDMzMzA2MzM1MzEzNzYyMzg2NTYyNjQ2MjMxMzczMTM0NjY2NDM0NjUzOTM2NjIzNDM4MzQ2NDM3MzY2MzM2MzMzNjYyMzUzODY0MzUzNDYyMzgzMDY2NjQzNTMxMzI2MzM5NjYzNjYzMzMzMzM0MzA=")

$mydata = @{}
$mydata.Add("taskTypeID", "1")
$mydata.Add("shutdown", "true")

$json = $mydata | ConvertTo-Json
$Uri = 'http://10.0.0.28/fog/host/testhost1/task'

Invoke-WebRequest -Method Post -Uri $Uri -Header $header -Body $json -ContentType 'application/json'

[Tom Elliott]

@george1421 There’ s a simpler method

Here’s some scripts that I run.

This is specific to my needs on a different project, but could be converted as needed.

buildheaders.ps1

<# Build headers script help
    .SYNOPSIS
        This powershell script just creates a single point for building headers
        rather than constantly rewriting the same script over and over.
    .USAGE
        This just sources the function so there is no real usage here.
#>
function Build-Headers {
    Param(
        [string]$authorizationString,
        [string]$tenantCode,
        [string]$acceptType,
        [string]$contentType
    )
    
    $header = @{
        "fog-api-token" = $fogApiToken;
        "fog-user-token" = $fogUserToken;
        #"Accept" = $accept;
        "Content-Type" = $contentType
    }

    Write-Verbose("");
    Write-Verbose("---------- Headers ----------");
    Write-Verbose("Authorization: " + $authorizationString);
    Write-Verbose("fog-api-token: " + $fogApiToken);
    Write-Verbose("fog-user-token: " + $fogUserToken);
    Write-Verbose("Accept: " + $acceptType);
    Write-Verbose("Content-Type: " + $contentType);
    Write-Verbose("-----------------------------");
    Write-Verbose("");

    Return $header
}

Use case script – To create a task for a host with say ID # 10.

taskhost.ps1

<# Creates Task for id passed in to script.
    .SYNOPSIS
        Helps create task from command line.
    .PARAMETER id (required)
        This is the ID Of the Host to task.
    .PARAMETER configFile (optional)
        This is not a required file, this allows you to use a different
        basicconfig.ps1 file if need be.
#>
[CmdletBinding()]
    Param(
        [Parameter(Mandatory=$True)]
        [string]$id,

        [Parameter()]
        [string]$configFile
    )

# Set errors to silent if we are not in verbose mode.
If (!$PSCmdlet.Myinvocation.BoundParameters["Verbose"].IsPresent) {
    $ErrorActionPreference = "SilentlyContinue"
}

# Setup up defailt if configFile is not already set.
If (!$configFile) {
    $configFile = '.\basicconfig.ps1'
}

# Load our config file.
. $configFile

# Set our base call (item) for the api.
$baseURL = $endpointURL + "/host/" + $id + "/task"

# Source build headers function.
. ".\buildheaders.ps1"

# We know we're using json so set accept/content type as such.
$contentType = "application/json"

# Get our headers Building off the config file information.
$headers = Build-Headers $fogApiToken $fogUserToken $contentType $contentType

# Display what url we are calling so somebody could use it later if in verbose.
Write-Verbose ""
Write-Verbose "---------- Caller URL ----------"
Write-Verbose ("URL: " + $baseURL)
Write-Verbose "--------------------------------"
Write-Verbose ""

$dataSet = @{
    "taskTypeID" = 1
    "shutdown" = true
}

$dataToSend = ($dataSet | ConvertTo-JSON)

# Display the data we're sending
Write-Verbose ""
Write-Verbose "---------- Sending Body ----------"
Write-Verbose $dataToSend
Write-Verbose "----------------------------------"
Write-Verbose ""

# Perform the request
$ret = Invoke-RestMethod -Method Post -Uri $baseURL -Headers $headers -ContentType $contentType -Body $dataToSend

# Write our return information if there is anything to see.
Write-Verbose ""
Write-Verbose "---------- Returned Data ----------"
Write-Verbose $ret
Write-Verbose "-----------------------------------"
Write-Verbose ""

# All Done

You would have all three files in the same place and call from powershell:
.\taskhost.ps1 -id 10

Hopefully this helps. Of course it could be more generalized, but I’m just giving a basic overview.

[Tom Elliott]

basicconfig.ps1

<# Config for our scripts.
    .SYNOPSIS
        Just used to store our common variables that we don't want to
        recode for every script.
    .USAGE
        No related usage, just sets variables.
#>
$fogApiToken = "TokenFromGUIForAPIAccess";
$fogUserToken = "TokenFromGUIForUserToken";
$endpointURL = "http://fogserver/fog/";

[Wayne Workman]

@theWizard I’ve listed the examples I have here: https://forums.fogproject.org/topic/9779/can-i-use-some-kind-of-script-to-create-image-and-ghost-my-lab-machines

[AndrewG78]

Hi, Could you please share an example of query to obtain list of active tasks per given GROUP ID?
I just want to check if all multicast jobs are done in a specific group.
Thx.

[Wayne Workman]

@andrewg78 Probably, I’ll have to look into it. Multicast tasks are handled differently than unicast tasks - they are treated as an individual job. If you wanted to get the status of the entire job, you could probably just follow along with the examples in this link: https://forums.fogproject.org/topic/9779/can-i-use-some-kind-of-script-to-create-image-and-ghost-my-lab-machines Though you would need to use the multicast task type, or know the task ID already.

[AndrewG78]

@wayne-workman
Thx. I figured out where was the issue. Maybe this info will help somebody.
I use curl under Windows, but command line doesn’t support single quotes '.
I used " and had to escape inner ones
–data “{\“hostID\”:13}”