To improve this functionality, we only need to extends (mdl_user_add_instance) to add_users defining:

array_users (Array) containing each user as:

• firstname (string)
• lastname (string)
• email (string)
• idnumber (string)
• authentication_method (string)

/**

• Adds a new user to the user database
• @private ?
• @param array $user
• $user format:
• <ul>
• <li>$user[firstname]</li>
• <li>$user[lastname]</li>
• <li>$user[email]</li>
• <li>$user[idnumber]</li>
• <li>$user[login]</li>
• <li>$user[auth]</li>
• <li>$user[pass]</li>
• </ul>
• @return int|boolean new user id or false
  */
  function add_user($user){
  }

/**

• Add several users to users database
• @param array $users
• $users format:
• <ul>
• <li>$users[i][firstname]</li>
• <li>$users[i][lastname]</li>
• <li>$users[i][email]</li>
• <li>$users[i][idnumber]</li>
• <li>$users[i][login]</li>
• <li>$users[i][auth]</li>
• <li>$users[i][pass]</li>
• </ul>
• @uses add_user
• @return array|boolean array of new user ids or false
  */
  function add_users($users){
  }

1) Are you sure that the minimal list of fields provided here is enough for a successful first authentication of the created users without automatic redirection to his/her profile page to fill up missing required information ? Situation will be different depending of the auth method and synchronization strategy . Example : with ldap sync at every connexion, fisrtname, lastname and email may not be mandatory since they will be overwritten anyway at user's connexion ...

2) What about the password ? should it be converted to md5 on client before sending it to server or sent in clear and md5ized on the server ?

3) In OK tech implementation I had to make sure that the mnethostid field was also set before adding record to mdl_user table, otherwise login was later refused

4) the question of other fields, either "official" such as city, description, icq ... or "local" with the new "local custom fields" should be also addressed. Will you allow them at user creation, with some extra possible errors such as "illegal field name" or later in a set_user () or modify_user() operation ?

5) How do you return unevitable creation errors messages (duplicate username, duplicate email, missing required field, bad authentication method ... ? false seems to me not informative enough.

My 5 cents ...

1) It works with a manual auth, I haven't tested wih other methods. idnumber is not necessary but, in my opinion, can be very useful. Other field can be set by default or figured them out.

2) Password must be MD5 for this API function (it's a server function, WS layer must invoke it). I'm agree with you, client must encrypt the pwd before sending it.

3) I'm setting mnethostid to 1 by default. May we add another param or create a new function for mnet users? It can be a not mandatory param, if $user[mnethostid] is set, we use it, otherwise database field can be set to 1.

4) I rather modify_user($field, $value) than fatten up with code add_user operation. What's your opinion?

5) Moodle 2.0 was supposed to use PHP5......mmmm...... exceptions? ................... or we can define some error constants and return negative ints. In WS layer, the best solution is an error message.

http://cvs.moodle.org/contrib/patches/dfws/webservice/apis/user.lib.php?revision=1.3&view=markup

I think that the main purpose of WS is to make easier the implementation of 3rd party applications, without worrying about internal ids . Because of this I set idnumber is a mandatory. I take the example from flatfile role assigments format in Moodle (http://docs.moodle.org/en/enrol/flatfile). By now, obligatory fields are:

-username (obvious)
-idnumber
-firstname (obvious)
-lastname (obvious)
-email (is unique and not null)

And recommended fields are:

-password (in MD5)
-auth (Default is Manual)
-confirmed (for email and remote administration)

But required fields can be changed easily.

PD: Ludo, make me participant on WS Issues.

The name of the function in the implementation (http://cvs.moodle.org/contrib/patches/dfws/webservice/apis/user.lib.php?revision=1.3&view=markup ) is:

mdl_user_add_instances

This is because all WS function's names are organized in packages to avoid name collisions and make it easier to find later. It's like function's names in modules. Let's see the particles:

-mdl: this functions belongs to system package called mdl (can be found apis dir). In the future would be more packages like forum or wiki.
-user: this function is a part of user management api (can be found in apis/user.lib.php)
-add_instances: is just a name

The only parameter is an array of associative arrays (with the desired field) and it returns an associative array of username=>internal id (or -1 if there's an error).