Sneak peak at the Portal Builder in 10.2

[jstanden]

Introduction to the Portal Builder

For the past several years we've been migrating away from using plugins for customization. Creating a plugin requires a decent amount of experience with writing PHP code. Maintaining plugins requires constant testing so they continue to work with new platform updates. Plugins are also not a good fit for cloud-based deployments -- they don't scale well (divergent environments), and we have to manually audit and verify all third-party code before deploying every update.

Instead, we've been building functionality for creating customizations entirely within the browser. That started with bot behaviors, and it was recently significantly improved with the release of automations.

It's time to finally bring this mindset to community portals.

In the upcoming Cerb 10.2 update we're working on a Portal Builder. This will replace the built-in Support Center and bring many long-requested improvements to community portals.

The Support Center has remained relatively unchanged for the past 10 years. Meanwhile, we've introduced many new major building blocks on the worker side: custom workspaces, custom records, sheets, data queries, KATA, automations, interactions, toolbars, connected accounts, SSO, etc.

The goal is to use these same building blocks to enable you to quickly build and share a wide variety of customer-facing tools: contact forms, surveys, signups, troubleshooters, knowledgebases, FAQs, Q&As, discussion forums, mailing lists, blogs, bug trackers, accessible UIs, and more.

Identities

The Support Center used contact records for portal logins. Contacts were grouped into organizations.

This created problems for companies who manage multiple portals for each brand. A contact created for any portal could be used to log in to any of them.

It also required users to keep track of yet another login/password.

The Portal Builder introduces identities for logging in to portals. Identities are grouped into pools, which can be isolated or shared between portals. The same person could have different identities on each portal, specific to their interactions with that brand, with their own custom fields and preferences.

All portal logins are now based on single sign-in (SSO) functionality using OpenID Connect. This means you can refer to identities in existing identity providers (IdP) -- Azure Active Directory, AWS Cognito, Okta, GitHub, LinkedIn, etc.

If you have an existing identity provider, those logins will "just work", and once user consent is given, the portals will be able to refer to profile data (profile photo, name, email, etc). Any form of multi-factor authentication is available here (one-time codes, biometric, dongles), and you can manage your password policy.

If you don't have an existing identity provider, we're also shipping a new Identity Provider portal in the 10.2 update. This portal allows new account registration, manages profile data, and verifies logins with multi-factor authentication. It can be used as the provider for any portal or service. We'll make it easy to convert your contact logins to an identity pool.

We'll also be using identity providers to allow bots to verify who they're talking to before performing privileged actions.

This was one of the most heavily requested features in the Support Center.

Routes, pages, and widgets

The Portal Builder describes a web-based application entirely in KATA. That means there are no records for portal pages or widgets.

Routes are rules based on the attributes of an HTTP request (verb, host, path, query, identity, browser) that determine which page to show in response. You can define many routes, and the first match for a given request is used.

There are several types of pages:

• Text pages simply display Markdown formatted content. This is useful for static pages like "About Us" or a privacy policy.
• Interaction pages start a full-screen portal interaction. This is useful for surveys, troubleshooters, and contact forms.
• Dashboard pages display any number of "widgets" in a flexible layout. This is useful for dashboards (obviously), profile pages, and reports. There is more info about widgets below.
• Automation pages are the most interesting. They run a portal.page automation which can return any other page type. For instance, you could load a customer record and generate a personalized dashboard based on their specific account type.

There are currently two widget types:

• Text widgets display Markdown formatted content.
• Interaction widgets provide multi-step dynamic interactions from an interaction.portal automation. An interaction can display any combination of form elements (text input, choosers), sheets, maps, charts, and more. For instance, a sheet interaction provides searching, paging, and sorting functionality.

As KATA, any element of a portal (including the entire portal itself) can be generated "on the fly" by an automation.

For instance, when a client writes in by email, and their intent is detected by a classifier, your auto-reply can include a link to gather other necessary details based on that issue type (software versions, language, etc). By the time your workers review the issue, a bot has already gathered everything they need.

Layouts

