<?xml version="1.0" encoding="UTF-8"?>

<chapter xml:id='chap-ui'

xmlns='http://docbook.org/ns/docbook'

version='5.0' xml:lang='en'

xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'

xsi:schemaLocation='http://docbook.org/ns/docbook http://docbook.org/xml/5.0/xsd/docbook.xsd'

xmlns:xlink='http://www.w3.org/1999/xlink'

xmlns:xinclude='http://www.w3.org/2001/XInclude'>

<title>OpenIDM User Interface</title>

<para>OpenIDM provides a customizable, browser-based user interface. The

default user interface enables administrative users to create, modify and

delete user accounts. It provides role-based access to tasks based on BPMN2

workflows, and allows users to manage certain aspects of their own accounts,

including configurable self-service registration.</para>

<section xml:id="ui-overview">

<title>Overview of the Default User Interface</title>

<para>The default user interface is provided as a reference implementation

that demonstrates the capabilities of the REST API. You can modify certain

aspects of the default user interface according to the requirements of your

deployment. Note, however, that the default user interface is still evolving

and is not guaranteed to be compatible with the next OpenIDM release.</para>

<para>To access the user interface, install and start OpenIDM, then point

your browser to <link xlink:href="http://localhost:8080/openidmui">

http://localhost:8080/openidmui</link>.</para>

<para>Log in as the default administrative user (Login: openidm-admin,

Password: openidm-admin) or as an existing user in the repository. The

display differs, depending on the role of the user that has logged in.</para>

<para>For an administrative user (role <literal>openidm-admin</literal>),

two tabs are displayed - Dashboard and Users. The Dashboard tab lists any

tasks assigned to the user, processes available to be invoked, and any

notifications for that user. The Users tab provides an interface to manage

user entries (OpenIDM managed objects under <literal>managed/user</literal>).</para>

<mediaobject>

<alt>OpenIDM UI Administrator View</alt>

<imageobject>

<imagedata fileref="images/ui-admin-view.png" format="PNG" contentwidth="5in" scalefit="1"/>

</imageobject>

</mediaobject>

<para>The <literal>Profile</literal> link enables the user to modify elements

of his user data. The <literal>Change Security Data</literal> link enables

the user to change his password and, optionally, to select a new security

question.</para>

<para>For a regular user (role <literal>openidm-authorized</literal>), the

Users tab is not displayed - so regular users cannot manage user accounts,

except for certain aspects of their own accounts.</para>

</section>

<section xml:id="ui-configuring">

<title>Configuring the Default User Interface</title>

<para>The following sections outline the configurable aspects of the default

user interface.</para>

<section xml:id="ui-self-registration">

<title>Enabling Self-Registration</title>

<para>Self-registration (the ability for new users to create their own

accounts) is disabled by default. To enable self-registration, set

<literal>"selfRegistration"</literal> to <literal>true</literal> in

the <filename>conf/ui-configuration.json</filename> file.</para>

<programlisting language="javascript">

