Until you publish a flow, it is only visible to other users of your organization in the Formsort studio. Once you publish a flow, it becomes immediately accessible under a URL in the flow.formsort.com domain.

While your flow is fully functional under this domain, we do not recommend using it in production, as users may be confused by the root domain not matching the content.

If you'd like to embed Formsort within an existing page, there are a few different approaches.

Upon publishing, you will see an option to copy a javascript snippet that will load the flow. This is the simplest approach - by copy pasting this snippet into your HTML, the formsort flow will load.

If you are a non-technical user that just needs to put a flow within another page, such as embedding a form within Unbounce or integrating the flow with a Squarespace page, this approach should suffice.

If your flow ends in a redirect, the containing page will be navigated to the redirect URL once the flow is finalized.

The @formsort/react-embed package on npm allows to embed Formsort within React applications, and comes with Typescript type annotations. The flow parameters are passed as props to the component.

~~~jsx~~~
import EmbedFlow from '@formsort/react-embed';

//...

<EmbedFlow
  clientLabel='formsort'
  flowLabel='onboarding'
  variantLabel='main'
  embedConfig={{
    style: {
      width: '100%',
      height: '100%',
    }
  }}
/>

Compared to the javascript snippet, the React embed will load more quickly, as the loading code will be part of your javascript bundle and the flow can immediately start loading.

In addition to loading and displaying the flow, you will have access to callbacks for flow lifecycle events, such as when a step or the flow itself is completed.

If you don't use react, @formsort/web-embed-api is a pure-javascript embed option.

Internally, Formsort loads as an <iframe> and communicates with your page using a protocol using window.postMessage. web-embed-api wraps that communication with an event emitter that you can use more simply.

If you'd rather not host a page just to present a form, you can configure your DNS to point to formsort servers, and we will serve your flow at that domain.

When you add a domain to formsort, we will issue a star certificate for that URL pattern. For example, if you add flow.example.com, we will issue a certificate for *.example.com. After domain verification, you will be able to add other subdomains to point to Formsort.

For performance, your DNS records will actually point to our CDN provider, Amazon CloudFront, which then loads your flows from our origin servers.

Once configured, domains may be pointed to one of your flows. That flow (or specific variant of a flow), will be served at the root of that domain.

Other flows and variants that you have created will be accessible by explicitly providing their flow parameters in the URL. For example, you could load a variant called beta of a flow called cancellation by specifying it in the URL:

flow.example.com/flow/cancellation/variant/beta

Note that unlike when using the bare flow.formsort.com domain it is not necessary to specify your client name when using a CNAME, as only you can publish flows on your own domain

If you create multiple domains, one of your domains will be selectable as the default domain. The domain that is chosen for this purpose will be used as the base for all other flows in your account, if those flows do not have another domain pointed directly at them.

Overview of domains, embeds, and form hosting.

We've seen, across countless organizations, a similar pattern of the life of a product form. Regardless of where you are along the lifecycle, it's useful to be mindful of it.

So you need to collect some information from your users, and are setting out to build a product form. In all likelihood, it's something that's a key part of your user experience: perhaps even the first conversation you have with a user, in the form of a sign-up flow.

Forms seem like they'd be easy to build. After all, html has supported the <form> element for ages, and you have access to some developers, so why not let them build? Particularly since your form feels pretty unique, given your organization's unique product or pitch, and the branding aesthetic you have in mind to support it, it seems that nothing off the shelf would work for this.

You get together with your designer, a couple of stakeholders, and in a couple of hours come together with a user flow - a handful of post-it notes on a wall, some presentation slides, and some copy to go alongside a design that's likely inspired by work that others have done.

You're feeling confident, this should be a quick project and then you'll be able to move on.

Since this probably isn't the only thing your company has going on, you might end up needing to wait a few days or weeks for developers to get involved. But once you're at the top of the list, you hand off the project to the developers, you provide them the content, design, as well as some wise guidance like "we'll want to test changes to this in the future" and "make sure that it's responsive", and "we might want to make parts of this dynamic".

The developers are initially excited about the project. Unlike working on backend work, or cobbling together marketing pages, this feels like something that will directly speak to users. Plus, most everyone on the team has done some variation of forms in the past, and it seems to them that they'll be able to string together a few off-the-shelf libraries to put the flow together, and they'll be done. Wise engineers will also take a little time to architect a small framework for managing form state, and it's off to building.

