Webservice: Security

users and groups handling

Index Method Request(s) Response Description
1 getUserByUsername sid
username
 user finds a user by his username
2 changePassword sid
userId
oldPassword
newPassword
 changeResult changes the password of a user.
0 if all is ok, 1 if the password is incorrect, 2 if the new password cannot be notified, otherwise a positive number grater than 2
3 deleteGroup sid
groupId
 deletes an existing group
4 listUsers sid
group
 user gets all existing users
5 storeUser sid
user
 userId creates/updates a user; you can completely customize the user through a value object containing the user's metadata;
the current user must be an administrator;
returns the identifier of the created/updated user
6 deleteUser sid
userId
 deletes an existing user
7 storeGroup sid
group
 groupId creates/updates a group; you can completely customize the group through a value object containing the group's metadata;
the current user must be an administrator;
returns the identifier of the created/updated user
8 listGroups sid
 group gets all existing groups
9 getUser sid
userId
 user gets an existing user
10 getGroup sid
groupId
 group gets an existing group

Method #1: getUserByUsername

finds a user by his username

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     username
String Y

Response

Name Type Required Multiple Description
     user
WSUser Y
          id
Long Y unique identifier
          username
String Y
          password
String
          decodedPassword
String
          passwordmd4
String
          name
String
          firstName
String
          street
String
          postalcode
String
          city
String
          country
String
          state
String
          language
String default language; See specification
          email
String Y address used for notifications, must be a valid e-mail
          emailSignature
String a simple text to be used as a signature in the footer of the outgoing emails
          email2
String secondary email address, must be a valid e-mail
          emailSignature2
String a simple text to be used as a signature in the footer of the outgoing emails
          telephone
String
          telephone2
String
          company
String
          department
String
          organizationalUnit
String
          building
String
          type
Int Y must be 0: normal or 2: guest
          groupIds
Long Y Y ids of the groups this user belongs to
          enabled
Int Y if 1 the user is enabled, if 0 the user is disabled
          enforceWorkingTime
Int Y if 1 the user can connect during working time only
          passwordChanged
