switchvox.scheduledReports.add
From SwitchvoxExtendAPI
Contents |
Description
This method allows you to define the parameters for a Call Report you want run in the system and attach it to a previously created schedule (see switchvox.schedule.add). Everytime date/time this schedule fires it will email the report to the delivery_email parameter. For more information about Scheduled Reports see our Switchvox Administration Manual.
Arguments
- See the Constructing Requests page to learn how to use arguments in requests.
| Name | Required | Type | Default | Description |
| schedule_id | required | integer | ID of the schedule you want to use. | |
| scheduled_report_name | required | string | Name of your scheduled report. Example: "Sales Outgoing Full Day" | |
| scheduled_report_type | required | string | Type of the report you want. Possible values:call_report | |
| scheduled_report_format | required | string | The delivery format of the report. Possible values:xml,chart, or html. | |
| start_from_beginning | require one | string | Defines that the start time of each scheduled report should be the beginning of the same day, week, month or year that the report runs. Only one of the following parameters may be submitted, and at least one of them is required: start_from_beginning, start_from_decrement or start_from_date. |
|
| start_from_decrement | require one | string | Defines that the start time of the each scheduled report should be calculated from the current run time of the report minus a defined decrement. Format: 1Y,2M,3W,4D,2h,3m = 1 year, 2 months, 3 weeks, 4 days, 2 hours, 3 minutes. Example: To create a sliding window and get the past 4 hours of call reports you would use: 4h.
Only one of the following parameters may be submitted, and at least one of them is required: start_from_beginning, start_from_decrement or start_from_date. |
|
| start_from_date | require one | datetime | Defines that the start date / time of each scheduled report should be from a defined date. Only one of the following parameters may be submitted, and at least one of them is required: start_from_beginning, start_from_decrement or start_from_date. |
|
| delivery_email | required | Email address where the reports should be sent. | ||
| account_ids account_id |
required (account searches) |
integer | A list of account ids. To get a list of account_ids on your system or convert extensions to account_ids see switchvox.extensions.search. | |
| iax_provider_ids iax_provider_id |
required (provider searches) |
integer | A list of IAX provider IDs. | |
| sip_provider_ids sip_provider_id |
required (provider searches) |
integer | A list of SIP provider IDs. | |
| incoming_did | required (did searches) |
integer | Search based on incoming DID. | |
| breakdown | optional | string | cumulative | The report breakdown. Possible values: cumulative, by_day, by_account, by_hour_of_day, and by_day_of_week. |
| report_fields report_field |
optional | string | total_calls | A list of the fields to report. Possible values: total_calls, total_incoming_calls, total_outgoing_calls, talking_duration, call_duration, avg_talking_duration, and avg_call_duration. |
| ignore_weekends | optional | boolean | 0 | Flag to ignore weekends or not. Set to 1 to ignore weekends or 0 to include weekends in your report. |
| format | optional | string | xml | Format of the report. Possible values: xml, excel and chart. |
| sort_field | optional | string | sort_name | The field on which to sort the returned report. Possible values: sort_name, date, hour, day_of_week, account, extension, total_calls, total_incoming_calls, total_outgoing_calls, talking_duration, call_duration, avg_talking_duration and avg_call_duration. Value ignored for cumulative searches. |
| sort_order | optional | string | ASC | The order in which to sort returned call log entries. Possible values: ASC and DESC. |
| page_number | optional | integer | 1 | The page number of the results to return |
Example Requests & Responses
- Please see the API Request and Response Format section for more information on various request encodings.
Example One
Creates a scheduled report that will be delivered in HTML format to test@switchvox.com
Request
<request method="switchvox.scheduledReports.callReports.add"> <parameters> <schedule_id>23</schedule_id> <scheduled_report_name>Sample Report</scheduled_report_name> <scheduled_report_type>call_report</scheduled_report_type> <scheduled_report_format>html</scheduled_report_format> <start_from_beginning>day</start_from_beginning> <delivery_email>test@switchvox.com</delivery_email> <ignore_weekends>1</ignore_weekends> <breakdown>by_account</breakdown> <report_fields> <report_field>total_calls</report_field> <report_field>total_incoming_calls</report_field> <report_field>total_outgoing_calls</report_field> <report_field>talking_duration</report_field> <report_field>call_duration</report_field> <report_field>avg_talking_duration</report_field> <report_field>avg_call_duration</report_field> </report_fields> <account_ids> <account_id>1107</account_id> <account_id>1106</account_id> <account_id>1107</account_id> </account_ids> <sort_field>sort_name</sort_field> <sort_order>ASC</sort_order> <items_per_page>50</items_per_page> <page_number>1</page_number> </parameters> </request>
Response
<response method="switchvox.scheduledReports.callReports.add"> <result> <scheduled_report id="24" /> </result> </response>
Error Codes
- See the Error Code Formatting section to see the xml structure when an error is returned.
- See the Generic Error Codes section to see a list of general fault codes that may be returned.
| Code | Description |
| 77534 | Invalid from the date/time (%s). Date and time format is (YYYY-MM-DD HH:MM:SS) |
| 51066 | Invalid scheduled report format. Must be html, chart, or xml. |
| 25117 | Invalid value for your start date/time decrement value. Format example: 1Y,2M,3W,4D,5h = 1 year,2 months,3 weeks, 4 days, 5 hours. |
| 38704 | Your email address must contain an @ sign. |
| 53769 | Invalid value scheduled report name. |
| 98115 | Invalid value entered for start from beginning. Possible values: day,week,month,year. |
| 97748 | Invalid value scheduled report type. |
| 84035 | Conflicting parameters. Only one of the following parameters is allowed : start_from_beginning, start_from_decrement, start_from_date. |
| 77534 | Requested schedule id does not exist in the system. |
| 64617 | That schedule name already exists in the system. |
See switchvox.callReports.search for other potential faults codes that could be thrown by this method.