{

"configuration" : {

"selfRegistration" : true,

...

</programlisting>

<para>With <literal>"selfRegistration" : true</literal>, the following

capabilities are provided on the right-hand pane of the user interface:

</para>

<simplelist>

<member>Register my account</member>

<member>Reset my password</member>

</simplelist>

<para>User objects created using self-registration automatically have the

role <literal>openidm-authorized</literal>.</para>

</section>

<section xml:id="ui-security-questions">

<title>Configuring Security Questions</title>

<para>Security questions are disabled by default. To guard against

unauthorized access, you can specify that users be prompted with security

questions if they request a password reset. A default set of questions is

provided, but you can add to these, or overwrite them.

To enable security questions, set <literal>"securityQuestions"</literal>

to <literal>true</literal> in the

<filename>conf/ui-configuration.json</filename> file.</para>

<programlisting language="javascript">

{

"configuration" : {

"securityQuestions" : true,

...

</programlisting>

<para>Specify the list of questions to be asked in the

<filename>conf/ui-secquestions.json</filename> file.</para>

<para>Refresh your browser after this configuration change for the change

to be picked up by the UI.</para>

</section>

<section xml:id="ui-site-identification">

<title>Enabling Site Identification</title>

<para>To ensure that users are entering their details onto the correct

site, you can enable site identification. Site identification provides a

preventative measure against phishing.

</para>

<para>With site identification enabled, users are presented with a range of

images from which they can select. To enable site identification, set

<literal>"siteIdentification"</literal> to <literal>true</literal>

in the <filename>conf/ui-configuration.json</filename> file.</para>

<programlisting language="javascript">

{

"configuration" : {

"siteIdentification" : true,

...

</programlisting>

<para>Refresh your browser after this configuration change for the change

to be picked up by the UI.</para>

<para>A default list of four images is presented for site identification.

The images are defined in the <literal>siteImages</literal> property in the

<filename>conf/ui-configuration.json</filename> file:</para>

<programlisting language="javascript">

"siteImages" : [

"images/passphrase/mail.png",

"images/passphrase/user.png",

"images/passphrase/report.png",

"images/passphrase/twitter.png"

],

...

</programlisting>

<para>

The user selects one of these images, which is displayed on login. In

addition, the user enters a Site Phrase, which is displayed beneath the

site image on login. If either the site image, or site phrase is incorrect

or absent when the user logs in, the user is aware that he is not logging

in to the correct site.</para>

<para>You can change the default images, and include additional images, by

placing image files in the <filename>ui/extension/images</filename> folder

and modifying the <literal>siteImages</literal> property in the

<filename>ui-configuration.json</filename> file to point to the new images.

The following example assumes a file named <filename>my-new-image.jpg</filename>,

located in <filename>ui/extension/images</filename>.

</para>

<programlisting language="javascript">

"siteImages" : [

"images/passphrase/mail.png",

"images/passphrase/user.png",

"images/passphrase/report.png",

"images/passphrase/twitter.png",

"images/my-new-image.jpg"

],

...

</programlisting>

<para>Note that the default image files are located in

<filename>ui/default/admin/public/images/passphrase</filename>.</para>

</section>

<section xml:id="ui-country-list">

<title>Configuring the Country List</title>

<para>The default user profile includes the ability to specify the user's

country and state or province. To specify the countries that appear in

this drop down list, and their associated states or provinces, edit the

<filename>conf/ui-countries.json</filename> file. For example, to add

Norway to the list of countries, you would add the following to the

<filename>conf/ui-countries.json</filename> file:</para>

<programlisting language="javascript">

{

"key" : "norway",

"value" : "Norway",

"states" : [

{

"key" : "akershus",

"value" : "Akershus"

},

{

"key" : "aust-agder",

"value" : "Aust-Agder"

},

{

"key" : "buskerud",

"value" : "Buskerud"

},

...

</programlisting>

<para>Refresh your browser after this configuration change for the change

to be picked up by the UI.</para>

</section>

</section>

<section xml:id="ui-managing-users">

<title>Managing User Accounts With the User Interface</title>

<para>Only administrative users (with the role <literal>openidm-admin</literal>)

can add, modify, and delete user accounts. Regular users can modify certain

aspects of their own accounts.</para>

<procedure>

<title>To Add a User Account</title>

<step>

<para>Log into the user interface as an administrative user.</para>

</step>

<step>

<para>Select the Users tab.</para>

</step>

<step>

<para>Click Add User.</para>

</step>

<step>

<para>Complete the fields on the Create new account page.</para>

<para>Most of these fields are self-explanatory. Be aware that the user

interface is subject to policy validation, as described in <link

xlink:href="integrators-guide#chap-policies"

xlink:role="http://docbook.org/xlink/role/olink">

<citetitle>Using Policies to Validate Data</citetitle></link>. So, for

example, the Email address must be of valid email address format, and

the Password must comply with the password validation settings that are

indicated in the panel to the right.</para>

<para>The Admin Role field reflects the roles that are defined in the

<filename>ui-configuration.json</filename> file. The roles are mapped as

follows:</para>

<programlisting language="javascript">

"roles" : {

"openidm-admin" : "Administrator",

"openidm-authorized" : "User",

"tasks-manager" : "Tasks Manager"

},

</programlisting>

<para>By default, a user can be assigned more than one role. Only users

with the <literal>tasks-manager</literal> role can assign tasks to any

candidate user for that task.</para>

</step>

</procedure>

<procedure xml:id="ui-update-account">

<title>To Update a User Account</title>

<step>

<para>Log into the user interface as an administrative user.</para>

</step>

<step>

<para>Select the Users tab.</para>

</step>

<step>

<para>Click the Username of the user that you want to update.</para>

</step>

<step>

<para>On the user's profile page, modify the fields you want to change

and click Update.</para>

<para>The user account is updated in the internal repository.</para>

</step>

</procedure>

<!-- Not supported for Xpress

<procedure>

<title>To Reset a User's Password</title>

<para>Users can change their own passwords by following the Change Security

Data link in their profiles. This process requires that users know their

existing passwords.</para>

<para>In a situation where a user forgets his password, an administrator

can reset the password of that user without knowing the user's existing

password.</para>

<step>

<para>Follow steps 1-3 in <xref linkend="ui-update-account" />.</para>

</step>

<step>

<para>On the user's profile page, click Change password.</para>

</step>

<step>

<para>Enter a new password that conforms to the password policy and click

Update.</para>

<para>The user password is updated in the repository.</para>

</step>

</procedure>

<procedure>

<title>To Delete a User Account</title>

<step>

<para>Log into the user interface as an administrative user.</para>

</step>

<step>

<para>Select the Users tab.</para>

</step>

<step>

<para>Click the Username of the user that you want to delete.</para>

</step>

<step>

<para>On the user's profile page, click Delete.</para>

</step>

<step>

<para>Click OK to confirm the deletion.</para>

<para>The user is deleted from the internal repository.</para>

</step>

</procedure>

</section>

<section xml:id="ui-managing-workflows">

<title>Managing Workflows From the User Interface</title>

<para>The user interface is integrated with the embedded Activiti worfklow

engine, enabling users to interact with workflows. Available workflows are

displayed under the Processes item on the Dashboard. In order for a workflow

to be displayed here, the workflow definition file must be present in the

<filename>openidm/workflow</filename> directory.</para>

<para>A sample workflow integration with the user interface is provided in

<filename>openidm/samples/workflow</filename>, and documented in <link

xlink:href="integrators-guide#example-provisioning-workflow"

xlink:role="http://docbook.org/xlink/role/olink"><citetitle>Sample Workflow -

Provisioning User Accounts</citetitle></link>. Follow the steps in that

sample for an understanding of how the workflow integration works.</para>

<para>Access to workflows is based on OpenIDM roles, and is configured in

the file <filename>conf/process-access.json</filename>. By default all users

with the role <literal>openidm-authorized</literal> or

<literal>openidm-admin</literal> can invoke any available workflow. The

default <filename>process-access.json</filename> file is as follows:</para>

<programlisting language="javascript">

{

"workflowAccess" : [

{

"propertiesCheck" : {

"property" : "_id",

"matches" : ".*",

"requiresRole" : "openidm-authorized"

}

},

{

"propertiesCheck" : {

"property" : "_id",

"matches" : ".*",

"requiresRole" : "openidm-admin"

}

}

]

}

</programlisting>

</section>

<section xml:id="ui-customizing">

<title>Changing the UI Theme</title>

<para>You can customize the theme of the default user interface to apply your

own branding. Note that at this stage, the default user interface is still

evolving. Customizations that you make to the <emphasis>functionality</emphasis>

of the UI, are therefore not guaranteed to work in the next OpenIDM release.</para>

<para>By default the user interface reads the stylesheets and images from the

<filename>openidm/ui/default</filename> directory. Modifications to the

default theme should be made in the <filename>openidm/ui/extension</filename>

directory. If you modify the files in the default directory, there is no

guarantee that your changes will not be overwritten in the next OpenIDM

release. The UI searches the <literal>extension</literal> directory first

and applies any styles or images located in this directory.

</para>

<section xml:id="ui-style">

<title>Changing the Default Stylesheet</title>

<para>The default stylesheets are located in the

<filename>openidm/ui/default/admin/public/css</filename> directory.

To customize the stylesheets, copy them to

<filename>openidm/ui/extension/css</filename>, and edit them according

to your requirements.</para>

<para>The following example changes the background color of the input

forms to green.</para>

<orderedlist>

<listitem>

<para>Copy the default stylesheets to <filename>openidm/ui/extension/css</filename>:</para>

<screen>$ cd /path/to/openidm/ui/default/admin/public/

$ cp -r css /extension/</screen>

</listitem>

<listitem>

<para>Edit the <filename>openidm/ui/extension/css/user/config.less</filename>

file as follows:</para>

<screen>@content-background: #99CC66;</screen>

</listitem>

<listitem>

<para>Refresh your browser window for the change to appear.</para>

</listitem>

</orderedlist>

</section>

<section xml:id="ui-logo">

<title>Changing the Default Logo</title>

<para>The default logo is located in the

<filename>openidm/ui/default/admin/public/images</filename> directory.

To customize the logo:</para>

<orderedlist>

<listitem>

<para>Add your own logo image file, named <filename>logo.png</filename>,

to the directory <filename>openidm/ui/extension/images</filename>.

</para>

</listitem>

<listitem>

<para>Refresh your browser window for the new logo to appear.</para>

</listitem>

</orderedlist>

</section>

<section xml:id="ui-locale">

<title>Changing the Language of the UI</title>

<para>Currently, the UI is provided only in US English. You can

translate the UI and specify that your own locale is used. The

following example shows how to translate the UI into French.</para>

<orderedlist>

<listitem>

<para>Copy the default locale to <filename>openidm/ui/extension/locales</filename>:</para>

<screen>$ cd /path/to/openidm/ui/default/admin/public/

$ cp -r locales /extension/</screen>

<para>The <filename>extension/locales</filename> folder now

contains one locale, <literal>en-US</literal>.</para>

</listitem>

<listitem>

<para>Create a copy of the <literal>en-US</literal> locale, in

a new folder named <literal>fr-FR</literal>.</para>

<screen>$ cd /path/to/openidm/ui/extension/locales

$ cp -r en-US fr-FR </screen>

</listitem>

<listitem>

<para>Translate the values of the properties in the

<filename>fr-FR/translate.json</filename> file. Do not translate

the property names. For example:</para>

<screen>...

"user" : {

"user" : "Utilisateur"

"login" : "Login",

"profile" : "Profil",

....</screen>

</listitem>

<listitem>

<para>Change the UI configuration to use the new locale by

setting the value of the <literal>language</literal> property

in the <filename>openidm/conf/ui-configuration.json</filename>

file, as follows:</para>

<screen>"language" : "fr-FR",

</screen>

</listitem>

<listitem>

<para>Refresh your browser window for the modification to be

applied.</para>

</listitem>

</orderedlist>

</section>

<section xml:id="ui-project-config">

<title>Creating a Project-Specific UI Theme</title>

<para>You can create specific UI themes for different projects and

then point a particular UI instance to use a defined theme on startup.

To create a complete custom theme, follow these steps:</para>

<orderedlist>

<listitem>

<para>Shut down the OpenIDM instance, if it is running. In the

Felix administration console, type:</para>

<screen>shutdown

-&gt;</screen>

</listitem>

<listitem>

<para>Clear the <literal>felix-cache</literal> directory.</para>

<screen>$ rm -rf felix-cache</screen>

</listitem>

<listitem>

<para>Copy the entire default UI theme to an accessible

location. For example:</para>

<screen>$ cd /path/to/openidm/ui

$ cp -r default /new-project-theme</screen>

</listitem>

<listitem>

<para>In the copied theme, modify the required elements, as

described in the previous sections. Note that nothing is copied

to the extension folder in this case - changes are made in the

copied theme.</para>

</listitem>

<listitem>

<para>In the <literal>openidm/conf/boot/boot.properties</literal>

file, add the following line, specifying the location of the new

theme. The path is relative to the installation root of the

OpenIDM instance.</para>

<screen>openidm.ui.fileinstall.dir=new-project-theme</screen>

</listitem>

<listitem>

<para>Restart OpenIDM.</para>

<screen>$ cd /path/to/openidm

$ /startup.sh</screen>

</listitem>

<listitem>

<para>Relaunch the UI in your browser. The UI is displayed with

the new custom theme.</para>

</listitem>

</orderedlist>

</section>

</section>

<section xml:id="ui-external-password-reset">

<title>Using an External System for Password Reset</title>

<para>By default, the password reset mechanism is handled

internally, in OpenIDM. You can reroute password reset in the event that

a user has forgotten his password, by specifying an external URL to which

password reset requests are sent. Note that this URL applies to the

password reset link on the login page only, not to the security data change

facility that is available after a user has logged in.</para>

<para>To set an external URL to handle password reset, set the

<literal>passwordResetLink</literal> parameter in the

<filename>conf/ui-configuration.json</filename> file. The following example

sets the <literal>passwordResetLink</literal> to

<literal>https://accounts.example.com/account/reset-password</literal>.</para>

<screen>passwordResetLink: "https://accounts.example.com/reset-password"</screen>

<para>The <literal>passwordResetLink</literal> parameter takes either an

empty string as a value (which indicates that no external link is used) or

a full URL to the external system that handles password reset requests.</para>

<note><para>External password reset and security questions for internal

password reset are mutually exclusive. Therefore, if you set a value for the

<literal>passwordResetLink</literal> parameter, users will not be prompted

with any security questions, regardless of the setting of the

<literal>securityQuestions</literal> parameter.</para></note>

</section>

<section xml:id="ui-external-logout">

<title>Providing a Logout URL to External Applications</title>

<para>By default, a UI session is invalidated when a user clicks on the

Log out link. In certain situations your external applications might

require a distinct logout URL to which users can be routed, to terminate

their UI session.</para>

<para>The logout URL is <literal>#logout</literal>, appended to the UI URL,

for example, <literal>http://localhost:8080/openidmui/index.html#logout/</literal>.

</para>

<para>The logout URL effectively performs the same action as clicking on

the Log out link of the UI.</para>

</section>

<section xml:id="ui-path">

<title>Changing the UI Path</title>

<para>By default, the UI is registered at a specific URL

(<literal><replaceable>base-context</replaceable>/openidmui</literal>).

To override the default URL and specify your own path, edit the

<filename>openidm/conf/ui.context-enduser.json</filename>

file, setting the <literal>urlContextRoot</literal> property to the

new URL. For example, to change the path to

<literal><replaceable>base-context</replaceable>/exampleui</literal>,

edit the file as follows:</para>

<screen>"urlContextRoot" : "/exampleui",</screen>

</section>

<section xml:id="ui-disabling">

<title>Disabling the UI</title>

<para>The UI is packaged as a separate bundle that can be disabled

in the configuration before server startup. To disable the registration

of the UI servlet, edit the <filename>openidm/conf/ui.context-enduser.json</filename>

file, setting the <literal>enabled</literal> property to false:</para>

<screen>"enabled" : false,</screen>

</section>

</chapter>