Appboard/2.4/admin/provisioning/batch loading: Difference between revisions

imported>Jason.nicholls
No edit summary
imported>Jason.nicholls
 
(12 intermediate revisions by the same user not shown)
Line 1: Line 1:
{{DISPLAYTITLE:Batch Loading Users}}
{{DISPLAYTITLE:Batch Loading via XML}}
[[Category:AppBoard 2.4]]
[[Category:AppBoard 2.4]]
__TOC__
== Overview ==
== Overview ==
The AppBoard/enPortal administration user interface (UI) is a robust set of screens and menus that assist the administrator with configuring Users, Domains, Roles, and content permissions in the system.  However, in cases with a high volume of Users, a tool may be desired that will enable the administrator to process batch updates to the system.


Rather than managing users through the AppBoard administration interface, or via LDAP-based authentication integration, it's also possible to batch load domains, users, roles, and role assignment via XML files.


This document outlines a method of creating an AppBoard/enPortal customization to allow an administrator to implement some elements of [[Provisioning_Basics|User Provisioning]] outside of the standard application UI.
This document covers the XML format and process to load the file. For a general overview and links to manage users via the AppBoard administration interface, refer to the main [[appboard/2.4/admin/provisioning|Provisioning]] documentation.




== Batch Processing of Provisioning Updates ==
{{Warning|Using batch loading via XML files is considered a customization of AppBoard and not directly supported under the standard product maintenance contract. It is recommended this type of solution be implemented as part of a
consulting engagement to ensure that it is configured and implemented correctly.  }}


There are several potential options for an administrator to perform batch updates to system provisioning:
== XML Format ==


# <b>Custom JSP</b> - Installing a custom JSP file that enables URL commands that can be used to apply provisioning.  This is similar to a "Command Line" type of solution (with the application URL used as the "command line"). More information on this approach is available under [[Direct_Provisioning|Direct Provisioning By Custom JSP]].
The XML file format is defined by the AccountDefinitions document type definition (DTD). This can be found at <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/dtds</tt>. Refer to this document for a complete reference, as below is a simple example:
# <b>XML Load</b> - This method involves creating an XML file detailing the updates to be made in the system, and then loading the file.  Because of the effort required in formatting the XML file, this is typically not a preferred method.  The XML Load solution is the option detailed in this document. 
# <b>API Access Interface</b> - A tool and interface can be built that would provide direct access to the AppBoard/enPortal provisioning API.  This may be available in the future as a product enhancement.


