Lenses and boards (TIPP Lenses)

The page is called “Lenses and boards” on screen (TIPP Lenses). It is the one list of everything built with TIPP lenses and boards: lenses (saved data views) and boards (dashboards made of tiles, where each tile shows a lens). You can open from here the active lenses and boards that you are allowed to open. Synergy administrators can also create, edit, export and import them. It is found under the TIPP menu, Reports tab, General section. The source does not state a CORE or PRO requirement for this page, so check your licence if it does not open.

Before you start

• The page follows TIPP page security. If your user is not allowed, access is denied.
• Each lens and board can carry access restrictions, such as a minimum security level or a role. The list only shows the lenses and boards you are allowed to open. A lens or board you may not open is not listed for you.
• Only members of Synergy role 0 (administrators) see the buttons New lens, New board, Export and Import, the tick boxes and the Edit link, and only they can use Show inactive. Other users see a read-only list of the active lenses and boards they may open.
• Administrators see every row in the list, because they maintain them, including rows they themselves may not open. For such a row the Name is plain text instead of a link, so you do not end up on an Access denied page. Use Edit on that row to maintain it.
• To import, you need an export file (.json) written by Export on this or another Synergy site.

How to find and open a lens or board

1. Open Lenses and boards. The list shows the active lenses and boards you may open, together, sorted by Name, with 50 rows per page.
2. To narrow it, type part of a name in Name or part of the title in Caption, then click Search. Both are contains matches. Click Reset to clear the criteria.
3. Click the Name of a row. A lens opens its lens page, a board opens its board page. The row’s Type column tells you which one it is.

How to create a lens or board (administrators)

1. Click New lens or New board. A blank maintenance page opens.
2. Fill it in and save there. Afterwards the new item appears in this list.

How to edit a lens or board (administrators)

1. Find the row and click Edit at the end of the row. The maintenance page of that lens or board opens.
2. To see inactive ones, tick Show inactive and click Search.

How to export lenses and boards to a file (administrators)

1. Tick the rows you want in the first column. The links “all on this page” and “none” above the list tick or untick every row on the current page.
2. Click Export. If nothing is ticked you get the message “Tick the lenses and boards to export first.”
3. Your browser downloads a .json file and the page stays where it is. With one item selected the file is named TIPP_Lens_[name].json or TIPP_Board_[name].json. With several, it is named TIPP_Lenses_ followed by the date and time.
4. When you export a board, the lenses used by its tiles are added to the file automatically, because a board is empty without them.

How to import lenses and boards from a file (administrators)

1. Click Import. A panel “Import lenses and boards from a file” opens.
2. Click the file box and choose the .json export file.
3. Tick Replace existing only if a lens or board with the same name that already exists here must be overwritten. Otherwise those are skipped.
4. Click Import file. Click Cancel to close the panel without importing.
5. Read the green result: “Imported [file name]: [n] added, [n] replaced, [n] skipped.” followed by a line for each item, such as “Added lens ‘[name]’.” or “Replaced board ‘[name]’.”.
6. Check roles, functions and divisions afterwards. They are copied as they are, so on sites that are set up differently they may need adjusting on the maintenance page.

Screen guide

Search criteria

• Name: part of the technical name. Contains match.
• Caption: part of the title users see. Contains match.
• Show inactive: administrators only. Ticked shows inactive lenses and boards too. Unticked (default) shows active only. Other users always see active only.

Buttons

• Search: applies the criteria.
• Reset: clears the criteria.
• New lens, New board: open blank maintenance pages. Administrators only.
• Export: downloads the ticked rows as a file. Administrators only.
• Import: shows or hides the import panel. Administrators only.
• Import file: runs the import of the chosen file.
• Cancel: closes the import panel.

List columns

