AgileApps Support Wiki

REST API:user Resource

From AgileApps Support Wiki
Revision as of 22:28, 8 September 2011 by imported>Aeric (→‎Fields)

Performs actions on User records via the REST API

Access Permissions

Lock-tiny.gif

Users that have the Access Control/User Management permission can use this Resource. 

Determine if a Valid Session is in Progress

Determine if the current session is valid.

Method
GET
URI
https://{yourDomain}/networking/rest/user/isSessionValid
Response
:<syntaxhighlight lang="xml" enclose="div">

<platform> 

   <user>
       <is_session_valid>true</is_session_valid>
   </user>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Get Information about the Logged-In User

Gets information about the logged in user.

Method
GET
URI
https://{yourDomain}/networking/rest/user/info
Response
The same information returned by the query to Get a User Record: first name, last name, employee number, and so on.

Get a User Record

Retrieves data for the specified user.

Method
GET
URI
https://{domain}/networking/rest/user/{user_id}
Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <user>
       <id>16016a880c064ad1ba92115424851462</id>
       <first_name>John</first_name>
       <last_name>Smith</last_name>

       <full_name>John Smith</full_name>
       <phone/>
       <street/>
       <city/>
       <username>userA@gmail.com</username>
       <single_sign_on>0</single_sign_on>
       <community_user_id/>
       <auto_generated_community_user_record>0</auto_generated_community_user_record>
       <employee_number/>
       <fax/>
       <user_type>P</user_type>
       <country/>
       <last_login>1236041001000</last_login>
       <time_zone>12</time_zone>
       <email>userA@gmail.com</email>
       <company>CompanyA</company>
       <last_name>Smith</last_name>
       <date_last_password_change>2010-11-12T13:14:15Z</date_last_password_change>
       <active>1</active>
       <language>en</language>
       <mobile/>
       <state/>
       <date_created>2010-11-12T13:14:15Z</date_created>
       <title/>
       <reports_to type="" 
          uri="https://{domain}/rest/user/123qwe456rty"
          displayValue="John Smith">123qwe456rty</reports_to>
       <zip/>
       <alias/>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <object_id>USER</object_id>
       <customer_language>en</customer_language>
       <customerId>123223323</customerId>
       <created_id type="" 
         uri="https://{domain}/networking/rest/user/1524089492" 
         displayValue="Peter Parker">1424089492</created_id>
       <modified_id type="" 
         uri="https://{domain}/networking/rest/user/1524089492" 
         displayValue="Peter Parker">1424089492</modified_id>
   </user>

   <message>
       0
       <description>Success</description>
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Dynamic Search

Returns the fields requested by a dynamic search based on number of records, offset, sort column, sort order, and specified criteria.

Method
GET
URI
https://{domain}/networking/rest/user?{query_parameters}
Sample Search
?fieldList=name,id & filter=name contains 'smith' & sortby='id'
(Field names are in the Fields section.)
Query Parameters
  • fieldList - A comma-separated list of field names to retrieve
  • The asterisk (*) wildcard specifies all fields
  • {fieldname} specifies an individual field (e.g. name)
(Use the REST API:field Resource to get a complete list of fields.)
  • For a Composite Object, specify {alias}.{fieldname} to select a related-record field, where the alias is defined in the Object Relationships.
  • For a Database View, specify {alias}.{fieldname}, where the object alias is defined in the Database View.
  • alias.* specifies all fields in the aliased object.
  • filter - Filtering criteria to filter the records
  • pageSize - Number of records to retrieve from the result set in order to make a "page".
  • page - Number of the logical page in a database result set. The first page is page "zero" (0).
Page zero is returned by default, so appending &pageSize=1 to your query returns a single record.
  • getTotalRecordCount returns the number of total records.
    Causes the following structure to be returned, where N is the total number of records:
<syntaxhighlight lang="xml" enclose="div">

<platform> 

  <status>
  <packageDeploy>
  ...
  </packageDeploy>
  </status>
  <message>
     0
     <description>Success</description>
  </message>

  <totalRecordCount>N</totalRecordCount>

</platform> </syntaxhighlight>

  • sortBy - Field name for primary sort
    Ex: &sortBy=name
  • sortOrder - Sort order of the primary field, either asc or desc (ascending or descending)
    Ex: &sortOrder=desc
  • sortBy2 - Field name for secondary sort
  • sortOrder2 - Sort order of the second field, either asc or desc (ascending or descending)
