Skip to main content

How to write to a custom field using the FileWave API

Frequently you might find it convenient to publish data back to a FileWave Custom Field, especially when it comes to driving automated workflows.  There are some distinct advantages to this...especially in that the data change is made server-side immediately on the API call.

In this article, we'll show you how to do this with a macOS shell script and with a Windows PowerShell script for boolean, string and date/time Custom Field values.  Note: We'll read data from the API as a smart starting block. Being smart is always good.

We recommend only attempting to amend Custom Fields that will not be updated otherwise through other methods, Inventory for example.  'Administrator' Data Types are the most obvious choice.

The things we'll need to know to write a script:

  • FileWave server address
  • Base64 Encoded API token (from Assistants → Manage Administrators, and highly recommend a new admin account for this that has no rights assigned)
  • The Internal Name of the field you want to update
  • The type of Custom Field (string, boolean, integer, date/time)
  • The Device ID of the device you want to test with (in an actual script, FileWave can supply this automatically through a launch argument)
  • The URLs currently shown in this article use RESTful API (v1 API) so you will see 20445 used as a port. Simply add /api/ to the front of the /inv/api/ URL to make it. begin /api/inv/api/ and you can use 443 instead like the other APIs use. 

How to be Smart:

We can be smart by asking the API to show us data for Custom Fields we want to update.  So, we'll look at details for a specific device that has values set.  (Note this is a desktop client so we used /DesktopClient, but if a mobile device then it would be /MobileClient instead).  Elements in blue would need to be replaced with values for your environment. 

Platform API Call Partial Result
macOS shell curl -s -k -H "Authorization: base_64_token https://my.server.address:20445/inv/api/v1/client/details/device_id/DesktopClient | python -mjson.tool

Partial JSON Result

 

Partial JSON Result 
"CustomFields__school_type": {
        "updateTime": null,
        "value": "None",
        "type": "string"
    },
 
    "CustomFields__user_role": {
        "updateTime": null,
        "value": "Student",
        "type": "string"
    },
 
    "CustomFields__asset_tag": {
        "updateTime": "2020-07-28T18:47:20.604074Z",
        "value": "FW-123456",
        "type": "string"
    },
 
    "CustomFields__phase_1": {
        "updateTime": null,
        "value": false,
        "type": "bool"
    },
 
    "CustomFields__image_date": {
        "updateTime": "2020-07-28T19:15:34.568518Z",
        "value": "2019-05-28T15:15:09.672000Z",
        "type": "datetime"
    },
 
    "CustomFields__school_name": {
        "updateTime": "2020-07-28T19:15:34.571554Z",
        "value": "Deckard ES",
        "type": "string"
    }

 
Windows PowerShell Invoke-RestMethod -Headers @{Authorization=('base_64_token')} "https://my.server.address:20445/inv/api/v1/client/details/device_id/DesktopClient" | ConvertTo-JSON

Partial JSON Result

Partial JSON Result 
"CustomFields__school_type": {
"updateTime": null,
"value": "None",
"type": "string"
},
"CustomFields__user_role": {
"updateTime": null,
"value": "Student",
"type": "string"
},
"CustomFields__asset_tag": {
"updateTime": "2020-07-28T18:47:20.604074Z",
"value": "FW-123456",
"type": "string"
},
"CustomFields__phase_1": {
"updateTime": null,
"value": false,
"type": "bool"
},
"CustomFields__image_date": {
"updateTime": "2020-07-28T19:15:34.568518Z",
"value": "2019-05-28T15:15:09.672000Z",
"type": "datetime"
},
"CustomFields__school_name": {
"updateTime": "2020-07-28T19:15:34.571554Z",
"value": "Deckard ES",
"type": "string"
}

 

As you can see, the results above are the same from the API regardless of calling platform and the data for the Custom Field is in the form of an array, so when we go to change it, we'll write it back that way as well using the PATCH command and an array data structure.

Changing Values:

The basic method for changing a value looks like this, where you would again substitute your values and environment info:

Platform Shell Script
macOS shell 
curl -X PATCH \
  https://<server address>:20445/inv/api/v1/client/<device id> \
  -H 'authorization: <base64 token>' \
  -H 'cache-control: no-cache' \
  -H 'content-type: application/json' \
  -d '{"CustomFields":{"field_name":{"exitCode":null,"status":0,"updateTime":"current_time","value":value_to_set}}}'
