Main Nav

Purpose

The Main Nav extension allows you put a linkable icon directly into your Seismic navigation pane. When a user clicks on your icon, Seismic will place the destination page into the Seismic via an iFrame. Although this extension point can be very simple to work with, it also supports a wide range of advanced functionality including:

• Text sub-items
• GET and POST URLs
• Deep linking
• iFramed HTML pages and proxy redirect pages
• Redirect (302) logons to your external pages

Common use cases include:

• Access to external content repositories, such as training materials
• Access to your intranet site
• Access to external web apps or other SAAS platforms

App prerequisites

Aside from enabling the extension point and configuring it, there are no additional prerequisites.

How it works

High level flow

1. Seismic displays the icon you provide (SVG) in Seismic's navigation bar
2. When your icon or subitem is clicked, Seismic displays the linked destination within Seismic's main window

When it's triggered

• Without Subitems, clicking on the icon in the navigation bar will call your URL
• With subitems, clicking on the icon will expose your subitems in a dropdown style, similar to "Settings"
• Clicking on a subitem will load that specific URL into Seismic's main window
• With deep linking, clicking on a piece of content that is associate with your item or subitem will

Security and authentication

It is recommended to validate the Signing Secret in the POST request that Seismic is making

How to configure

Configure the Main Nav extension

• Add Main Nav to your application as described here
• Configure the fields for this extension, please refer to the table below for definitions and notes
• Make sure to enable the extension point and click Save Changes

URL route types

Get URL Route Type
This is the most simple configuration. Your URL will simply return the HTML that should be displayed in Seismic. iFraming must be allowed on your site.

POST URL Route Type
Seismic will delivery a payload to your endpoint which allows you to do things like validate the call and capture details of the tenant, user, and app.

The POST call from Seismic will include the app's signing signature with the label "x-seismic-signature"

{
  "UserId": "1234431f-4eee-42d5-9141-e56c5b00b391",
  "UserEmail": "[email protected]",
  "Language": "en-US",
  "AppId": "00007df8-9ebb-487a-98b8-471ececc5f46",
  "AppName": "My Test App",
  "Tenant": "mytenantname",
  "TenantId": "11181086-49d3-495b-b063-2c35319a30b5",
  "RequestId": "53a712d3-66db-4664-96c3-67d36cb89fd6",
  "Version": "1.6.5",
  "Timestamp": "2022-05-18T16:17:30.8724593Z"
}

Your response to Seismic should be the contents you expect to see iFramed within Seismic's main window, either as HTML or as a redirect URL

Proxy URL Route Type

Seismic will add some valuable query parameters to the endpoint that you provide.

• url - the url requested either via a deep link or via the user clicking from the main nav menu or submenu items.
• userId - the id of the user who requested the url
• email - the email address of the user
• tenant - the tenant of the user (human readable)
• tenantId - the id of the tenant
• timestamp
• signature - the whole proxy url plus query params will be HMAC-SHA265 hashed using the signing secret. This will be stringified and appended as a query param.

Sample:
https://mydomain.com/myproxy?url=[requestedUrl]&userId=[userId]&email=[email]&tenant=[tenant]&tenantId=[tenantId]×tamp=[ISO 8601]&signature=[sig]

This is a good choice if you are using an API based call such as our Search Extension or Related Training Extension. You can have your proxy access your same database where you have matched your external user to the Seismic user and then the user would only need to login once to your system. By returning a 302 redirect to the url with a cookie, the user doesn’t need to login to the web side of your application.

📘

Proxy domain vs Destination domain

If your proxy is not on the same domain that the requested/final url that the user is trying to access you’ll need to redirect twice, once from the proxy to something within the correct domain and then to the final url with the cookie

Here is a sample of how you can validate the signing signature from a Proxy URL POST with Ruby

require "openssl"
require "base64"
require "time"
require "addressable"

def shared_template
  @template ||= Addressable::Template.new("https://mysrs.com/myProxy/{?url,email,userId,tenantId,timestamp,signature}")
end

def shared_secret
  "aacfd657bd324f91a418b4c3766d492682538752a1684a3280beb3733c35aa0b"
end

def verify_url(url)
  uri = Addressable::URI.parse(url)

  args = shared_template.extract(uri)
  incoming_sig = args["signature"]

  url_without_sig = url.gsub(/&signature=.*/, "")
  computed_sig = OpenSSL::HMAC.hexdigest("SHA256", shared_secret, url_without_sig).upcase

  matches = incoming_sig.eql?(computed_sig)

  puts "sig matched? #{matches}"

  if matches
    ts = Time.parse(args["timestamp"])
    recent = ts > Time.now - 30 * 60
    puts "ts recent? #{recent}"

    if recent
      puts "Creating cookie for email=#{args["email"]}, domain=#mysrs.com. Sending user to #{args["url"]}"
    end
   end
end

url = generate_url("https://tenant1.mysrs.com/123");
verify_url(url);

Visual recommendations & guidelines

Icon format

• Please use an SVG (vector graphic) for your icon
• It is recommended to use a transparent background
• You can set your canvas size to 25x25 for design & previewing purposes, but the size of your SVG canvas is not important to functionality

Icon line color

If you want your icon to blend in naturally with the other icons, please follow the guidelines below

• Seismic's icons are line based vectors. We do not currently use shapes or colors in our UI iconography
• If your tenant is using Seismic's new UI (white background in the navigation bar with dark gray icons), you will want your to use the color code #535B64 (R: 83, G: 91, B: 100)
• If your tenant is using Seismic's original UI (dark blue/gray background with light gray icons) in the navigation bar with gray icons), you will want your to use the color code #9EA8AE (R: 158, G: 168, B: 174)

Item character length

Seismic's navigation does not use a Monospace font, so the recommendations below are impacted by wider or more narrow characters. Please test your application for readability.

• The label on an icon without subitems should typically be less than 11 characters
• When subitems are present, it is still recommended to keep the label less than 11 characters, however when a user clicks on your icon they can see a larger name above the subitems. You can typically display up to 14 characters without overlap on the dropdown arrow

Subitem character length

• The label on a subitem should typically be less than 20 characters. As above, this can change slightly due to character width

Additional best practices

Limit the scope for each sub-nav item

Each item should serve a clear and distinct purpose. For SRS applications that have a coaching component, we recommend separate sub-nav items for “Training” and “Coaching”. For SRS applications without a coaching component, we recommend using a single main nav item without any sub-nav items.

Simplify UI for iFrames

For the best user experience, we recommend providing iFrame URLs that strip out peripheral content that can distract the user.

• Remove navigation menus that aren’t needed given the scope of the nav item
• Remove any unneeded headers and footers
• Remove search bars if your users are searching for content within Seismic via the Search Extension

Troubleshooting

• Ensure your Main Nav icon is in an SVG format
• Ensure your URLs allow iFraming
• Ensure the extension point is enabled within your app
• If using POST or Proxy URLs, ensure your app is configured with a signing secret via the Basic Information tab

Related Documentation

• Extension Points
• Search Extension