Purpose
Scriptable Exports allows you to automatically generate a Data Export Job on a schedule and save the file to a specified location. To do this, you will need to save your Authentication Keys from Subscription Analytics, generate a custom PowerShell script using the Scriptable Exports tool, and schedule the script. The following instructions will walk you through how to do this. If you have any questions or need additional help, please contact technical support.
Breaking Changes Possible on Dec 17th : The capitalization of some properties has been modified. If you have failing scripts, please consider these modifications:
JobStatus -> jobStatus
ExportDataFileUrl->exportDataFileUrl
Roles
Users with at least one of the following roles are able to access the report:
- Admins
- Co-Admins
Overview
- Save your Authentication Keys
- Enter Job Settings
- Edit Script Settings
- Schedule with Task Scheduler
- Usage Date
1. Go to Subscription Analytics
2. Click on Data Export.
3. Click on the gear icon in the upper right-hand corner.
4. The Manage Keys dialog box will open. Save both of the authentication keys.
If the keys are mostly asterisks, as in the above screenshot, an Admin at your organization has already viewed these keys. You will need to get the keys from that Admin or regenerate the keys using the refresh icon.
Authentication Keys are basically a password that allow you to run a scriptable export. The first time this screen is accessed by anyone at your organization, or after they have been refreshed, the authentication keys will be visible. Save them and keep them in a safe location. Protect them with the same level of security as you would a password. After this, they will not be visible to anyone in the organization. If you are unable to access the existing keys, or suspect an unauthorized person has accessed them, please refresh them as soon as possible. Any Admin or Co-Admin in your organization may do this. When an authentication key is refreshed, the previous key is permanently disabled. There are only two active authentication keys per organization.
Once you have obtained at least one of your authorization keys, you are ready to generate the script.
1. From the previous screen (Data Export), select Create a New Export Job in the upper right-hand corner.
2. This will open the Create a New Export Job window. Select the Export Type, enter your Job Name, and Date Range. The Date Range may be a maximum of one year.
If you select a pre-set date range, such as Yesterday, the script will automatically pick up the date that is Yesterday according to when the script is run. For example, if you generate the script on February 26 and run it, it will retrieve data for February 25. If you execute the same script on February 28, it will retrieve data from February 27.
2. Click Download Script. This will allow you to download a PowerShell script (extension .ps1) to your machine. Make sure to save it to a directory that is not write-protected. This script will be custom to the particular job settings you entered.
This section describes the settings you must change to be able to run a scriptable export.
1. Right-click your downloaded script and select Properties.
2. At the bottom of the General tab, in the Security section, there may be a warning that the file came from another computer. If this is present, check the 'Unblock' box and click OK.
3. Right-click the file and select Edit. By default, this will open in Windows PowerShell ISE.
4. Place one of your authorization keys in the file. This is on Line 18 in the $AuthorizationKey parameter. Replace the "$$FeedMeAPIKey$$" value with your authorization key. The row directly above, row 17, shows the correct format.
5. By default, the data export file will be saved into the same directory as this script. If you would like it to be saved to a different directly, simply update the $DownloadLocalDataExportJobFilePath parameter on row 46. The row directly above, row 45, shows the correct format.
6. Save the file. The script is ready to be run.
At this point, you may test the script without having to schedule it. To do so, simply click the green Run Script button on the toolbar.
1. Open the Task Scheduler on your machine.
2. From the Actions menu on the right-hand side of the window, select Create Basic Task... This will launch the Create Basic Task Wizard.
3. Create a Basic Task - Enter a Name and Description
4. Trigger - Select the frequency of the task. Ex., Daily, Weekly and specify a time. Note that your machine must be on in order for the task to run.
5. Action - Select Start a program
6. Start a Program - Program/script - enter the PowerShell program. This is not the script that was downloaded. The default PowerShell path is "C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe" (without the quotation marks).
7. Start a Program - Add arguments - enter the location of the script downloaded from the Data Export. The format is "-File <FileName>" (without the quotation marks). For example, if the file is on your desktop and named "Sample_Job_LastSevenDays.ps1", then you should enter "-File C:\Users\Path\Desktop\Sample_Job_LastSevenDays.ps1" in the arguments field.
8. Finish - Review the selections and click Finish. Your task is now scheduled.
When the task runs, a PowerShell window will open. You do not need to interact with this window and it will close automatically when the task is complete. The data export file will, by default, be saved into the same directory as the script that was downloaded from Subscription Analytics. The file will also be downloadable by any Admin in your organization from the Data Export page.
Please note that if the authorization key changes, the script will need to be updated with the new authorization key.
Only one script may be executed at a time. If you schedule multiple scripts to run at the same time, they will queue up and execute in the order in which they were received.
Most of the reports have some type of a UsageDate column. When the CSV is viewed in a plain-text tool such as Notepad, the column is visible as a YYYY-MM-DD format.
Depending on your default Excel settings, if you open the CSV in Excel, you may need to change the column format.
Other Language Sources