SonaSetUserTimeslotUsageLimit

Description¶

This function sets the Study Time Usage Limit, in participant-hours, for an existing user. It is available only when the site is configured for per-Researcher or per-P.I. timeslot usage limits and the user has the role required by that configuration.

When the site uses per-Researcher limits, the user must have the Researcher role. When the site uses per-P.I. limits, the user must have the P.I. role. Multi-role users are eligible when they have the role required by the site's configured mode. The request is rejected when usage limits are disabled or configured per study.

The function updates only the user's usage limit. A limit may be set below the user's current usage. Existing timeslots and previously calculated usage are not changed, and subsequent operations remain subject to normal quota enforcement. The updated value is returned as usage_limit by person-information functions that return APIPerson.

This function can be called after SonaCreateUser to replace the site's default limit for the newly created user.

Input Parameters¶

Below are the input parameters for use with the SonaSetUserTimeslotUsageLimit API function.

Parameter	Description / Possible Values
`api_key`	API key generated for a Sona administrator. Required.
`person_id`	Positive numeric identifier of the user whose limit will be updated. Required.
`usage_limit`	New usage limit in participant-hours. Must be a non-negative whole number. Decimals and negative values are invalid. Required.

Output Parameters¶

Will return an integer value of 1 when the usage limit is updated, or 2 when the requested limit is already set and no update is required.

Error Codes¶

Below are the possible error messages encountered and their respective descriptions.

Error Type	Error Code	Description
Authentication Failed	-1 through -7	Standard authentication errors.
Error Code	-8	`person_id` must be a positive integer.
Error Code	-9	No user exists with the supplied `person_id`.
Error Code	-10	`usage_limit` must be a non-negative integer.
Error Code	-11	The site is not configured for per-Researcher or per-P.I. timeslot usage limits.
Error Code	-12	The user does not have the role required by the site's timeslot usage limit setting.

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaSetUserTimeslotUsageLimit?api_key=YOUR_API_KEY&person_id=15&usage_limit=10

URL components

Component	Value
Scheme	`https`
Host	`myschool.sona-systems.com`
Service path	`/services/SonaAPI.svc`
Function	`SonaSetUserTimeslotUsageLimit`

Query parameters

api_key = YOUR_API_KEY
person_id = 15
usage_limit = 10

Sample Output¶

<SonaSetUserTimeslotUsageLimitResponse
  xmlns="https://www.sona-systems.com/"
  xmlns:a="http://schemas.datacontract.org/2004/07/emsdotnet.sonasystems"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance">
  <SonaSetUserTimeslotUsageLimitResult>
    <a:Errors i:nil="true" />
    <a:Result>1</a:Result>
  </SonaSetUserTimeslotUsageLimitResult>
</SonaSetUserTimeslotUsageLimitResponse>