For more information, see: Specifying Query Parameters in REST APIs
Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <record>
       <phone/>
       <street/>
       <state/>
       <date_created>2010-11-12T13:14:15Z</date_created>
       <city/>
       <id>1424089492</id>
       <first_name>Admin</first_name>
       <username>admin@platform.com</username>
       <title/>
       <primary_team>1</primary_team>
       <reports_to type="" uri="" displayValue=""/>
       <zip/>
       <employee_number/>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <object_id>USER</object_id>
       <last_login>1267756624000</last_login>
       <country/>
       <created_id type=""

uri="https://{domain}/networking/rest/user/5" displayValue="Platform Admin">5</created_id> 

       <time_zone>12</time_zone>
       <modified_id type=""
 	    uri="https://{domain}/networking/rest/user/16016a880c064ad1ba92115424851462"

displayValue="Sheela Sarva">16016a880c064ad1ba92115424851462</modified_id> 

       <email>demo@platform.com</email>
       <last_name>Platform</last_name>
       <active>1</active>
       <role_in_primary_team>1</role_in_primary_team>
   </record>

   <record>
       <phone/>
       <street/>
       <state/>
       <date_created>2010-11-12T13:14:15Z</date_created>
       <city/>
       <id>151b28b700dc45abbb12b65ea451fc97</id>
       <first_name>Me</first_name>
       <username>myusername</username>
       <title/>
       <primary_team>1</primary_team>
       <reports_to type="" uri="" displayValue=""/>
       <zip/>
       <employee_number/>
       <date_modified>2010-11-12T13:14:15Z</date_modified>
       <object_id>USER</object_id>
       <last_login/>
       <country/>
       <created_id type=""

uri="https://{domain}/networking/rest/user/123223323" displayValue="Platform Admin">123223323</created_id> 

       <time_zone>12</time_zone>
       <modified_id type=""

uri="https://{domain}/networking/rest/user/123223323" displayValue="Platform Admin">123223323</modified_id> 

       <email>myusernamecp@gmail.com</email>
       <last_name>Mostly</last_name>
       <active>1</active>
       <role_in_primary_team>1</role_in_primary_team>
   </record>

   <message>
       0
       <description>Success</description>
   </message>
   <recordCount>2</recordCount>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Add a User Record

Adds a user record

Method
POST
URI
https://{domain}/networking/rest/user/
Request
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <user>
       <phone/>
       <street/>
       <city/>
       <first_name>John</first_name>
       <username>userA@gmail.com</username>
       <single_sign_on>0</single_sign_on>
       <employee_number/>
       <fax/>
       <country/>
       <time_zone>12</time_zone>
       <email>userA@gmail.com</email>
       <company>CompanyA</company>
       <last_name>Smith</last_name>
       <active>1</active>
       <language>en</language>
       <mobile/>
       <state/>
       <title/>
       <notify_info>1</notify_info>
       <reports_to>151b28b700dc45abbb12b65ea451fc97</reports_to><zip/>
       <alias/>
       <customer_language>en</customer_language>
       <team_id>1</team_id>  // only required on add 
       <role_id>3</role_id>  // only required on add
   </user>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>1818437421</id>      // id of the user that was added
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Update a User Record

Updates data for the User specified in the URI.

Method
PUT
URI
https://{domain}/networking/rest/user/{recordId}
Request
Field elements are optional. If a field is missing, existing data in that field is unaffected. If a field is specified, but empty, any existing data in that field is deleted.
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <user>
       <phone/>
       <street/>
       <city/>
       <first_name>John</first_name>
       <username>userA@gmail.com</username>
       <single_sign_on>0</single_sign_on>
       <employee_number/>
       <fax/>
       <country/>
       <time_zone>12</time_zone>
       <email>userA@gmail.com</email>
       <company>CompanyA</company>
       <last_name>Smith</last_name>
       <active>1</active>
       <language>en</language>
       <mobile/>
       <state/>
       <title/>
       <reports_to>151b28b700dc45abbb12b65ea451fc97</reports_to>

<zip/> 

       <alias/>
       <customer_language>en</customer_language>        
   </user>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>
       <id>1818437421</id>      // id of the user that was updated
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Update (Reset) Password for a User

Change the password to a new or existing user.

