Set Custom Field Association

[AnEngelsen]

If I don't want to associate a custom field to "all devices", I can right-click on a client (or client group) within the Native Admin and manually associate a custom field to a device/group.

However, has anyone found a way to use the FileWave API to associate a custom field to a device? According to the API documentation, there should be 0 parameters required to execute:

https://FQDN:20445/inv/api/v1/custom_field/set_association

(But that's simply not the case)

Edited September 27, 2022 by AnEngelsen

[Pierre-Nicolas]

Hello - sounds like we're missing description in this part of the API.

This call requires a dict with the list of client ids, and another dict for each custom fields with the association state (true / false).

For instance, if I have 2 devices with IDs 230 and 231 and a custom field "my_custom_field", I can associate the field to the devices with:

$ cat cf_association.json
{
    "client_ids" : [230, 231],
    "fields" : {
        "my_custom_field" : true
    }
}

$ curl -s -k -H "Authorization: my_base_64b" -X POST -H "Content-Type: application/json" -d @cf_association.json https://pn.filewave.ch:20445/inv/api/v1/custom_field/set_association

Let me know if that worked for you !

 

[AnEngelsen]

Many Thanks @Pierre-Nicolas!

I was able to use this syntax to create the following shell script.

#!/bin/bash

#Set the following environment variables (within the fileset's executable tab): apitoken, clientID, customFieldName, flag

#ENV variable advice...
#   customFieldName: Use the "Internal Name" which can be found in the Assistants --> Custom Field menu in FileWave Admin.
#   flag: true or false
#   clientID should be set to %filewave_id%

serverURL="https://lifeisgood.filewave.net:20445/inv/api/v1/custom_field/set_association"

curl -X POST $serverURL \
  -H  "accept: application/json" \
  -H  "Authorization: $apitoken" \
  -H  "Content-Type: application/json" \
  -H 'cache-control: no-cache' \
  -d "{\"client_ids\" : [$clientID], \"fields\" : {\"$customFieldName\" : $flag }}"
#JSON data without using variables:     -d "{\"client_ids\" : [3092211, 123, 77],\"fields\" : {\"printNode_computerID\" : true}}"

exit 0

 

I would also love to create a Windows-friendly fileset. However, I'm having issues creating a fully-functional PowerShell script. Currently, the script does not produce an error message. However, when I check FileWave Admin, I can see that the custom field is not being associated to the target device.

My suspicion is that I'm experiencing a syntax-related issue with the line that contains the JSON Data. Can someone help me correct my $data payload?

$server = "FQDN_GOES_HERE"
$token = "API_Token_GOES_HERE"
$customFieldName = "CF_Name_GOES_HERE"

$api = "https://" + $server +  ":20445/inv/api/v1/custom_field/set_association/"
$header = @{Authorization=$token}
$date = Get-Date -Format "o"

#Data (Attempt 1)
#REPLACE CLIENT ID!
$flag = 1
#$data = '{"client_ids" : [3092254], "fields" : {"' + $customFieldName + '" : {"exitCode":null,"status":0,"updateTime":"' + $date + '","value":"' + $flag + '"}}}'

# Data (Attempt 2)
#REPLACE CLIENT ID!
$flag = "true"
$data = '{"client_ids" : [3092254], "fields" : {"' + $customFieldName + '" : ' + $flag + '}}'

Invoke-RestMethod -Method POST -Headers $header -Body $data -ContentType application/json -Uri $api
exit 0

 

[Pierre-Nicolas]

Could you try without the trailing / at the end of the url ?

 

$api = "https://" + $server +  ":20445/inv/api/v1/custom_field/set_association"

The following works in my side :

 

$server = "fqdn"
$token = "auth"
$customFieldName = "cf_field"

$api = "https://" + $server +  ":20445/inv/api/v1/custom_field/set_association"
$header = @{Authorization=$token}
$date = Get-Date -Format "o"

#Data (Attempt 1)
#REPLACE CLIENT ID!
$flag = 1
#$data = '{"client_ids" : [3092254], "fields" : {"' + $customFieldName + '" : {"exitCode":null,"status":0,"updateTime":"' + $date + '","value":"' + $flag + '"}}}'

# Data (Attempt 2)
#REPLACE CLIENT ID!
$flag = "true"
$data = '{"client_ids" : [233, 232, 231], "fields" : {"' + $customFieldName + '" : ' + $flag + '}}'

Invoke-RestMethod -Method POST -Headers $header -Body $data -ContentType application/json -Uri $api
exit 0

 

[AnEngelsen]

@Pierre-Nicolas Sorry. That was a copy & paste fail on my part. You're right, you  need to remove the trailing forward slash from the Server URL.

Then, when you run the PS1 script you get no error message. However, when you review the custom field association (within FileWave Admin); the Custom Field is not associated to the target device. (See attachment)

[AnEngelsen]

Lol. Wow! I feel dumb.

This whole time I was trying to run the API call using the ID of a client clone object. As soon as I replaced the ClientID with the ID of the original client object (what's listed in the `Device Details` tab, the script started working great!

Live & learn!

[AnEngelsen]

@Pierre-Nicolas any idea why many of the API examples on kb.filewave.com have a bunch of "extra" meta data nested inside the data payload?

Why include it? Why omit it?

{"exitCode":null, "status":0, "updateTime":"TIMESTAMP_HERE", "value":"CF_VALUE_HERE"}

 

[AnEngelsen]

Here is the final result (for all you Windows users).

$customFieldName = $Env:CF_Name
$flag = $Env:CF_Value
$id = $Env:ClientID
$server = (Get-ItemProperty -Path REgistry::HKEY_LOCAL_MACHINE\SOFTWARE\WOW6432Node\FileWave\WinClient).server
$token = $Env:apitoken

$header = @{Authorization=$token}
$api = "https://" + $server +  ":20445/inv/api/v1/custom_field/set_association"
$data = '{"client_ids" : [' + $id + '], "fields" : {"' + $customFieldName + '" : ' + $flag + '}}'

Invoke-RestMethod -Method POST -Headers $header -Body $data -ContentType application/json -Uri $api
exit 0

You will need to set (4) environment variables. (See attachment)

Make sure to set the ClientID variable to %filewave_id%. (Not %device_id%)

Associate the fileset to a Client or a Client Group. Then perform a model update. Enjoy!

[Pierre-Nicolas]

13 hours ago, AnEngelsen said:

Lol. Wow! I feel dumb.

This whole time I was trying to run the API call using the ID of a client clone object. As soon as I replaced the ClientID with the ID of the original client object (what's listed in the `Device Details` tab, the script started working great!

Live & learn!

Ah, yes - the code is using filewave_id field ; we could do the lookup for originals, but it's not done yet.

And regarding the error handling, the code is actually quite simple : it takes all clients for which filewave_id is in the list in parameter, then, for each custom field matching a name passed in parameter, either it creates or it deletes custom field values.

There is no error checking in the sense that errors are simply ignored - if you pass an unknown field or unknown client, it is simply ignored. We could definitely add some checks, we "just" need to make sure this does not have significant impact on performances.

 

[Pierre-Nicolas]

13 hours ago, AnEngelsen said:

@Pierre-Nicolas any idea why many of the API examples on kb.filewave.com have a bunch of "extra" meta data nested inside the data payload?

Why include it? Why omit it?

{"exitCode":null, "status":0, "updateTime":"TIMESTAMP_HERE", "value":"CF_VALUE_HERE"}

 

These attributes are populated by fwcld (desktop agent) when executing command line and script based custom fields.

Inventory system on the client side is based on what we called different scanners which run either on a schedule base (at least every verify) or depending on events (Network Scanner runs when we detect a network change) , and to limit the load on the server, the client waits for all scanners to report their data so it can send only one update (and, in addition, we have some random wait time window to make sure all your 1.000 devices you turned on at 8 AM this morning report at the exact same time, overloading the server).

Therefore, the custom field scanner stores when the custom field value has been changed locally (updateTime), what was the exitCode of the process, and an higher level status which can be:

• success,
• failure,
• conversion error,
• value not acceptable (usually when there is a limited list of possible values but the script returned something else),
• unknown (because, of course, if there is no unknown error in an API it's not a serious API),
• 3 statuses regarding LDAP fields (so not used by the client): missing attribute, user and computer not found

If you're dealing with admin based only fields, you can omit them.

They have no usage internally except for reporting.

[AnEngelsen]

Here are instructions that explain the full process:

I'm re-uploading the screenshots. (They should now be significantly less blurry.)

Overview:

Custom fields can be manually associated to FileWave desktop clients. You can also associate a custom field to all desktop devices. However, If you want the ability to automatically enable/disable a custom field association from a specific group of clients, you will need to use the FileWave API.

Here's how:

1. Log into FileWave Admin. Create a new FileWave Administrator account. Call this user something along the lines of API_helper.
   1. Assistants (menu) -> Manage Administrators
2. Go to the Application Tokens tab. Copy the base64 token to a secure note. (You'll need it later on.)
   
    
3. Create (or select) a custom field. Copy the Internal Name to the same secure note. (You'll need it later on.)
   1. Custom fields can be found in: Assistants (menu) -> Custom Fields -> Edit Custom Fields
      
       
4. Import the .fileset file that I have attached to this post. FilesetExport-SetCustomFieldAssociation.zip
   1. Importing a fileset: Filesets (in the sidebar) -> New Desktop Fileset (top of window) -> Import
      
       
5. Double-click the (recently-imported) fileset. Locate, then double-click, on the .ps1 or .sh script.
   
    
6. Select the Executable (tab) -> Enviornment Variables (tab)
7. Replace the value of the CF_Name variable with the Internal Name. (Copied during step #3)
8. Replace the value of the apitoken variable with the base64 token. (Copied during step #2)
9. Click Apply.
10. Associate the fileset to a "test device".
    1. Right-click the test client. Choose Edit custom field values. Verify that the client does not currently possess the custom field.
11. Update the model.
12. Right-click the test device. Choose Edit custom field values.
13. Verify that the test client now has the custom field associated to it. (Delete the client <--> fileset association. Created in step #10)
14. Create a smart client group. Associate the fileset (from step #4) to the smart client group.
15. Update the model.
16. Done!

If you want to automatically disassociate a custom field (when a client leaves the smart group), you could repurpose the same script (applied as a pre-uninstall script). Just change the CF_Value to false.