Look up a device in your documentation platform

Give the SuperIT agent read access to what your team has documented about a device, such as its role, location, owner, warranty notes and related procedures, so it can use that context when an engineer works a ticket in chat. For MSPs and IT teams that keep device records in a documentation platform such as Hudu or IT Glue.

Why use an action instead of asking SuperIT

SuperIT has no access to your documentation platform. It can't store its API key and can't call arbitrary web APIs, only search the public web. This action holds the credential encrypted, calls the platform's API in the cloud sandbox and returns a short summary, so SuperIT can add what only your documentation knows, such as a device's role, owner and runbooks.

For live data about a device with the SuperIT RMM agent, such as disk space, signed-in users or installed software, just ask SuperIT in chat.

When to use it

Engineers ask the SuperIT agent questions like:

• "What do we have documented for SRV-DC02?"
• "Which site is LAPTOP-4471 at, and who is it assigned to?"
• "Is there a runbook for this customer's file server?"

What the action does

1. Reads the device name from the device_name input.
2. Searches the documentation platform's assets for that name with the API key from the linked credential.
3. For each match (up to 5), prints the company, asset type, link and the documented fields on your allowlist.
4. Leaves out every other field, and any field of a password or confidential type, even if its label is on the allowlist.

What it doesn't do:

• It doesn't return fields that aren't on the allowlist. A field label such as "Passphrase", "PSK", "Admin login" or "BitLocker recovery" never reaches the output unless you add it, so don't. Keep secrets in the documentation platform, where access is logged.
• It doesn't create or update documentation. Writing back is a separate action with its own approval.
• It doesn't reach a self-hosted documentation server on a private network. The cloud sandbox reaches public internet addresses only.

Before you begin

• A credential. Under Workflows → Credentials, select New. Name it Hudu and choose the Hudu Auth scheme (an x-api-key header). The script reads it as CREDENTIAL_HUDU_X_API_KEY. For IT Glue, choose IT Glue, which uses the same header. See Credentials.
• A read-only API key in the documentation platform, ideally limited to asset reads, with password access turned off.
• Your documentation platform's base URL, for example https://yourcompany.huducloud.com.
• The field labels to return. Decide which documented fields engineers need in chat, such as role, location and assigned user, and list them in $allowedLabels. Labels must match your asset layouts exactly.
• No authorization policy is needed for a read-only lookup: with none, engineers and admins can run it without approval. See Approvals.
• Your role. Creating an action in chat needs the Admin role. Engineers can build it by hand under Workflows → Actions.

Build it with SuperIT

Create an action called "Look up device in Hudu".
Purpose: search our Hudu instance at https://yourcompany.huducloud.com for an asset by device name and summarise its company, asset type, link and documented fields.
Runtime: PowerShell in the cloud sandbox.
Input: device_name (string, required).
Credential: our "Hudu" credential (x-api-key).
Read-only. Return at most 5 matches. Only output fields whose label is in this allowlist: Role, Location, Assigned to, Serial number, Model, Operating system, Warranty expiry. Drop any field whose type is a password or confidential type, even if its label is allowed.
No authorization policy: engineers and admins only, no approval.

SuperIT checks the credential's environment variable names, drafts the script, validates it and creates the action as a draft. You review the script, test it and publish it under Workflows → Actions.

Or build it yourself

Create the action under Workflows → Actions → Add action → Create from scratch, link the Hudu credential, and add this input:

On Script, set Runtime to PowerShell:

# Goal: find a device in Hudu by name (read-only) and return its company, type, link and allowlisted fields.
$baseUrl = "https://yourcompany.huducloud.com"   # your Hudu URL
$apiKey = $env:CREDENTIAL_HUDU_X_API_KEY
# Only these field labels are returned. Never add labels that can hold secrets.
$allowedLabels = @('Role', 'Location', 'Assigned to', 'Serial number', 'Model', 'Operating system', 'Warranty expiry')
$secretFieldTypes = @('Password', 'ConfidentialText')

