User guide

Signing in and your first board

Oqiva lives at an address your organisation chose, which ends in /oqiva. You do not need a separate account: you sign in with the same name and password you use for the rest of your Frappe site.

The welcome page

The very first time, a short welcome page asks what to call your personal workspace. It starts as “Your name’s workspace” and you can change it later. Choose Continue (or Skip for now) and you land on your home page.

You see this page once. It will not come back on another computer or after you clear your browser.

Your first board in a minute

1. Choose New board

   The black button at the top right of the home page makes a blank board and opens it.

2. Add something

   Press R and drag on the board to draw a rectangle, then double-click it and type. That is the whole idea; the rest of this guide shows what else you can do.

3. Name it

   Click the board’s title at the top and type a name. Everything saves by itself, and the top bar says Saved when it has.

Finding your way around

The home page is where you start and where you come back to. A sidebar on the left lists where things are, and a bar across the top holds the actions you use most. Every number on the pictures below matches the list under it.

The sidebar

12345678910

1. Workspace switcher. Shows the workspace you are in and your role. Open it to change workspace or to make a new one.
2. Home. The boards you worked on most recently in this workspace.
3. Recent. Everything you have opened lately.
4. Favorites. Boards you starred. The star appears when you point at a board.
5. Shared with me. Boards other people gave you access to, from any workspace.
6. Templates. The template gallery, with search and categories.
7. Notifications. Mentions and replies. The same list as the bell on a board.
8. Archive. Boards you put away without deleting them.
9. Trash. Deleted boards, kept for 30 days by default, where you can restore them or delete them for good.
10. Projects. Folders for boards. Use the plus to add one.

The top bar

1234

1. Search. Finds boards by name and comments by their text. Press Ctrl + K from anywhere.
2. From template. Opens the template gallery.
3. Import. Brings in a board file (.oqiva.json) as a new board.
4. New board. A blank board in the current workspace.

On a phone or a narrow window the sidebar becomes a drawer behind a menu button, and the top bar’s buttons tuck into a menu.

Workspaces and projects

A workspace is the space for a team, a client or just you. Everyone has a personal workspace, and you can belong to as many others as you are invited to. Inside a workspace, projects group related boards, like folders. A board can also sit at the top level with no project.

Making and organising boards

There are three ways to get a new board, and a handful of things you can do with it once it exists.

Three ways to start

• New board gives you an empty infinite canvas.
• From template (or Templates in the sidebar) opens a gallery of about forty ready-made boards. Use the search box or the category buttons, then choose Use template. You get your own copy, and the original is never changed.
• Import reads a board file (.oqiva.json) saved from Oqiva earlier, here or on another site, and makes it a new board. Pictures are not carried in the file.

Looking after a board

Point at a board on the home page and two small buttons appear on its card: a star to make it a favorite, and a … menu.

• Rename, or click the title while you are inside the board.
• Duplicate makes a copy to try ideas on.
• Move puts it into a project, or back at the top level.
• Archive hides it without deleting it. It stays in Archive.
• Move to Trash deletes it, but not yet: it stays in Trash for 30 days (your administrator can change that) and can be restored with one click. Delete permanently in Trash removes it for good, and asks you to type its name first.

Finding a board

Press Ctrl + K and type. Search looks at board names and at the text of comments, and only ever shows what you are allowed to see. Switch between cards and a list with the two small buttons at the right of the board list.

The canvas and its toolbar

A board is an endless canvas. Everything you add goes on it, and the toolbar floating at the bottom is how you add it. Here is every button, left to right.

1234567891011121314151617181920212223