Portal pages can have various layouts. A layout is a combination of header, footer, and style/theme.

Headers and footers are built using layout widgets:

• Text layout widgets display Markdown formatted content: logos, links, etc.
• Menu layout widgets display nested navigation menus.

All pages and widgets can be targeted individually with a custom stylesheet.

By default, the portal builder has a minimalistic style so you start with a clean slate.

Portal builder layouts are also responsive -- they automatically adapt to different devices (desktops, laptops, tablets, smartphones).

Portal users will also be able to toggle themes, like light/dark mode.

Portal resources

The portal builder also introduces portal resources.

When creating portal layouts, pages, and widgets, you often need to bring your own resources -- images, icons, fonts, etc.

Previously, the Support Center used attachments for files and images in the knowledgebase. This wasn't ideal from a security standpoint, because attachments also included private files from clients. There were security checks, but a future bug shouldn't be able to create a vulnerability.

In 10.2+, these files can be uploaded as portal resources instead, where they are isolated from private customer data.

As well, anywhere you'd use a URL (like an image source) you can use a Cerb URI (cerb:portal_resource:example.png), which will automatically generate a URL for the current portal. This makes it seamless to reuse resources between portals, or between a portal and the worker interface.

For instance, managing images on knowledgebase articles.

Example

Let's look at a quick example. Keep in mind that this example intentionally uses a basic default style. You would choose or create a theme.

Here's a portal that replicates the legacy Support Center.

routes:
  page/home:
    disabled@bool: {{request_path not in ['', 'home']}}
  page/login:
    disabled@bool: {{request_path|split('/')|first != 'login'}}
  page/announcements:
    disabled@bool: {{request_path != 'announcements'}}
  page/contact:
    disabled@bool: {{request_path != 'contact'}}
  page/kb:
    disabled@bool: {{request_path != 'kb'}}
  page/privacy:
    disabled@bool: {{request_path != 'privacy'}}
  page/history:
    disabled@bool: {{not identity_id or request_path != 'history'}}
  page/historyTicket:
    disabled@bool: {{not identity_id or request_path is not prefixed ('history/ticket/')}}
  page/404:

