Build and publish a portal

This page takes you from an empty portal register to a live portal in one sitting: create the site, open it to the right visitors, publish the data its pages read, add and publish the pages, publish the site, invite signed-in members and check the result as a visitor. The order below avoids backtracking. What a portal is, and the three publishing gates that decide what visitors see, are explained on xMatix Portals; this page is the hands-on build.

Overview

A working portal needs four things, and each has its own explicit switch:

• The site — created in the portal register, then Published and Active. A new portal is neither open to anonymous visitors nor published.
• Data views — each one publishes a single entity view (its columns and base filter) to this portal. They are the only general way an authored page can read records.
• Pages — addressed by path. A page is served only after Publish draft.
• Members — the external people who can sign in, needed only for pages and data views with the Authenticated users only audience.

When to use it

Use this procedure when you set up a new portal, or rebuild one from scratch in a sandbox before repeating it in production. To change one part of a running portal, go straight to the page that owns it: Portal pages and data views for content, Publishing, hostnames and custom domains for the address, Portal visitors, signup and identity for sign-in.

How xMatix handles it

• Creating a portal exposes nothing. It starts Active, unpublished (State: Draft) and sign-in only (Anonymous: Sign-in only).
• Site settings are live on save. Label, description, switches, theme and navigation apply to the published portal as soon as you click Save on General.
• Only the page layout waits for publishing. A page's draft layout is served only after Publish draft. Its path, audience, embed target and SEO, and every data-view setting, apply as soon as you save them.
• A public data view opens a read grant. Publishing a data view with the Public audience gives the shared Portal Anonymous profile read access to that entity; the view's columns and base filter still limit what visitors reach. Authenticated views run as the signed-in visitor, under that person's own record security. See How portal security works.
• Publishing the site registers its address. The platform hostname is the portal slug and your organization's slug joined by a hyphen, under the platform's portal domain. It appears in the page header as Address.

Prerequisites

• The Manage portals capability (setup.portals.manage) on your security profile.
• The Portals product licensed for your organization, and Enable Portals switched on at Setup → Feature Hub → Portals → Settings (on by default).
• The entity views you want to publish already exist, with the columns and base filter you are willing to expose. Shape them first in Setup → Design Studio → Entities → the entity → Experience.
• A slug for the portal: lowercase letters, digits and hyphens, starting and ending with a letter or digit, up to 63 characters. It becomes part of the portal's hostname, so choose it like a domain name.
• For a signed-in area: the contacts you will invite, each linked to the account (customer or partner) they work for.

Procedure

Step 1 — Create the portal

Open Setup → Feature Hub → Portals → Portals and click New in the page header. In the New portal dialog, enter a Label (for example "Customer Store"). The Slug (portal hostname label) fills in from the label until you edit it yourself. Click Create.

The portal opens on its detail page. The header shows the portal name, its Address marked Draft, and the statistics State (Draft), Active (Yes), Anonymous (Sign-in only), Pages, Data views and Version. Below are four tabs: General, Pages, Data Views and Members, and Publish sits in the page header.

Step 2 — Configure the site

On General:

1. Write a Description. Visitors see it in the portal footer; without one, the footer shows the label.
2. Set the switches:
   • Anonymous visitors — switch it on for any portal the public should see. While it is off, everyone who is not a signed-in member of this portal gets "not found", even on Public pages.
   • Self-service signup — lets visitors create their own external account; they get an email to set a password.
   • Create customer on signup — signup also creates a customer Account and Contact linked to the new user. Leave it on for a customer or commerce portal; switch it off for a careers portal.
   • Learning, Careers and Challenges — switch these on only for a partner learning portal, a careers site at /careers, or sales-challenge share links at /challenge/<code>. Careers and Challenges need the HR product, and Challenges also needs Anonymous visitors.
3. Optionally expand Advanced (JSON): theme, navigation, settings. A theme looks like {"tokens": {"primary": "#1d4ed8", "text": "#1f2937", "border": "#e5e7eb", "headerBackground": "#ffffff"}}. A header menu looks like {"header": [{"label": "Products", "path": "/products"}, {"label": "Contact us", "url": "https://example.com/contact"}]}. Leave Navigation empty and the menu is built from the published pages in their Order.
4. Click Save. You see "Portal saved", and Version goes up by one.

Step 3 — Publish the data views

Open Data Views and click Publish Data View. In the dialog:

1. Enter a Label (for example "Products").
2. Pick the Entity, then one of its View entries. The view's columns and base filter bound everything the portal can read through this data view.
3. Choose the Audience: Public (anonymous + signed-in) for catalogue-style data everyone may read, or Authenticated users only for "my records" data.
4. Set Page size cap — rows per request, 50 by default, from 1 to 250.
5. Click Publish. You see "Data view published", and the row shows Active.

