Function prototype	team_user_insert ( session, user , team, [roles])
API Version	All
Supported interfaces	SOAP, REST (Since API Version 2.7.31)

Description

Short description of the function.

Creates a new user and adds it as a member of a team

NOTE: The format of the response changed in version 2.7.12. See Response format prior to version 2.7.12 for additional information

Required permissions: The active user must have role TEAM MANAGER in the affected TEAM. Otherwise an INSUFFICIENT_PRIVILEGES error will be returned.

1 Description
2 Request example
- 2.1 Response
3 Return Error codes
4 PRIVATE TEAMS
- 4.1 Example
5 Response format in version prior to version 2.7.12

Input parameters:

session: a token obtained by calling session_init ()
user: a user xml
- ref: id refs to external sources (i.e. radius authentication systems)
- data: user data
  - nickname: an optional “alias” for the user
  - contact: user contact data. See user_get_contact () and user_set_contact ()
  - username: Linkcare’s user name for login pruposes
  - bdate: birthday date
  - status: (ACTIVE|INACTIVE) is user is active
  - preferences
    - team_private: indicates whether a "private team" must be created along with the new user. See notes about team_user_insert ()#PRIVATE TEAMS below
    - private_program_code: only makes sense if "team_private = true". Is the PROGRAM CODE in which a subscription will be created for the private team. See notes about team_user_insert ()#PRIVATE TEAMS below
    - editable_by_user
    - editable_by_team_manager
team: reference or TEAM CODE of the parent TEAM in which the new USER will be inserted as a member.
roles: Comma separated string with the list of ROLES that will be assigned to the new USER member. Introduced in API Version 2.7.27

Output parameters:

result: XML with information about the execution of the function:
- user: reference to the new USER created or empty if any error occurred
- type: ("NEW" / "EXIST") If the operation was successful, indicates whether a new CASE was created or a existing one that matched the information was used
- validation: This information is generated only if an error of type CONTACT_DATA.VALIDATION happens. See CONTACT DATA VALIDATION for a detailed explanation of the validation information
ErrorMsg: any fault in the call, either in the validation of input parameters, errors in the connection to the database or any other error, this parameter returns the error message produced
ErrorCode: If any error occurs, then this value contains any of the standard ERROR CODES

Request example

team_user_insert ( “LCAAAAAAAAAAAA”, "
<?xml version="1.0" encoding="UTF-8"?>
<user>
  <refs>
    <ref>
      <source>URL</source>
      <id>1234</id>
    </ref>
    <ref>…</ref>
  </refs>
  <data>
    <nickname>Raul P.M.</nickname>
    <contact></contact>
    <username></username>
    <bdate>
    </bdate>
    <gender>M|F</gender>
    <status>ACTIVE|INACTIVE</status>
    <preferences>
      <team_private>false</team_private>
      <private_program_code>REGISTRATION</private_program_code>
      <editable_by_user>false</editable_by_user>
      <editable_by_team_manager>true</editable_by_team_manager>
    </preferences>
  </data>
</user>
", "LINKCARE")

Response

The response format is XML when the function has been invoked via the SOAP API, and JSON when it has been invoked via the REST API

Return Error codes

ERROR CODE

ERROR CODE
INVALID_TOKEN	The session token provided is not valid
XML_ERROR	The information provided for creating the CASE does not have a valid XML format
INSUFFICIENT_PRIVILEGES	The session user does not have the necessary privileges to execute this action
TEAM.NOT_FOUND	The TEAM provided was not found
CONTACT_DATA.VALIDATION	The information provided to validate the CASE is not valid

PRIVATE TEAMS

When the property "team_private" is true, a new TEAM will be created that will be internally associated to the new USER. A USER can only have one private PRIVATE TEAM and the characteristics of this TEAM are:

The TEAM OWNER of the PRIVATE TEAM will be the ACTIVE TEAM of the SESSION
The PARENT TEAM will be included as member of the PRIVATE TEAM with roles (supervisor, Team Manager, Team Editor, Library Manager)
The ACTIVE TEAM will be included as member of the PRIVATE TEAM with roles (Team Manager, Team Editor)
The new USER will be included as member of the PRIVATE TEAM with role "Case Manager" (necessary to create ADMISSIONS)
The SETTINGS of the PRIVATE TEAM will be inherited from the PARENT TEAM

Additionally, a new SUBSCRIPTION will be created automatically. The subscription will be created for a PROGRAM determined by the following rules:

If the property private_program_code is set, then use this PROGRAM CODE to create the subscription
Otherwise, if the setting #TEAM.PRACTICE_DEFAULT_PROGRAM (see SETTINGS OBJECT) is defined for the PARENT TEAM.
If no PROGRAM CODE has been defined, or it is invalid (the PROGRAM CODE does not exist) then an error will be returned

Once the SUBSCRIPTION is created, the PARENT TEAM and the new USER will be added as members:

PARENT TEAM will be added to the SUBSCRIPTION with role (supervisor)
new USER will be added to the SUBSCRIPTION with role (Case manager)

Example

Consider a situation where 2 users called “Doctor 1” and “Doctor 2” have been added as members of the “Parent Team” and both of them have their own PRIVATE TEAM:

Response format in version prior to version 2.7.12

The XML response generated in previous versions was the following

result: reference to the new USER created or empty if any error occurred
type: ("NEW" / "EXIST") If the operation was successful, indicates whether a new USER was created or a existing one that matched the information was used
ErrorMsg: any fault in the call, either in the validation of input parameters, errors in the connection to the database or any other error, this parameter returns the error message produced
ErrorCode: If any error occurs, then this value contains any of the standard ERROR CODES

<?xml version="1.0" encoding="utf-8" standalone="yes"?>
<result>user_id</result>
<type>NEW</type>
<ErrorMsg></ErrorMsg>

Linkcare Server WS API

team_user_insert ()