Sana - Serval Documentation

About Sana

Sana is an AI knowledge and learning platform. Serval connects to your Sana tenant using an API client (a client ID and secret) that you create inside Sana, plus your tenant domain (for example acme.sana.ai). Once connected, workflows can read and act on your learning data: people, the groups they belong to, the courses and programs they’re enrolled in, and the reports that track completion. The Sana integration is currently in beta.

When you connect, you choose whether Serval has read access or read and write access. Read access covers everything that looks up or reports on Sana data. Read and write access is required for anything that changes Sana, such as creating a user, enrolling someone in a program, or marking a course complete. Pick read only if you want to be certain that no workflow can ever modify Sana.

Authentication Serval authenticates with a Sana API client: a client ID and a client secret created in Sana. Serval stores the secret encrypted and exchanges it for a short-lived access token each time it calls Sana, so the workflows you build never handle the secret directly and there is no long-lived token sitting in a workflow. Tokens are refreshed automatically before they expire. Data sync On demand only. Serval calls Sana at the moment a workflow step runs. There is no background sync, and the integration ships no pre-installed workflows.

What the Sana integration enables

Workflows can work with the main areas of your Sana tenant:

Capability	Description
Users	Look up and manage people in Sana: create, update, and remove users, send or regenerate invitations, set a user’s manager, and read the groups a user belongs to.
Groups	Manage groups and their membership: create, update, and delete groups, add or remove members, and change a member’s role. Groups are how course and program assignment is often organized.
Programs	Manage structured learning programs: create, update, and delete them, and enroll or unenroll members.
Courses	Manage courses: create and link courses, update them, and record progress such as marking a course completed or resetting it for a learner.
Assignments	See what content is assigned to a person, and assign or unassign content to them.
Paths	Read the learning paths defined in your tenant.
Teamspaces	Manage teamspaces and their membership: create and delete teamspaces, and add or remove members.
Reporting	Run reporting jobs to pull completion and engagement data out of Sana for use in the rest of Serval.

Serval works with your tenant’s learning and knowledge data. It doesn’t configure single sign-on or identity-provider user provisioning for Sana, which are set up directly in your identity provider.

Get your credentials

You create an API client inside Sana and give Serval its client ID and secret. The API client’s access in Sana determines what Serval can do, so create it with the scopes your workflows need.

Create an API client

Go to Manage → API in Sana and create a new API client. Grant it read access, or read and write access, to match how you plan to use it in Serval.

Copy the client ID and secret

Copy the client ID and client secret. Store the secret somewhere safe: you will paste it into Serval, and Sana may show it only once.

Note your tenant domain

Your tenant domain is the host you use to reach Sana, for example acme.sana.ai. You will enter this in Serval.

Serval only connects to hosts under sana.ai. Enter your real tenant host (for example acme.sana.ai), not sana.com, which belongs to an unrelated company.

Connect in Serval

Open your team workspace, go to Integrations → Connect new, choose Sana, and fill in the connect form. Every field is required.

Enter the Sana domain

Enter your tenant host without https://, for example acme.sana.ai. Serval tidies up a pasted address (it strips the scheme, any trailing slash, and any path).

Enter the Client ID

Paste the client ID from the API client you created in Sana.

Enter the Client secret

Paste the client secret. Serval stores it encrypted and only ever uses it to mint the short-lived tokens it needs to call Sana.

Choose Access

Choose Read and write (the default) or Read only. Write access is required for any workflow that changes Sana. Choose read only to guarantee that workflows can never modify your Sana data.

Submit the form

Submit to create the connection. Serval verifies it with a health check against your tenant.

Verifying the connection

When you connect, Serval runs a check that confirms it can mint a token from your credentials and reach your tenant. The integration also includes four built-in health checks you can run at any time from the connection’s API Integration tab:

Check	What it verifies
Test Connection	Confirms Serval can obtain a token from your client credentials and reach the tenant API.
List Users	Confirms read access to user records.
List Groups	Confirms read access to groups.
List Courses	Confirms read access to courses.

If every check fails with valid-looking credentials, the most common cause is that the API client in Sana wasn’t granted the access you chose in the connect form. Confirm the client’s scopes in Sana, then rerun the checks.

Gotchas and troubleshooting

Read versus read and write

The access you pick at connect time is enforced on every call. A connection created with read only can’t create users, enroll people, or mark courses complete, even if a workflow asks it to. If a write action fails, check whether the connection (and the underlying Sana API client) has write access.

Use your real tenant host

Serval only reaches hosts under sana.ai, and the host you enter is where every request goes. Enter your tenant host (for example acme.sana.ai) without https://. Don’t use sana.com, which belongs to an unrelated company.

The API client's access in Sana bounds what Serval can do

Serval can do exactly what the API client is allowed to do in Sana. If workflows hit permission errors while the connection looks healthy, widen the client’s access in Sana (or create a new client with the scopes you need) and update the connection.

Beta integration

The Sana integration is marked beta in the connect screen. Behavior and available capabilities may change.

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

​About Sana

​What the Sana integration enables

​Get your credentials

​Connect in Serval

​Verifying the connection

​Gotchas and troubleshooting

About Sana

What the Sana integration enables

Get your credentials

Connect in Serval

Verifying the connection

Gotchas and troubleshooting