Best Practices for Creating Apps
Data sources
Use the alias
- Except in specific cases, data sources accessing databases (MSSQL, ev|ITSM, etc.) should all be based on the alias instead of a connector. This will guarantee that all data will be fetched from the right database whenever the application's execution context is changed (like from Sandbox to Production).
- On the data sources' list, it is easy to distinguish those that are based on aliases from the others as they are displayed in bold.
Choose a naming convention
- Choose a naming convention where the data source's name indicates its configuration (query, filter and view).
example My Service Requests in Progress (Status)
- When the data source is used in a filter, it may be helpful to add a sign to its name, because such usage makes it a bad candidate for some computations.
example My Opened Incidents (Category)
- The asterisk indicates that there is a Filter List widget based on this data source.
- If it is used to display the number of my opened incidents, then the result will differ whenever the filter is changed (like from Open to None).
- Add an indication to names so that Master/Detail relationships are easily identified.
example (1) Employees (List)
- (1.1) Service Requests (List)
- (1.1.1) History of Actions (List)
- (1.2) Equipment (List)
==>
- Service Requests and Equipment are details of Employees
- History of Actions is a detail of Service Requests.
Avoid useless duplicates
- Before creating a new data source, make sure it doesn't already exist. Respecting a naming convention makes it easier to follow this good practice.
- When a data source you were planning to use for a KPI turns out to be used in a Filter List widget, then create a new one with a different aggregated view. The computation will be the same and you'll have a new view available for the same data.
Use aggregated views for counters
- When a widget (Data Viewer) is based on a data source with variable results (EV|ITSM, MSSQL, MySQL, etc.) then the result is displayed by batches of 30 rows. If you need to add a calculated field based on such data sources, then you should use one with an aggregated view.
example To display the number of opened incidents, you should not use a data source configured with the List view, even if it already exists.
- Make sure the aggregation criterion doesn't have more than 30 distinct values: Status is a good aggregation criterion for assets, while Manufacturer might be a bad one (over 30 distinct manufacturers).
New request
Data Sources used for listing catalog items in a store should be based on the Home module menus (New Service Request, New Change Request) where Application Perimeters defined on catalogs in Service Manager are applied. Do not use the Operation / Transition > Catalogs menus.
Master/Detail relationships
Detail data sources are populated with the records matching the first record of the related Master data source, provided that its Select First Row As Current Record option is checked. In order to be able to access the Data Picker and configure your widgets based on Detail data sources, you must ensure that the first record of the Master data source has at least one detail record.
See Master/Detail relationships
example To configure a widget listing the equipment of a user selected in the directory, make sure that the first employee of the list in your testing database has at least one equipment and that the Select First Row As Current Record option is checked on the Employees Data Source. The option may be unchecked after the widget settings is finished.
Delete draft or unused data sources
When the user leaves the process of creating a new data source after setting the type (EasyVista, CSV, etc.), the draft of the newly created data source is not automatically deleted.
example Easyvista(1), csv(1)
Shortcuts
Access rights
Do not forget to set the access rights when configuring a Shortcut, otherwise users who launch it would get the er22 error code corresponding to access right issues.
Exposed Properties - Link for a direct access to a record
Exposed properties enable you to configure URL links to access a specific record. To do so:
- Configure the Data Source that needs to be filtered and set the field that will be used as filter in the Search section
- Add an Exposed Property corresponding to the Data Source's field
- Configure the URL
In the current version, when a URL with exposed properties (ex: an incident's number) is called, the properties remain in the link when the user navigates in the app which means that widgets based on the Data Source in play will always be filtered.
In order to display other records (like when the user want to access the page of all of his/her incidents after opening a link to the details of an incident in particular), Data Sources and pages in play in the direct access must be duplicated.
Note: An enhancement is under analysis to avoid duplications.
- Identify the pages that need to be filtered to a specific record (ex: My Incidents + History of actions (incidents) + Incidents' Attachments) and duplicate them. Add a suffix to the names of copied pages to indicate the filterinf criteria (ex: My Incidents [RFC])
- Identify the Data Sources used in the duplicated pages and duplicate them. Rename them by adding a suffix as you did for the pages (ex: (1) My Incidents (List) [RFC])
- On Master Data Sources: Set the Search Field in the Search section
Note: in the case of direct access to a ticket and when the Data Source's default filter doesn't fetch all records (ex: Opened Incidents), consider changing the filter to None to ensure that a solved ticket may be visualized via a direct link. - Change the Master Datasource in the Master/Detail section of duplicated Data Sources which are of type Detail
- Configure the duplicated pages to make their widgets point to the new Data Sources.
Images
Upload images in the application
- Images should be added via the graphic editor so that they will be stored in the application's resources folder, which will guarantee a correct handling of images in case of import/export.
- When you copy/paste HTML code with images from another application you should upload the images via the graphic editor, otherwise they will only be displayed as long as the application from which they were copied exists on the same tenant.
- When you use a custom widget that was created in a different app and having images, upload the images via the graphic editor, copy their respective paths and replace the paths of the images in the custom widget.
Design
Arranging widgets for responsive applications
On multi-device applications, think about the display order on smartphones when you position the widgets (widgets Layout).
example Incidents / Service Requests Dashboards, with pie (widget Pie/Donut Chart) and line (widget Line Chart) charts
| If this is the display you want | Arrange your Widgets like this | Example |
|---|---|---|
| The incidents charts followed by the service requests charts | Place the widgets on a single row of two columns
|  |
| Pie charts first then line charts | Place the widgets on 2 rows of two columns
|
 |