Skip to main content

About Poly Lens

Poly Lens is HP’s cloud service for managing Poly devices, such as video conferencing systems, and the rooms and sites they’re placed in. This integration connects Serval to the Lens API so workflows can look up devices, rooms, and sites, and act on devices: reboot them, start or end calls, and collect logs. Authentication: Poly Lens API credentials, a client ID and client secret created in the Poly Lens Admin Portal. Serval stores the secret encrypted and exchanges the credentials for a Lens access token, which it adds to requests server-side, so workflows never handle the credentials or the token. Serval sends the credentials only to the Poly token endpoint, login.lens.poly.com, and the token only to the Lens API, api.silica-prod01.io.lens.poly.com. Data sync: No background sync starts when you connect, and the integration has no installable workflows. Data access is on demand through workflows.

What the Poly Lens integration enables

Get your credentials

Serval needs a set of Poly Lens API credentials. Creating them requires Administrator permissions in Poly Lens.
1

Open API Credentials

Sign in to the Poly Lens Admin Portal, open the Account menu, then go to Account Settings then API Credentials.
2

Add credentials for Serval

Select Add New and choose the data scope: Just this account, or Multiple accounts if Serval should work across several. Serval can reach only the accounts in scope.
3

Name the credentials and choose a role

Enter a name, for example Serval, and choose a role. Lens uses the role to control what the credentials can access, so choose one that covers only what your workflows need. Select Confirm.
4

Copy the Client ID and Client Secret

Copy both values from the new credentials. They aren’t tied to your SSO user account.
The Poly Lens GraphQL request action can send any query or mutation that Lens accepts, including ones that reboot or factory reset devices, end calls, or remove devices from Poly Lens. The action doesn’t restrict which operations it sends: the credentials’ role and data scope in Lens are what limit what a workflow can change. A reboot ends all active calls on the device and takes it offline for several minutes. A factory reset resets all the device’s settings and its connection to Poly Lens.

Connect in Serval

1

Open the Poly Lens connect form

Add a new Poly Lens connection from your Serval integrations page. There’s no address to enter: Serval always connects to the Poly Lens API, and the credentials’ data scope decides which accounts it reaches.
2

Enter the Client ID

Paste the Client ID from the API credentials you created.
3

Enter the Client Secret

Paste the Client Secret shown with that Client ID. It’s stored encrypted and shown masked after saving.
4

Save, then check the health check

Saving doesn’t test the credentials. The health check runs automatically after you connect: confirm it passes before you build workflows on the connection.
To rotate credentials, create new API credentials in Lens, edit the connection, enter both the new Client ID and the new Client Secret, and confirm the health check passes. Then delete the old credentials in Lens. If you change only the Client ID and leave the masked secret, Serval keeps the old secret, and Poly rejects the mismatched pair.

Verifying the connection

The connection ships one health check that makes a live call to Poly Lens:
  • List Poly Lens Accounts: exchanges the credentials for an access token, then asks Lens for one account the credentials can reach. On success: “Successfully reached Poly Lens (accounts visible: 1).”
When the check passes, the credentials are valid and Serval can reach the Lens API. Because the check asks for a single account, the count is at most 1, however many accounts the credentials reach. The check doesn’t test whether the role can read devices or run device actions.

Gotchas and troubleshooting

Lens accepted the credentials but returned no account for them. Check the credentials’ data scope and role in Lens.
The check reports “Unable to reach Poly Lens.” An error saying the credentials were rejected means Poly refused the Client ID and Client Secret pair. Confirm that both values come from the same API credentials under Account Settings then API Credentials, rather than an SSO sign-in, and that the credentials still exist in Lens.
Serval reuses each access token until shortly before its 24-hour expiry, and requests a new token as soon as you save different credentials on the connection. Deleting the API credentials in Lens stops Serval from getting new tokens, but whether Lens still accepts a token it already issued is up to Poly. To stop Serval’s access right away, also delete the connection in Serval or replace its credentials.
Lens answers a failed operation with HTTP 200 and a list of errors. Even when part of the data came back, the Poly Lens GraphQL request action turns that list into a step error that starts with “Poly Lens GraphQL request returned errors.”
Lens prices each request in points. A single request must stay under 10,000 points, and requests draw from a 100,000-point balance that resets every 60 seconds. Select only the fields a workflow needs, and page through large inventories instead of requesting everything at once.
deviceSearch returns 10 devices unless you set params.pageSize, up to 5,000. To read every device, pass pageInfo.nextToken back as params.nextToken until pageInfo.hasNextPage is false. Send the same pageSize on every page: Lens returns an error if it changes after the first request, including dropping it to fall back to the default.
Lens marks the devices, searchDevices, rooms, and sites queries as deprecated. In workflows you write yourself, use deviceSearch, roomData, and siteData instead.
Serval calls two Poly hosts: login.lens.poly.com for access tokens and api.silica-prod01.io.lens.poly.com for the Lens API. If the Serval deployment or worker serving the connection restricts outbound traffic, allow HTTPS to both.

Need help? Contact support@serval.com for assistance with your Poly Lens integration.