The Sesam Databrowser

High level overview / Introduction

The Sesam Databrowser is a generic browser that lets you inspect information as it exists in the data hub. The interaction principle is a combination of search and traditional navigation.

The startpage

This is the first page you see when loading the databrowser url.

Screenshot of startpage

Screenshot of startpage

This page gives you a little bit of everything that is relevant to your user account.

  1. The logo. This is always displayed and links to the startpage.
  2. This is the search field
  3. The date filter lets you filter the results by time
  4. Toggle edit-mode on/off. Edit-mode is used when configuring the databrowser.
  5. Link to the item that represents the logged-in user

(6), (7) and (8): Sections that results are grouped into

  1. A searchresult
  2. link to the admin pages
  3. Toggle debug-information on/off
  4. Section logo
  5. Section "more" link

The sections

The searchresult items each has a type ("Ansatt", "Prosjekt", "Avdeling"). To organize the searchresults, the databrowser splits the searchresults into separate sections, based on the item types.

There will typically be three sections present: "Who", "What" and "Where". (6, 7, 8 in the startpage image above).

The "Who"-section will typically contain items that represents people ("Employee", "Manager", etc).

The "What"-section will typically contain items that represents things ("Project", "Task", etc).

The "Where"-section will typically contain items that represents places ("Department", "Country", etc).

A searchresult

Searchresult items (9 in the startpage image above) contains the following information:

searchresult item

searchresult item

  1. The type of the item. This is also a link for filtering image based on the name of the type.
  2. The title(s). This is also a link to the itemdetail image for the item.
  3. The date(s), if available. This is typically a last-modified date.
  4. A link for filtering image the searchresults based on the items title.

Doing a search with a searchtext

You can do a text-search by entering a text in the searchtext input field (Element (2) in the startpage image above). The searchresults in the sections will update automatically as the user types in a searchtext. If the searchquery results an a section containing zero searchresults, that section will be hidden.

Narrowing a search with the daterange slider

The daterange slider (Element (3) in the startpage image above) lets you narrow the searchresults based on a daterange.

daterange slider

daterange slider

The first (1) and last (2) year in the searchresults are displayed at the top of the daterange-slider. You can use the handles (3) and (4) to narrow the daterange, like this:

daterange slider

daterange slider

As you drag the start-date and end-date handles back and forth, the searchresults will be updated automatically.

Focused section

