> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# HCL BigFix

> Connect Serval to your HCL BigFix root server so workflows can look up managed endpoints, evaluate relevance queries, inspect patch content, and take actions.

## About HCL BigFix

HCL BigFix manages endpoints at scale: it inventories every computer running the BigFix agent, evaluates patch and compliance content (Fixlets, tasks, and baselines) against them, and deploys actions to fix what is out of policy. This integration connects Serval to your BigFix root server so workflows can find a computer and its reported properties, answer inventory and compliance questions with Session Relevance, list the content that applies to an endpoint, and, when you allow it, take actions. The integration is marked **Beta** in the connect screen, so its capabilities may still change.

**Authentication:** Username and password for a BigFix Console operator account, sent to your server as HTTP Basic authentication on each request. Workflows never handle the credentials.

**Access level:** You choose what Serval may do when you connect, and Serval enforces it server-side on every request:

* **Read-only** lists computers, content, actions, and sites, and evaluates Session Relevance and BigFix Query expressions.
* **Full** adds taking actions, managing content, and administering operators and roles.

**Data sync:** None. Everything is on demand: Serval calls your server only when a workflow or health check runs. There is no background sync, no webhooks, and no data ingestion.

## What the HCL BigFix integration enables

| Capability              | Description                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| BigFix API request      | A generic workflow action that can call the supported REST API endpoints: computers and their properties and client settings, relevance queries, actions and their per-computer status, sites, Fixlets, tasks, baselines, analyses, computer groups, retrieved properties, operators, roles, and Web Reports servers. XML responses are converted to JSON automatically. |
| Session Relevance query | A workflow action that evaluates a Session Relevance expression, the same language the BigFix Console uses, and returns typed JSON results.                                                                                                                                                                                                                              |