== XML Load Instructions ==
This section details the procedures for implementing the XML Load solution for direct provisioning.
{{Note|This section documents an optional customization to AppBoard/enPortal that is not part of the core system or supported under the standard product maintenance contract.  It is recommended that this solution be implemented as part of a consulting engagement to ensure that it is configured and implemented correctly.  This solution offers some pieces of provisioning, but does not offer all of the provisioning options that are available in the application's web administration interface.}}
=== Installation and Configuration ===
Perform the following steps to create an XML Load file for custom batch provisioning:
# Save the code shown in the "XML Code" section below into a text file with the file name: batchLoad.xml
# Modify the XML code as appropriate to meet the needs of the customer.
# Save the file in to <tt>${Application_Home}/server/webapps/enportal/WEB-INF/xmlroot/server/provisioning/batchLoad.xml</tt>
# Load the XML File into the system, as detailed under <i>Applying Provisioning Updates</i>
=== XML Sample Code ===
<code>[xml,N]
<code>[xml,N]
<?xml version="1.0" encoding="UTF-8"?>
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE AccountDefinitions SYSTEM "../dtds/AccountDefinitions.dtd">
<!DOCTYPE AccountDefinitions SYSTEM "../dtds/AccountDefinitions.dtd">
<AccountDefinitions>
<AccountDefinitions>
<Role name="testing"/>
<Role name="testing"/>
<Role name="manager" parentRoleID="/testing"/>
        <Role name="training"/>
 
<Domain name="EdgeFairfax">
<Domain name="EdgeFairfax">
<User userID="ktaylor">
<User userID="jsmith">
<RoleLink roleID="/testing/manager"/>
<RoleLink roleID="/testing"/>
<RoleLink roleID="/training"/>
<RoleLink roleID="/training"/>
</User>
</User>
<User userID="jrowe">
<User userID="emustermann">
<RoleLink roleID="/training/instructor"/>
<RoleLink roleID="/training"/>
</User>
</User>
</Domain>
</Domain>
<Domain name="EdgeLaurel">
 
<User userID="cmorgan">
<Domain name="EdgeAustralia">
<User userID="jbloggs">
<RoleLink roleID="/testing"/>
<RoleLink roleID="/testing"/>
</User>
</User>
Line 58: Line 42:




=== Applying Provisioning Updates ===
When loaded, the above example will:
 
* create 2 roles: ''testing'', and ''training''
* create 2 domains:
** ''EdgeFairfax'' with users ''jsmith'' and ''emustermann''
** ''EdgeAustralia'' with user ''jbloggs''
* assign roles to those users:
** jsmith: ''testing'' and ''training''
** emustermann: ''training''
** jbloggs: ''testing''
 
== Loading the XML ==
 
The AppBoard server must be told to process the XML file. This is done by creating a list of files to process and either restarting the server or using the administration interface to trigger a load.
 
# Create an XML file with the appropriate user, domain, and role definitions as outlined above. This file needs to be placed onto the AppBoard server into the following directory: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/provisioning/''yourfile.xml''</tt> (''yourfile.xml'' can be anything as long as it ends with <tt>.xml</tt>).
# Creating a load list:
## This is a simple text file with one line per XML file to be loaded.
## The file path is relative to the server xmlroot, so for the example above it should contain a single line with the following: <tt>provisioning/''yourfile.xml''</tt>
## Save this file as <tt>load_provisoning.txt</tt> and place onto the AppBoard server into the following directory: <tt>[INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server</tt>
# Triggering a load:
#* Either restart the AppBoard server or
#* Via the administration interface and manually triggering an XML Import:
#*# Log into AppBoard as an administrator
#*# switch to the enPortal interface.
#*# Browse to ''Advanced -> Utilities -> XMLImport''.
#*# Click the ''Start'' button.


Perform the following steps to apply provisioning updates using the XML batch file:
After a successful load the changes should be visible in the administration interface for users, domains, and roles. The <tt>load_provisioning.txt</tt> file on the AppBoard server will be renamed so that this operation is not performed again on restart.


# Follow the steps above under <i>Installation and Configuration</i> to save the XML code into the application file system as <tt>${Application_Home}/server/webapps/enportal/WEB-INF/xmlroot/server/provisioning/batchLoad.xml</tt>.
{{Note|Batch loading via XML is an additive operation. i.e. it can only be used to '''add''' users, domains, roles, and role assignments, not remove them.}}
# Create the following single-line file as <tt>${Application_Home}/server/webapps/enportal/WEB-INF/xmlroot/server/loadBatch.txt</tt>:
#*  provisioning/batchLoad.xml
# Perform the following steps to load the XML file into the system database:
#* Log into enPortal/AppBoard as an administrator.
#* Go to the enPortal URL: <tt>http://<<i>hostname</i>>:<i>port</i>/enportal/home</tt>
#* Under the “Advanced” tab, select “XMLImport”.
#* Click “Start” to detect and load the XML file into enPortal.
#* Observe the message that batchLoad.txt was loaded into the system.
#* In the Admin UI, review and confirm that the new User accounts and assignments were automatically created.

Latest revision as of 15:20, 16 July 2014

Overview

Rather than managing users through the AppBoard administration interface, or via LDAP-based authentication integration, it's also possible to batch load domains, users, roles, and role assignment via XML files.

This document covers the XML format and process to load the file. For a general overview and links to manage users via the AppBoard administration interface, refer to the main Provisioning documentation.


Template-warning.png
Using batch loading via XML files is considered a customization of AppBoard and not directly supported under the standard product maintenance contract. It is recommended this type of solution be implemented as part of a consulting engagement to ensure that it is configured and implemented correctly.

XML Format

The XML file format is defined by the AccountDefinitions document type definition (DTD). This can be found at [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/dtds. Refer to this document for a complete reference, as below is a simple example:

[xml,N] <?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE AccountDefinitions SYSTEM "../dtds/AccountDefinitions.dtd"> <AccountDefinitions> <Role name="testing"/>

       <Role name="training"/>

<Domain name="EdgeFairfax"> <User userID="jsmith"> <RoleLink roleID="/testing"/> <RoleLink roleID="/training"/> </User> <User userID="emustermann"> <RoleLink roleID="/training"/> </User> </Domain>

<Domain name="EdgeAustralia"> <User userID="jbloggs"> <RoleLink roleID="/testing"/> </User> </Domain> </AccountDefinitions>


When loaded, the above example will:

  • create 2 roles: testing, and training
  • create 2 domains:
    • EdgeFairfax with users jsmith and emustermann
    • EdgeAustralia with user jbloggs
  • assign roles to those users:
    • jsmith: testing and training
    • emustermann: training
    • jbloggs: testing

Loading the XML

The AppBoard server must be told to process the XML file. This is done by creating a list of files to process and either restarting the server or using the administration interface to trigger a load.

  1. Create an XML file with the appropriate user, domain, and role definitions as outlined above. This file needs to be placed onto the AppBoard server into the following directory: [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server/provisioning/yourfile.xml (yourfile.xml can be anything as long as it ends with .xml).
  2. Creating a load list:
    1. This is a simple text file with one line per XML file to be loaded.
    2. The file path is relative to the server xmlroot, so for the example above it should contain a single line with the following: provisioning/yourfile.xml
    3. Save this file as load_provisoning.txt and place onto the AppBoard server into the following directory: [INSTALL_HOME]/server/webapps/enportal/WEB-INF/xmlroot/server
  3. Triggering a load:
    • Either restart the AppBoard server or
    • Via the administration interface and manually triggering an XML Import:
      1. Log into AppBoard as an administrator
      2. switch to the enPortal interface.
      3. Browse to Advanced -> Utilities -> XMLImport.
      4. Click the Start button.

After a successful load the changes should be visible in the administration interface for users, domains, and roles. The load_provisioning.txt file on the AppBoard server will be renamed so that this operation is not performed again on restart.

Template-note.png
Batch loading via XML is an additive operation. i.e. it can only be used to add users, domains, roles, and role assignments, not remove them.