function Invoke-HuduDeviceLookup {
    param([string]$DeviceName)

    $name = $DeviceName.Trim()
    Assert-Inputs -Name $name
    $assets = @(Find-HuduAsset -Name $name)
    $summary = @($assets | ForEach-Object { ConvertTo-AssetSummary -Asset $_ })
    Write-AssetReport -Name $name -Assets $summary
    # $script: so the runner can still read $result after this function returns.
    $script:result = @{ device = $name; found = $summary.Count }
    if ($summary.Count -gt 0) { $script:result.assets = $summary }
}

function Assert-Inputs {
    param([string]$Name)
    if (-not $Name) { throw "Input 'device_name' is required." }
    if (-not $apiKey) { throw "The 'Hudu' credential is not linked to this action." }
}

function Find-HuduAsset {
    param([string]$Name)
    $uri = "$baseUrl/api/v1/assets?search=$([uri]::EscapeDataString($Name))"
    try {
        $response = Invoke-RestMethod -Uri $uri -Headers @{ "x-api-key" = $apiKey } -TimeoutSec 30
    } catch {
        throw "Failed to search Hudu for '$Name': $($_.Exception.Message)"
    }
    return @($response.assets | Select-Object -First 5)
}

function ConvertTo-AssetSummary {
    param($Asset)
    # An allowlist, not a denylist: a secret under an unexpected label can't slip through.
    $fields = @($Asset.fields | Where-Object {
            $_.value -and $allowedLabels -contains "$($_.label)".Trim() -and $secretFieldTypes -notcontains "$($_.field_type)"
        } | ForEach-Object { "$($_.label): $($_.value)" })
    return @{ name = $Asset.name; company = $Asset.company_name; type = $Asset.asset_type; url = $Asset.url; fields = $fields }
}

function Write-AssetReport {
    param([string]$Name, [object[]]$Assets)
    Write-Output "=== HUDU DEVICE LOOKUP ==="
    Write-Output "Device  : $Name"
    Write-Output "Matches : $($Assets.Count)"
    if ($Assets.Count -eq 0) {
        Write-Output "No documented asset matches '$Name'."
    }
    foreach ($a in $Assets) {
        Write-Output "== $($a.name) ($($a.type)) - $($a.company)"
        Write-Output "   Link: $($a.url)"
        foreach ($f in $a.fields) { Write-Output "   $f" }
    }
}

Invoke-HuduDeviceLookup -DeviceName $ctx.inputs.device_name

When nothing matches, the script still sets $result with found at 0, so SuperIT can tell an empty search from a failed run. Fields are filtered when each asset is summarised, before anything is printed or returned: only labels in $allowedLabels are kept, and fields whose type is in $secretFieldTypes are dropped even then. Check the field type names your platform's API returns, and add any other secret types it uses.

Test it

1. Save the draft and select Test.
2. Remember that Test is not a dry run: it skips authorization and approvals and uses the real credential and network access. This action only reads, so it's safe to test. Test runs aren't billed.
3. Tick the confirmation box, enter a device name you know is documented, and select Start test run.
4. Check Stdout: the company, asset type and link are right, and only the fields on your allowlist appear.
5. Test a name that doesn't exist and confirm the output says "No documented asset matches".
6. Select Publish.

Use it

• In chat: "What do we have documented for SRV-DC02?" SuperIT runs the action and combines the documented details with live data from the device.
• From ticket investigations: SuperIT can recommend the action after investigating a ticket. An action with a credential needs an authorization policy before Run automatically can run it without an engineer. The investigation only recommends the action: it doesn't read the output, so the documented details appear in the run, not in the investigation's findings.
• Managed teams: most MSPs use one documentation platform for every customer, so keep this action in the service provider team. If each managed team has its own documentation instance, use Publish to teams: each team gets a read-only copy and a blank Hudu credential for its admin to fill in. The base URL is in the script, so a different instance per team needs its own action, or an input for the URL.

Variations

• IT Glue: call the configurations endpoint with a name filter and the x-api-key header, and read data[].attributes. IT Glue's API address differs by region, so check its API documentation for your region's address and the filter syntax. Use the same allowlist approach for the attributes you return.
• Look up a contact or a company instead of a device, for example the site's contacts and opening hours.
• Find the runbook: search the platform's knowledge base articles for the device's role and return the article links.

Related

• Call a third-party API
• Credentials
• Approvals
• Look up device warranty