1. Select V. Pick, move, resize and rotate things. This is the tool you are in most of the time.
2. Hand H. Drag the board around. Holding Space does the same for as long as you hold it.
3. Draw. A menu with the pen, highlighter, eraser and laser pointer, and the board’s hand-drawn look.
4. Shape library Shift + S. Ready-made shapes for architecture, flowcharts, wireframes and more, with a search box.
5. Shapes. Rectangle, ellipse, triangle, diamond and other basic shapes. The last one you used is remembered.
6. Lines and arrows L. Straight, elbow and curved connectors with your choice of arrowheads.
7. Text box T. Free text with no shape around it.
8. Sticky note N. A coloured note. Press Tab while writing one to start the next one beside it.
9. New mind map M. Starts a mind map in the middle of what you are looking at.
10. New flowchart Shift + F. Starts a flowchart with a Start step and a first step.
11. Create with AI. Describe a diagram and have it drawn. It tells you plainly if your administrator has not turned it on.
12. Frame F. A named section of the board. Moving a frame carries what is inside it.
13. Comment C. Click a shape, or any place, to leave a comment there.
14. Add picture. Upload a PNG, JPEG, GIF or WebP. You can also paste a picture from your clipboard.
15. Table. Choose how many rows and columns; double-click a cell to type in it.
16. Icons and emoji. A picker for icons and emoji to place on the board.
17. Jump to a section. Lists the frames on the board so you can go straight to one.
18. Undo. Takes back your own last step. Ctrl + Z.
19. Redo. Puts it back. Ctrl + Shift + Z.
20. Zoom out. Also Ctrl + -, or Ctrl and the mouse wheel.
21. Zoom level. Shows the current zoom. Open it to fit everything on screen, set a zoom, or show or hide the small map.
22. Zoom in. Also Ctrl + +.
23. Canvas settings. Infinite canvas or a fixed page size, background colour, grid, and hand-drawn outlines for the whole board.

Moving around

• Pan: scroll, or drag with the Hand tool, or hold Space and drag.
• Zoom: hold Ctrl and scroll to zoom at the pointer, use the plus and minus buttons, or pinch on a touch screen. Shift + 1 fits everything on screen, and Ctrl + 0 goes back to 100%.
• The small map in the bottom corner shows the whole board and where you are. Click it to jump. Hide it from the zoom menu if you do not want it.

The shape library

Press Shift + S to open the library. Click a shape to add it near the middle of your view, or drag it exactly where you want it. Type in the search box to find one by name.

Shapes, text, lines and pictures

Click anything to select it. A bar appears above the board with exactly the things you can change about it, and the bar differs by what you picked. For an ordinary shape it looks like this:

12345678910111213

1. Shape. Turn it into a different shape without losing its text.
2. Link. Attach a web address or another board to it. People can click through.
3. Comment. Start a comment pinned to this shape.
4. Arrange. Bring to front or forward, send backward or to back, group and ungroup.
5. Align. Line up several shapes (left, centre, right, top, middle, bottom), space them evenly, make them the same size or swap places.
6. Rotate and flip. Quarter turns and mirror images.
7. Fill. The colour inside the shape.
8. Border. Colour, thickness and style of the outline.
9. Text. Font size, bold, italic, underline, colour and alignment.
10. Hand-drawn style. A sketchy outline for this shape only.
11. Transparency. How see-through it is.
12. Corner radius. Sharp or rounded corners.
13. Copy format. Pick up this shape’s look, then click another shape to give it the same.

Putting things on the board

• Shapes: choose one and drag on the board for the size you want, or just click for a standard size. R is a rectangle and O an ellipse.
• Text inside a shape: double-click it, or select it and press Enter. Press Esc to finish. Text grows the shape when it needs room.
• Text on its own: the Text box tool, then click where it should go.
• Sticky notes: N, then click. Notes come in several colours.
• Pictures: the picture button, or paste one. Pictures are stored privately with the board, so only people who can see the board can see them.
• Tables: pick a size, then double-click a cell to type. Tab moves to the next cell.

Selecting, moving, resizing

• Drag a shape to move it. Coloured guide lines appear to help you line it up with others; hold Alt to move freely.
• Drag the handles on the corners and sides to resize, and the round handle above it to rotate.
• Drag on an empty part of the board to draw a selection box round several things, or hold Shift and click to add them one by one. Ctrl + A selects everything.
• Arrow keys nudge by one step, or ten with Shift. Ctrl + D duplicates.

Lines and arrows

Choose the line tool (L) and drag from one shape to another. The ends stick: move either shape and the line follows. There is a shortcut too: point at a shape and small arrows appear around it. Click one and Oqiva adds a connected copy in that direction.

• Choose straight, elbow or curved lines, and the arrowheads at each end, from the line menu.
• Double-click a line to give it a label.
• Drag an end to move it or attach it to a different shape.

Frames and sections

A frame is a named rectangle behind other things, for dividing a board into sections. Double-click its name to rename it. When you move a frame, whatever sits inside it moves too. Jump to a section on the toolbar lists all frames.

Mind maps

A mind map in Oqiva is a real tree, not a pile of shapes with lines: it arranges itself, and each node knows its parent. That makes it quick to grow and easy to rearrange.

Building one

1. Start the map

   Press M (or use the mind map button). A central idea appears in the middle of your view, ready for you to type over.

