⠀⠀⠀⠀This is a complementary guide to the OpenMAINT Installation Guide, with
the aim of documenting the usage openMAINT in a simple manner, so that I can help the people that end up working with openMAINT figure out
how things work, even after I finish my internship. (Yes, dear reader, this isn't entirely selfless).
⠀⠀⠀⠀Anyways, openMAINT can be quite hard and confusing to understand at first, but I assure you that it really isn't. There are a lot of things in the main screen which might make your head spin, but if you just relax, read this manual, and abstract yourself from what isn't exactly needed, everything will be clearer.
- Previous Knowledge
- User Menus Overview
- Data Management
- Administration
⠀⠀⠀⠀Before actually getting into the ins and outs of openMAINT, you should understand some core concepts about openMAINT and Databases, that will make your life much, much easier.
⠀⠀⠀⠀Starting off with some notions about CMDBuild and openMAINT. I'll be quoting something I've written in Installation Guide - Observations
OpenMAINT is one of the many apps built on top of CMDBUILD, that handles the maintenance, both preventive and corrective, of the assets registered in it. Now, even though it is technically a fully separate app built on top of CMDBuild, it still relies heavily on it to the point where it can be considered almost a CMDBuild addon/framework. This means that the two are virtually the same, as far as the user input and experience goes. OpenMAINT offers a buit-in organised structure for asset maintenance, which should not be altered, and a bunch of pre-built reports, workflows and custom pages to be used. Essentially, people made it amazingly simple to handle maintenance by setting up and creating everything related to maintenance for us.
⠀⠀⠀⠀As mentioned, the structure of openMAINT is not to be altered, just built upon. By the end of this guide though, you'll be able to hide, show, and move everything around in a way that doesn't break the program.
⠀⠀⠀⠀At last, you should also know what a database is, as well as database tables, entity relationships and entries. Don't worry about understanding everything in-depth, you just need to know the general gist of how it works, and I'll do the rest.
⠀⠀⠀⠀Right when you get into your openMAINT website, you're going to see this screen.
⠀⠀⠀⠀As the administrator of openMAINT, you can simply type admin; admin (USERNAME; PASSWORD) into the screen, and you'll be logged in, and your default menu will be showing you everything. What's a menu you ask? Essentially your navigation screen. Every user that you define in the settings may have its own menu, needs to have a group and permissions assigned, which will allow them to see different things based on what they need to see. For instance, you wouldn't want a forklift operator messing with the financial records of your company, would you? Using a menu, you can restrict them to only be able to see the corrective maintenance request forms, so that they don't mess with anything else. We'll learn to do this later on.
⠀⠀⠀⠀After logging in, you'll be presented with the following screen:
⠀⠀⠀⠀The navigation tab present on the right side of the screen is the place you should know the best. It, just like any other navigation tab, allows you to browse through different assets, items, reports, pages, whatever you want, and allows you to select them to add more entries.
⠀⠀⠀⠀The editing tab is the main panel of the application, it allows you to create new entries in classes and also allows you to see them. Pretty much how you'd imagine a DBMS (Database Management System) to act, showing you the database tables and allowing you to add entries to them.
⠀⠀⠀⠀This is more of an administrative tab that is pretty "default". The first item is just a shortcut for the scheduler, something we will talk about later, the second one is the user you're logged in as, the third one is the notifications menu, the fourth is the administrative menu, something we will talk about soon, and the last one is the log out button.
⠀⠀⠀⠀By the way, you must've been worried about your password being admin, and since we're now talking about the tools tab, you can change that in the user settings.
*This section will have less images due to the sheer amount of information it needs to convey, so it is recommended that you follow along with your openMAINT instance.
⠀⠀⠀⠀The default folder structure is pretty handy to understand what does what, and is (arguably) optimally divided accordingly to functionality, and we'll use it to understand what does what. (We're only covering Facilities & Assets, Basic Archives and the Maintenance Management here, because the rest has pretty much the same logic as these three.)
⠀⠀⠀⠀First off, we need to understand what a Class is, and then we can go on and explain everything else. A Class is the same as a Database Table mixed with the inheritance of classes from programming theory. If you're not a programmer and don't know what I'm talking about, it's okay, it just means that every table can have other tables that stem from it, and have all of their attributes. [If a class "Battery" was a superclass (main table) and had a child class (table stemming from it) called "Forklift Battery", then the latter would have all the attributes of the Battery].
⠀⠀⠀⠀Now, if you're confused about what an attribute is, imagine that every class (table) is an excel grid. The attributes are the headers :) If needed, Go back to previous knowledge and check out the links about databases I referenced.
- Classes
- Superclasses *In the data management module, these show all the entries in the classes associated with them.
- Reports *These are dynamically loaded, rendered and stored using Alfresco.
- Custom Pages *Essentially, custom webpages connected to the database using JS. openMAINT created them all for us.
- Processes *Programmed algorithm workflows that run tasks.
- Dashboards *In-App graphs and visual indicators, dynamically loaded according to the database.
- Scheduler * The Scheduler
⠀⠀⠀⠀The Facilities and Assets folder is the place where you'll register every asset you want, aswell as its locations, systems, etc. It is divided in two major groups, the "Locations" and "Elements.
⠀⠀⠀⠀The Locations folder contains the classes that define the buildings, floors, units, complexes, rooms, etc... of your company. You need to fill out the information from top to bottom, making sure to fill in all the location data for each of them to avoid any issues during maintenance. No, you can't skip any of them.
⠀⠀⠀⠀The Elements folder contains the classes that define the your Configuration Items (CI). This is a common term that will pop up here and there in openMAINT, and it just means "The things you have in your company that may need maintenance. Simple as that!
They're really neatly organised into devices, finishings, items, machineries, outdoors, etc...
⠀⠀⠀⠀This one is pretty straightforward. It's where you define your employees, suppliers and companies; You're free to add any other classes here, but you'll have to manually create their relations.
⠀⠀⠀⠀This is the most complicated one out of the three, so it will be divided into three sections: The Maintenance Configuration and the Corrective and Preventive Maintenances. For both of these, you need to have at least one item configured (so you can perform maintenance on it), the location section of the facilities needs to be configured, an employee, and optionally, a category, subcategory, team, equipment, etc...
⠀⠀⠀⠀Before diving into the how-to's, lets check out the maintenance configuration classes that exist and are used for maintenance, which can all be found within the folders under "Maintenance/Maintenance Configuration"
-
Categories and Subcategories are just identifiers for types of maintenance that might exist. For instance, you can create a "General Maintenance" category, and then a "Machinery" subcategory linked to it, and it will then be merged (during the corrective maintenance request, we'll get there) into "General Maintenance - Machinery". This is useful for what we'll talk about next, the Corrective Assignments.
-
Corrective Assignments are simple lookup tables where you can assign a category and subcategory to a given team, so that they can perform the maintenance tasks assigned to it. Whenever you select their category anywhere, the team boxes will be automatically filled with the correct team.
-
Teams are just assigned groups of people (managed outside the app), run by a supervisor, that can be set in order to perform tasks. Once a team is created, you can expand it in the editing tab and check its process calendar to look up future and past maintenance jobs that they have to do.
-
Maintenance/Knowledge Base/Topics are instructions, useful tips or general knowledge on how to perform corrective maintenance of a certain registered category.
-
CI Subsets are automatically generated clumps of entries that belong to the same type. This can all be changed in the CI Subset attribute of their classes. This exists because often you'll have 30 different... phone chargers, for instance, and the maintenance procedures will be the same for all of them, so a subset of "Phone Chargers" is automatically created once you add an entry to "Phone Chargers" to assign them all to one page of the Maintenance Manual.
-
Maintenance Manuals can be understood as virtual "Preventive Maintenance Manuals" for certain buildings, the pages of which are the different CI Subsets, mapped to a checklist and notes of how to perform maintenance on the CI Subset.
-
Preventive activity definitions are the tasks to perform while underdoing the execution of a preventive plan.
-
Preventive Plans are the configurations of periodic preventive maintenance jobs on certain CI Subsets.
⠀⠀⠀⠀To properly create a corrective maintenance workorder, you first need to roughly configure the facilities, the employees, the assets, the categories and subcategories that you're going to have (Optionally, also add knowledge bases for the categories of maintenance you have). After that, just go into the corrective maintenance custom page and start your work order! If you're worried that your users might be able to assign the workorders, execute them, and more, refer to the users and permissions section.
⠀⠀⠀⠀To properly schedule the preventive maintenance of a CI Subset, you can use use the Preventive Planner. This is a calendar-like custom page where you can follow the formulary in order to schedule maintenances of assets for a team.
⠀⠀⠀⠀Simply create a new entry in the planner, and follow the formularu from top to bottom, and it should all set into place! To make things simpler, you can click on the magnifying glass icons inside every text boxes, to indirectly access the tables for whatever you need, and add the entry there. Once you're finished, you should have something like this showing:
⠀⠀⠀⠀With the scheduler you can schedule other types of activities not mentioned here, be it letting the supervisors know about something on some day, scheduling meetings, expiring contracts, whatever really, betweeen groups and users. You can set up e-mail notification templates to complement it, and it can also be shown in a month-days calendar!
⠀⠀⠀⠀To "create an entry" is the same as "registering an item or asset or employee or ... adding them to a table". This is the basis of openMAINT, and you will see that literally everything we do is quite literally adding entries into a table that is related to other tables through One-To-Many entity relations. Thinking like this will simplify everything tenfold.
⠀⠀⠀⠀To add entries into a table, just click the + Add Card, or 🡆 Start Maintenance or whatever the blue button at the top of the screen says, follow the steps, and hit save.
⠀⠀⠀⠀To edit an entry, all you need to do is open it, and click on the editing pen. This will bring up the same display as the card creation one, and you can simply edit the values as you find fit.
⠀⠀⠀⠀To print the entries you can either select the ones you want to print (Using the multiselect tool, present in the menu acessible through the three horizontal bars), select one of them (By expanding it and printing it there) or just print everything (By clicking in the print icon at the top of the page). Either way, it's all pretty straightforward; Find the printing icon, and hit it.
⠀⠀⠀⠀It should be noted that the information that will appear as the attributes in the printed table will be the same as shown in the table, in the editing panel.
⠀⠀⠀⠀To delete an entry, expand it as you would for editing, and click on the trash bin icon.
! This might not work if the card has defined relations that inhibit it from doing so. !
⠀⠀⠀⠀A generic card will look like this most of the time:
⠀⠀⠀⠀As you can see, it is divided into many different sections; Card, Details, Notes, Relations, History, Emails, Attachments and Schedules. Let's go over all of these.
-
The Card section shows all the raw information about a card.
-
The Details section shows all the extra information related to a card. This can be set if you edit the card, and, in the sidebar, add whatever details you want into the table.
-
The Note section shows any extra notes added by the editors
-
The Relations section shows the Domain of the entry. We'll talk more about these later on, but they're the database entity relations between classes.
-
The History section records any changes made to the card.
-
The Emails section records any emails sent during the maintenance, edition, scheduling, etc... of the card.
-
The Attachments section records, with the help of Alfresco, all the attachments created related to the card.
-
The Schedules section records data related to the Scheduler and the card.
⠀⠀⠀⠀To use reports, you simply need to click on the "files" with the report symbol. Sometimes openMAINT will display a menu asking you for time data, so as for you to specify a certain range of time to get the reports from. The exact same applies to dashboards!
⠀⠀⠀⠀Views are essentially new tables that allow you to join other classes and view their contents as one. To create one, simply go to the more options menu and click "Create View", and follow the menu selecting the classes you want to join, in order to create it. You can then set the permissions for certain users to view only these views instead of the classes themselves, which is really useful.
⠀⠀⠀⠀To switch from the Data Management view into the Administrative view, you're going to have to have to look at the Tools Tab and click on the Administrative Menu button. This will take you into a view that looks like this:
⠀⠀⠀⠀Everything in this view is pretty much the same as the Data Management view, except save for the Navigation Tab, that is slightly different. Instead of a menu view with everything sorted into folders logically and neatly, we have a Inheritance Class Divisions and Settings. This means that everything shown in there doesn't accurately translate to the menu you see, and instead, everything is divided into different folders, referring to what type of "file" they are, and inside those, they're divided based on a hierarchical system, where the child classes are nested under the parent classes, and their child classes are nested under them, and so on. This applies to classes, processes, menus, settings, users, etc.
⠀⠀⠀⠀Classes are the basis of openMAINT, and as such, they're all listed in first place. These are divided into two groups, the Simple classes (Classes with no inheritance, no relations or domains, data history, mechanisms, etc; heavily optimised for HUGE amounts of raw data, like data received from monitoring systems or IP addresses connected to an entire company's network, whatever really.) and the Standard classes, which are common CMDBuild classes, with relations, history, references and not really optimised for massive amounts of data.
⠀⠀⠀⠀We're only going to be talking about the specifics of Standard classes, but don't worry, because simple classes only have properties and attributes, which means that they have everything that the standard ones have.
⠀⠀⠀⠀Before advancing any further, I'd like to talk about superclasses and their children. As you're going to see next, while creating a class, you have the option of making it a superclass. This will mean that the next time you create a class, it will appear as an option to be inherited, and if you so choose to make it inherit the parent class, openMAINT will automatically add all the domains and attributes of the parent class, into the child, and these will be impossible to remove.
⠀⠀⠀⠀This is where the "identity" of the class will be created; The main properties to be set here are the Name, Description, Inherits from, Superclass, Type and Active fields, which function as such.:
⠀⠀⠀⠀• "Name" sets the class's identifier. This identifier is unique and used to pinpoint the class internally.
⠀⠀⠀⠀• "Description" sets the name that the class will use to display itself. It's the actual "Name" of the class.
⠀⠀⠀⠀• "Inherits from" sets the parent of the class that is being created. The current class will inherit all the attributes of the parent.
⠀⠀⠀⠀• "Superclass" is a toggle for making the class a superclass, allowing it to have child classes inheriting all of its attributes.
⠀⠀⠀⠀• "Type" sets the class type, either Simple or Standard.
⠀⠀⠀⠀• "Active" is a toggle to activate or disable the class, to make it either usable or unusable.
⠀⠀⠀⠀We're going to skip over a bunch of property settings since they're usually not needed and this manual is already a pain to write as it is. If you scroll down through the property settings you'll find the Data cards sorting, Attribute groupings and Icon settings. These work as such:
⠀⠀⠀⠀• "Data cards sorting" - Defines the order that the cards are displayed in, based on their attributes.
⠀⠀⠀⠀• "Attribute groupings" - Defines how the attributes are grouped under the cards section. This one is really just used for aesthetic purposes.
⠀⠀⠀⠀• "Icon" - Defines the icon to display every entry of this card in the geographical map.
⠀⠀⠀⠀The attributes are just the headers for every row in the table, which define what types of data can go into them. They have some properties when being created, and we'll get to know them now:
⠀⠀⠀⠀• Name is the attribute name, which just like the class names, is used to identify them internally.
⠀⠀⠀⠀• Description is the attribute description, which is displayed to the user so that they can identify the attribute.
⠀⠀⠀⠀• Group is the attribute group to nest this attribute under.
⠀⠀⠀⠀• Mode is whether the attribute can be changed after the initial edition.
⠀⠀⠀⠀• Show in grid is whether to show the attribute it in the editing tab or not.
⠀⠀⠀⠀• Show in reduced grid is whether to show the attribute in the details grid and the quick addition grids (The ones shown when you add stuff through the magnifying glasses, like the preventime maintenance).
⠀⠀⠀⠀Those are all the general properties that really matter, now lets go into the type properties. This field specifies what kind of data can go into the attribute at any point in time, and here are the different types available:
⠀⠀⠀⠀• BIGINTEGER - A number as large as -2^63 to 2^63-1.
⠀⠀⠀⠀• BOOLEAN - True or false.
⠀⠀⠀⠀• CHAR - A character.
⠀⠀⠀⠀• DATE - A date.
⠀⠀⠀⠀• DECIMAL - A floating point number with at max 29 precise decimal places.
⠀⠀⠀⠀• DOUBLE - A floating point number with at max 15 precise decimal places.
⠀⠀⠀⠀• FORMULA - A function or a script, similar to excel.
⠀⠀⠀⠀• INTEGER - A number as large as -2^32 to 2^32-1.
⠀⠀⠀⠀• IP_ADDRESS - A masked textbox for either Ipv4, Ipv6 or both.
⠀⠀⠀⠀• LINK - A link to resources provided through an URL (think images or documents, like this http://users.isr.ist.utl.pt/~cfb/VdS/v096.txt)
⠀⠀⠀⠀• LOOKUP - Preconfigured value lists, such as asset condition values, operation values and more. These can be configured in the lookup values tab, like a class.
⠀⠀⠀⠀• LOOKUPARRAY - LOOKUP but you can select multiple values.
⠀⠀⠀⠀• REFERENCE - Cards of other classes. You need to select a domain (relation) in order to assign what classes you can choose, and for that, refer to the domains explanation section. (This is useful to assign, for instance, a battery to a forklift.)
⠀⠀⠀⠀• STRING - A fixed-size amount of characters. The text box used to display this is small and thin.
⠀⠀⠀⠀• TEXT - An unlimited-size amount of characters, used for big texts and notes. The text box used to display this is big and wide.
⠀⠀⠀⠀• TIMESTAMP - A unix timestamp.
⠀⠀⠀⠀At last, the "other properties". These are used to write JS code to complement the attributes in certain situations. I, however, can't talk much about it because at the time of writing, I don't know any javascript.
⠀⠀⠀⠀The class domain is the same as the database relations between two tables. The way you set one up is pretty similar to a normal database, so lets look at it now:
⠀⠀⠀⠀• Name is, again, the identifier for the domain.
⠀⠀⠀⠀• Description is the name of the domain.
⠀⠀⠀⠀• Origin is the origin table from where the relation comes. (The left-side node)
⠀⠀⠀⠀• Destination is the destination table from where the relation goes to. (The right side node)
⠀⠀⠀⠀• Direct Description is a representation of what the origin does to the destination. E.g.: "contains battery", "includes file"
⠀⠀⠀⠀• Inverse Description is the reverse of the Direct Description. E.g: "is contained by car", "is included by dossier"
⠀⠀⠀⠀• Cardinality is the relation between the two tables. -> [1:1, 1:N, N:1, N:N], mapped to origin:destination, where 1 is 1, and N is "Many".
⠀⠀⠀⠀The importation and exportation of data is very critical for facilities with a LOT of data, and openMAINT offers us an interface that facilitates all of this, with either csv, xls and xlsx files. This one is actually pretty self-explaining, so there's no need to go into detail, however, there are still a few fields that should be explained.:
⠀⠀⠀⠀• Attributes - Here you have to map out the attributes of the class to the excel headers, and add a default value if none is found.
⠀⠀⠀⠀• Import mode - What to do to the tables when importing. Merging will ignore entries with the same key attribute, and Add will add them anyways.
⠀⠀⠀⠀• Import key attribute - The "primary key" to use when importing data.
⠀⠀⠀⠀• Missing records- What to do with the cards that don't exist inside the importing file.<br<>br>
⠀⠀⠀⠀After finishing this setup, you can go into any class in the data management module, and a new "import/export" option will be present in the "more options (three horizontal lines)" menu.
⠀⠀⠀⠀ These geo attributes are essentially configurations for the display of buildings and items in the map. Let's go and look at what it offers:
⠀⠀⠀⠀• Type is the "handler" that will be used to determine how the asset is drawn. You can just leave this as "Geometry".
⠀⠀⠀⠀• Name is the identifier of the geo attribute, used internally.
⠀⠀⠀⠀• Description is the name of the geo attribute, that we will see.
⠀⠀⠀⠀• Sub type is the shape in which the asset will be drawn. It can be a line, a polygon or a point.
⠀⠀⠀⠀• Visibiliy is the selection of which classes will be able to see the class you're configuring in their own map. (E.g, you can configure the "Buildings" to be able to see the "Complex", and then draw a sectioned map.)
⠀⠀⠀⠀Most of what's in this range of folders has either already been talked about and is just being categorised here, or isn't necessary for a "What you need to know guide". Nonetheless, if you want to understand more about it, I recommend you to check out the CMDBuild Manuals.
⠀⠀⠀⠀First off, read the overview if you haven't already. Now, to repeat myself, menus are essentially different navigation tabs that you can set up for different accounts, and while browsing through the menus folder, you'll see exactly that in Desktop/Default: That's the admin menu!.
⠀⠀⠀⠀Menus work in conjunction with group permissions, meaning that even though the admin can see all of those folders, a user with the same menu assigned to them but with no permissions to see any of the asset folders, simply wouldn't be able to see any of it. Permissions and groups will be explained further down, but stick with the menus for now.
⠀⠀⠀⠀Adding a new menu is simple, just select the group it will be aimed at, and use the drag and drop interface to drag classes from the administrative menu on the right (>>) to add them to that menu. To separate classes into folders, type the name of the folder you want to create on the "New Folder" text box and hit "+", and to take something out, be it a folder or a class, just drag it back into anywhere in the right side administration menu.
⠀⠀⠀⠀Finally, you can always edit any menu at a later time by clicking in the editing pen near the top of it.
⠀⠀⠀⠀As mentioned before, the groups and permissions work alongside the menus. Whilst the latter define what the user can possibly ever see, the groups define what the user is allowed to see and do. As for properties, the groups and permissions have a few:
⠀⠀⠀⠀• Name is the identifier of the group, used internally.
⠀⠀⠀⠀• Description is the name of the group, that we will see.
⠀⠀⠀⠀• Type is a predefined setting with a bunch of permissions based on common account types. You can leave this as normal.
⠀⠀⠀⠀• Email is the email associated with this group.
⠀⠀⠀⠀• Default page is the "landing page" for everyone in this group. So, the page they log-in into.
⠀⠀⠀⠀The permissions tab allows you to set the permissions for a group across pretty much anything. It's both simple and complicated, but its intuitive, so I won't go into much detail here, but essentially you can set none/read/write permissions to the user in every class of the app (which, for simplicity, should be only set on the classes that the user can see through menus), aswell as filters that limit what the user can interact with and view, and more. To get a more indepth view on permissions, go to page 137 of the administrator manual.
*Note: The "grant" functions in the maintenance filters limit how many stages a user can see. The default one for creation and the topic for execution.
⠀⠀⠀⠀Finally, on the users list, you have a drag and drop menu akin to the menu's one where you can drag users into the group you're configuring. This is meant to be a shortcut to going to the users tab and editing it there.
⠀⠀⠀⠀The users folder allows you to create new users that people can log in as - It's really simple, just clicking add user and filling in the very self-explaining fields will do. One thing to note though, is that if you for some reason need to change the user passwords, you're able to do so by expanding them and clicking in the key symbol, in the top right.
⠀⠀⠀⠀The e-mails are configured through the "Notifications" folder, and are actually pretty straightforward. Lets have a look at them and figure out what they do.
⠀⠀⠀⠀• Email accounts - This is the place where you'll set up your email accounts to send and receive notifications.
⠀⠀⠀⠀• Templates/Email - This is where you can see all the different email templates (and also add more).
⠀⠀⠀⠀• Templates/In-App Notification - Same as the previous one.
⠀⠀⠀⠀• Email signatures - The different useable signatures left at the end of the emails.
⠀⠀⠀⠀In the templates you'll see stuff like {Role-MaintOffice.Email}. This is essentially a placeholder variable that will be replaced by, as it reads, the maintenance office's email. You can of course change this at any time. In that string, the "role" just means "group".
⠀⠀⠀⠀As you might've known form the installation, openMAINT uses a bunch of other servers and resources in order to work. In the server management tab, under the "System" option, you can see all of the possible servers in openMAINT, aswell as their state (Errored, Disabled, Online). This is extremely useful for troubleshooting errors all over the app.
⠀⠀⠀⠀In the GIS, BIM and DMS folders, you'll find the External Services, Settings and Settings options, respectively. Those are the options in which you're able to change both the URI's for the servers and the options of each.