Skip to main content
Product11 min read

906 - Pages people open

An application answers a browser at an address of its own: a page endpoint, static files pinned by the release, the application’s endpoints, and a record of who is signed in. Who may open each page, how a viewer signs in, how a page’s script is held to its own origin, how a public storefront and a portal report reach the application, and how one environment of a site becomes a part the release moves.

What you will take away from this lesson

Lesson 701 drew a hard line: an endpoint answers with data, and whatever it returns is shown as an inert document. That line protects the portal, and it stays. An application gets something more: an address of its own, separate from the portal, where its pages run as real web pages. The tool the agent builds for the warehouse team, the suppliers or the customers opens like any other web application, at its own address, with the sign-in your organization already uses.

This lesson gives the shop a storefront page, shows who can open it and what the shop learns about them, and then joins a website’s environment to the application so that the site and the system behind it are released together.

Learning Objectives

  1. 01Say what answers at an application’s own address, path by path.
  2. 02Bind an endpoint as a page and read the handler that serves it.
  3. 03State the rules that hold a page’s script to its own origin, and why they make pages safe to run.
  4. 04Describe how a viewer signs in on an application’s address and what the application learns about them.
  5. 05Say how a public storefront and a portal report reach the application’s endpoints.
  6. 06Make one environment of a site a part of an application, and say what a release and a rollback do to it.

Where this lesson sits

The shop is released, and its storefront is a portal asset. This lesson gives the application a face of its own: pages at its own address, and a website as one of its parts.

900 Series: Applications

Open index

The 900 series assembles what the 600 series and the 700 series taught one part at a time: automations, endpoints and forms become one application with a database of its own, released as a whole.

An address of the application’s own

Every application answers a browser at an address named for it, apart from the portal. Four kinds of path answer there.

What answers at the application’s address

/

and paths under it

The page endpoint named after the application. For the shop, the storefront. A page whose path ends in a catch-all, such as /{route...}, answers every path the platform does not reserve, and the handler reads the rest of the path to route it, so one page can serve a whole single-page application.

/endpoints/<name>/...

Any endpoint of this application: the shop’s API and its checkout. The page’s own script calls them here.

/_static/<asset name>

An asset part, served at the version the release pins: the storefront’s stylesheet, its script, its images.

/_viewer

Who is signed in on this address, as JSON: their email, id, persona and name. It carries nothing signed and no cookie.

Nothing else answers there. A request to the application’s address never reaches a portal, admin or agent route, and the address never sees a portal session. That separation is what makes it safe to run a page’s script.

Making an endpoint a page

A page is an endpoint with one more setting. The agent writes the handler and an administrator binds it.

Binding the storefront as a page

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_script
  {
    "command": "endpoint_set",
    "name": "shop-storefront",
    "endpoint": "shop",
    "response_mode": "page",
    "methods": ["GET"],
    "path": "/",
    "auth_mode": "authenticated",
    "callers": ["shop-customer"],
    "page_cdns": ["https://cdn.jsdelivr.net"]
  }

← {
    "endpoint": "shop",
    "enabled": true,
    "response_mode": "page",
    "message": "shop-storefront now answers GET as a page at the
                application's own address."
  }

One setting makes an endpoint a page: response_mode: "page". The automation must be a part of an application, because the address belongs to the application. The page endpoint is named after the application, which is how it comes to answer at the root. page_cdns lists the outside libraries the page may load, here a charting library’s host.

The storefront page

The handler answers with HTML that loads the shop’s own stylesheet and script.

shop-storefront, the page handler

def handle(req):
    """Answers the storefront page."""
    body = (
        "<!doctype html>" +
        "<link rel=stylesheet href=/_static/shop.css>" +
        "<main id=shop></main>" +
        "<script src=/_static/shop.js></script>" +
        "<script nonce=" + req["csp_nonce"] + ">startShop()</script>"
    )
    return {
        "headers": {"Content-Type": "text/html; charset=utf-8"},
        "body": body,
    }

The handler returns HTML. The stylesheet and the script are asset parts loaded from /_static, so they are versioned, pinned and rolled back with everything else. The one inline script carries the nonce the platform issued for this response. In the browser, shop.js fetches /endpoints/shop/products and draws the catalog.

What a page is able to do

A page that runs script is powerful, so the platform fixes its limits in the browser itself.

How a page’s script is held

  1. 1

    A page loads from its own address and the hosts it listed

    The platform builds a content policy for each page binding. Scripts and styles load from the application’s own address and from the hosts the binding names, and from nowhere else.

  2. 2

    An inline script runs only with the response’s nonce

    The handler reads the nonce from the request and writes it on the script. A script without it does not run, and the browser’s console says so. Inline style is allowed.

  3. 3

    A page talks to its own application and the origins its binding names

    Requests from the page’s script go to the page’s own address, plus any https origins the binding lists for calls, frames and form posts, such as a partner’s API. The browser refuses everything else, so a page cannot be turned into a way to reach another system from a visitor’s browser.

  4. 4

    The portal is out of reach

    The application’s address is a different site from the portal as far as a browser is concerned. A page’s script cannot read the portal, act as the signed-in person there, or see their session.

  5. 5

    The same endpoint on the portal’s address stays inert

    Called at the portal’s own address, a page endpoint answers as any endpoint does: an opaque document that runs nothing.