2. Grow it from the keyboard

   Tab adds a child. Enter adds a sibling after the selected node. Shift + Tab moves a node up a level. Use the arrow keys to walk through the tree, and Alt + Up or Down to reorder.

3. Fold what you are not discussing

   Press - to collapse a node (a small badge shows how many nodes are hidden) and + to open it again.

The mind map bar

Select a node and the bar changes to the things that matter for a map:

123456789

1. Add a child Tab. A new branch growing from the selected node.
2. Branch colour. Colour for this node and the branch below it.
3. Marker. A small icon or coloured dot on the node.
4. Text size. Size of the text for this node.
5. Note. A longer note kept behind the node.
6. Layout. Spread branches left and right of the centre, or all to the right.
7. Focus on this branch. Dims everything else so you can concentrate on one branch.
8. Outline. Opens the whole map as an indented list you can edit like a document.
9. Delete. Removes the node and everything that grows from it.

More you can do

• Drag a node onto another to make it a child of that one, or between siblings to reorder.
• Paste a list. Copy an indented or bulleted list (or one with # headings) and paste it on the board: it becomes a map. Paste it while a node is selected and it becomes that node’s children.
• Cross-links join two branches that are related but not parent and child: select two nodes (hold Shift and click) and the bar offers to link them.
• Press F2 or double-click to edit a node’s text, and Shift + Enter for a new line inside it.

Flowcharts

Flowcharts work like mind maps in one important way: you describe the structure and Oqiva looks after the layout. Steps are joined as you add them, and arrows find their own way round other steps.

Building one

1. Start

   Press Shift + F. You get a Start step and a first step, joined. Type to change the text.

2. Add steps from the keyboard

   Enter adds the next step after the selected one. D adds a decision, T a start or end, I an input or output. With an arrow selected the same keys insert a step in the middle of it.

3. Or use the plus buttons

   Select a step and small plus buttons appear on the sides its arrows can leave from. Click one and choose what kind of step comes next.

The flowchart bar

123456789

1. Add next step Enter. A step joined after the selected one.
2. Step type. Start or end, process, decision, input or output, or a junction.
3. Text size. Size of the text in the step.
4. Add another output. For a decision: another branch (Yes, No, Option 3…).
5. Edit text F2. Type in the step.
6. Tidy up. Lays the whole chart out again in a single undoable step.
7. Flow left to right. Turns the chart sideways, or back.
8. Number the steps. Shows a number on every step.
9. Delete. Removes the step and joins its neighbours up.

Decisions

A decision’s outputs are labelled Yes, No, Option 3 and so on, in the order you add them. Double-click a label to rename it. Add another output gives a decision one more branch.

Tidy up

Drag any step where you want it and Oqiva remembers. When the chart gets untidy, Tidy up lays out everything in one go, and one Ctrl + Z puts it back as it was.

Drawing and the whiteboard tools

For sketching, annotating and pointing, open the Draw menu on the toolbar. The tools can be used alongside shapes and diagrams on the same board.

When a drawing tool is active, a small bar appears at the top of the board:

12

1. Pen colour. Choose the colour of the pen or highlighter.
2. Pen width. Type a width, or open the presets next to it.

Each stroke is one object, so you can move, resize, rotate, copy and delete it like anything else. Everything you draw is saved with the board. The Draw menu also has Hand-drawn outlines, which gives every shape and line on the board a sketchy look.

Working together

Everyone who has a board open sees it change as it changes, and nobody has to take turns.

What you see

• Who is here: a round avatar for each other person at the top of the board.
• Their pointer and selection in their own colour, with their name, so you can tell who is editing what.
• Changes as they happen: moves, edits and drawings arrive while the other person is still working.

When two people change the same thing

Edits made at the same time are merged, not overwritten. If you both move the same shape, the last move wins; if you both change different things, you both keep your changes.

If your connection drops

Keep working. The top bar will say you are offline, your changes are kept on your device, and they merge and save when you are back. You will not lose them by closing the tab either: they are still there next time you open the board on that device.

Undo is your own

Ctrl + Z takes back your own last step, never someone else’s. Big actions (a pasted outline, a whole flowchart, an AI diagram, restoring a version) are a single step, so one undo reverses all of it.

Sharing and who can do what

Choose Share at the top right of a board. You can give access to people, or to anyone who has a link.

People

Type a name or email address, choose what they may do, and press Share. If they have no account yet, they are invited and get access when they join. Change someone’s level or remove them from the same list at any time. It takes effect at once, even if they have the board open.

Sharing a board never gives anyone the right to delete it, move it, or share it onwards. Those stay with the people who run the workspace and the person who made the board.

Links

1. Choose what the link allows

   View, comment or edit, and when it should expire.

2. Decide who can use it

   By default, people need to be signed in. For a view link you can tick Anyone with the link can look, even without an account.

3. Copy it now

   The link is shown once, when you create it. Oqiva keeps only a scrambled form of it, so it cannot show it to you again. If you lose it, make a new one.

You can end any link whenever you like, and it stops working immediately.

Comments and notifications

Talk about the work on the work, so feedback stays attached to what it is about.

1. Press C and click

   Click a shape to attach the comment to it, or click an empty place on the board.

2. Write it

   Type your comment. Type @ and start a name to mention a teammate from the people on the board. Press Ctrl + Enter or choose Comment to post it.

3. Follow it up

   People reply in the thread. Choose Resolve when it is dealt with, and it moves to the Resolved tab. Open the Comments button at the top left of a board to see every thread, and Show on board to find where one sits.

• A pin follows its shape when the shape moves, and says so if the shape was deleted.
• You can edit or delete your own comments. Workspace admins can delete anyone’s.
• When someone mentions you or replies to you, the bell at the top shows it. The Notifications page in the sidebar keeps the full list, and you can mark everything as read.

Version history

Oqiva keeps versions of every board as you work, so a big change is never a risk.

• Automatic versions are saved about every ten minutes while you are changing a board. The newest fifty are kept.
• Named versions: open History, type a name (“Before the re-org”) and press Save. Named versions are kept until you remove them.
• Pin a version to make sure it is never cleaned up.
• Look first: choose a version to see exactly how the board looked, without changing anything.
• Restore: bring that version back. The board as it is now is kept, and restoring is itself a single step you can undo with Ctrl + Z.

Exporting and importing

Choose Export at the top right of a board.

Select some shapes first and the menu also offers Export the selection, which exports only those.

Creating diagrams with AI

If your administrator has turned it on, you can describe a diagram and have it drawn. It is a way to get a first draft quickly, which you then edit like anything else.

1. Open it

   Choose the sparkles button on the toolbar.

2. Choose a kind

   Flowchart for steps and decisions, Architecture for systems and how they connect, Mind map for a topic and its branches.

3. Describe it

   Write a sentence or two, up to 2,000 characters. Say what the parts are and how they relate. The example buttons show the idea.

4. Create the diagram

   It takes a few seconds. The diagram appears in free space on your board, selected, in one step: Ctrl + Z takes it away.

• An architecture diagram comes as ordinary shapes in named columns for each tier, joined with connectors, so you can edit it like any other shapes.
• A flowchart or mind map is a real one, with all the keyboard commands above.
• If the answer cannot be used, nothing is drawn and you see a message. Try describing it a little differently.
• You can make up to ten requests a minute.

If the button says the feature is not turned on, ask your administrator. They can turn it on in Oqiva Settings.

Keyboard shortcuts

Press ? on any board to see this list. Shortcuts do nothing while you are typing text.

When something looks wrong

Still stuck? Write to support@oqiva.in with what you were doing, what happened, and your browser, and we will help.

For administrators: installing Oqiva

Oqiva is a Frappe app. You need a Frappe 16 bench with MariaDB and Redis, the bench’s socket server (for live editing) and at least one background worker (for AI diagrams).

cd ~/frappe-bench
bench get-app https://github.com/mohitjosii/Oqiva.git
bench --site your-site install-app oqiva
bench build --app oqiva
bench --site your-site migrate
bench restart

Then open https://your-site/oqiva. The first visit by each person creates their personal workspace.

Settings you may want to change

Open Oqiva Settings in Desk to set the fair-use limits (objects per board, board size, boards per workspace, picture storage), how long the Trash and automatic versions are kept, and whether the Oqiva User role is granted on a person’s first visit.

Turning on AI diagrams

1. In Oqiva Settings, choose the provider: Anthropic or Google Gemini.
2. Paste the provider’s API key. It is stored encrypted and is never shown to users.
3. Leave the model blank for the default, or enter one that belongs to that provider.
4. Make sure a background worker is running (bench start does this for development).

Keeping it healthy

Back up with files (bench backup --with-files), because pictures are stored as private files. After every upgrade run bench build --app oqiva, bench migrate, and restart everything, including the socket server.

Frequently asked questions