However, as the project is underway, they start encountering hiccups. The many existing form frameworks and validation libraries don't play well together. There's a question of what should be done on the frontend, and what should be done on the backend. You're not really sure how the flow will evolve in the future, so you eschew making complicated schemas in favor of down-the-line flexibility. Everyone starts to get a feeling of re-inventing the wheel, poorly.

As many complicated technical issues of state management, data integrity, and logic get encountered, the short initial estimates for the project timeline result in those issues being punted down the line, and some "nice to haves" get cut out as being "out of scope". Business counterparts get told: we'll be able to fix things and change them later, since we designed the system well.

After a few weeks, it's good enough, you slap in google analytics to understand what's going on, and you're ready to go live!

Everyone's excited! Your onboarding flow is live. You catch a couple of small issues but you're pretty happy with it overall, so you take a little bit of time to celebrate.

Ah… missed a couple more things, just some low-hanging fruit.

Once you're live for a few days, little issues start popping up. Not quite unexpected, but there seem to be a lot of them. Some executives complain it doesn't work on their home computers. Developers forgot to make the back button work. The inputs seem to jump around in some cases. It's hard to read some of the pages on smaller screens.

At first it seems like a lot of low-hanging fruit. But there's a lot of this low hanging fruit. You fix a few of the first problems, but then it gets hard to address the bigger issues, since the basics work after all, and inevitably the form project gets deprioritization since the company has other things to work on. After all, you're trying to run a business, not a form company.

Seems like we'll need to address some of that technical debt.

After a couple weeks, you start running into some bigger problems with the forms. You realize that it's pretty difficult to actually analyze the flow, and you'll need to redo the marketing events. Some customers start the flow, go away, and then come back later, and their experience is broken. And then a junior developer makes a small change to the flow logic, and accidentally breaks the ability to complete the signup. Minor changes seem to take on the complexity of performing surgeries, if surgeries were performed in the dark.

There's a mounting need to address some of the technical debt, but there's no time to. After all, the project is done, and you've moved on.

Turns out we didn't really understand the user.

Once the data starts coming in, and you hear from real users, it turns out, the meeting a few months ago where we sketched out the user journey wasn't entirely correct. Perhaps your product isn't suitable for a single-shot purchase, and people are re-visiting your site multiple times before converting. Or you've realized that your idealized persona of a "user" is actually dozens of different user types -- some, very experienced, technical users who just want to breeze through, while others need a bit more handholding. People care about different things, but you're putting them all in through the same flow.

People want quicker iterations. Can't we can we just test things? But the engineering time isn't focused on the onboarding flow -- changes are risky, and take a bunch of time as tests must be rewritten, logic tested manually.

Yikes, this form is a mess, as is the team that built it.

While all this is happening, the world around doesn't stop. Your organization's design and brand evolves over time. Marketing wants to try new experiences with new customer segments. Browsers, devices, and the web platform evolve in parallel. Data people want to consume more data in different ways. People start setting up landing page tools, experiment frameworks, and analytics providers, hoping that something will be a magic bullet to make the forms work well.

Organizational discontent starts to brew. Engineers don't want to make small changes to the flow, because they're risky, and they'd rather build more interesting things. But they don't have the time to do the big project of building a full out forms CMS. Executives wonder why they can't have the latest shiny thing. Marketing folks lament how difficult it is to do personalization, or just improve conversion in the first place. Product people are trying to make everyone happy, but can't.

Okay, we need to build it again, hopefully we'll get it right this time.

You end up re-building your whole onboarding. Your initial assumptions weren't correct, but this time you'll get it right. You have another series of meetings, you re-prioritize the form project, and you end up spending a couple of months building a new thing, while keeping the old thing running, making sure to also transition smoothly from the old to the new, now that dozens of poorly-documented downstream integrations and dependencies exist.