The agent writes the page. The platform decides what the page is able to do. An agent-written page that tried to load a script from an unlisted host would simply not load it.

Who is viewing

An application that serves people needs to know who they are, and must never have to take their word for it.

Who is viewing

Sign-in

A page that requires sign-in sends a browser with no viewer through your organization’s sign-in once, and returns it to the page it asked for.

A session of the application’s own

The application’s address then holds its own cookie, scoped to this application, good for 12 hours. It is not the portal’s session and cannot be used as one.

Cookies of the application’s own

A handler reads and sets cookies under a prefix no platform cookie uses, for a cart or a preference. A write from another site carries none of them, and their values are kept out of the audit record.

What the handler knows

The handler reads the viewer as req["caller"], found by the platform, never taken from the request. The page’s script reads the same person from /_viewer.

Calls run as the viewer

When the page’s script calls the application’s endpoints, each call runs as the signed-in person. The shop’s orders endpoint returns that customer’s orders because the policy from lesson 902 sees that customer’s email.

Browsers only

API keys are not honored on an application’s page address; a partner system calls the endpoint at its ordinary address, as in lesson 702. A POST from the page’s own script is accepted, and one from any other site is refused.

A page chooses its audience with the same three access modes every endpoint has, from lesson 702: signed-in people in the personas it names, anyone, or anyone who passes a bot check. The shop’s storefront requires sign-in; a public catalog page would not. An endpoint can also cap the requests each visitor’s address may make, so one client cannot flood a public checkout.

Public pages, and reports that call the application

After the first page, the two most common requests are a storefront the public uses and a portal dashboard that reads the application as the person viewing it.

Public pages, and reports that call the application

A public storefront

a site that calls the application

The platform documents for the agent how to build a shop the public uses: a site on your own domain calling the application’s JSON endpoints, with a cart kept in an application cookie, single-use sign-in links for returning customers, confirmation mail with a scheduled re-send, and limits per visitor address. The agent builds it from that page’s own steps.

A report that calls an endpoint

an HTML asset in the portal

A dashboard or report declares an endpoint and calls it from the page as the person reading it, with a viewer token and never a credential. Only the endpoint’s owner or an administrator declares an endpoint that needs a sign-in, and a public link’s copy calls it as nobody.

A single-page application

one file, every route

A page with a catch-all path answers every route at the application’s address. A site does the same with a redirect rule of status 200, which answers a path with one of the site’s own files.

Each one reaches the application through its endpoints, so the policy that hides one customer’s orders from another holds whichever page asks.

A website as a part

A page endpoint suits an application’s working screens. A full website, with many pages and its own releases, is a site, and one of its environments can belong to the application.

A site’s environment as a part

What the agent calls. This is the exchange the agent has with Plexara on your behalf, shown for the technical reader. You ask in plain language; you never type any of it.

→ manage_application
  {
    "command": "add_part",
    "application": "shop",
    "kind": "site",
    "part_id": "acme-store/prod"
  }

← { "name": "shop", "current_release": 3,
    "parts": [ ..., { "kind": "site", "id": "acme-store/prod" } ] }

→ manage_application
  { "command": "get", "application": "shop" }

← { "pending": [
      { "kind": "site", "part_id": "acme-store/prod", "from": 0, "to": 12 }
    ],
    "problems": [] }

A site is a set of web pages with environments and releases of its own, the subject of the 1000 series. One environment of a site can be a part of an application. The next release of the shop points that environment at the release the environment before it serves, one step as a promotion would, and a rollback of the shop restores the one it served before.

A site and an application cannot share a name, since each answers at an address built from its name, so the shop’s website is a site called acme-store.

A site named marketing in the portal's Sites section: an explainer with three steps, Changes land in dev, Promote one step at a time, and Only a domain you make public opens for anyone, and three environment cards, dev, stage and prod, prod marked Public domain and Requires approval, each with the release it serves and its addresses.
A site’s environments. One of them, typically the one people use, can be a part of an application, so the application’s release decides which site release it serves.

What joining changes

Four things follow from making the environment a part.

What changes when a site joins an application

  1. 1

    The site and the system release together

    A website that shows a new product field and the API that returns it go live in the same release. Neither can be ahead of the other.

  2. 2

    The site’s addresses serve the application’s endpoints

    Every address of that environment, its own and any domain on it, also answers the application’s endpoints at /endpoints/<name>. At a private address they run as the signed-in person, and at a public domain as nobody. The site’s pages call the shop, and its cart cookie, without any cross-site arrangement.

  3. 3

    Public endpoints answer the application’s own sites

    A public or bot-checked endpoint answers the sites its application holds without those sites being listed on the binding, and a public form may be framed by them.

  4. 4

    One way back

    Rolling the application back restores the site environment with the automations and the schema. The website never shows a button whose endpoint was just rolled back.

A name your customers know

Key terms

Five terms cover what an application shows a browser.

Key Terms

Page
An endpoint of an application bound to answer as a working web page at the application’s own address, under a content policy the platform builds for the binding.
Application address
The address an application answers a browser at, separate from the portal. It serves the application’s page, its endpoints, its pinned static files and who is signed in.
Nonce
A one-time value the platform issues with each page response. An inline script runs only when it carries it.
Viewer
The person signed in on an application’s or a site’s address, identified by the platform and handed to the handler as the caller.
Site part
One environment of a site held as a part of an application, pointed by each release at the release of the environment before it, and restored by a rollback.