To see more results from a section you can click/tap its icon or more-link (Elements (12) and (13) in the startpage image above . This is called "focusing" on the section.

When a section is focused, the other sections gets hidden, and all the searchresults in the focused section is available. We use "infinite scrolling" to show all the searchresults: when you scroll down more searchresults are fetched from the server and added to the end of the list of searchresults.

In the image below we have focused on the "Who"-section:

focused section

focused section

A number of things change when focusing on a section:

  1. A vertical scrollbar appears in the browserwindow, to indicate that the user can scroll down to see more searchresults.
  2. and (3) Smaller boxes (called "facetsections") are displayed inside the focused section. The facetsections contains facetvalues (4) that lets you filter image the searchresults on things like item type.

Facetsections

The facetsection displays one or more filters that can be applied to narrow down the number of searchresults. The number after each filtername gives an indication on the number of searchresults that would result by applying the filter.

The purpose of the filters is to only display items that is connected to the item that the filter refers to. The most common usecase is to filter items based on their type. (An item's type is described by having the item refer to another item that represents the type).

You can apply multiple filters by clicking on the #Name of the filters you want. The searchresult will be the intersection of the searchresults you would get or each of the filters on its own:

focused section with filters applied

focused section with filters applied

Note that the selected filters (1) and (2) appears in the searchtext inputfield as text (3) and (4). Power-users can type in filters manually and get the same effect as clicking on a filter.

You can remove a filter by clicking on it again, or by deleting the text from the searchtext inputfield.

In the configuration chapter we will describe how to specify the filters each facetsection should contain.

More on Filters

What follows is a detailed and somewhat technical description of how the facet filtering is done. A user is normally not required to know the details here, but in some cases it can be very useful to know what is going on behind the scenes.

Each item is stored as a separate document in a search-index. Each document has a number of fields, but in this context only three fields are important:

  • "titles": A list of the titles of the document (for instance a person's name)
  • "ids": The unique identifiers of the document
  • "entities": The ids of other documents that this document refers to.

When the user uses a #Filter, the system will do the following:

  1. Extract the title-strings from the #Filter. Examples: #SomeTitle => "SomeTitle", #"Knut Johannessen" => "Knut Johannessen"

  2. Do a search for documents whose "titles"-field contains the exact title as specified in the filter. Make a
    combined list of all the ids of the documents.
  3. Do a search for documents whose "entities"-field contains at least one of the documentids from step (2), and that also fulfills all the other searchparameters (daterange, etc).

  4. Display the documents from step (3) to the user.

If more than one #Filter is defined, separate lists of ids are created for each #Filter in step (2). In step (3) a search is made for documents whose entities match at least one id in each of the lists from step (2).

Syntax:
Filtering is normally done by clicking on a facetvalue in a facetsection, but it is also possible to manually type in filter in the searchtext inputfield, using the following syntax:
  • The filter always starts with the hashtag (#) character.
  • If the title-string contains a space-characters, the title-string must be enclosed in double-quote (") characters.
  • Only exact title-string searches are done. For instance: #orang will not give any matches on items with the title 'orange'.
  • If the closing double-quote is missing, all the remaining text in the search-input field is assumed to be a part of the title-string.

Examples:

Search string Resulting title-string Resulting free-text query
#orange "orange"  
#orange apple "orange" "apple"
#"orange" apple "orange" "apple"
#"orange apple" "orange apple"  
#"orange apple "orange apple"  

The itemdetail page

When you click on a searchresult item, that item gets selected, and is displayed on the itemdetail page.

This page displays all the attributes of the selected item, and the searchresults are filtered so that only items that refer to the selected item is displayed:

Itemdetail page collapsed screenshot

Itemdetail page collapsed screenshot

  1. The itemdetail view.
  2. Filtered searchresults.
  3. Expand/collaps button.

To see more of the selected item (and less of the filtered searchresults), you can click the Expand-button (element 3 in the image above).

Itemdetail page collapsed screenshot

Itemdetail page collapsed screenshot

When the itemdetail page is expanded, the following information is displayed:

  1. The names of the type or types of the item.
  2. The title or titles of the item.
  3. The date(s) or the item. This is typically a "created" or "last changed" date, but this will be different for different itemtypes. Example: For an item that represents a calendar entry, the date will typically be the date the event occurs.
  4. All the attributes of the item. The user can configure how the itemattributes are displayed; ordering, headers, etc can all be specified. This is described in detail in the configuration chapter below.
  5. An overview of the searchresults. The searchresult is squashed down a bit to take as little room as possible, while still making it possible for the user to use the searchtext inputfield and the daterange slider.
  6. The expand/collapse button.

Getting back to start

There are two ways to get back to the startpage after clicking around in the databrowser: The first is the web-browser's backbutton. This will take you one step back toward the starting point.

Example:

  1. Open the startpage
  2. Click on the more-link on a section => this focuses on the section
  3. Click on a searchresult item in the section => this causes the item detail page to load.
  4. Click on the browser's backbutton => this takes you back to the focused section as in step 3.
  5. Click on the browser's backbutton => this takes you back to the startpage

The other way to navigate is to click on the logo in the top left corner. This will take you directly back to the startpage, no matter which page you are currently at.

Logging in

TODO: explain how authentication works:

User object

The "user object" is the item that represents the currently logged-in user. This item will not be displayed in any searchresults, but can be reached by clicking on the little person-icon in the top right corner.

Configuration

Specifying what appears in the "Who"-section.

As mentioned in the chapter about "Sections", the searchresults are organized into different sections (for instance "Who", "What", "Where" and "Why), based on the type of each searchresult item.

You can select which section an item type belongs to via the itemdetail page. This is done as follows:

  • Go to the startpage
  • Click on the first search-result in the "Where"-section. This opens the itemdetail view.
  • Click on the expand-button, if needed
  • Click on the "edit"-button (The little pencil in the top right corner of the browserwindow). This changes the view to "edit"-mode, see the screenshot below.
itemdetail page editmode

itemdetail page editmode

  1. At the top of the itemdetail view all the types of the selected item will be displayed. After each type name is listed the section that items of that type will appear in. If the link after a type says "Unknown", it means that that itemtype hasn't been assigned to a section. The item may have more than one type, but at least one of the types will be assigned to the "Where"-section.
  • To change which section the item appears in, click on the sectioname link after the itemtype (element (1) in the screenshot above. This will open a dialogbox where you can select one of the "Who", "What", "Where" sections. Select "What".
itemdetail page editmode

itemdetail page editmode

You can now return to the front page (by clicking on the sesam-logo in the top left corner) to see who your change has affected the searchresults: The item will now have been moved from the "Where" to the "What" section.

Note: It is a good idea to change the section back to the original value afterwards; all the changes you make apply to all users, not just to you. Click the browsers back-button to go back to the itemdetail page and select the "Where"- section again.

Specifying what appears in a facetsection via the itemdetail view.

The content of the facetsections can also be specified on the itemdetail page. In this example we will add the "Avdeling"-

Click on the "What"-heading to to focus on the "What"-section. The section will expand to take up the full width of the screen, and will display a "What" facetsection.

Lets assume that we want to have a "Hvor" facetsection that displays the values of the "departmentid" attribute.

  • Go to the front page and click on the first searchresult in the "Hvem"-section
  • Click on the "expand"-link if neccessary, to make the itemdetail view take up the whole browserwindow.
  • Click on the "edit"-button (The little pencil in the top right corner of the browserwindow)
  • Find the "departmentid" label and click on it. This opens a dialog where you can configure the attribute.
  • Select "Hvor" in the "Facet section" dropdown (1) and click the submit-button (2).
Facet section dropdown

Facet section dropdown

  • Click on the sesam-logo in the top left corner to go back to the front page
  • Click on the "more"-link in the bottom right corner of the "Hvem"-section

The "Hvem"-section will now display a "Hvor"-facetsection (in addition to the old "Hva"-facetsection). As before: If this is a production system is is a good idea to revert your changes afterwards.

Display fields

Some of the fields of an item has a special significance, and we often want to display the fields in a more prominent place than the generic field list. There are three different types of display fields:

itemdetail page with displayfields

itemdetail page with displayfields

  1. "Title"-fields are displayed as the title(s) of an item. Typically usage: a persons full name.
  2. "Description"-fields are displayed below the titles. They are typically used to display a longer text that describes the item somehow.
  3. "Date"-fields describes the dates of the item. This can be things like "created date" or "modification date", "birth date".

A field is assigned to a display-field via the edit-mode in the itemdetail-page:

itemdetail page with displayfields

itemdetail page with displayfields

To change the display-field setting, select a setting from the dropdown (1) and click the submit-button (2).

Only the display-field settings that apply to a particular field; in the example above we are looking at a text-field, so the "Date" display-field setting is not available in this case.

Search fields

Search-fields are similar to display-fields, in that they are item fields with some special significance. But while the display-fields settings describes how a field is displayed to the user, the search-field settings describe how a field is used when searching for data.

There are three different kinds of search-fields:

  1. "Title": These fields are used when doing using a #TitleFilter. See the More on Filters chapter
  2. "Date": These fields are used when narrowing a set of searchresults with the daterange slider.
  3. "Email": These fields are used when searching for items that are related to the currently logged-in user. These items are then used to boost searchresults relevant to the current user.

Item attributes

In addition to the itemattribute settings we have already mentioned, there are a few others that we also must mention.

itemdetail page misc item attributes

itemdetail page misc item attributes

  1. The "psi" is the unique identifier of the item attribute type. This is readonly.

  2. "Type specific": This checkbox specifies whether or not the settings should apply to all instances of the item attribute, or only instances of the attribute on items of the same type as the current item.
    This could for instance be used to give the "title"-attribute a label of "First- and lastname" for a person, and "Project title" for a project.
  3. "Label": The headingtext for the itemattribute.

  4. "Group": The name of the group the itemattribute should be place under. To create a new group, simply set this value to a new value. If no such group already exists, it will be implicitly created.

  5. "Sortorder": The attribute's sortorder within the group.

  6. Visible: A checkbox that specified whether or not this attribute should be displayed or not. (An attribute is alwasy visible in edit-mode, regardless of this setting)

  7. Renderer: How the attribute should be rendered. This is normally set to "default", which means that the system will attempt to guess at the best way of rendering the attribute.

Admin pages

In addition to the normal searchresults and itemdetail pages, the datebrowser also has some pages that is only visible for administrative users.

These are reached by adding "/admin_index" to the databrower address in your browser. Example: if your databrowser is reached at "https://databrowser.example.com", the admin-pages will be at ""https://databrowser.example.com/admin_index".

Screenshot of admin index page

Screenshot of admin index page

Below we will look at each of the avialable admin-pages.

Configuration page

Screenshot of configuration admin page

Screenshot of configuration admin page

This page displays all the configuration-settings of the databrowser. It is mostly useful for developers who are trying to track down some problem.

Near the top of the page is a listing of where the databrowser read its configuration from:

  1. A list of the default configuration-files. These are the files that all installations of the databrowser shares.
  2. A list of the installation-specific configuration-files. These files are supplied by each installation of the databrowser, and will typically override configuration-settings found in the default configuration-files.
  3. The redis-server that the databrowser is connected to. When making configuration-changes via the gui, the changes are stored in this redis-server.
  4. Links for downloading and uploading all configuration-changes to the redis server. See the Redis configuration upload page
  5. A list of configuration attributes is displayed for each [section] in the databrowser.ini file.

Data types page

Screenshot of datatypes admin page

Screenshot of datatypes admin page

This page displays information about item-types and attriute-types, and lets you do the same configurations as on the itemdetail page. Sometimes it is easier to do such configuration here, since you don't first have to find an item that has the item-type or attribute-types that you want to configure.

Logging page

Screenshot of logging admin page

Screenshot of logging admin page

This page is only of interest to developers that has access to the server logs. It is not meant to be used by end-users. The page lets you change the log-levels of the various bits of the code. These settings are not persisted anywhere, and will be reset to their default values once the databrowser server restarts. To permanently change the log-levels you have to modify your installation-specific "production.ini"-file.

Debug information

The "Enable debug"-link on the bottom of the page will cause additional information to be displayed on the page. This can be useful when trying to track down problems with the configuration of the databrowser.

In the image below we have enabled debug information on the frontpage:

screenshot with debug information enabled

screenshot with debug information enabled

Explanation:

  1. This links to a "searchresult explanation page" that shows detailed technical information about the search-queries that were run in order to generate the search results.
  2. This debug-info text describes the settings the databrowser sued to render the searchresult item.
  3. A link to the underlying solr-data of the searchresult item.
  4. The link in the footer has now changed to "Disable debug"

Searchresult explanation page

This is a special debuginfo page that displays information about the solr-queries that was used to generate a list of searchresults. It is mostly useful for developers and administrators that needs to debug and tweak the search configuration.

Searchresult explanation page screenshot

Searchresult explanation page screenshot

Redis configuration upload page

Redis configuration upload page screenshot

Screenshot of Redis upload page

This page lets you bulk-upload configuration settings directly to the Redis server. The current configuration is displayed in the textarea. You can either make changes to the existing configuration or copy/paste the config from somewhere else (for instance another databrowser instance).

This is useful if you have more than one databrowser instance and you want to copy configuration from one instance to another (for instance from a test-instance to a -instance).

Databrowser API Reference

GET /api

Returns information about the sesam portal.

Status Codes
GET /api/profile

Returns information about the currently logged-in user.

Status Codes
PUT /api/profile

Updates information about the currently logged-in user. This endpoint accepts the same json structure as the GET /api/profile endpoint produces, but only a few of the fields in that structure will be used, since the user is only allowed to change a few of the fields. The "name" field can be changed, but the "email" field can not be changed, for instance. This endpoint also accept a "sparse" json-structure, that only contains the field(s) that the client wants to modify. The values represented by any "missing" fields will not be modified; if for instance the json only contains the "picture"-field, the "name"-field will not be modified.

Status Codes
GET /api/profile2

Returns information about the currently logged-in user. If the user is not logged in a 401 response is returned instead. TODO replace the "/api/profile" endpoint with this when we deploy the unified frontend.

Status Codes
  • 200 OK -- This returns the same response as the /api/profile endpoint
  • 401 Unauthorized -- The user is not logged in
DELETE /api/profile/{user_id}

Deletes the specified user.

Parameters
  • user_id (string) -- The id of the user to delete.
Status Codes
GET /api/jwt

Returns the JSON Web Token for the currently logged in user.

Status Codes
POST /api/jwt

Returns the JSON Web Token for the user described in the post parameters (email+password).

Status Codes
GET /api/subscriptions/{subscription_id}/jwt

Returns the JSON Web Token for the specified subscription for the currently logged in user.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/jwt/publickey

Returns the RSA public key that can be used to verify the JWT signature

Status Codes
GET /api/jwt/zendesk

Returns the JWT to be used with the Zendesk authentication api for the currently logged in user

Status Codes
GET /api/jwt/zendesk-chat

Returns the JWT to be used with the Zendesk Chat authentication api for the currently logged in user

Status Codes
GET /api/subscriptions

Returns the subscriptions that this user is connected to.

Status Codes
POST /api/subscriptions

Creates a new subscription

Status Codes
GET /api/subscriptions/{subscription_id}

Returns information about the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
DELETE /api/subscriptions/{subscription_id}

Deletes the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
PUT /api/subscriptions/{subscription_id}

Update the subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/subscriptions/{subscription_id}/available-roles

Returns a list of the roles that are available for the specified subscription. This includes the build-in roles and any custom-roles that has been created in the subscription.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/subscriptions/{subscription_id}/available-roles

Adds a new custom-role.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/subscriptions/{subscription_id}/licenses

Renews the subscription's license. This extends the current license's expirationdate, but keeps all other license-values the same. Returns the updated Subscription.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/subscriptions/{subscription_id}/api_json_web_tokens

Returns a list of the api JWT tokens for this subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/subscriptions/{subscription_id}/api_json_web_tokens

Creates a new API JWT for the specified subscription. These are json web tokens that are intended for use by things like scripts and cron-jobs, where you need a long-lasting JWT with a specific set of roles.

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
  • 200 OK -- The new SubscriptionJWT
DELETE /api/subscriptions/{subscription_id}/api_json_web_tokens/{api_json_web_token_id}

Deletes the specified api JWT token

Parameters
  • subscription_id (string) -- The subscription id
  • api_json_web_token_id (string) -- The api jwt id
Status Codes
GET /api/subscriptions/{subscription_id}/available-roles/{role_id}

Returns information about the specified role in the specified subscription.

Parameters
  • subscription_id (string) -- The subscription id
  • role_id (string) -- The role id
Status Codes
DELETE /api/subscriptions/{subscription_id}/available-roles/{role_id}

Deletes the specified role in the specified subscription.

Parameters
  • subscription_id (string) -- The subscription id
  • role_id (string) -- The role id
Status Codes
PUT /api/subscriptions/{subscription_id}/available-roles/{role_id}

Updates the specified role in the specified subscription.

Parameters
  • subscription_id (string) -- The subscription id
  • role_id (string) -- The role id
Status Codes
GET /api/subscriptions/{subscription_id}/members

returns a list of the members in the subscription

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • limit (integer) -- Specifies the maximum number of members to return. If this is not specified, all available members are returned.
  • start (integer) -- The index of the first member to return. This defaults to 0 (zero), which means to start at the beginning of the list of members. The 'start' parameter can be used in conjunction with the 'limit' parameter to implement pagination.
Status Codes
POST /api/subscriptions/{subscription_id}/members

Invites a user to the subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/subscriptions/{subscription_id}/members/{user_id}

returns information about the roles the specified user has in the subscription

Parameters
  • subscription_id (string) -- The subscription id
  • user_id (string) -- The user id
Status Codes
PUT /api/subscriptions/{subscription_id}/members/{user_id}

updates the roles the specified user has in the subscription

Parameters
  • subscription_id (string) -- The subscription id
  • user_id (string) -- The user id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/available-notification-ruletypes

Returns a list of the available notification rule types on the specified pipe. The idea is that the client can use this list to dynamically generate a gui that lets the user add and edit notification rules.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
PUT /api/admin/config/validation_hack_for_NewPipeNotificationRuleInfo

This is a dummy endpoint that is used to register the NewPipeNotificationRuleInfo definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
POST /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules

Add a new notification rule entry on the specified pipe

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules

Returns a list of the notification rules on the specified pipe

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
PUT /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Updates the specified notification rule entry.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Gets the specified notification rule entry.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Status Codes
DELETE /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}

Deletes the specified notification rule entry.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Status Codes
GET /api/subscriptions/{subscription_id}/pipes/{pipe_id}/notification-rules/{notification_rule_id}/notifications

Returns the notifications that has been triggered by the specified notification rule.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
  • notification_rule_id (string) -- The notification_rule id
Query Parameters
  • limit (integer) -- Specifies the maximum number of notifications to return. If this is not specified, a reasonable default limit will still be used.
  • since (string) -- This can be set to a ISO 8601 datetime string to only return notifications that are more recent than the specified datetime.
  • include_dismissed (boolean) -- Specified if dismissed notifications should be included in the results.
Status Codes
GET /api/notifications

Returns the notifications that should be displayed in the "Alerts"-list for this user.

Query Parameters
  • limit (integer) -- Specifies the maximum number of notifications to return. If this is not specified, a reasonable default limit will still be used.
  • since (string) -- This can be set to a ISO 8601 datetime string to only return notifications that are more recent than the specified datetime.
  • include_dismissed (boolean) -- Specifies if dismissed notifications should be included in the results.
Status Codes
GET /api/notifications-summary

Returns the status of all subscriptions and pipes with notification-rules that the user have access to. This endpoint implements the Sesam "json-pull" protocol (https://docs.sesam.io/json-pull.html).

Query Parameters
  • limit (integer) -- Specifies the maximum number of items to return. If this is not specified, all available items will be returned
  • since (integer) -- This is the 'since'-value in the sesam json-pull protocol (https://docs.sesam.io/json-pull.html)
  • deleted (boolean) -- Specifies if deleted entries should be included in the results.
Status Codes
GET /api/monitoring/standard/{subscription_id}/pipes/{pipe_id}

Returns standard monitoring information about the specified pipe

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
GET /api/monitoring/standard/{subscription_id}

Returns standard monitoring information about the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/monitoring/invoicing/{subscription_id}

Returns invoicing information for the specified subscription

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
GET /api/sso

Used for SSO authentication. If the portal detects that a user is in session, it creates a JWT and redirects to a provided URL. If not, it serves a login page to authenticate. Right now, this only works with Zendesk.

Query Parameters
  • return_to (string) -- The URL to return to after authentication
Status Codes
GET /api/login_implicit_flow

This is only used when logging in with openid connect providers that only support the "implicit flow" method. In that case the "id_token" is returned as part for the fragment-part of the url (the bit after the "#"-sign), which isn't sent to the backend. The login_implicit_flow page contains a javascript snippet that extracts the id_token and calls the jwt_login endpoint.

Status Codes
POST /api/jwt_login

This is only used when logging in with openid connect providers that only support the "implicit flow" method.

Status Codes
POST /api/login/{provider_id}

This starts an openid connect authentication prosess. The user will eventually be redirected back to the '/login_callback/{provider_id}' endpoint.

Parameters
  • provider_id (string) -- The name of the openid connect authentication provider. This must match a provider that has been configured in the sesamportal.yaml file.
Status Codes
  • 302 Found -- A redirect to the authentication provider's login-page.
GET /api/login_callback/{provider_id}

The user is redirected back here after authenticating with an openid connect authentication provider.

Parameters
  • provider_id (string) -- The name of the openid connect authentication provider. This must match a provider that has been configured in the sesamportal.yaml file.
Query Parameters
  • code (string) -- A short-lived authorization code from the authentication provider. The DAP backend will use this code to retrieve the user's information from the authentication provider.
Status Codes
  • 302 Found -- Redirect to the sesam portal frontpage
POST /api/login

This is called when the user wants to authenticate with an email-address and a password. If the login is successful, a new http session is created, and the sessionid is returned in a cookie.

Status Codes
GET /api/logout

Logs out the currently logged-in user, and clears the http session data. This is the legacy logout that returns a json object (the same as the /api/profile endpoint). This endpoint is deprected and should be removed once the gui has been updated to use the "/api/logout2" endpoint.

Status Codes
GET /api/logout2

Logs out the currently logged-in user, and clears the http session data.

Status Codes
  • 302 Found -- This redirect either to the sesam portal frontpage, or to a url that lets the user log out properly from a third party authentication provider.
POST /api/signup

Signs up a new user

Status Codes
GET /api/available-subscription-settings

service for returning the various choices that exists for the various subscription settings

Status Codes
POST /api/estimate-subscription-price

service for calculating subscription price, based on a description of the select subscription options

Status Codes
POST /api/subscriptions/{subscription_id}/estimate-subscription-price

service for calculating a new subscription price, based on a description of the select subscription options

Parameters
  • subscription_id (string) -- The subscription id
Status Codes
POST /api/is-available-subscription-name

This service checks that the specified subscription name is unique for specified "owner" and that is a valid name.

Status Codes
POST /api/request_trial

This is called when a user wants to request a trial subscription.

Status Codes
POST /api/cancel_request_trial

This is called when a user wants to cancel a previously made 'create trial' request.

Status Codes
POST /api/dismiss_denied_request_trial

This is called when a user wants to dismiss a denied 'create trial' request (so that the request doens't show up in the user's gui any longer).

Status Codes
PUT /api/password

Changes the password of the user. This is called when a user is logged in, but wants to change their password.

Status Codes
POST /api/forgot-password

Sends a mail to the specified emailaddress with a one-time link that lets the user change the password. The link leads to the normal gui with a url parameter that contains the "change-password" one-time token.

Status Codes
POST /api/reset-password

changes the user's password. This is part of the "forgotten password" flow.

Status Codes
POST /api/verify-emailaddress

Verifies the user's email address. This is part of the "verify emailaddress" flow.

Status Codes
  • 200 OK -- OK, address has been verified
  • 400 Bad Request -- Token might be invalid, already used or expired
POST /api/request-email-verification

Asks the portal to send a new 'Verify emailaddress' email.

Status Codes
  • 200 OK -- OK, a new email has been sent
  • 409 Conflict -- The current user already has a pending 'verify emailaddress email', so no new email can be sent at this time.
GET /api/payment/stripe_publishable_api_key

Returns the Stripe publishable api key.

Status Codes
POST /api/payment/stripe_coupon

Returns a coupon if it exists

Status Codes
POST /api/payment/subscription

Creates a new customer and subscription in Stripe and creates a PaymentMethod in the Sesam portal. Also creates a new gdpr subscription in the Sesam Portal (using the new paymentmethod).

Status Codes
GET /api/paymentmethods

Returns the paymentmethods that this user owns.

Status Codes
POST /api/paymentmethods

Creates a new paymentmethod

Status Codes
GET /api/paymentmethods/{paymentmethod_id}

Returns information about the specified paymentmethod

Parameters
  • paymentmethod_id (string) -- The paymentmethod id
Status Codes
DELETE /api/paymentmethods/{paymentmethod_id}

Deletes the specified paymentmethod

Parameters
  • paymentmethod_id (string) -- The paymentmethod id
Status Codes
PUT /api/paymentmethods/{paymentmethod_id}

Update the paymentmethod

Parameters
  • paymentmethod_id (string) -- The paymentmethod id
Status Codes
GET /api/admin

Returns a simple htmlpage that lets portal admin perform various operations. This should probably be replaces with a proper fancy page in the normal javascript GUI, but we want the functionality quickly, and only sesam employees will ever see it.

Status Codes
POST /api/admin

Handles POSTs for the various forms on the main admin-page.

Status Codes

Returns a simple htmlpage that lets admins search for subscriptions and perform various operations on them.

Query Parameters
  • search_type (string) -- The type of items to search for.
  • query (string) -- Specifies the text to filter search for. An empty string means to display all the items of the selected type.
  • search_in_all_fields (boolean) -- If this is set to false (the default), the query-text will only be matched against a few selected fields (name and id, usually). If it is set to true, the query-text will be matched against all the fields.
Status Codes
POST /api/admin/search

Handles POSTs for the various forms on the search-page.

Status Codes
GET /api/admin/portal_administrators

Returns a simple htmlpage that display the current portal admins.

Status Codes
POST /api/admin/portal_administrators

Handles POSTs for the various forms on the portal_admins-page.

Status Codes
GET /api/admin/delete_user

Returns a simple htmlpage that lets the admin delete users

Status Codes
POST /api/admin/delete_user

Handles POSTs for the various forms on the delete_user-page.

Status Codes
POST /api/admin/throw_exception

This is a test-endpoint for throwing various exceptions. This is used in ci-tests to verify that exceptions of various types are logged correctly.

Status Codes
GET /api/admin/config_gui

Returns a gui for examining and modifying the portal configuration.

Status Codes
GET /api/admin/pre_created_subscriptions

Returns a gui for examining and modifying the "pre-created subscriptions" settings.

Status Codes
GET /api/admin/config

Returns the current runtime configuration of the Portal. This is config that is intended to be modified at runtime (as opposed to stuff like database usernames and passwords, which is specified in the sesamportal.yaml file). See the definition of the ConfigEntity model and it's child models.

Status Codes
POST /api/admin/config

Adds one or more new runtime configuration entries to the Portal.

Status Codes
PUT /api/admin/config/validation_hack_for_SubscriptionJWT

This is a dummy endpoint that is used to register the SubscriptionJWT definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_AllowedProvidersForDomains

This is a dummy endpoint that is used to register the AllowedProvidersForDomains definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_AutoJoinSubscriptionGroup

This is a dummy endpoint that is used to register the AutoJoinSubscriptionGroup definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_PreCreatedSubscription

This is a dummy endpoint that is used to register the PreCreatedSubscription definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/validation_hack_for_RateLimits

This is a dummy endpoint that is used to register the RateLimits definition, so that it can be used to validate configuration entities in the python code. The endpoint just returns a 400 response.

Status Codes
PUT /api/admin/config/{config_entity_id}

Updates the specified configuration entry.

Parameters
  • config_entity_id (string) -- The config entity id
Status Codes
GET /api/admin/config/{config_entity_id}

Returns the specified configuration entry.

Parameters
  • config_entity_id (string) -- The config entity id
Status Codes
DELETE /api/admin/config/{config_entity_id}

Deletes the specified configuration entry.

Parameters
  • config_entity_id (string) -- The config entity id
Status Codes
GET /api/subscriptions/{subscription_id}/subscription-settings

This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user has done something that changes a subscription's settings. For instance, this is used by the self-service multinode to retrieve the ip-filtering rules to use.

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • since (integer) -- Specifies that the endpoint should only return entities newer than the specified 'since' value. The since-value should be set to the value of the "_updated"-attribute in the last seen entity. See https://docs.sesam.io/configuration.html#continuation-support for details on how this works.
Status Codes
GET /api/subscriptions/{subscription_id}/pipe-settings

Returns a list of pipe-setting dicts. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user has done something that changes a pipe's monitoring requirements.

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • since (string) -- Specifies that the endpoint should only return entities newer than the specified 'since' value. The since-value should be set to the value of the "_updated"-attribute in the last seen entity. See https://docs.sesam.io/configuration.html#continuation-support for details on how this works.
Status Codes
PUT /api/subscriptions/{subscription_id}/pipe-settings/{pipe_id}

Update the settings of the specified pipe.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
GET /api/subscriptions/{subscription_id}/pipe-settings/{pipe_id}

Returns the settings of the specified pipe.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
DELETE /api/subscriptions/{subscription_id}/pipe-settings/{pipe_id}

Deletes the settings of the specified pipe.

Parameters
  • subscription_id (string) -- The subscription id
  • pipe_id (string) -- The pipe id
Status Codes
GET /api/subscriptions/{subscription_id}/revoked_json_web_tokens

Returns a list of revoked json web tokens. Note that this includes both the transient JWTs that are issued by the unified GUI to talk to the node, and the special API JWTs that are typically very long-lived. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a user's permissions have been modified, and when an api JWT has been revoked.

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • since (string) -- Specifies that the endpoint should only return entities newer than the specified 'since' value. The since-value should be set to the value of the "_updated"-attribute in the last seen entity. See https://docs.sesam.io/configuration.html#continuation-support for details on how this works.
Status Codes
GET /api/subscriptions/{subscription_id}/updated_licences

Returns a list of updated licenses. This endpoint is intended to be used by subscription sesam-nodes; these nodes needs a way to get notified when a subscription's lisence has been upgraded.

Parameters
  • subscription_id (string) -- The subscription id
Query Parameters
  • since (string) -- Specifies that the endpoint should only return entities newer than the specified 'since' value. The since-value should be set to the value of the "_updated"-attribute in the last seen entity. See https://docs.sesam.io/configuration.html#continuation-support for details on how this works.
Status Codes
GET /api/provisioning/domain

Returns information about availability of a domain name.

Query Parameters
  • fqdn (string) --
  • subscription_id (string) --
Status Codes
POST /api/feedback

Submits feedback from the feedback form to Slack

Status Codes
GET /.well-known/openid-configuration

This endpoint returns the "OpenID Provider Configuration Response", as described at https://openid.net/specs/openid-connect-discovery-1_0.html#ProviderConfigurationResponse

Status Codes
POST /api/openid_connect/token

This is the "OpenID Connect Token endpoint", as described at https://tools.ietf.org/html/rfc6749#section-3.2

Status Codes