Last modified by Aurelie Bertrand on 2025/02/07 10:18
Show last authors
1 {{ddtoc/}}
2
3 ----
4
5 = **{{id name="__RefHeading___Toc1848_2652393712"/}}**Description =
6
7 **importtools **is a tool for managing users in DigDash LDAP. It is particularly useful for managing a large user base.
8
9 importtools can be run directly using the "importtools.bat" command file provided, with the default arguments (which can be modified by editing the .bat file)
10
11 or
12
13 It can be run via the "importtools.jar" Java tool provided in the <digdash_install>\add-ons\tools\lib folder with default or customisable arguments (see next section).
14
15 (% class="box infomessage" %)
16 (((
17 java -jar importtools.jar [-conf configfile] [-users userfile] [-out outputfile]
18 )))
19
20 (% class="box warningmessage" id="HImportationd2019utilisateurs" %)
21 (((
22 {{id name="__RefHeading___Toc474_3721803795"/}}
23
24 Since version 2022R1, the value of the **langChoice **user parameter is now a language code rather than an index. For example, 0 has become "en", 1 has become "fr". You need to take this change into account and adapt your existing user import scripts if necessary.
25 )))
26
27 = Importing users =
28
29 This mainly involves having two input files:
30
31 * the configuration file in XML format: the example file conf.xml is delivered in <digdash_install>\add-ons\tools\importtools; It is used to map a column in the users file (see next) to an attribute of an LDAP user in the output file (see next).
32 * the user file in Excel or CSV format: the example file users.xls is delivered in <digdash_install>\add-ons\tools\importtools; This is the user database (one line per user) to be imported into LDAP. Its columns correspond to the attributes in the XML configuration file.
33
34 And an output file:
35
36 * the output file in XML format: named "out.xml" by default, it is generated when the "importtools" tool is launched with the two files mentioned above as input; it is generated in such a way as to map onto the LDAP structure.
37
38 |=Tag|=Description
39 |**-conf** <config file>|Path to the XML configuration file. By default, conf.xml.
40 |**-users** <excel file / csvfile>|Path to the input file of users to be imported. This can be an Excel file or a CSV file. By default, users.xls.
41 |**-out** <outputfile>|Path to the XML output file mapping to LDAP. By default, out.xml.
42 |**-help**|Usage help command.
43 |**-debug**|Displays traces of errors.
44 |**-import**|Sends the output file (by default out.xml) to the server for import into LDAP.
45 |**-importonly**|Uses an existing output file (by default, out.xml) and sends it to the server to be imported into LDAP.
46 |**-server**|Address of the DigDash server.
47 |**-domain**|DigDash Enterprise domain name (for example, ddenterpriseapi)
48 |**-user**|The supervisor user.
49 |**-pass**|The password of the supervisor user.
50
51 = {{id name="__RefHeading___Toc476_3721803795"/}}Commands for adding users =
52
53 There are three ways of adding a user to LDAP:
54
55 == create ==
56
57 In this mode the user will be added if, and only if, it does not exist.
58 In other words, with the create command, adding an existing user is an error.
59
60 == overwrite ==
61
62 This command will overwrite an existing user.
63 To be more precise, the user will be deleted before being completely created with the new attributes.
64 If the user does not already exist, it will simply be added.
65
66 == update ==
67
68 This command will update the user with the attributes contained in your import file.
69 The user must already exist. It will not be deleted.
70
71 = {{id name="__RefHeading___Toc476_3721803795"/}}Deleting users =
72
73 You can delete all or some of the users in the DigDash LDAP database.
74
75 |=Tag|=Description
76 |**-removeall**|Deletes ALL users present in LDAP AND the license.
77 |**-removeall -attr=**"ldap attribute name" **-regexp=**"attribute value or regular expression|Removes all users whose specified ldap attribute value checks the regular expression.
78 |**-removeall -license_type=**"all.missing.forbidden.[usertype]"|(((
79 Removes all users according to their type or status in the licence:
80
81 * **all**: all
82 * **missing **: users not in the licence
83 * **forbidden**: users in the licence but not authorised
84 * [**user type]**: possible values are **named**, **extranet**, **concurrent**, **public**, **broadcast**.
85 None, one or more values can be used, separated by a ".".
86 Example: named.extranet or missing.extranet.named
87
88 At least one of these parameters must be used.
89 )))
90
91 = {{id name="__RefHeading___Toc478_3721803795"/}}Exporting users =
92
93 It is possible to export users from the LDAP database.
94
95 **Options :**
96
97 |=Tag|=Description
98 |**-export**|Exports all users to a CSV file. By default, the export file is called users_export.csv.
99 |**-exportfile** "file.csv|Exports all users to the CSV file indicated by its absolute path (preceded by **-export**).
100
101 (% id="HIV.Exemples" %)
102 = {{id name="__RefHeading___Toc1856_2652393712"/}}General parameters =
103
104 |(% colspan="2" %)**Logs**
105 |**-log** "C:\temp"|The log file will be created in the specified directory, named as follows: importtool-yyyy-mm-dd_hh-mm-ss.log.
106 |**-log** "C:\log.txt"|The log file will be created in the directory and under the name specified.
107 |(% colspan="2" %)**Other**
108 |**-loginForm**|Forces LDAP authentication in the SSO case.
109
110 = Examples =
111
112 * **java -jar importtools.jar**
113 * **java -jar importtools.jar -conf ../importtools/conf.xml -users ../importtools/users.xls -out ../importtools/out.xml**
114 * **java -jar importtools.jar -conf ../importtools/conf.xml -users ../importtools/users.xls -out ../importtools/out.xml -import -server http:~/~/localhost:8080 -domain ddenterpriseapi -user admin -pass admin**
115 * **java -jar importtools.jar -export -server http:~/~/localhost:8080 -domain ddenterpriseapi -user admin -pass admin**
116 * **java -jar importtools.jar -export -exportfile "D:\my_users_export.csv" -server http:~/~/localhost:8080 -domain ddenterpriseapi -loginForm -user admin -pass admin**
117 * **java -jar importtools.jar -removeall -server http:~/~/localhost:8080 -domain ddenterpriseapi -user admin -pass admin**
118 * **java -jar importtools.jar -removeall -attr "license_type" -regexp "extranet" -server http:~/~/localhost:8080 -domain ddenterpriseapi -user admin -pass admin**
119 * **java -jar importtools.jar -removeall -attr "uid" -regexp "toto1[0-9]*" -server http:~/~/localhost:8080 -domain ddenterpriseapi -user admin -pass admin**
120
121 = Troubleshooting encoding errors on Windows =
122
123 Windows can contain encoding errors. To overcome these errors, you need to add the following command when exporting:
124
125 {{code language="shell"}}
126 -Dfile.encoding=utf-8
127 {{/code}}
128
129 This command is a parameter for JAVA, so you need to place it upstream of the options for importtool.jar. For example:
130
131 {{code language="shell"}}
132 "C:\java.exe" -Dfile.encoding=utf-8 -jar "importtools.jar" %* -export -exportFile "export_.csv" -server https://serveur.digdash.com -domain ddenterpriseapi -user admin -pass "AdminPassWrd"
133 {{/code}}
134
135 = SSL certificate problem =
136
137 (% class="wikigeneratedid" id="HContexte" %)
138 Running the **importtools **module to import users in batch to a DigDash server protected by an **SSL certificate, **from your local workstation or a workstation that is not the DigDash server, may fail because the SSL certificate has been incorrectly configured.
139 You are likely to get the following message when you run the script:
140
141 (% class="box errormessage" %)
142 (((
143 2020-11-09 20:39:34,407 INFO [main] (DDEnterpriseAPIRest.java:1593) - Exception raised (params: clientId=ImportTool, method=login, pass=~*~*~*~*~*~*, user=~#~#~#~##@~#~##.fr): URL download error: https:~/~/~#~##.fr/~#~#~#~#DOMAINE~#~##/DDEnterpriseAuthServlet
144 )))
145
146 (% class="wikigeneratedid" id="HContournement" %)
147 To work around this problem :
148
149 1. Modify the **importools.bat** file **.**
150 1. Add the **-DSSLNoPathCheck=true **parameter before **-jar **as in the example below:
151
152 (% class="box" %)
153 (((
154 java -Dlog4j.configuration="file:~/~//%importtoolshome%/import_log4j.properties" **-DSSLNoPathCheck=true** -jar "%importtoolshome%/importtools.jar" %* -conf conf.xml -users users.xls -out out.xml -import -server https:~/~/~#~##.fr -domain ~#~##DOMAIN~#~## -user admin -pass ~#~#PASS~#~#
155 )))