Method
POST
Example
URI
https://{domain}/networking/rest/user/operation/updatePassword
Request
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <user>
       <id>da80488c7e8d4f5a83c66a3bb2590295</id>
       <password>abc</password>
       <longjump_reset_user>1</longjump_reset_user>
       <skip_email>1</skip_email>
   </user>

</platform> </syntaxhighlight>

longjump_reset_user
  • 0 = Password field is required. User is not required to change it at next log in. (default)
  • 1 = Password field does not have to be specified. System automatically generates a new, random password. User is required to change it at next log in.
skip_email
This field is only used for a new user.
Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Change Password for the Current User

Change the password for the current user.

Method
POST
URI
https://{domain}/networking/rest/user/operation/changePassword
Request
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <user>
       <old_password>world44</old_password>
       <password>pass123</password>
   </user>

</platform> </syntaxhighlight>

Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <message>
       0
       <description>Success</description>        
   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes

Delete a User Record

Deletes a User record

Method
DELETE
URI
https://{domain}/networking/rest/user/{recordId}
Response
<syntaxhighlight lang="html4strict" enclose="div">

<platform> 

   <message>

0 <description>Success</description> 

   </message>

</platform> </syntaxhighlight>

See also: REST API:Error Codes


Fields

Note: In this object, Boolean fields accept either 1/0 or TRUE/FALSE
Name Type Attribute Required During Add Description Additional Information
id String Read Only Record Id
first_name String Editable on Add/Update
last_name String Editable on Add/Update Checkmark.gif
company String Editable on Add/Update
title String Editable on Add/Update
time_zone Integer Editable on Add/Update Checkmark.gif See: Time Zone Codes
date_format String Editable on Add/Update Checkmark.gif See: Date/Time Formats
reports_to String Editable on Add/Update
employee_number Editable on Add/Update
language String Editable on Add/Update Checkmark.gif Two letter language code that is available to tenant (ex: 'en', 'es', 'hi')
email String Editable on Add/Update Checkmark.gif
username String Editable on Add/Update Checkmark.gif
password String Editable on Add/Update Password used to login
If password is not provided, a temporary password is generated and sent to the user/tenant via email
Learn more: Manage Email Templates - Forgot Reset Password Email
active Boolean Editable on Add/Update
single_sign_on Boolean Editable on Add/Update
team_id Integer Editable on Add/Update Checkmark.gif
role_id Integer Editable on Add/Update Checkmark.gif
phone String Editable on Add/Update
mobile String Editable on Add/Update
fax String Editable on Add/Update
street String Editable on Add/Update
city String Editable on Add/Update
state String Editable on Add/Update
zip String Editable on Add/Update
country String Editable on Add/Update
notify_info Boolean Can be specified on Add/Update Send the Welcome email message When enabled, a notification email is sent (containing the username, welcome and login information) when a new user is added.

Default is 1 (email is sent automatically on new user creation)

This value is not stored in the database, and is not returned by a GET.

federation_id String Read Only Used in SAML authentication, if SAML is enabled
force_password_change_on_login Boolean Editable on Add/Update Force a password change action on first-time login When enabled, the User is prompted to change the password when logging in for the first time

Default is 1 (new user is forced to change password on first login)

last_login Date Read Only Date and time of last login UTC Format
date_last_password_change date Read Only Date and time of last password change UTC Format
customer_language String Read Only Default Language, specified in My Information
full_name String Read Only Full name of the user
date_created Date Read Only UTC Format
created_id Lookup Read Only
date_modified Date Read Only UTC Format
modified_id Lookup Read Only
role Read Only
community_user_id String Read Only User's ID in the community
auto_generated_community_user_record Boolean Read Only <true> for the initial admin user and any other user IDs automatically generated for the community
user_type String Read Only User type: Platform user (P) or Site User (S)
alias String Editable on Add/Update User's alias in the community
sso_type Integer Read Only Type of single sign on:

1 - Delegated
  Authentication
2 - SAML

 See: Single Sign On
tenant_id String Read Only
  • Blank when logged in as normal user in a non-community tenant.
  • The ID of the host tenant, when logged in as a community user.
tenant_user_id String Read Only
customerId String Read Only Customer ID The ID of the tenant where the user is logged in:
  • The host tenant ID, when logged in as a user for a normal (non-community) tenant.
  • The ID of the the community tenant, when logged in as a community user.
custom field User Fields User can add fields of various type, including text, date, time, etc.
Retrieved from "https://agileappscloud.info/aawiki-src/index.php?title=REST_API:user_Resource&oldid=10258"