• Tick box (administrators only): select the row for Export.
• Type: Lens or Board.
• Name: the technical name. Click it to open the lens or board. For an administrator who may not open that lens or board, the name is shown as plain text without a link.
• Caption: the title.
• Description: the explanation entered when it was made.
• Active: Yes or No. Inactive ones are only listed for administrators who tick Show inactive.
• Modified: date and time of the last change.
• Edit (administrators only): opens the maintenance page.

Messages and what to do

• “Tick the lenses and boards to export first.” Tick at least one row.
• “None of the ticked rows exist any more. Search again.” Someone deleted them. Click Search to refresh the list.
• “Choose an export file first.” Pick a file before clicking Import file.
• “That file is not readable as JSON: [detail]”. The file is damaged or is not a JSON file. Use a file written by Export.
• “That file is not a TIPP lenses export. Export writes a file that starts with “format”: “tipp-lenses”.” Use a file written by Export.
• “That file was written by a newer TIPP (format version [x]); this site reads version [y]. Update TIPP here first.” Update TIPP on this site, then import again.
• “The file contains no lenses or boards.” The file is empty of items.
• “Nothing was imported. Fix the file and try again:” followed by the problems. Nothing is changed when any item is wrong. Problems can be: a lens or board with no name, “the name is longer than 50 characters”, “the name may contain letters, digits, dot, underscore and hyphen only”, “appears twice in the file”, a lens with “no query”, a board with “no tiles”.
• “Skipped [lens or board] ‘[name]’: it already exists here. Tick ‘Replace existing’ to overwrite it.” Import again with Replace existing ticked if you want to overwrite.
• “Board ‘[name]’ uses lens ‘[lens]’, which is neither in the file nor on this site. That tile stays empty until the lens exists.” Import or create the missing lens.
• “Import failed, nothing was changed: [detail]”. The import is all or nothing. Fix the cause and retry.
• If the lists cannot be read, the table is hidden and the error text is shown instead.

What you cannot do here

• You cannot design a lens or board on this list. Use New lens, New board or Edit, which open the maintenance pages.
• Users who are not administrators cannot create, edit, export or import, and cannot see inactive items.
• You cannot see lenses and boards you are not allowed to open (unless you are an administrator). To get access, ask an administrator to adjust the restrictions on that lens or board in its maintenance page.
• You cannot delete a lens or board from this page.
• Import never changes who created an item: the importing site becomes the creator.

Related pages

• Lens page: opened by clicking the name of a lens.
• Board page: opened by clicking the name of a board.
• Lens maintenance and Board maintenance: opened by Edit, New lens and New board. They return to this list.

Common questions

What is this page for? It lists the lenses and boards you may open in one place so you can open them, and so administrators can create, edit, export and import them.

What is the difference between a lens and a board? A lens is a saved data view. A board is a dashboard of tiles, and each tile shows one lens. The Type column shows which a row is.

Why do I not see New lens, New board, Edit, Export or Import? These are only shown to members of Synergy role 0 (administrators).

Why is a lens or board I know about missing from my list? Lenses and boards you are not allowed to open, because of a minimum security level or a role restriction on them, are not listed for you. Ask an administrator to check the restrictions on it.

Why is a Name not a link for me as administrator? The lens or board has access restrictions that you yourself do not meet. The row is still listed so you can maintain it with Edit, but you cannot open it, so there is no link.

Why can I not see an inactive lens or board? Only administrators can see inactive ones, by ticking Show inactive and clicking Search.

What does clicking the Name do? It opens the lens or board itself. It does not open maintenance. Use Edit for that (administrators).

How do I copy lenses to another Synergy site? Tick them, click Export, and then on the other site click Import and choose the downloaded file.

Do I need to export the lenses of a board separately? No. Exporting a board adds the lenses its tiles use.

What happens if the name already exists on the importing site? It is skipped, unless Replace existing is ticked, then it is overwritten.

Why did the import say nothing was imported? At least one item in the file failed a check, such as a bad name, a missing query or a board without tiles. Nothing is saved until the whole file is valid.