> ## 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.

# FMS:Workplace

> Connect Serval to FMS:Workplace so workflows can read facility data through the FMInteract Web Service SOAP API.

## About FMS:Workplace

FMS:Workplace (FM Systems) is a facilities and workplace management platform. The Serval integration connects to your tenant's **FMInteract Web Service** — a SOAP endpoint that exposes permissioned views and stored procedures as data objects. Workflows call a single `getData` action with an object name and type; Serval injects the Web Service username and password into the SOAP body server-side on every request, so workflow code never handles those credentials.

**Authentication:** Web Service username and password embedded in the SOAP request body (not an HTTP header). Serval stores them encrypted and splices them into each `GetData` call automatically.

**Data sync:** On demand only. There is no background sync — workflows fetch facility data live when they run.

## What the FMS:Workplace integration enables

| Capability             | Description                                                                                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| FMS:Workplace getData  | Call the FMInteract `GetData` SOAP operation with an object name, object type, and optional parameters. Returns tabular rows from views or stored procedures your Web Service user is permissioned to access. |
| Typed workflow context | Workflows receive the configured service URL as `apiDomain` on the integration context, so the SDK routes requests to your tenant's `.svc` endpoint.                                                          |

The objects available to your workflows depend entirely on what your FMS administrator permissioned to the Web Service user — Serval does not ship a fixed catalog of facility views.

## Get your credentials

You need three values from your FMS:Workplace administrator: the full Web Service URL, a Web Service username, and its password.

<Steps>
  <Step title="Locate the Web Service URL">
    Hosted FMS:Workplace instances typically use a path like `yourcompany.fmshosted.com/FMIWebService/FMInteractWebService.svc`. Test and production environments may use different path segments (for example a `TST_FMIWebservices` prefix). Copy the host and path **without** `https://`.
  </Step>

  <Step title="Confirm the Web Service user">
    In FMS:Workplace, open **System Administration → Modify System Settings → Web Services → Web Services User Setting**. Note the dedicated Web Service user — this is not necessarily the same as an interactive FMS application login.
  </Step>

  <Step title="Collect the Web Service password">
    Use the password configured for that Web Service user. Serval stores it encrypted and injects it into the SOAP envelope on every call.
  </Step>

  <Step title="Verify L0 (floors) access for the health check">
    Serval's connection test reads the `L0` text view. Ensure the Web Service user is permissioned to that object, or expect the health check to fail even when other views work.
  </Step>
</Steps>

<Note>
  Serval's outbound allowlist currently covers `*.fmshosted.com` hosted instances. Self-hosted FMS:Workplace deployments on other domains require an allowlist extension — contact Serval support if your service URL is not on `fmshosted.com`.
</Note>

## Connect in Serval

<Steps>
  <Step title="Open the FMS:Workplace connect form">
    In Serval, add the FMS:Workplace integration.
  </Step>

  <Step title="Service URL (required)">
    Enter the full Web Service endpoint host and path, without `https://`. Example: `yourcompany.fmshosted.com/FMIWebService/FMInteractWebService.svc`.
  </Step>

  <Step title="Web Service Username (required)">
    Enter the Web Service user from FMS system settings.
  </Step>

  <Step title="Web Service Password (required)">
    Enter the Web Service user's password in the password field.
  </Step>

  <Step title="Save and run the health check">
    Submit the form. Serval runs **Test FMS:Workplace Connection**, which calls `GetData` for the `L0` view.
  </Step>
</Steps>

## Verifying the connection

**Test FMS:Workplace Connection** — reads the `L0` (floors) text view through the full SOAP path, including server-side credential injection.

* Success: `Successfully connected to FMS:Workplace (L0 returned N row(s)).`
* Failure (auth or URL): `Unable to connect to FMS:Workplace. Verify the Service URL, username, and password, and that the user is permissioned to the L0 view in Web Services settings.`
* Failure (reachable but denied): `FMS:Workplace reachable but returned a non-success status… Confirm the Web Service user is permissioned to the L0 view.`

<Tip>
  If the connection test fails but you know the credentials are correct, ask your FMS admin to grant the Web Service user access to the `L0` view — that is the object Serval uses to prove connectivity.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Do not include https:// in the Service URL">
    Paste only the hostname and path. Serval adds TLS when calling the service.
  </Accordion>

  <Accordion title="Web Service user ≠ application user">
    The username in FMS interactive login screens may differ from the Web Service user configured under System Administration. Use the value from Web Services User Setting.
  </Accordion>

  <Accordion title="Object availability is customer-specific">
    `getData` succeeds only for object names and types your Web Service user can read. Build workflows against views your administrator documents for the integration account.
  </Accordion>

  <Accordion title="Credentials never appear in workflow logs">
    UserName and Password elements are injected by the Serval proxy after the workflow submits the SOAP template. Workflow code only contains placeholders.
  </Accordion>
</AccordionGroup>

***

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