Repeat for every list the portal needs. Before you publish a Public view, read its columns and filter as if you were a stranger: a public view grants read access on the whole entity to the anonymous visitor profile. Each data view also gets an internal name, made from the portal's internal name and the data view's label (for example customer-store-c-products). You need that name in Step 5; how to find it is in Portal pages and data views.

Step 4 — Add the pages

Open Pages and click Add Page. Enter:

• Label — the page name, also used for the menu when Navigation is empty.
• Path — the site-relative address: / for the home page, then /products, /my-orders and so on.
• Page type — Designed page (a layout) or Entity list embed (one data view as a paged table). Entity detail embed and App page embed can be chosen, but the portal does not render their target, so use them only with a layout.
• Audience — Public (anonymous + signed-in) or Authenticated users only.
• Order — the menu position.

Click Create. You see "Page created", and the page is listed with Published showing Empty. Add the home page at / first: a portal with no published page at / answers "not found" at its root address (unless it is a storefront or learning portal, which serve their own home there).

Step 5 — Give each page its content

Click the page's name (or Edit in its row) and expand Content (JSON): draft layout, embed target, SEO:

• For an Entity list embed page, leave Draft layout empty and set Embed target to the data view's name, for example {"dataView": "customer-store-c-products", "title": "Our range"}.
• For a Designed page, paste the layout into Draft layout.
• Optionally fill Description and SEO.

Click Save. A page with a draft layout now shows Draft. The embed target and SEO already apply to the live page if it is published; the draft layout does not. The full rules for page content are in Portal pages and data views.

Step 6 — Publish each page

In each finished page's row, click Publish draft. You see "Page published", and Published shows Published. Publishing copies the current draft layout as the served version; later edits stay in the draft until you click Publish draft again. Unpublish in the same row takes one page off the portal.

Step 7 — Publish the site

Click Publish in the page header and confirm ("The portal becomes servable; only published pages and data views are visible to visitors."). You see "Portal published". State changes to Published, the Draft tag beside Address disappears, and the header button becomes Unpublish. The address works without any DNS work; to serve the portal on your own domain, see Publishing, hostnames and custom domains.

Step 8 — Invite members (signed-in areas only)

Skip this step if the portal has only Public pages. Otherwise open Members and click Invite a contact:

1. Search for the Contact by name or email. The contact must belong to an account.
2. Fill Email only when the contact's email on record is missing or wrong.
3. Leave Send the set-password email now on to send the invite straight away, or switch it off to hold it back.
4. Click Invite.

The member's Login shows Invite sent (or Invite held back) until their sign-in account has been set up, then On. Turn on in the row sends a held-back invite; Turn off stops the person signing in and keeps their records. Visitors can also join through Self-service signup. See Portal visitors, signup and identity.

Step 9 — Check it as a visitor

Open the Address in a private browser window, so your own session does not count:

1. The menu lists the published pages (or your navigation).
2. Every Public page opens, and each list shows only the columns and rows of its data view.
3. Opening an Authenticated users only page sends you to the sign-in screen.
4. Sign in as an invited member: the signed-in pages open, and "my records" lists show only that member's rows.

If the address answers "not found" straight after publishing, wait a minute and retry: an address that was looked up before publishing can stay cached as "not found" for up to 30 seconds.

Fields

This page uses the fields of four dialogs. Each is described in full on the page that owns it:

Business rules

• New portals start closed. Active on, unpublished, Anonymous visitors off. Nothing is served until you publish, and anonymous visitors see nothing until you also switch Anonymous visitors on.
• Slugs are checked on save. Invalid: "Slug must be a valid DNS label (lowercase letters, digits, hyphens; max 63 chars)." Reserved (for example www, api, admin, app, portal, login): "This slug is reserved." Already used by another portal: "A portal with this slug already exists."
• Paths are unique per portal. A path is stored with a leading slash and no trailing slash; it cannot contain //, .., ? or # or exceed 400 characters ("A valid site-relative path is required."). A duplicate is refused with "A page with this path already exists on the site."
• The module switch blocks authoring. While Enable Portals is off, creating a portal, publishing a portal, adding a page and publishing a page are refused with "The Portals module is disabled for this organization.", and every portal answers "not found".
• Publishing the site does not check its content. You can publish a portal with no pages; its address then answers "not found".
• Version counts changes. It goes up on every site save, site publish or unpublish, and page publish or unpublish.
• The address is registered at publish time. After changing the slug of a published portal, click Unpublish and then Publish so the new address is registered.

Example

A distributor wants a public product range for shoppers and a signed-in order history for its retail customers.