pages:
  text/404:
    content@text:
      # Whoops!
      The page you're looking for doesn't exist.
  login:
    disabled@bool: no
  automation/assets:
    uri: cerb:automation:wgm.portal.page.sc.assets
  text/home:
    content@text:
      # Welcome
      This is a custom template.
  text/privacy:
    content@text:
      # Privacy
      Even our privacy policy is private.
  automation/announcements:
    uri: cerb:automation:wgm.portal.page.sc.announcements
  interaction/contact:
    label: Contact
    uri: cerb:automation:wgm.portal.page.sc.contact
  automation/historyTicket:
    disabled@bool: {{not identity_id}}
    uri: cerb:automation:wgm.portal.sc.page.historyTicket
    inputs:
      ticket_mask: {{request_path|split('/')[2]}}
  dashboard/history:
    label: Support History
    layout:
      content:
        interaction/tickets:
          label: Tickets
          uri: cerb:automation:wgm.portal.page.sc.tickets
          disabled@bool: {{not identity_id}}
  dashboard/kb:
    label: Knowledgebase
    layout:
      content:
        interaction/articles:
          label: Articles
          uri: cerb:automation:wgm.portal.page.sc.kb.articles
      sidebar:
        text/feeds:
          label: RSS Feeds
          content@text:
            ![RSS 16x16](cerb:portal_resource:c5ca4986-bcf0-11eb-bb22-a54f14ec972f/rss.svg) [Most popular](#)
            ![RSS 16x16](cerb:portal_resource:c5ca4986-bcf0-11eb-bb22-a54f14ec972f/rss.svg) [Recently added](#)
            ![RSS 16x16](cerb:portal_resource:c5ca4986-bcf0-11eb-bb22-a54f14ec972f/rss.svg) [Recently updated](#)

layouts:
  layout/default:
    header:
      section/nav:
        block/sidebar:
          width: 205px
          scale: 0
          widgets:
            text/logo:
              content@text:
                [![Logo 200x](cerb:portal_resource:b208e668-bcec-11eb-b280-45364ccc73b5/logo.png)](/)
        block/content:
          width: 50%
          scale: 1
          widgets:
            menu:
              items:
                page/home:
                  label: home
                  path: /home
                page/announcements:
                  label: announcements
                  path: /announcements
                page/contact:
                  label: contact us
                  path: /contact
                page/history:
                  label: history
                  path: /history
                  hidden@bool: {{not identity_id}}
                page/knowledgebase:
                  label: knowledgebase
                  path: /kb
        block/identity:
          width: 150px
          scale: 0
          align: right
          widgets:
            menu/loggedIn:
              hidden@bool: {{not identity_id}}
              items:
                menu/login:
                  label: {{identity__label}}
                  items:
                    page/logout:
                      label: Log out
                      path: /login/logout
            text/loggedOut:
              hidden@bool: {{identity_id is not empty}}
              content@text: [log in](/login)
    footer:
      section/links:
        block/left:
          widgets:
            text/contact:
              label: Contact
              content@text:
                Webgroup Media, LLC.
                340 S. Lemon Ave #2048
                Walnut, CA 91789 USA
                
                [[email protected]](mailto:[email protected])
                
                [+1.714.671.9090](tel:+17146719090)
                
                [Billing portal](https://webgroupmedia.freshbooks.com/)
                [PGP Public Key](https://keybase.io/wgm)
                
        block/center:
          widgets:
            text/follow:
              label: Follow
              content@text:
                [@cerb](https://twitter.com/cerb_ai)
                [License](#)
                [GDPR](#)
        block/right:
          widgets:
            text/about:
              label: About
              content@text:
                We're a commercial open source company that was founded in 2001 to build web-based software. We're lean, profitable, and organically bootstrapped. We share 100% of our source code due to a fundamental belief that bits and bytes have less value than experience and mutually advantageous, long-term relationships.
      section/copyright:
        block/left:
          widgets:
            text/copyright:
              content: **Cerb**™, **Devblocks**™ © Copyright 2002-2021 by Webgroup Media LLC.
        block/right:
          widgets:
            text/links:
              content: [Privacy](/privacy)

The default page of this portal looks like:

You'll find in routes: that we send the paths / and /home to a page called home:

routes:
  page/home:
    disabled@bool: {{request_path not in ['', 'home']}}

And home is a simple text page:

pages:
  text/home:
    content@text:
      # Welcome
      This is a custom template.

The page uses the default layout, which defines the header (logo and nav menu), and the footer (contact info, nav links, about, and copyright).

Announcements

Let's look at a dynamic page. If we click into Announcements we see:

The route is for /announcements is:

routes:
  page/announcements:
    disabled@bool: {{request_path != 'announcements'}}

And the announcements page is:

pages:
  automation/announcements:
    uri: cerb:automation:wgm.portal.page.sc.announcements

This page runs a portal.page automation named wgm.portal.page.sc.announcements.

That automation looks like:

start:
  set:
    dashboard:
      label: Announcements
      layout:
        content@json: []

  http.request:
    output: http_response
    inputs:
      url: https://cerb.ai/feed.xml
    on_success:
      set:
        feed@json:
          {% set xml = xml_decode(http_response.body) %}
          {{xml.channel|json_encode}}
      repeat:
        each@csv: {{feed.item|keys|slice(0,10)|join(',')}}
        as: item_key
        do:
          var.push:
            inputs:
              key: dashboard:layout:content:text/{{item_key}}
              value:
                width: {{item_key ? 33 : 100}}
                content@text:
                  ## [${title}]({{feed.item[item_key].link}})
                  
                  _${pubDate}_
                  
                  ${description}
                content_params:
                  title@text:
                    {{feed.item[item_key].title}}
                  pubDate@text:
                    {{feed.item[item_key].pubDate|date('F d, Y')}}
                  description@text:
                    {{feed.item[item_key].description|striptags|trim|truncate(255)}}
  return:
    dashboard@key: dashboard

With automation policy:

commands:
  http.request:
    deny/method@bool: {{inputs.method != 'GET'}}
    deny/url@bool: {{inputs.url != 'https://cerb.ai/feed.xml'}}
    allow@bool: yes

The automation fetches the RSS feed from Cerb's project website with an HTTP request, converts the XML to JSON, and iterates through each feed item. It dynamically creates a 'dashboard' page with text widgets that use one-third width -- except the most recent item, which is full width on top. Each widget externally links to the original article.

In production, this output would be cached by the automation for a reasonable TTL (time-to-live) like an hour. These results don't need to be personalized per visitor.

Unlike the same feature in the Support Center, this automation approach could aggregate multiple RSS feeds into a single set. It could personalize based on the current identity, their region, or language. Announcements could also come from non-RSS sources (Twitter posts, custom records, etc).

Contact

Now let's look at an interaction. The old Support Center contact form frequently confused admins with its "contact situations". This displayed a contact form based on a specific subject, but it lacked customizability.

With the portal builder, we route /contact:

routes:
  page/contact:
    disabled@bool: {{request_path != 'contact'}}

To the contact page:

pages:
  interaction/contact:
    label: Contact
    uri: cerb:automation:wgm.portal.page.sc.contact

This runs an interaction.portal automation named cerb:automation:wgm.portal.page.sc.contact.

start:
  set/types:
    issue_types:
      info:
        key: info
        label: I'd like more info about your products
      billing:
        key: billing
        label: I have a question about an invoice
  
  await/type:
    form:
      elements:
        sheet/prompt_type:
          label: How can we help?
          required@bool: yes
          default: info
          data@key: issue_types
          schema:
            layout:
              filtering@bool: no
              headings@bool: no
              paging@bool: no
            columns:
              selection/key:
                params:
                  mode: single
              text/label:
                params:
                  bold@bool: yes
  
  await/contact:
    form:
      elements:
        text/prompt_email:
          label: What email address should we reply to?
          required@bool: yes
          type: email
        text/prompt_subject:
          label: Subject:
          required@bool: yes
          default: {{issue_types[prompt_type].label}}
        textarea/prompt_message:
          label: Message:
          required@bool: yes
        captcha/prompt_captcha:
          label: Please enter the text from the image:
          required@bool: yes
        say/ip:
          content@text: **Logged IP:** {{client_ip}}
  
  # [TODO] Create ticket, etc.

This page first displays a contact reason like the Support Center, but it's now completely customizable. You can prompt for any kind of information to determine the approach destination, and tailor the form to that exact situation. There can be as many steps as you want.

The form displays with prompts for email address, subject, and message. It also displays a CAPTCHA challenge, and shows the visitor's current IP.

Form validation is handled for you automatically:

There are endless customization options, including:

• Display all content in the identity's language.
• Suggest knowledgebase articles between the contact reason and the form to quickly resolve common issues without opening a ticket.
• Run a troubleshooter first to diagnose common problems.
• Gather all of the information you need for a resolution in the first contact to reduce back and forth email conversations.
• Verify email addresses from anonymous visitors before completing the form.
• Provide a fee-based escalated support option (holidays/weekends/after-hours).
• Display an estimated response time based on recent averages for the given group/bucket.

Login

We can click the log in link in the top right to authenticate as an identity. In this example it takes us to one of Cerb's new identity portals:

It supports two-factor authentication:

And asks us for consent:

After logging in, we are seamlessly returned to the portal.

The layout previously hid the 'Ticket history' menu option unless we were logged in:

layouts:
  layout/default:
    header:
      section/nav:
        block/content:
          width: 50%
          scale: 1
          widgets:
            menu:
              items:
                page/history:
                  label: history
                  path: /history
                  hidden@bool: {{not identity_id}}

The page was also disabled for direct requests (by URL not menu) without an identity:

routes:
  page/history:
    disabled@bool: {{not identity_id or request_path != 'history'}}

pages:
  dashboard/history:
    label: Support History
    layout:
      content:
        interaction/tickets:
          label: Tickets
          uri: cerb:automation:wgm.portal.page.sc.tickets
          disabled@bool: {{not identity_id}}

We can see the menu option now that we're logged in:

After clicking the link, we see the page:

This is a dashboard page, with an interaction (cerb:automation:wgm.portal.page.sc.tickets) that displays a sheet of tickets for the current identity. The sheet is filterable and pageable.

start:
  await:
    form:
      elements:
        sheet/prompt_ticket:
          data:
            automation:
              uri: cerb:automation:cerb.data.records
              inputs:
                record_type: ticket
                query_required@text:
                  status:!d participant:(id:${email_id}) sort:-created
                query_params:
                  email_id@key,int: identity_email_id
          schema:
            layout:
              filtering@bool: yes
              headings@bool: yes
              paging@bool: yes
            columns:
              link/subject:
                params:
                  text_key: subject
                  href_template@raw: /history/ticket/{{mask}}
                  bold@bool: yes
              text/status:
              date/created:
        submit:
          continue@bool: no

This sheet can be completely customized to meet your needs.

In this case, clicking on a ticket routes to /history/ticket/ with the ticket's mask as the third part of the path.

routes:
  page/historyTicket:
    disabled@bool: {{not identity_id or request_path is not prefixed ('history/ticket/')}}

pages:
  automation/historyTicket:
    disabled@bool: {{not identity_id}}
    uri: cerb:automation:wgm.portal.sc.page.historyTicket
    inputs:
      ticket_mask: {{request_path|split('/')[2]}}

And the historyTicket page is an automation that receives the mask as input and generates a dashboard page (with widgets) as output:

inputs:
  text/ticket_mask:
    required@bool: yes
    type: freeform

start:
  record.search:
    output: record_ticket
    inputs:
      record_type: ticket
      record_query@text:
        mask:${mask}
        participant:(id:${email_id})
        status:!d
        limit:1
      record_query_params:
        mask@key: inputs:ticket_mask
        email_id@key,int: identity_email_id
      record_expand: customfields
  
  return:
    dashboard:
      label: {{record_ticket._label}}
      layout:
        content:
          interaction/name:
            label: Messages
            uri: cerb:automation:wgm.portal.sc.widget.messages
            inputs:
              ticket: {{record_ticket.id}}
        sidebar:
          text/summary:
            label: Ticket
            content@text:
              **Group:** ${group}
              **Bucket:** ${bucket}
              **Status:** ${status}
            content_params:
              group: {{record_ticket.group__label}}
              bucket: {{record_ticket.bucket__label}}
              status: {{record_ticket.status}}

The dashboard includes an interaction widget for Messages named cerb:automation:wgm.portal.sc.widget.messages that pages through all messages on the ticket:

inputs:
  record/ticket:
    record_type: ticket
    required@bool: yes

start:
  await:
    form:
      elements:
        sheet:
          data:
            automation:
              uri: cerb:automation:cerb.data.records
              inputs:
                record_type: message
                query@text:
                  ticket:(
                    id:${ticket_id}
                    participant:(id:${email_id})
                  )
                  sort:-id
                query_params:
                  email_id: {{identity_email_id}}
                  ticket_id: {{inputs.ticket.id}}
          limit: 1
          schema:
            layout:
              filtering@bool: no
              headings@bool: no
              paging@bool: yes
            columns:
              text/_:
                params:
                  value_template@raw:
                    <b>From:</b> {{headers.from}}<br>
                    <b>To:</b> {{headers.to}}<br>
                    <b>Subject:</b> {{headers.subject}}<br>
                    <b>Date:</b> {{created|date('r')}}<br>
                    <br>
                    {{content|nl2br}}
        
        submit:
          continue@bool: no

NPS

Since portal widgets are dynamic, you can occasionally prompt an identity to complete a one-click NPS survey:

Conclusion

You can use the Portal Builder to quickly create customer-facing tools with complete customization.

While our example replicated the Support Center, there are countless uses.

We're working hard to ship this feature in 10.2 within the next few months.