Edge Documentation

[[Category:enPortal 5.4]]
{{DISPLAYTITLE:Batch Loading User Accounts and Roles}}

An XML-based language is used to define valid roles, domains, and users. While most administration of roles, domains, and users occurs in the '''System Explorer''' (Under '''Advanced''' Tab and '''Explore System'''), an alternative method is to load this information from XML-encoded text files.
<br>
This section explains the XML specifications for account definition files. 
<!-- DOES THAT APPLY? / Mylene - After creating your own account definition XML files, see Validating and Loading XML on page 200 for information on how to validate and load the files.-->

== File Locations ==
<br>

A default account definition file is shipped with the system and can be used as an example for customizing or adding roles, domains, or users. The account definition file, <tt>accounts.xml</tt>, is contained on the server in the directory: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/content/system</tt>.
<br>
<br>
Be sure to save your own account definition XML files in the following location (other than the default location shown above):
:<tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/custom</tt>.
<br>
The account definition DTD can be found on the server at:
:<tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/dtds/AccountDefinitions.dtd</tt>

<br>

== Account Definitions XML Specifications ==
<br>

It is recommended that you be familiar with the user management concepts (role, domain, and user) before reading this section. 
<br>

The following is an example of an <tt>Account Definitions</tt> file.

<code>[xml,N]
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE AccountDefinitions SYSTEM "../dtds/AccountDefinitions.dtd">
<AccountDefinitions>
<!-- Define Role staff -->
<Role name="helpdesk" />
<Role name="staff" parentRoleID="/helpdesk" />
<!-- Define Roles NOC, managers, and operators -->
<Role name="NOC" >
    <Role name="managers" />
    <Role name="operators" />
</Role>
<!-- Define Domain Accounting -->
<Domain name="Accounting" >
<!-- All users defined for this role will have access to the Data Entry and Bookkeeper roles -->
    <RoleLink roleID="/dataentry" />
    <RoleLink roleID="/bookkeeper" />
    <!-- Define Users of domain Accounting -->
    <User userID="john" password="apple" >
        <!-- This user also has access to the NOC Manager role -->
        <RoleLink roleID="/NOC/manager" />
    </User>
    <User userID="mary" password="orange" >
        <!-- This user also has access to the NOC Manager role -->
        <RoleLink roleID="/NOC/manager" />
    </User>
    <User userID="sue" password="grape" >
        <!-- This user also has access to the NOC Operator role -->
        <RoleLink roleID="/NOC/operator" />
    </User>
</Domain>
</AccountDefinitions>
</code>

<br>
The following sections explain each part in the <tt>Account Definitions</tt> file:
<br>
=== Account Definitions Tag ===
<br>
The <tt><AccountDefinitions></tt> tag is the root tag that identifies the enclosed tags as account definitions.
The tag can contain any number of <tt><Role></tt>, <tt><Domain></tt>, and <tt><User></tt> tags. There are no attributes for this tag.

<br>
=== Role Tag ===
<br>

The <tt><Role></tt> tag is used to define a role in the system. The <tt>Account Definitions</tt> file can contain any
number of <tt><Role></tt> tags, which allow the creation of a nested hierarchy of roles. This tag has two required
attributes:
:*Name: used in the name of the specific role or subrole.
:*ParentRoleID: used to identify the parent role in the hierarchical rolespace.

The following example defines a role entitled 'staff' in the 'helpdesk' rolespace:
<<tt><Role name="staff" parentRoleID="/helpdesk" /></tt>

The following example defines a hierarchical rolespace with two roles 'managers' and 'operators' under the
'NOC' rolespace:

:<tt><Role name="NOC" ></tt>
:<tt><Role name="managers" /></tt>
:<tt><Role name="operators" /></tt>
:<tt></Role></tt>

If the NOC rolespace existed previously, the roles 'managers' and 'operators' could be created with the
following:

:<tt><Role name="managers" parentRoleID="/NOC" /></tt>
:<tt><Role name="operators" parentRoleID="/NOC" /></tt>

<br>
=== Domain, User, and Role Link Tags ===
<br>
The <tt><Domain></tt>, <tt><User></tt>, and <tt><RoleLink></tt> tags are used together to create domains and users, and to assign domains and users to existing roles.
<br>
<br>
'''<Domain> Tag'''
<br>
The <tt><Domain></tt> tag is used to define a domain in the system. This tag can contain any number of <tt><RoleLink></tt> and <tt><User></tt> tags. The <tt><Domain></tt> tag has one required attribute:
:* name: used in display labels of the domain.
<br>
'''<User> Tag'''
<br>
The <User> tag is used to define a user in the enclosing domain. The tag can contain any number of
<RoleLink> tags. The <User> tag has two required attributes:
:* userID: a user account name that must be unique to the domain.
:* password: password for the account.
<br>
'''<RoleLink> Tag'''
<br>
The <RoleLink> tag is used to assign the enclosing domain and/or user to a role in the system:
:* When enclosed in a <tt><Domain></tt> tag, a <tt><RoleLink></tt> tag assigns the specified role to all users in the domain.
:* When enclosed in a <tt><User></tt> tag, a <tt><RoleLink></tt> tag assigns the specified role to only that user.
The tag has one required attribute:
:* roleID: reference to the role ID of a previously defined role, as described in the <tt>Role</tt> Tag subsection.
<br>
'''Example'''
<br>
The following example defines a domain named 'Accounting' with the roles 'dataentry' and 'bookkeeper'
assigned to all users defined in the domain.
<code>[xml,N]
<Domain name="Accounting" >
    <RoleLink roleID="/dataentry" />
    <RoleLink roleID="/bookkeeper" />
    <User userID="john" password="apple" />
    <User userID="mary" password="orange" />
    <User userID="sue" password="grape" />
</Domain>
</code>

=== Loading into System ===
Once the account definitions file (for example, <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/custom/accounts.xml</tt>) is created, use the following step to load it to the system

# Use a text editor to create a custom load file (for example, <tt>load_account.txt</tt>) in <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/</tt> directory.
# The content of <tt>load_account.txt</tt> has one line <tt>custom/accounts.xml</tt> in it.
#Log in to enPortal as administrator.
#Mouse over the '''Advanced''' tab and then "'''Utilities'''" and click '''XMLImport''' to load the account definitions file to the system.