These use the [BigFix REST API](https://developer.bigfix.com/rest-api/) served by the root server on port 52311.

<Note>
  The read-only access level is enforced by Serval, not just documented: with it selected, Serval refuses any request to your server that is not a read, so workflows cannot take actions, change content, or modify settings on endpoints.
</Note>

## Before you connect

Two things about your BigFix deployment decide whether a connection can work at all. Check both before creating the operator account.

<AccordionGroup>
  <Accordion title="Serval must be able to reach the root server over the network">
    Most BigFix root servers sit on an internal network that Serval's cloud cannot reach. Three deployments are possible:

    * **Root server reachable from the internet**: connect normally, nothing extra needed.
    * **Self-hosted Serval deployment**: works when your deployment is configured to allow internal targets.
    * **Serval cloud with a self-hosted worker**: Enable **Run on self-hosted workers** for the connection. Requests then run from your network; the worker must be able to reach the root server on its REST API port (52311 by default) and trust its TLS certificate. A read-only connection also needs an up-to-date worker: on an older worker every request fails with a message asking you to upgrade it, because the older worker cannot enforce the read-only boundary per request.
  </Accordion>

  <Accordion title="The root server needs a CA-signed TLS certificate">
    Serval verifies the server's certificate against its trust store, and there is no option to skip that check or supply a private CA. A root server still serving the self-signed certificate BigFix generates at install time will fail to connect. Replace it with a certificate signed by a CA your Serval deployment trusts, following HCL's guidance on configuring the BigFix server's HTTPS certificate.
  </Accordion>
</AccordionGroup>

## Get your credentials

Serval needs your root server's host and a BigFix Console operator account.

<Steps>
  <Step title="Create a dedicated operator">
    In the BigFix Console, go to **Tools** then **Create Operator** and create a local operator such as `svc-serval` with a strong password. Using a dedicated account rather than a person's login keeps the connection working when staff change. If your deployment restricts REST API access to LDAP operators, create an LDAP-backed operator instead.
  </Step>

  <Step title="Assign the computers and sites it may see">
    A non-master operator only sees the computers and sites assigned to it. Assign the computers Serval should be able to look up, and grant **Reader** access to the sites whose content it should see. For the read-only access level, no further permissions are needed.
  </Step>

  <Step title="Grant action permissions only if you need them">
    If you plan to select the **Full** access level so workflows can take actions, also grant the operator the **Can Create Actions** permission and, for custom content, **Writer** access to the relevant sites. Skip this for a read-only connection.
  </Step>

  <Step title="Note your root server host">
    Use the hostname or IP address the BigFix Console connects to, without the "https\://" prefix, for example "bigfix.example.com". The REST API listens on port 52311 unless your deployment changed it.
  </Step>
</Steps>

## Connect in Serval

<Steps>
  <Step title="Open the HCL BigFix integration">
    In Serval, go to the integrations page and select **HCL BigFix** (marked Beta).
  </Step>

  <Step title="Enter the BigFix Server Host">
    Enter the hostname or IP address of your root server, for example "bigfix.example.com". Port 52311 is assumed; add a port only if your server uses a different one. Serval always connects over HTTPS.
  </Step>

  <Step title="Enter the Username and Password">
    Enter the operator account, for example "svc-serval", and its password. The password is stored encrypted and shown masked after saving.
  </Step>

  <Step title="Choose the Access Level">
    Select **Read-only** unless workflows need to take actions or manage content. You can change it later in the integration settings.
  </Step>

  <Step title="Save, then run the health checks">
    Saving validates the format of what you entered but does not call your server, because the connect screen cannot reach an internal network even when workflows can. Run the health checks afterwards to confirm the credentials work.
  </Step>
</Steps>

## Verifying the connection

Four health checks run on demand and are the way to confirm a working connection:

| Health check               | What it proves                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------ |
| Test BigFix Connection     | The credentials are accepted and the server is reachable.                            |
| List BigFix Computers      | The operator has been assigned computers to manage.                                  |
| Evaluate Session Relevance | The server can forward relevance queries to a Web Reports or BigFix Explorer server. |
| List BigFix Sites          | The operator can read at least one site.                                             |

If Test BigFix Connection passes but List BigFix Computers returns zero computers, the credentials are correct and the operator has no computers assigned.

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Session Relevance needs a Web Reports or Explorer server">
    The root server does not evaluate Session Relevance itself. It forwards each query to the Web Reports server or BigFix Explorer server with the highest priority, so a deployment without either fails the **Evaluate Session Relevance** health check while every other endpoint keeps working. Install or register one of those components, or use the REST endpoints for computers and content instead.
  </Accordion>

  <Accordion title="A non-master operator sees only what it is assigned">
    Every list the integration returns is scoped to the operator's permissions. A computer that exists in BigFix but is not assigned to the operator is invisible, as is content in a site the operator cannot read. When a workflow cannot find a computer you know is managed, check the operator's assignments before suspecting the connection.
  </Accordion>

  <Accordion title="Values come back as text">
    BigFix returns XML, and Serval converts it to JSON with every value kept as a string, so an ID or a count arrives as "538222075" rather than a number. Use the **Session Relevance query** action when you need typed values; its results are returned as JSON with numbers as numbers.
  </Accordion>

  <Accordion title="List responses are not paged">
    The REST API returns complete lists with no paging. On a deployment with tens of thousands of endpoints, listing all computers with their properties is slow and large. Use the fields parameter to limit what comes back, or express the question as a Session Relevance query so the server does the filtering.
  </Accordion>

  <Accordion title="Taking actions runs code on endpoints">
    With the Full access level, a workflow can create an action, which runs ActionScript on every targeted computer once the BigFix agent picks it up. Scope such workflows to explicit computer IDs or a computer group rather than all computers, and prefer Fixlet-sourced actions over inline scripts so the content has been reviewed in the console.
  </Accordion>

  <Accordion title="Changing the password breaks the connection until you update it">
    Serval sends the stored password on every request. If the operator's password is rotated or the account is disabled in BigFix, requests fail with an authentication error. Update the password in the integration settings to restore it.
  </Accordion>

  <Accordion title="This integration is in Beta">
    The HCL BigFix connect tile is marked Beta, so the available actions may still change.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your HCL BigFix integration.