This takes way longer than the first time. And while you've addressed some of the problems with the v1, the v2 comes with its own problems. You still don't have the institutional buy-in to build a proper forms platform (after all, you're not a forms company) so you end up with another cobbled-together second system.

Guess this stuff is harder than it seemed...

By this point, you realize that this is going to be an ongoing process. Now, you've staffed a whole team of top engineers, product managers, and data people to work on your form flow. That quick project you thought would be done in a few weeks is now a line item in your staffing budget. It's costing you hundreds of thousands of dollars, yet it feels like it's moving slower than ever before.

Build and iterate on your form flows quickly.

Integrate directly with your data and analytics.

Extend when needed, use best practices when you don't.

Stay confident with schemas and logic validation.

Don't worry about keeping up to date on web trends.

Focus on the content of your user journey, not how it's made.

Forms are the center of many technical and organizational problems

Often, you'll already know something about a responder before they even start filling out your form flow.

Avoid repetition and personalize the responder's experience by pre-filling form answers. Formsort supports three 

Formsort supports 3 methods of passing data into form flows:

The easiest way to pre-populate forms with existing answers is to pass them directly in the URL, using the query string. The query string appears at the end of the URL's pathname (but before a hash). It begins with a ?, and is followed by a number of key and value pairs, each separated by an & and joined with a =.

Example URL     https://flow.formsort.com/client/formsort/flow/onboarding/variant/main?email=hello%40formsort.com&name=Fil#0
Host            https://flow.formsort.com
Pathname        /client/formsort/flow/onboarding/variant/main
Query string    ?email=hello%40formsort.com&name=Fil
Hash            #0

For each value that you wish to set, use the Answer variable name as the key, and the value you wish to set as the value.

Safe and easy generation of the query string

The query string is part of the URL, and its components need to be url-safe. Characters list spaces, ampersands, and others cannot appear in URLs, and so need to be escaped. This is why in the above example hello@formsort.com actually appears as hello%40formsort.com: it has been percent-encoded.

If you're generating the URL to redirect to in javascript, make sure to use the encodeURIComponent() method on each part that you're encoding. Similar functions exist for other languages.

If you're using the Formsort preview window, you can also set answers and see the generated URL using the Set answers... dialog.

If you aren't seeing your answers pre-populate, check your browser's javascript console. It may be the case that you have typoed the variable name or have formatted the value incorrectly.

There is no single standard for setting multiple values (eg, a select question that allows choosing multiple values). Formsort handles this by allowing you to repeat the answer key.

If you have a variable named favorite_fruits and want to pre-set it to both Apple and Banana, the query string should look like this:

?favorite_fruits=Apple&favorite_fruits=Banana

When adding or editing a domain under which you will be hosting flows, you may set a default query string using the Default URL params field.

This is useful if you want to parametrize a flow based on what URL a responder is accessing it from, without needing to include URL parameters in every usage of that URL. For example, if you have a flow that contains a variable named country, you can set up one domain called fr.example.com with Default URL params set to ?country=France and another domain called es.example.com with Default URL params set to ?country=Spain and those answers would be pre-set when accessing the flows, even if accessing the bare URL without any query string.

Note that default query strings don't actually appear in the URL, but are merged with any query string that does appear in the url. Answers appearing in the URL take precedence over those set in the default.

Consideration: personally-identifying information (PII)

As part of the loading sequence, and before loading any third-party analytics, Formsort strips any values that correspond to semantically-labeled answers (such as responder_email or responder_first_name), or answers that have been marked as Don't send to analytics from the URL.

This is because many third party analytics scripts will happily log the URL of an event, and since the query string is part of the event, you may be sending PII to third parties if the answer were not stripped.

Url modification is an imperfect solution

While the query string approach is the easiest way to pre-populate data into Formsort, there's always a risk of leaking information with URLs (for example, browser extensions that load before Formsort and report which URLs they are loaded on.

When working with particularly sensitive data, we recommend using either cookies or POSTing answers, described below.

Cookies are text data that websites can store in your browser, which your browser sends back to servers, as a way of persisting data.You can use cookies to pass values into Formsort flows.

For security, browsers do not send cookies acrossdomains: flow.formsort.com cannot access or write cookie data on the example.com domain.

This restriction does not apply to subdomains, however: survey.example.com can read and write cookies from the example.com domain just fine.

Enable Read/write in cookie in the schema editor for the answers you wish to read and write using cookies.

Write a cookie, on your root domain, with a key of the variable name and a value of the answer for each answer you wish to pass forward.

If, in the course of filling out the flow, the responder changes their answer for one of the cookie-enabled answers, the cookie will be updated with the new answer.

One of the most secure ways of passing data into a Formsort flow is to POST into the form.

Normally, when you navigate to a flow URL, your browser does a GET request to our servers. GET requests do not have a payload (known as a body): when making a link, the only way to pass information to the receiving page is using URL parameters, as described above. Since the parameters appear in the URL, they are visible to not only the responder but potentially to other scripts or browser extensions that you or the responder has loaded on their flow.

A POST request, on the other hand, has an encrypted body, and is the default way to submit form data in basic HTML. Formsort supports POSTing to the flow URLs are well as GET. A form like the following would ask the responder for a name answer, then submit it to the Formsort URL. Note that we set the name attribute to match the Answer variable name value we've defined in the flow.

~~~html~~~
<!doctype html>
<html>
  <body>
    <form action="https://flow.formsort.com/client/formsort/flow/test/variant/test-post" method="POST">
      <label for="first_name">Enter your first name</label>
      <input type="text" name="first_name" required />
      <button type="submit">Let's go</button>
    </form>
  </body>
</html>

If you don't actually want to ask questions before redirecting to formsort, that's not a problem: just set all of the answers you wish to pass forward within the value attribute of <input> elements with type=hidden, like this:

~~~html~~~
<input type="hidden" name="first_name" value="Olivia" />

When the containing <form> is submitted, the answers will come along for the ride, just as if the responder has entered them.

Different ways to provide information about a responder ahead of time.

Conceptually, you can think of a table in a columnar relational database such as Redshift as similar to a spreadsheet.

The table's schema determines which columns are present, and what the types the values in those columns should take.

Date              Name              Age
--------------------------------------------------

A database can enforce that dates are formatted as dates, and much more.

When data is written into the table, rows are created, which you can think of as new rows in a spreadsheet.

Date              Name              Age
--------------------------------------------------
12/09/2019        Olivia            4
12/09/2019        Stubby            7

While Formsort flows also have schemas, those schemas can change over time, as new questions are added in order to collect new answers. To prevent needing to update the Redshift database columns every time a new answer is collected, answers are written into a single column, answers, in a data format known as JSON.

JSON allows us to express objects that contain multiple values, which are referenced by their keys. So instead of needing multiple columns for the above examples, the single answers column would contain the values all together.

date              answers
--------------------------------------------------------------
12/09/2019        {
                    "name": "Olivia",
                    "age": 4
                  }

12/10/2019        {
                    "name": "Stubby",
                    "age": 7
                  }             

Note that while every row will have the same columns, not every row might have the same set of keys and values. For example, if we start asking users for their birthday, the answer to that question will only be present in the dataset from that point on.

date              answers
--------------------------------------------------------------
12/09/2019        {
                    "name": "Olivia",
                    "age": 4
                  }

12/10/2019        {
                    "name": "Stubby",
                    "age": 7
                  }

12/11/2019        {
                    "name": "Rosie",
                    "age": 10,
                    "birthday": "02/13/2009"
                  }         

To get answers out of the JSON column, you'd use the standard SELECT statement that you may be familiar with.

~~~sql~~~
SELECT
  answers
FROM
  formsort.answer_set

But if you merely select answers, you'll get a blob of text containing the JSON object, which isn't easy to use for direct analysis:

{
  "name": "Olivia",
  "age": 4
}

{
  "name": "Stubby",
  "age": 7
}

{
  "name": "Rosie",
  "age": 10,
  "birthday": "02/13/2009"
}

To reach into answers you'll want to use a function called json_extract_path_text instead, telling the database which key we want from answers using the second parameter, in this case, 'name'.

~~~sql~~~
SELECT
  json_extract_path_text(answers, 'name') AS name
FROM
  formsort.answer_set

You can also select multiple answers out at once by repeating the fields you'd like to select out.

~~~sql~~~
SELECT
  json_extract_path_text(answers, 'name') AS name,
  json_extract_path_text(answers, 'age') AS age
FROM
  formsort.answer_set

name          age
-------------------
Olivia        4
Stubby        7
Rosie         10

Omitting rows without particular answer values

As mentioned earlier, when new answers are collected in a flow, they will only appear in the answers column from that point on. The behavior of json_extract_path_text is to return the empty string when a value is missing, so we can use that in a WHERE clause to filter out rows where a particular answer is not set.

~~~sql~~~
SELECT
  json_extract_path_text(answers, 'birthday') AS name,
FROM
  formsort.answer_set
WHERE json_extract_path_text(answers, 'birthday') != ''

Sort of a blog

Form deployment options

Pitfalls of building your own form flows

Passing data into form flows

Finding answers inside of Redshift JSON columns