1. The administrator opens Setup → Feature Hub → Portals → Portals, clicks New, enters Customer Store, keeps the slug customer-store and clicks Create.
2. On General they enter "Our range and your orders, in one place", switch Anonymous visitors on, leave Self-service signup off (customers are invited) and click Save.
3. On Data Views they publish Products (Item, an "Active items" view with name, description and price, Public, cap 50) and My orders (Order, a "My orders" view, Authenticated users only, cap 25).
4. On Pages they add Home at / (Designed page, Public, order 0), Products at /products (Entity list embed, Public, order 1) and My orders at /my-orders (Entity list embed, Authenticated users only, order 2).
5. They set the embed targets to {"dataView": "customer-store-c-products"} and {"dataView": "customer-store-c-my-orders"}, paste a simple layout into Home's Draft layout, and click Publish draft on all three pages.
6. They click Publish, then on Members invite a contact from one retail customer.
7. In a private window, the menu shows Home, Products and My orders. Products lists items, and My orders sends them to sign in. Signed in as the invited contact, My orders shows only that customer's orders.

Training

Practice exercise

In a sandbox, create a portal called Training Portal, switch Anonymous visitors on and save. Publish one Public data view of any entity. Add a Designed page at / and an Entity list embed page at /list whose Embed target names your data view. Publish both pages, then the site, and open the address in a private window. Then click Unpublish on the /list page and reload it.

Expected result: the register shows Training Portal as Published, Active and Allowed, with 2 pages. The menu lists both pages and /list shows a paged table. After you unpublish /list, it disappears from the menu and its address answers "not found", while / still works.

Quick reference

• Register: Setup → Feature Hub → Portals → Portals → New.
• New portals are sign-in only: switch Anonymous visitors on for a public portal.
• Build order: site → data views → pages → page content → Publish draft → Publish → members → check.
• Always add a page at /.
• Entity list embed + {"dataView": "<name>"} in Embed target gives a paged table.
• Only the draft layout waits for Publish draft; everything else is live on save.
• A Public data view grants the anonymous profile read access to the entity.
• Check the portal in a private window, never in your administrator session.

Permissions

Without Manage portals, Portals does not appear under Feature Hub and the portal screens refuse access. Full detail: xMatix Portals — Permissions.

Configuration

Common problems

The address answers "not found"

Check the header statistics in order: State is Published, Active is Yes, Anonymous is Allowed (or you are signed in as a member), there is a published page at the path you opened (/ for the root), and Enable Portals is on. If you changed the slug after publishing, unpublish and publish again. More checks: Troubleshooting portals.

A page says "has no published content yet"

The page has no published layout and is not an Entity list embed with an Embed target. Add the layout or embed target, then click Publish draft again — it was probably published while the draft was empty.

A list shows "Data view failed (404)"

The Embed target names a data view that does not exist on this portal or is inactive. Check the name exactly, including any -c or -2 part, and that the data view's Status is Active.

"Draft layout is not valid JSON." (or Theme, Navigation, Settings, Target, SEO)

The text in that box is not valid JSON. Check quotes and commas, or empty the box to clear the setting.

"The Portals module is disabled for this organization."

Enable Portals is off. Switch it on at Setup → Feature Hub → Portals → Settings, or ask an administrator with the Feature Hub settings capability.

The Address is missing from the header

This environment has no portal hostname configured, so no address can be built. Publishing still works; serve the portal on a custom domain or contact xMatix support.

Common questions

Why is my new portal not visible even after publishing?

Most often, Anonymous visitors is still off. A new portal is sign-in only, so a private browser window gets "not found" on every page until you switch Anonymous visitors on and click Save. The next most common cause is a missing home page: if no published page has the path /, the root address answers "not found" while /products and other published paths work. Check both before anything else.

Do I have to publish the data views separately from the pages?

Data views have no draft: a data view serves as soon as you create it and while it is Active, but only once the site itself is published. Pages are different, because their layout waits for Publish draft. That is why the procedure publishes the data views first: the pages that embed them work the moment you publish them. To pause a data view, use Activate / deactivate in its row.

Can I build the portal while it is live?

Yes, with care. Draft layouts are safe to rework, because visitors keep the last published version until you click Publish draft. Everything else — a page's path, audience or embed target, a data view's view or audience, and the underlying entity view — changes the live portal the moment you save. For bigger changes, unpublish the page or deactivate the data view while you work, or build in a sandbox first.

How do I take the portal offline again?

Click Unpublish in the page header and confirm. The portal stops being served to every visitor immediately, and its pages, data views, members and settings are kept, so Publish brings it straight back. Switching Active off on General has the same effect without changing the publish state. Delete in the register removes the portal for good; see xMatix Portals.

Related topics

• xMatix Portals — the register, the publishing gates and every site field
• Portal pages and data views
• Publishing, hostnames and custom domains
• Portal visitors, signup and identity
• How portal security works
• Troubleshooting portals
• Portal storefronts
• Portals on the xMatix site