String last time the password was changed (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          passwordExpires
Int Y if 1 the password is eligible for expiration, if 0 the password never expires
          evalFormEnabled
Int Y if 1 the evaluation form is available, if 0 the evaluation form is not evailable
          source
Int Y must be 0
          quota
Long Y maximum allowed user's quota expressed in bytes, -1 for no limits
          quotaCount
Long Y actual quota used by the user
          lastModified
String
          lastLogin
String last time the user has logged in
          creation
String when the user has been created
          dateFormat
String date format to use when display dates
          dateFormatShort
String date format to use when display dates in short format
          dateFormatLong
String date format to use when display dates and times
          searchPref
String comma separated list of searches that defines the order they are displayed in the user interface
          expire
String when this account expires
          workingTimes
WSWorkingTime Y the working time specification
               dayOfWeek
Int Y the day of week ranges from 1 (Sunday) to 7 (Saturday)
               hourStart
Int Y the start hour in the day (0-23)
               minuteStart
Int Y the start minute in the day (0-59)
               hourEnd
Int Y the end hour in the day (0-23)
               minuteEnd
Int Y the end minute in the day (0-59)
               label
String an optional label to give to this working time
               description
String an optional description to give to this working time
          maxInactivity
Integer maximum number of inactivity days after which the account gets disabled
          timeZone
String the time zone of the suer
          secondFactor
String the second factor authenticator to use
          key
String key used by the second factor authenticator

Method #2: changePassword

changes the password of a user.<br/><b>0</b> if all is ok, <b>1</b> if the password is incorrect, <b>2</b> if the new password cannot be notified, otherwise a positive number grater than <b>2</b>

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     userId
Long Y
     oldPassword
String Y
     newPassword
String Y

Response

Name Type Required Multiple Description
     changeResult
Int Y

Method #3: deleteGroup

deletes an existing group

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session
     groupId
Long Y

Method #4: listUsers

gets all existing users

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     group
String Y if not null, all the users that belong to this group will be returned

Response

Name Type Required Multiple Description
     user
WSUser Y Y
          id
Long Y unique identifier
          username
String Y
          password
String
          decodedPassword
String
          passwordmd4
String
          name
String
          firstName
String
          street
String
          postalcode
String
          city
String
          country
String
          state
String
          language
String default language; See specification
          email
String Y address used for notifications, must be a valid e-mail
          emailSignature
String a simple text to be used as a signature in the footer of the outgoing emails
          email2
String secondary email address, must be a valid e-mail
          emailSignature2
String a simple text to be used as a signature in the footer of the outgoing emails
          telephone
String
          telephone2
String
          company
String
          department
String
          organizationalUnit
String
          building
String
          type
Int Y must be 0: normal or 2: guest
          groupIds
Long Y Y ids of the groups this user belongs to
          enabled
Int Y if 1 the user is enabled, if 0 the user is disabled
          enforceWorkingTime
Int Y if 1 the user can connect during working time only
          passwordChanged
String last time the password was changed (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          passwordExpires
Int Y if 1 the password is eligible for expiration, if 0 the password never expires
          evalFormEnabled
Int Y if 1 the evaluation form is available, if 0 the evaluation form is not evailable
          source
Int Y must be 0
          quota
Long Y maximum allowed user's quota expressed in bytes, -1 for no limits
          quotaCount
Long Y actual quota used by the user
          lastModified
String
          lastLogin
String last time the user has logged in
          creation
String when the user has been created
          dateFormat
String date format to use when display dates
          dateFormatShort
String date format to use when display dates in short format
          dateFormatLong
String date format to use when display dates and times
          searchPref
String comma separated list of searches that defines the order they are displayed in the user interface
          expire
String when this account expires
          workingTimes
WSWorkingTime Y the working time specification
               dayOfWeek
Int Y the day of week ranges from 1 (Sunday) to 7 (Saturday)
               hourStart
Int Y the start hour in the day (0-23)
               minuteStart
Int Y the start minute in the day (0-59)
               hourEnd
Int Y the end hour in the day (0-23)
               minuteEnd
Int Y the end minute in the day (0-59)
               label
String an optional label to give to this working time
               description
String an optional description to give to this working time
          maxInactivity
Integer maximum number of inactivity days after which the account gets disabled
          timeZone
String the time zone of the suer
          secondFactor
String the second factor authenticator to use
          key
String key used by the second factor authenticator

Method #5: storeUser

creates/updates a user; you can completely customize the user through a value object containing the user's metadata;<br/>the current user must be an administrator;<br/>returns the identifier of the created/updated user

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     user
WSUser Y
          id
Long Y unique identifier
          username
String Y
          password
String
          decodedPassword
String
          passwordmd4
String
          name
String
          firstName
String
          street
String
          postalcode
String
          city
String
          country
String
          state
String
          language
String default language; See specification
          email
String Y address used for notifications, must be a valid e-mail
          emailSignature
String a simple text to be used as a signature in the footer of the outgoing emails
          email2
String secondary email address, must be a valid e-mail
          emailSignature2
String a simple text to be used as a signature in the footer of the outgoing emails
          telephone
String
          telephone2
String
          company
String
          department
String
          organizationalUnit
String
          building
String
          type
Int Y must be 0: normal or 2: guest
          groupIds
Long Y Y ids of the groups this user belongs to
          enabled
Int Y if 1 the user is enabled, if 0 the user is disabled
          enforceWorkingTime
Int Y if 1 the user can connect during working time only
          passwordChanged
String last time the password was changed (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          passwordExpires
Int Y if 1 the password is eligible for expiration, if 0 the password never expires
          evalFormEnabled
Int Y if 1 the evaluation form is available, if 0 the evaluation form is not evailable
          source
Int Y must be 0
          quota
Long Y maximum allowed user's quota expressed in bytes, -1 for no limits
          quotaCount
Long Y actual quota used by the user
          lastModified
String
          lastLogin
String last time the user has logged in
          creation
String when the user has been created
          dateFormat
String date format to use when display dates
          dateFormatShort
String date format to use when display dates in short format
          dateFormatLong
String date format to use when display dates and times
          searchPref
String comma separated list of searches that defines the order they are displayed in the user interface
          expire
String when this account expires
          workingTimes
WSWorkingTime Y the working time specification
               dayOfWeek
Int Y the day of week ranges from 1 (Sunday) to 7 (Saturday)
               hourStart
Int Y the start hour in the day (0-23)
               minuteStart
Int Y the start minute in the day (0-59)
               hourEnd
Int Y the end hour in the day (0-23)
               minuteEnd
Int Y the end minute in the day (0-59)
               label
String an optional label to give to this working time
               description
String an optional description to give to this working time
          maxInactivity
Integer maximum number of inactivity days after which the account gets disabled
          timeZone
String the time zone of the suer
          secondFactor
String the second factor authenticator to use
          key
String key used by the second factor authenticator

Response

Name Type Required Multiple Description
     userId
Long Y

Method #6: deleteUser

deletes an existing user

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session
     userId
Long Y

Method #7: storeGroup

creates/updates a group; you can completely customize the group through a value object containing the group's metadata;<br/>the current user must be an administrator;<br/>returns the identifier of the created/updated user

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     group
WSGroup Y
          id
Long Y unique identifier
          name
String Y must be unique
          description
String Y
          type
Int Y set it to 0
          inheritGroupId
Long inherit security policies from this referenced group at creation time
          userIds
Long Y Y set of users in this group
          lastModified
String the last modified date (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          source
String where the group was created, 'local' indicates it was created in the local database

Response

Name Type Required Multiple Description
     groupId
Long Y

Method #8: listGroups

gets all existing groups

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator

Response

Name Type Required Multiple Description
     group
WSGroup Y Y
          id
Long Y unique identifier
          name
String Y must be unique
          description
String Y
          type
Int Y set it to 0
          inheritGroupId
Long inherit security policies from this referenced group at creation time
          userIds
Long Y Y set of users in this group
          lastModified
String the last modified date (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          source
String where the group was created, 'local' indicates it was created in the local database

Method #9: getUser

gets an existing user

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     userId
Long Y

Response

Name Type Required Multiple Description
     user
WSUser Y
          id
Long Y unique identifier
          username
String Y
          password
String
          decodedPassword
String
          passwordmd4
String
          name
String
          firstName
String
          street
String
          postalcode
String
          city
String
          country
String
          state
String
          language
String default language; See specification
          email
String Y address used for notifications, must be a valid e-mail
          emailSignature
String a simple text to be used as a signature in the footer of the outgoing emails
          email2
String secondary email address, must be a valid e-mail
          emailSignature2
String a simple text to be used as a signature in the footer of the outgoing emails
          telephone
String
          telephone2
String
          company
String
          department
String
          organizationalUnit
String
          building
String
          type
Int Y must be 0: normal or 2: guest
          groupIds
Long Y Y ids of the groups this user belongs to
          enabled
Int Y if 1 the user is enabled, if 0 the user is disabled
          enforceWorkingTime
Int Y if 1 the user can connect during working time only
          passwordChanged
String last time the password was changed (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          passwordExpires
Int Y if 1 the password is eligible for expiration, if 0 the password never expires
          evalFormEnabled
Int Y if 1 the evaluation form is available, if 0 the evaluation form is not evailable
          source
Int Y must be 0
          quota
Long Y maximum allowed user's quota expressed in bytes, -1 for no limits
          quotaCount
Long Y actual quota used by the user
          lastModified
String
          lastLogin
String last time the user has logged in
          creation
String when the user has been created
          dateFormat
String date format to use when display dates
          dateFormatShort
String date format to use when display dates in short format
          dateFormatLong
String date format to use when display dates and times
          searchPref
String comma separated list of searches that defines the order they are displayed in the user interface
          expire
String when this account expires
          workingTimes
WSWorkingTime Y the working time specification
               dayOfWeek
Int Y the day of week ranges from 1 (Sunday) to 7 (Saturday)
               hourStart
Int Y the start hour in the day (0-23)
               minuteStart
Int Y the start minute in the day (0-59)
               hourEnd
Int Y the end hour in the day (0-23)
               minuteEnd
Int Y the end minute in the day (0-59)
               label
String an optional label to give to this working time
               description
String an optional description to give to this working time
          maxInactivity
Integer maximum number of inactivity days after which the account gets disabled
          timeZone
String the time zone of the suer
          secondFactor
String the second factor authenticator to use
          key
String key used by the second factor authenticator

Method #10: getGroup

gets an existing group

Request

Name Type Required Multiple Description
     sid
String Y identifier of the session, must be an administrator
     groupId
Long Y

Response

Name Type Required Multiple Description
     group
WSGroup Y
          id
Long Y unique identifier
          name
String Y must be unique
          description
String Y
          type
Int Y set it to 0
          inheritGroupId
Long inherit security policies from this referenced group at creation time
          userIds
Long Y Y set of users in this group
          lastModified
String the last modified date (format must be 'yyyy-MM-dd HH:mm:ss' or 'yyyy-MM-dd')
          source
String where the group was created, 'local' indicates it was created in the local database