Bootstrap a new Ontology SDK TypeScript application with a service user

As explained in the permission types section, the Ontology SDK can be used to query data based on a service user's permissions rather than the end user's permissions. The following walkthrough shows how to use Next.js© ↗ (external) to fetch data using the Ontology SDK and a service user.

1. Create an Ontology SDK package using Developer Console

Navigate to Developer Console in your Foundry instance, then select + New application.

Follow the steps in the creation wizard and add the following details:

• On the Application type page, choose Backend service.

• On the Permission page, choose Application's permissions.

Developer Console will create a service user for this application based on the application name. In the example above, the name of the generated service user is Ontology SDK application using service user. In addition to the submission criteria for any action types, you must grant this service user the permissions required to read the data of the object types you will select in the next step.

• On the Ontology & resource scopes page, select Yes, generate an Ontology SDK.

• Select an Ontology to use. Then, select the object types and action types that you want the Ontology SDK package to include. For this exercise, pick any object type available to you.

Review and confirm the information you entered, then select Create application to see the client secret for the new application. Copy and store the secret securely as this is the only time it is visible.

Finally, select Generate first version to use your newly created Ontology SDK.

2. Install the generated SDK package

Once the generation of the Ontology SDK is complete, you will see a set of installation steps to guide you in installing the generated SDK in your code project.

3. Use the Ontology SDK in your code project

In this walkthrough, we use Next.js© ↗. Next.js supports rendering code on the server side which is required for our service user example. To bootstrap a new Next.js project, follow the Next.js© documentation ↗ .

Client.ts

The following code uses a Country object type with a @serverside-osdk-example/sdk/ontology package name. Replace the example package name to match the package you just created and the object type to match the object type you selected. Finally, replace {country.countryName} with a property from your object type. Create a file named client.ts and enter the following code:

Copied!
1
2
3
4
5
6
7
8
9
10
import { ConfidentialClientAuth, FoundryClient } from "@serverside-osdk-example/sdk";

export const client = new FoundryClient({
    url: process.env.STACK!,
    auth: new ConfidentialClientAuth({
        clientId: process.env.CLIENT_ID!,
        clientSecret: process.env.CLIENT_SECRET!,
        url: process.env.SERVER_URL!,
    }),
});

Create a .env file with the same variables. Do not check in this file to your code repository.

Copied!
1
2
3
CLIENT_ID=<YOUR CLIENT ID>
CLIENT_SECRET=<YOUR CLIENT SECRET>
SERVER_URL=<YOUR ONTOLOGY SERVER DOMAIN NAME> # for example, https://myfoundrystack.com

Replace the code in the page.tsx with the following:

Copied!
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
import { isOk } from "@serverside-osdk-example/sdk";
import { Country } from "@serverside-osdk-example/sdk/ontology/objects";
import Image from "next/image";
import { client } from "./client";


async function getCountries(): Promise<Country[]> {
  // Handle authentication
  await client.auth.signInAsServiceUser();
  // You need to give the service user read access to the ontology
  try {
      const resp = await client.ontology.objects.Country.fetchPageWithErrors();
      if (isOk(resp)) {
          return resp.value.data;
      }
  } catch (err) {
      console.log(err);
  }
  console.log("No countries found");
  return [];
};

export default async function Home() {
  const countries: Country[]  = await getCountries();
  return (
    <main>
        <div>
          {countries.map((country: Country) => (
            <span key={country.__primaryKey}>{country.countryName}</span>
            )
          )}
        </div>
    </main>
  )
}

This method uses signInAsServiceUser to sign in to Foundry, as compared to using the client application.

To run a demo of your setup, first run the development server:

Copied!
1
npm run dev

Then, navigate to http://localhost:3000 ↗ with your browser to view the result.