• Documentation
    • Search documentation
    karat

    +

    K

    API Reference ↗
    Developer toolchainOntology SDKOSDK referencesUpdate OSDK application for Marketplace deployment

    Update OSDK application for Marketplace deployment

    This guide helps you migrate your OSDK applications to allow them to be deployable on Marketplace.

    When deploying existing OSDK applications through Marketplace, certain modifications are necessary to ensure proper deployment. These modifications enable the Marketplace installation process to automatically replace source environment identifiers with those of the target environment.

    If you are creating a new OSDK application, you can use @osdk/create-app CLI v2.1.3 ↗ which produces a Marketplace deployable OSDK application out of the box.

    Required changes

    Follow the changes below update your OSDK application for Marketplace deployment.

    1. Update index.html

    Add the following meta tags inside the <head> section of your index.html file:

    Copied!
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
<!doctype html>
<html>
  <head>
    <!-- Existing head content -->
    <meta name="osdk-clientId" content="%VITE_FOUNDRY_CLIENT_ID%" />
    <meta name="osdk-redirectUrl" content="%VITE_FOUNDRY_REDIRECT_URL%" />
    <meta name="osdk-foundryUrl" content="%VITE_FOUNDRY_API_URL%" />
    <meta name="osdk-ontologyRid" content="%VITE_FOUNDRY_ONTOLOGY_RID%" />
    <!-- Other head content -->
  </head>
  <body>
    <!-- Body content -->
  </body>
</html>

    2. Update environment files

    Add the following environment variable to all environment variable files present in your project. For example: .env.development, .env.production, and .env.code-workspaces:

    VITE_FOUNDRY_ONTOLOGY_RID=<ri.ontology.main.ontology.your-ontology-rid>

    Replace <ri.ontology.main.ontology.your-ontology-rid> with your OSDK application's Ontology RID.

    You can find your OSDK application's Ontology RID by looking at the value of $ontologyRid which is exported from your OSDK. Example: import { $ontologyRid } from "@your-app/sdk";

    3. Read meta tags and initialize client

    These changes are specific to TypeScript OSDK 2.0. If necessary, review the migration guide for moving an existing OSDK application from 1.x to 2.0.

    Update your client.ts file (or wherever your OAuth Client is initialized) with the following code:

    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 { createClient, type Client } from "@osdk/client";
import { createPublicOauthClient, type PublicOauthClient } from "@osdk/oauth";

function getMetaTagContent(tagName: string): string {
  const elements = document.querySelectorAll(`meta[name="${tagName}"]`);
  const element = elements.item(elements.length - 1);
  const value = element ? element.getAttribute("content") : null;

  if (value == null || value === "") {
    throw new Error(`Meta tag ${tagName} not found or empty`);
  }

  if (value.match(/^%.+%$/)) {
    throw new Error(`Meta tag ${tagName} contains placeholder value. Add ${value.replace(/docs/%/g, "")} to your .env files`);
  }

  return value;
}

const foundryUrl = getMetaTagContent("osdk-foundryUrl");
const clientId = getMetaTagContent("osdk-clientId");
const redirectUrl = getMetaTagContent("osdk-redirectUrl");
const ontologyRid = getMetaTagContent("osdk-ontologyRid");
const scopes = [/* TODO: Add your existing scopes here */];

export const auth: PublicOauthClient = createPublicOauthClient(
  clientId,
  foundryUrl,
  redirectUrl,
  {scopes}
);

const client: Client = createClient(foundryUrl, ontologyRid, auth);

export default client;

    API name consistency between environments

    When deploying OSDK applications across environments, the shipped website assets reference entities in your Ontology using their API names, which creates a dependency that requires attention during deployment. To avoid issues with your application, be aware of the following API name considerations:

    • API name consistency: When deploying to a target environment, ensure that the entities in the target ontology have the same API names as in the source environment.
    • Entities with the same API names: API names will change between environments if an entity with the same API name already exists in the target environment. This will cause your application to fail to reference the required entities.