SonaCreateTimeslot

Description¶

This function allows creation of a timeslot programmatically via API. It returns the new timeslot’s ID and logs the event for auditing or indicates if creation wasn’t allowed.

Input Parameters¶

Below are the following input parameters for use with the SonaCreateTimeslot API function.

Parameter	Description / Possible Values
`api_key`	Use API key generated for Sona admin user
`occur_date`	The date (YYYY-MM-DD format) when the timeslot is to occur. For online studies, this is the participation deadline. E.g. 1999-12-31
`start_time`	The start time (HH24:MI format) of the timeslot. E.g. 17:30
`num_students`	The total number of participants allowed for this timeslot
`experiment_id`	The numeric identifier of the study
`experimenter_id`	The numeric identifier of the researcher to assign to this timeslot. Optional – `experimenter_id` may be omitted. Applicable only if all three conditions are met: 1. The study is configured so that researchers are assigned at the timeslot level. 2. Multiple researcher support is enabled in System Settings. 3. The specified researcher is listed as one of the researchers for the study.
`resource_id`	The numeric identifier of the location, which is the pulldown list of locations that appears when adding a timeslot. Only applies to lab studies, and if Location Scheduling is enabled in System Settings. Optional – an empty string or omitting the `resource_id` is valid. `resource_id`, `videoconf_url`, or location must be specified for a lab study.
`videoconf_url`	The URL of the videoconference. Only applies to lab studies. Optional – either `resource_id`, `videoconf_url`, or location must be specified for a lab study.
`location`	The location of the lab study. This does not apply to online studies. Optional – either `resource_id`, `videoconf_url`, or location must be specified for a lab study.

Output Parameters¶

Will return the timeslot_id of the timeslot that was created.

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	Invalid `start_time` or `occur_date`
Error Code	-9	Invalid number of participants
Error Code	-10	Invalid `experiment_id`
Error Code	-11	Invalid `resource_id`
Error Code	-12	Study not found
Error Code	-13	Timeslot add failed. Adding a timeslot with the number of participants specified would exceed the timeslot usage limits.
Error Code	-17	Slot not valid You must enter a valid date/start time combination in proper format There are other timeslots scheduled in the same location during the time you have scheduled your timeslot You must specify a location The timeslot may not occur after the approval expiration date
Error Code	-18	The `experimenter_id` is not numeric, or the specified researcher is not assigned to the study.
Error Code	-19	Invalid location, and `videoconf_url` and `resource_id` not specified

Sample Input¶

Request URL

https://myschool.sona-systems.com/services/SonaAPI.svc/SonaCreateTimeslot?api_key=YOUR_API_KEY&occur_date=2012-06-26&start_time=17%3A30&location=Miller%20Hall&num_students=200&experiment_id=3141&experimenter_id=3117&resource_id=2718&videoconf_url=https%3A%2F%2Fwww.zoom.com%2F123

URL components

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

Query parameters

api_key = YOUR_API_KEY
occur_date = 2012-06-26
start_time = 17:30
location = Miller%20Hall
num_students = 200
experiment_id = 3141
experimenter_id = 3117
resource_id = 2718
videoconf_url = https%3A%2F%2Fwww.zoom.com%2F123

Sample Output¶

<SonaCreateTimeslotResponse
  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">
  <SonaCreateTimeslotResult>
    <a:Errors i:nil="true" />
    <a:Result>5678</a:Result>
  </SonaCreateTimeslotResult>
</SonaCreateTimeslotResponse>