Import and export users/roles
You can provision a standalone node or a primary node with users and/or roles by importing a user file. Such a file can be created by exporting users from another Decision Insight deployment, or with an external process by following the User file format.
Import users/roles
You must never upload untrusted files to your installation. Make sure to have every file scanned by an anti-malware software before it can be used in the product.
You can import users and/or roles from the user interface, via shell commands, JMX or via automatic provisioning.
Import users/roles from the user interface
Step |
Action |
1 |
On the main menu, click the Configuration icon. On the left menu, click Roles. OR click the Security & Monitoring icon. On the left menu, click Users (process is the same on both screens).
|
2 |
Click the Import button.

|
3 |
Specify the date and time at which to perform the import and click the Import button.

|
4 |
Select the file containing users and/or roles with which you want to provision the node and click OK. |
5 |
If everything has been correctly imported, you are redirected to the previous screen and the new users/roles are displayed. |
6 |
If a problem arises, the popup stays open and displays an error message. Close the popup and correct the issues in your file, then re-import.

|
Import users/roles via automatic provisioning
To import users/roles via automatic provisioning, simply copy the import file into the <installation directory>/
var/data/carbon-provisioning/autoimport/incoming
directory of your standalone node or your primary node.
The node regularly scans this directory and automatically imports all files whose name end with .user.xml .
- If the file can be imported, users are imported and the file is moved to the Done subdirectory (the file name is prefixed with the import date).
- If an error occurs during the import, the file is moved to the error subdirectory (the file name is prefixed with the import date). An error message is logged.
Possible errors are:
- An entry is missing a mandatory attribute/element.
- An entry specifies both a password and a hash for a user.
- Multiple entries have an identical user name.
A temporary file (named after the file but with the .tmp
extension) is created at the beginning of an import process and deleted just after the import has completed.
For more information, see Automatic process .
Import users/roles from the shell
To import users and/or roles from the shell, use the importUsers
command.
importUsers <input file path>
Examples
Import users and/or roles from C:\export.user.xml
g! importUsers "C:\\export.user.xml"
Users/roles from [C:\export.user.xml] successfully imported into the platform
g!
Import users/roles via JMX
Step |
Action |
1 |
Use a JMX client such as jconsole and connect to the application |
2 |
In the
MBeans tree, open the node
com.systar.carbon.security.impl.UserManagerCommandsMXBean

|
3 |
You can then invoke the operation importUsers. The operation is self-documented in JMX. |
Export users/roles
You can export users and/or roles from the graphical user interface, from the shell or via JMX.
Export users/roles from the user interface
Step |
Action |
1 |
On the main menu, click the Configuration icon. On the left menu, click Roles. OR click the Security & Monitoring icon. On the left menu, click Users.
|
2 |
Click the Export button. 
|
3 |
Select what you want to export, then click the Export button to generate an export file.

|
4 |
Click the Download here hyperlink and save the file onto your computer

|
Export users/roles from the shell
To export users from the shell, use the exportUsers
command.
exportUsers <output file path> true|false true|false
g! ? exportUsers
exportUsers - Export users information into a file
scope: carbon-user
parameters:
String Full path of the export file (ex: "~/export/my_node.users.xml")
boolean true to include users in xml
boolean true to include roles in xml
g!
Examples
Export users into C:\export.user.xml
g! exportUsers "C:\\export.user.xml" true true
Users successfully exported into [C:\export.user.xml]
g!
Export users/roles via JMX
Step |
Action |
1 |
Use a JMX client such as jconsole and connect to the application. |
2 |
In the MBeans tree, open the node com.systar.carbon.security.impl.UserManagerCommandsMXBean 
|
3 |
You can then invoke the operation exportUsers. The operation is self-documented in JMX . |
The name of XML files must end with .user.xml.
An example of a valid file name is list.user.xml
.
The XML file must comply with the following format (sample content: list.user.xml ):
<users xmlns="http://www.systar.com/carbon/users">
<role name="...">
<description>...</description>
<platformCapability name="..."/>
</role>
<user name="..." password="..." hash="..." firstName="..." lastName="..." email="..." avatar="..." developmentMode="..." accountDisabled="..." authenticationDelegated="...">
<description>...</description>
<role name="..."/>
</user>
</users>
Role syntax
Each role is defined with the following attributes/elements:
Attribute / Element |
Description |
Mandatory / Optional |
name |
Name of the role. |
mandatory |
description |
A role description (see below) |
optional |
platformCapability.name |
Name of the capability granted to the role (see below) |
optional, multiple |
User syntax
Each user is defined with the following attributes/elements:
Attribute / Element |
Description |
Mandatory / Optional |
name |
Name of the user. The only valid characters are lowercase letters, numbers, dashes, underscores and periods.
|
mandatory |
password |
Password of the user, in clear form |
either password or hash attributes must be filled or authenticationDelegated must be set to true |
hash |
Password of the user, in hashed form ( using PBKDF2 (Wikipedia), HMAC, 4096 iterations and a 24 bytes salt) |
either password or hash attributes must be filled or authenticationDelegated must be set to true |
firstName |
First name of the user |
optional |
lastName |
Last name of the user |
optional |
email |
Email of the user |
optional |
description |
A user description (see below) |
optional |
avatar |
Name of the user avatar |
optional (default: none) |
developmentMode |
Whether the development mode is active in the interface |
optional (default: false) |
accountDisabled |
Whether the user account is disabled |
optional (default: false) |
authenticationDelegated |
Whether the password is stored on another system such as LDAP |
mandatory If set to true, password and hash must not be set. |
role.name |
Name of a role for the user |
optional, multiple |
The user file is using a UTF-8 encoded charset: it means you can use accents in your attributes (except name and password, due to authentication rules).
Description
Description of a user or role is a multiline field, and it must be contained in its own tag.
You can enter text directly within the tag, or use a CDATA
section if you need multiline (and other) abilities:
<users xmlns="http://www.systar.com/carbon/users">
<user name="user1" authenticationDelegated="true"><description>Simple user description</description></user>
<user name="user2" authenticationDelegated="true">
<description><![CDATA[User description on its own tag.
You can use multi line description !!
Groovy baby !]]></description>
</user>
</users>
When creating / updating roles, you can use one of the following names in the attribute platformCapability.name
platformCapability.name |
Full name |
data-integration-api |
Access data integration API |
debug-tools |
Access debugging tools |
full-admin |
Bypass Security |
libraries-import |
Access data integration libraries (UI/Import) |
manage-application |
Manage the application |
platform-administration |
Access administration tools |
platform-logs |
Access logs |
platform-monitoring |
Access monitoring tools |
rights-management |
Manage users and roles |