Launching an Embedded Portal with a Server-Side Listener

Launching a Portal that combines a server-side listener with a client-side embed can be an effective way to streamline your data processing workflow. You may find that you want to run your validations and store your workbook configuration outside of your client-side Portal, and this guide will walk you through the process of configuring and deploying your listener to Flatfile’s servers and setting up the client-side embed using Flatfile’s JavaScript SDK. Even though this guide works with the JavaScript SDK, the same concepts will work with the other Embedded wrappers as well.

Step 1: Deploying a Server-Side Listener

First, you need to deploy a server-side listener to Flatfile’s servers. This listener will handle your validations and blueprint configuration for the Portal.

Create and Deploy Your Listener

Create a Repository: Set up listener file containing your custom listener and validations, similar to the example provided in our Getting Started Guide on creating a custom workbook. The example below shows the listener filtered to a namespace of "portal", though this could be updated to whatever you want.

import api from "@flatfile/api";
import { recordHook } from "@flatfile/plugin-record-hook";

export default function flatfileEventListener(listener) {
  listener.namespace(["space:portal"], (portal) => {
    // Configure a Space (https://flatfile.com/docs/apps/custom)
    portal.on(
      "job:ready",
      { job: "space:configure" },
      async ({ context: { spaceId, environmentId, jobId } }) => {
        try {
          await api.jobs.ack(jobId, {
            info: "Gettin started.",
            progress: 10,
          });

          await api.workbooks.create({
            spaceId,
            environmentId,
            name: "All Data",
            labels: ["pinned"],
            sheets: [
              {
                name: "Contacts",
                slug: "contacts",
                fields: [
                  {
                    key: "firstName",
                    type: "string",
                    label: "First Name",
                  },
                  {
                    key: "lastName",
                    type: "string",
                    label: "Last Name",
                  },
                  {
                    key: "email",
                    type: "string",
                    label: "Email",
                  },
                ],
              },
            ],
            actions: [
              {
                operation: "submitAction",
                mode: "foreground",
                label: "Submit foreground",
                description: "Submit data to webhook.site",
                primary: true,
              },
            ],
          });

          await api.jobs.complete(jobId, {
            outcome: {
              message: "Your Space was created.",
              acknowledge: true,
            },
          });
        } catch (error) {
          console.error("Error:", error.stack);

          await api.jobs.fail(jobId, {
            outcome: {
              message: "Creating a Space encountered an error. See Event Logs.",
              acknowledge: true,
            },
          });
        }
      }
    );

    portal.use(
      recordHook("contacts", (record) => {
        const value = record.get("firstName");

        if (typeof value === "string") {
          record.set("firstName", value.toLowerCase());
        }

        return record;
      })
    );
  });
}

Deploy to Flatfile: Deploy the listener to Flatfile’s servers. This listener will listen for events and apply the necessary logic, such as building the space when the button to launch the Portal is clicked and listening for any further events emitted in that namespace.
```
npx flatfile@latest deploy <path to your file> 
```

Step 2: Configuring the Client-Side Embed

Once your server-side listener is deployed, the next step is to configure the client-side embed. Here, this is done using the JavaScript SDK.

To configure the client-side embed, you will remove the workbook and listener parameters from the standard embed parameters. The Portal will rely on the deployed server-side listener to handle these moving forward.

Here's an example of how the Portal configuration might look:

const flatfileOptions = {
  publishableKey,
  sidebarConfig: {
    showSidebar: false,
  },
  namespace: "portal",
  themeConfig: {
    root: {
      primaryColor: "teal",
    },
  },
  // Additional props...
};

Step 3: Handling the Space Configuration

With the client-side embed configured, the deployed server-side listener will take over when the Portal is launched. The listener will react to the space:configure event, and handle tasks such as building the space and assigning the listener to the space dynamically.

Final Considerations

By separating the responsibilities between server-side and client-side configurations, you gain flexibility and control over how your Portal functions. The server-side listener manages the core logic and validation, while the client-side embed handles the user-facing aspects, such as theming and sidebar configuration.

For more detailed information on setting up a custom workbook and embedding using Flatfile's JavaScript SDK, refer to the Getting Started Guide and the Portal Guides.

This setup ensures a streamlined, efficient process that leverages the power of server-side processing while maintaining a smooth client-side experience.