Windows PowerShell 
Invoke-RestMethod -Method PATCH -Headers @{Authorization=<base_64_token>} `
 -Body '{"CustomFields":{"field_name":{"exitCode":null,"status":0,"updateTime":"current_time","value":value_to_set}}}' `
 -ContentType application/json `
 -Uri https://<server address>:20445/inv/api/v1/client/<device id>

Note, that in the above, "exitCode" and "status" are always required and a date value passed must always be in ISO-8601 format.  Also, it may seem like device_id is a challenge to set, because it would be different every time, but this is where the beauty of passing FileWave data elements in a script comes in.  If you simply pass %device_id% as a Launch Argument to your fileset script, then that value can be read dynamically in your script and substituted with the specific Device ID of the current device.  See below, where %device_id% is read by the PowerShell script as $args[0].  In a mac shell script this same variable would be used as $1 in the script:

get_image_date.png
 Windows $api = "https://" + $server + ":20445/inv/api/v1/client/" + $args[0]
macOS https://$SERVER:20445/inv/api/v1/client/$1

Practical Examples (differing data types):

Using %device_id% as a  Launch Argument.

Field Name Data Type Purpose/Action macOS Shell Script PowerShell Script
Asset Tag String Set device asset tag (a string field)...in this case to FW-198724 Setting a string field (Bash)

Setting a string field (Bash) 
#!/bin/zsh
SERVER=$(defaults read /usr/local/etc/fwcld.plist server)
TOKEN="base_64_token"
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
TAG="FW-198724"
DEVICE=$1
QUERY='{"CustomFields":{"asset_tag":{"exitCode":null,"status":0,"updateTime":"'$DATE'","value":"'$TAG'"}}}'
 
curl -X PATCH https://$SERVER:20445/inv/api/v1/client/$DEVICE -H "authorization: $TOKEN" -H 'cache-control: no-cache' -H 'content-type: application/json' -d $QUERY
 
exit 0
 Setting string field (Powershell)

Setting a string field (Powershell) 
$server = (Get-ItemProperty -Path REgistry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\FileWave\WinClient).server
$token = "base_64_token"
$api = "https://" + $server +  ":20445/inv/api/v1/client/" + $args[0]
$header = @{Authorization=$token}
$date = Get-Date -Format "o"
$tag = "FW-198724"
$data = '{"CustomFields":{"asset_tag":{"exitCode":null,"status":0,"updateTime":"' + $date + '","value":"' + $tag + '"}}}'
  
Invoke-RestMethod -Method PATCH -Headers $header -Body $data -ContentType application/json -Uri $api
Image Date Date When a device is newly imaged set this Custom Field to current date/time (again must be ISO-8601 format) Setting a date-type field (Bash)

Setting a date-type field (Bash) 
#!/bin/zsh
SERVER=$(defaults read /usr/local/etc/fwcld.plist server)
TOKEN="base_64_token"
DATE=$(date -u +"%Y-%m-%d %H:%M:%S")
DEVICE=$1
QUERY='{"CustomFields":{"image_date":{"exitCode":null,"status":0,"updateTime":"'$DATE'","value":"'$DATE'"}}}'
 
curl -X PATCH https://$SERVER:20445/inv/api/v1/client/$DEVICE -H 'authorization: '$TOKEN'' -H 'cache-control: no-cache' -H 'content-type: application/json' -d $QUERY
 Setting a date-type field (Powershell)

Setting a date-type field (Powershell) 
$server = (Get-ItemProperty -Path REgistry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\FileWave\WinClient).server
$token = "base_64_token"
$api = "https://" + $server +  ":20445/inv/api/v1/client/" + $args[0]
$header = @{Authorization=$token}
$date = Get-Date -Format "o"
$data = '{"CustomFields":{"image_date":{"exitCode":null,"status":0,"updateTime":"' + $date + '","value":"' + $date + '"}}}'
 
Invoke-RestMethod -Method PATCH -Headers $header -Body $data -ContentType application/json -Uri $api
Phase 1 Boolean Simple boolean field to indicate whether Phase 1 is enabled (setting to 1, which is True) Setting a boolean field (Bash)

Setting a boolean field (Bash) 
#!/bin/zsh
SERVER=$(defaults read /usr/local/etc/fwcld.plist server)
TOKEN="base_64_token"
DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
FLAG=1
DEVICE=$1
QUERY='{"CustomFields":{"phase_1":{"exitCode":null,"status":0,"updateTime":"'$DATE'","value":"'$FLAG'"}}}'
 
curl -X PATCH https://$SERVER:20445/inv/api/v1/client/$DEVICE -H 'authorization: '$TOKEN'' -H 'cache-control: no-cache' -H 'content-type: application/json' -d $QUERY
 Setting boolean field (PowerShell)

Setting boolean field (PowerShell) 
$server = (Get-ItemProperty -Path REgistry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\FileWave\WinClient).server
$token = "base_64_token"
$api = "https://" + $server +  ":20445/inv/api/v1/client/" + $args[0]
$header = @{Authorization=$token}
$date = Get-Date -Format "o"
$flag = 1
$data = '{"CustomFields":{"phase_1":{"exitCode":null,"status":0,"updateTime":"' + $date + '","value":"' + $flag + '"}}}'
  
Invoke-RestMethod -Method PATCH -Headers $header -Body $data -ContentType application/json -Uri $api

SSL Certificate Problem

Self-Signed certificates may produce an error around SSL Certificates.  Please act accordingly, based upon the script output, to address this.

Back to top