-
Notifications
You must be signed in to change notification settings - Fork 25
User Manipulation
- User Create
- User Setup
- User Read
- User Search
- User Info Read
- User Stats Read
- User Update
- User Change Password
- User Delete
Creates a new user in the system. The user will have the capabilities as described by the input parameters.
user/create
Only users with admin capabilities may access this API.
- (r) auth_token = Authentication token.
- (r) client = A string representing the client.
- (r) username = The new user's username.
- (r) password = The new user's password.
- (r) admin = [true | false] Whether this user should be an admin.
- (r) enabled = [true | false] Whether or not this account should be enabled.
- (o) new_account = [true | false] Whether or not the user must change their password before being able to use any of the APIs. The default is 'true'.
- (o) campaign_creation_privilege = [true | false] Whether or not this account can create new campaigns. The default is based on how the system is currently configured.
POST /app/user/create HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f
username=new.user
&password=new.pass
&admin=false
&enabled=true
&client=ohmage-gwt
curl -v -d "username=george.costanza&password=serenity.now&admin=false&enabled=true" http://localhost:8080/app/user/create
{
"result" : "success",
}
See the error page for a description of error codes and their associated descriptions.
Based on a user's personal information, creates a user if no existing user has the given personal information or returns the username and email address of the user with the given personal information. The new user will have the requesting user's email address as their own and has their personal information set to the given personal information.
user/setup
Only users with admin or the user_setup_privilege capabilities may access this API.
- (r) auth_token = Authentication token.
- (r) client = A string representing the client.
- (r) first_name = The user's first name.
- (r) last_name = The user's last name.
- (r) organization = The user's organization.
- (r) personal_id = The user's personal ID.
- (o) email_address = The user's email address. If not provided, the request's email address will be used.
- (o) username_prefix = The prefix to be used for generating a random user name. Default: "lausd-"
- (o) username_digits = The number of digits to be used for generating a random user name. Default: 5. An example of a username generated by default username configuration is lausd-00001.
POST /app/user/setup HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f
auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f
&first_name=Bob
&last_name=Builder
&organization=CanDoInc
&personal_id=1
curl -v -d "auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f&first_name=Bob&last_name=Builder&organization=CanDoInc&personal_id=1" http://localhost:8080/app/user/setup
{
"result" : "success",
"data":{
"username":"some_username",
"password":"some_password"
}
}
{
"result" : "success",
"data":{
"username":"some_username",
"email_address":"some_email_address"
}
}
See the error page for a description of error codes and their associated descriptions.
Returns a list of users belonging to the query criteria described by the input parameters.
user/read
The requester must be a supervisor in all campaigns present in the campaign_urn_list and privileged in the class_urn_list.
- (r) auth_token = Authentication token. May also be set using the Set-Cookie header.
- (r) client = A string representing the client.
- (o) user_list = Limits the results to only these usernames if they match the rest of the criteria.
- (o) username_search = A search string that limits the results to only those users whose username matches the search.
- (o) email_address_search = A search string that limits the results to only those users whose email address matches the search.
- (o) admin = Limits the results to only those users whose 'admin' value is equal to this one.
- (o) enabled = Limits the results to only those users whose 'enabled' value is equal to this one.
- (o) new_account = Limits the results to only those users whose 'new account' value is equal to this one.
- (o) campaign_creation_privilege = Limits the results to only those users whose 'campaign creation privilege' value is equal to this one.
- (o) first_name_search = A search string that limits the results to only those users that have personal information and their 'first name' value matches the search.
- (o) last_name_search = A search string that limits the results to only those users that have personal information and their 'last name' value matches the search.
- (o) organization_search = A search string that limits the results to only those users that have personal information and their 'organization' value matches the search.
- (o) personal_id_search = A search string that limits the results to only those users that have personal information and their 'personal_id' matches the search.
- (o) campaign_urn_list = List of campaigns whose users you would like information.
- (o) class_urn_list = List of classes whose users you would like information about.
- (o) num_to_skip = The number of user's to skip.
- (o) num_to_return = The number of user's information to return.
The search string is tokenized based on whitespace and respects double-quoted strings but does not respect single quoted strings or escaped quotes. For example, 'This 'is' "the search" string' would be broken into the following tokens, "this" (note: case-insensitive), "'is'" (note: it doesn't respect or remove single quotes), "the search", and "string".
POST /app/user/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
&campaign_urn_list=urn:sys:andwellness
&client=ohmage-gwt
curl -v -d "auth_token=d80685d4-db0e-45d8-82b3-ce93f8f37369&campaign_urn_list=urn:campaign:ucla:sleep&client=curl" http://dev.andwellness.org/app/user/read
{
"result" : "success",
"metadata" : {
"total_num_results" : <Total number of users that matched the criteria as opposed to those returned from paging.>
}
"data" : {
"<First user name>" : {
"first_name" : "<User's first name>",
"last_name" : "<User's last name>",
"organization" : "<The organization to which the user belongs>",
"personal_id" : "<The personal ID number for the user>",
"email_address" : "<The email address of the user or an empty string if one doesn't exist>"
"permissions" : {
"admin" : <true | false, as literals not strings>,
"enabled" : <true | false, as literals not strings>,
"new_account" : <true | false, as literals not strings>,
"can_create_campaigns" : <true | false, as literals not strings>,
"can_create_classes" : <true | false, as literals not strings>,
"can_setup_users" : <true | false, as literals not strings>
},
"<Second user name>" : {
...
},
...
}
}
See the error page for a description of error codes and their associated descriptions.
Returns a list of users belonging to the query criteria described by the input parameters.
user/search
The requester must be a supervisor in all campaigns present in the campaign_urn_list and privileged in the class_urn_list.
- (r) auth_token = Authentication token. May also be set using the Set-Cookie header.
- (r) client = A string representing the client.
- (o) username = A partial username to use for the search string
- (o) email_address = A partial email address to use for the search string
- (o) admin = Limits the results to only those users whose 'admin' value is equal to this one.
- (o) enabled = Limits the results to only those users whose 'enabled' value is equal to this one.
- (o) new_account = Limits the results to only those users whose 'new account' value is equal to this one.
- (o) campaign_creation_privilege = Limits the results to only those users whose 'campaign creation privilege' value is equal to this one.
- (o) first_name = A partial first name to be used in the search.
- (o) last_name = A partial last name to be used in the search.
- (o) organization = A partial organization name to be used in the search.
- (o) personal_id = A partial personal id to be used in the search.
- (o) num_to_skip = The number of user's to skip.
- (o) num_to_return = The number of user's information to return.
The search string is tokenized based on whitespace and respects double-quoted strings but does not respect single quoted strings or escaped quotes. For example, 'This 'is' "the search" string' would be broken into the following tokens, "this" (note: case-insensitive), "'is'" (note: it doesn't respect or remove single quotes), "the search", and "string".
POST /app/user/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
&client=ohmage-gwt
curl -v -d "auth_token=d80685d4-db0e-45d8-82b3-ce93f8f37369&client=curl" http://dev.andwellness.org/app/user/read
{
"result" : "success",
"metadata" : {
"total_num_results" : <Total number of users that matched the criteria as opposed to those returned from paging.>
}
"data" : {
"<First user name>" : {
"first_name" : "<User's first name>",
"last_name" : "<User's last name>",
"organization" : "<The organization to which the user belongs>",
"personal_id" : "<The personal ID number for the user>",
"email_address" : "<The email address of the user or an empty string if one doesn't exist>"
"permissions" : {
"admin" : <true | false, as literals not strings>,
"enabled" : <true | false, as literals not strings>,
"new_account" : <true | false, as literals not strings>,
"can_create_campaigns" : <true | false, as literals not strings>,
"can_create_classes" : <true | false, as literals not strings>,
"can_setup_users" : <true | false, as literals not strings>
},
"<Second user name>" : {
...
},
...
}
}
See the error page for a description of error codes and their associated descriptions.
Returns detailed user information regarding the logged-in user's permissions in the system and their association with classes and campaigns.
user_info/read
Requesters may only use this API to query about their own data and relationships in the system.
- (r) auth_token = Authentication token. May also be set using the Set-Cookie header.
- (r) client = A string representing the client.
POST /app/user_info/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
&client=ohmage-gwt
curl -v -d "auth_token=3de9c54f-3797-43c2-9185-fbb1a6b3da99&client=curl" http://localhost:8080/app/user_info/read
{
"result" : "success",
"data" : {
"<requesting user's username>" : {
"permissions": {
"can_create_campaigns" : <true | false, as literals not strings>,
"can_create_classes" : <true | false, as literals not strings>,
"can_setup_users" : <true | false, as literals not strings>,
"is_admin" : true
},
"campaigns" : {
"<First campaign URN>" : "<First campaign name>",
"<Second campaign URN>" : "<Second campaign name>",
...
},
"campaign_roles" : [
"<First unique campaign role>",
"<Second unique campaign role>",
...
],
"classes" : {
"<First class URN>" : "<First class name>",
"<Second class URN>" : "<Second class name>",
...
},
"class_roles" : [
"<First unique class role>",
"<Second unique class role>",
...
]
}
See the error page for a description of error codes and their associated descriptions.
Returns the following statistics about a user: hours since last survey upload, hours since last mobility upload, past day percent successful survey location updates, past day percent successful mobility location updates. The 'user' must be part of the 'campaign'. Also, the 'user' must be either the user that generated the 'auth_token' and the campaign must be running, or they must be a supervisor in the 'campaign'.
user_stats/read
See the access rules for survey_response/read.
- (r) auth_token = A valid authentication token from user/auth_token. May also be set using the Set-Cookie header.
- (r) user = A username of the user attempting to login
- (r) password = A password for the above user.
- (r) client = A string identifying the client performing the action.
- (r) campaign_urn = A campaign URN specifying the campaign to return stats against.
- (r) username = This is the username of the user's data that the stats are being calculated against.
POST /app/user_stats/read HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
campaign_urn=urn:ohmage:nih:moms
&client=ohmage-gwt
&auth_token=abcfcd36-ab25-4494-8434-7798cb1d718e
&username=username
curl -v -d "auth_token=c01fc44d-d116-43a0-bd7b-9221bc53697d&user=john.c&campaign_urn=urn:campaign:giant_steps&client=curl" http://localhost:8080/app/user_stats/read
{
"result":"success",
"stats" : {
"Hours Since Last Survey Upload" : 3.5,
"Hours Since Last Mobility Upload" : 6.78,
"Past Day Percent Successful Survey Location Updates" : 0.45,
"Past Day Percent Successful Mobility Location Updates" : 1.0
}
}
See the error page for a description of error codes and their associated descriptions.
Allows updates to user information.
user/update
Only admins may access this API.
- (r) auth_token = Authentication token.
- (r) client = A string representing the client.
- (r) username = The user to be updated's username
- (o) admin = [true | false] Whether this user should be an admin.
- (o) enabled = [true | false] Whether or not this account should be enabled.
- (o) new_account = [true | false] Whether or not the user must change their password before being able to use any of the APIs. The default is 'true'.
- (o) campaign_creation_privilege = [true | false] Whether or not this account can create new campaigns. The default is based on how the system is currently configured.
- (o) class_creation_privilege = [true | false] Whether or not this account can create new classes. The default is based on how the system is currently configured.
- (o) user_setup_privilege = [true | false] Whether or not this account can setup users. The default is based on how the system is currently configured.
- (o) delete_personal_info = [true | false] Whether or not all personal info (first name, last name, organization, personal ID) should be deleted.
- (Ø) first_name = The user's first name.
- (Ø) last_name = The user's last name.
- (Ø) organization = The organization to which the user belongs.
- (Ø) personal_id = The user's personal ID.
- (∏) email_address = The user's email address.
- (∏) json_data = A JSONObject containing additional information about the user.
Ø = If the user doesn't already have a personal entry, then all of the items with this symbol must be present.
∏ = This is not required to create a new personal enty, but if it is included, the user must already have a personal entry or those labeled with a Ø must be present.
POST /app/user/update HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
Cookie: auth_token=dff783ce-cf1a-4cc8-b750-dee774a82e6f
admin=true
&new_account=true
&first_name=Bob
&last_name=Builder
&organization=Deep Thoughts
&personal_id=42
curl -v -d "auth_token=c01fc44d-d116-43a0-bd7b-9221bc53697d&username=britney.s&admin=false&enabled=true&new_account=true" http://localhost:8080/app/user/update
{
"result":"success",
}
See the error page for a description of error codes and their associated descriptions.
Allows users to change their passwords. Admins also have access to this API for any user.
user/change_password
Admins may change passwords on behalf of other users. All other users may only change their own password.
- (r) user = Username
- (r) password = Plaintext password
- (r) client = A short description of the client making the request.
- (r) new_password = New password
- (o) username = The username of the user whose password you wish to change. Only admins may use this parameter.
POST /app/user/change_password HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
username=joe.bob
&password=my.password
&new_password=super.cool
&client=test
curl -v -d "client=curl&username=login_name&password=current_password&new_password=new_password" https://localhost:8080/app/user/change_password
{
"result":"success",
}
See the error page for a description of error codes and their associated descriptions.
Deletes users.
user/delete
Only admins may delete users.
- (r) client = A short description of the client making the request.
- (r) user = Username
- (r) user_list = A list of comma-separated user names to delete.
POST /app/user/change_password HTTP/1.1
Host: dev.ohmage.org
Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.77 Safari/535.7
Content-Length: byte-length-of-content
Content-Type: application/x-www-form-urlencoded
auth_token=84w8fsf9-wjj4-w84f84-h4h84hsf9j4
&user_list=joe.bob,other.guy
curl -v -d "auth_token=c01fc44d-d116-43a0-bd7b-9221bc53697d&user_list=ferris.bueller" http://localhost:8080/app/user/delete
{
"result":"success",
}
See the error page for a description of error codes and their associated descriptions.