Ultimate Customizer (formerly Ultimate Theming) for Jira Service Desk
- 1 Introduction
- 2 Installation
- 3 Getting started
- 3.1 Design (Original vs Module based)
- 3.2 Files (uploads)
- 3.3 Additional request fields, search fields, csv export and sorting
- 3.4 Anonymous portals
- 3.5 Request Types visibility
- 3.6 Categories based view of portals
- 3.7 Design login, signup and knowledge base pages
- 3.8 Modules
- 3.9 Global javascript/css
- 3.10 Delegated project admin
Introduction
This is the documentation and help page for the latest version (4.x) of the Ultimate Theming for Jira Service Desk.
You can find the old documentation for v.2.X here: V. 2 old documentation
Version 4
The addon was renamed to Ultimate Customizer.
Also fixed some visual issues with the newer JSD versions.
Version 3.3
We added visibility on additional fields and search fields. And scope by portal on additional fields.
Overridden field names now work everywhere.
What changed from version 2 to version 3
Added modular approach for building content (with content+sidebars or a customized grid). Removed functionality of themes.
Added full sorting of fields in ”Requests”.
Added fields to filter on in ”Requests”.
Improved fetch of SLA info.
Improved the generation of CSV in ”Requests”.
Edit ”Sign up” and ”Knowledge base” pages.
Added global JavaScript/CSS
Global files (can always be linked to from every page)
Installation
Installation in Jira is through Atlassian Marketplace, or by downloading a version and uploading into the Addons section of Jira.
Getting started
As as administrator (or Sysadmin) go to the portals. You will see a the Ultimate Theming top bar, and its context menu on the right side. The menu gives access to some of the functions in the plugin.
The following is a description of features in the plugin:
Design (Original vs Module based)
Any page in the Service Desk customer portal area can be edited. The standard design for a page is the Original JSD Design. But you can use a module build up instead.
Using modules, means everything comes in modules (even the standard content).
If using standard design, the main content of a page can be edited by clicking the Customize button in the top menu.
If using modules, means everything comes in modules, and edits are made through editing the page and then editing the modules.
Using module based design
When on a page, click "Change design" in the Ultimate menu. Choose the module based design. Click OK.
You will now see the page is rendered differently, which is the module design.
The page now consists of rows with columns with modules. Each row can be edited to display side bars, or a custom responsive layout (based on the Bootstrap Grid System. Please look into that for a complete understanding. It's simple).
Each column contains modules that fills the width. You can add and remove modules (read about modules beneath).
Normally, each page has a default module that's already in there. E.g. for the /portals page, the default module is the list of portals.
Remember to save your stuff. Note that module based pages are saved in versions, such that you can return to a previous one at a later time (use the versions button to see a list of versions).
Note that everything is published as your edit. Users will see changes instantly.
Files (uploads)
Go to Ultimate menu → Files. Upload and administer files here.
You can use these files in HTML modules, present files as images, or download links.
Additional request fields, search fields, csv export and sorting
If you enabled module based design for the Requests page, you need to edit page (e.g. menu → all requests), and then edit the module.
Otherwise click Edit, in the right bottom of the request list. Then you will see the options available.
Next, please read here, for a more detailed documentation.
Anonymous portals
Anon. portals are enabled in Permissions on per portal basis. If at least one portal is enabled, then the /portals page (and portal page) can be viewed without a user has been signed in. Other portal pages cannot be viewed.
A signup button is available in the top right corner (if public signup is enabled in the Service Desk configuration).
When a user wants to create a request, the form is prepended with a "email" field. Captcha is also enabled. When the user submits, the user (email) is instantly created with a random password, and reporter of the request is set to newly created user. The user is taken to the request details (and logged in), and a reset password email is sent.
The caveats are: knowledge articles cannot be shown.
Note: if your project is limited to customers who are added to the project, you need to add the UltimateTheming.AnonymousSDUser to that list.
Request Types visibility
The request types of a portal can be restricted wrt. visibility. (Sys)Admin goes to any portal, then in the Ultimate menu, Request types visibility can be clicked. A request type can be restricted to groups and/or organisations (at least one should be fulfilled to be able to view). A request type also can be disabled. If nothing is set for a request type, then it's visible.
Categories based view of portals
This is on the main page (/portals) module.
Go to the /portals page. Click edit below the list of portals. (Or if you have enabled ”Module based” design, you first need to click Edit in the top, before you can edit the module.)
A window opens where you can group the portals into categories, and then the portals are shown in a tab view instead.
You can sort the portals to change the order of things. Other options are also available.
Design login, signup and knowledge base pages
To edit login pages, one have to understand that there is a login page for each portal. But there is also a main page portal page.
To edit the main login page, go the /portals, click Ultimate menu → Edit login page. Now you are actually signed out, but can still edit the login page. Just login again to keep editing.
To edit a specific portal page, go the portal in question, and then Ultimate menu → Edit login page.
To edit the signup page, first edit the login page, and follow the Sign up link on that page.
Knowledge pages are editable as well, but you have to have set up a Confluence integration first.
Modules
Each page has a default module (containing content that would be shown if a module based design was not used). Some of those has editable options.
List of portals / Category view
Read above about "Categories based view of portals".
Request list (all requests, current requestt and so on)
Read about this module above in "Additional request fields, search fields, csv export and sorting".
HTML (upload images, or link to files)
Use source editor or the Rich Text Editor to create HTML. You can show uploaded images as well, and link to uploaded files.
Announcement
Show an announcement on the page.
Search bar
Applicable on all pages. It shows a search bar (equivalent to the standard one).
Recent portals, popular portals
Modules that shows recent selected portals, and popular portals. These are applicable on most pages.
Request details + requests actions
On the page showing request details, you can add a module that shows additional fields, actions and such. This is great to put in a side bar. When inserted, it will automatically take the share and actions from the main module.
Global javascript/css
In the Ultimate menu → global javascript/css, you can input javascript and css. JS will be evaluated on when a page is loaded. Css is injected automatically.
For javascript you have some variables available:
window.AJS.$ - contains a jQuery selector
window.ULTIMATE_SERVICEDESK_LOCATION - this contains info about the current location/page.
If you unfortunately input js/css that make the page not load, then add the following parameter and value to the URL: ?globaljs=false or ?globalcss=false. This will make the js/css not load.
Then correct your js/css and try reloading the page without the parameters.
As a last resort, if page still fails to load because of js/css, then call the following urls to clear the content (js or css):
JIRABASEURL/rest/net.koncis.ultimate/latest/admin/globaljsandcss/resetjs
JIRABASEURL/rest/net.koncis.ultimate/latest/admin/globaljsandcss/resetcss
A good template for adding JS is this:
(function(){
if(window.CUSTOM_CODE_LOADED == true) {
return;
}
window.CUSTOM_CODE_LOADED = true;
your_start_code_function_call()
window.Portal.Api.on("pageLoaded", function(){
console.log("do stuff on new view, e.g. check if missing to insert text")
your_code_on_new_view()
})
})()Delegated project admin
Go to permissions, and enable it. When enabled, project admins can edit portal pages that belongs to the project.
There are 5 types of portal pages:
Main portal page. It has url ./servicedesk/customer/portal/X, where X is the portal ID, e.g. 4.
Request create page. Example url: /servicedesk/customer/portal/10/create/87.
Request detail page. This page shows a request from the portal/project. Url example: ../servicedesk/customer/portal/10/EF-6. This page is normally accessed through emails, or the requests page.
Portal login/signup page. Can be edited by clickling edit login page (when on a portal main page).
The project admin can upload and delete own files. In the Ultimate → Files, there will be two buttons: Global and User files.
Global are the ones the (sys)admin uploaded. User files are the one that the user (project admin) uploaded.