Package: safetyculture-sdk-python
SafetyCulture Python SDK and iAuditor ToolsThere is a newer version of the Exporter tool that forms part of this SDK. If you're looking to export data out of iAuditor, please check out theiAuditor Exporterrather than following the instuctions below.Contains:The SafetyCulture Python SDK: core functions to interact with the iAuditor APIThe iAuditor Export Tool for exporting audit data to your computerThe Import Global Response Set (GRS) Tool for importing and updating response sets from a spreadsheetThe Export Users Tool to export a list of all users and their groups from iAuditor into a spreadsheetThe Sync Users Tool allows you to use a spreadsheet to keep your users and their group associations up to date and automatically reflect that in iAuditor.Examples of how to import individual modules of the SDK into your own scripts.iAuditor Export ToolFirst Time Install and RunYou will need to havePython 2.7 or higherandPipinstalled on your computer. If you are using Windows, make sure to select the option to "Add Python to PATH" during the installation process. Also, Windows users may need to prepend the following commands withpython -mi.e.python -m pip install safetyculture-sdk-pythonTo install the Python SDK, run the following commands from your terminal:Install the SDK and toolspip install safetyculture-sdk-pythonSetup (createsconfig.yamlfile in new folderiauditor_exports_folder)iauditor_exporter --setupNavigate into to the newly created foldercd iauditor_exports_folderRun the tool to export PDF reports of all your audits (for other formats see later sections in this tutorial)iauditor_exporterUpgrading from an Older Version of the Exporter ToolOption 1 (re-use existing exports folder)Install the latest version of the SDK and Export Tool (you may need to substitute pip with pip3 depending on your configuration):pip install safetyculture-sdk-pythonIf the above command reports that everything is already up to date, run with the force command:pip install safetyculture-sdk-python --forceThen navigate into your existing exporter folder. This is located within the cloned repository atsafetyculture-sdk-python/tools/exporterand runiauditor_exporterfrom there. Export data will be saved in the existingexportsfolder, and the existinglast_successful.txtfile will
be used to pick up where the last export left off.Option 2 (re-use existing exports folder)Get the latest version of the code by navigating intosafetyculture-sdk-pythonand runninggit pullNavigate intosafetyculture-sdk-python/tools/exporterRun the iAuditor export tool directly:python exporter.pyOption 3 (export audits in new folder)Follow the instructions above to start exporting data to the new folder namediauditor_exports_folder. The setup script will give you the option to start your exports from the
current date and time, so that you do not have to re-export older audits.How to use the iAuditor Export ToolThe API token saved inconfig.yamlprovides access to data associated with a single account. Namely, the account used to generate the API token.
Only audits that are accessible to the single iAuditor account associated with the iAuditor API token used are available for exporting.All exported data is saved in a folder calledexports. The folder will be created in the current working directory if it does not already exist.To export all completed audits in PDF format, runiauditor_exporterTo enable the exporter to run continuously until interrupted, use the loop command line argumentiauditor_exporter --loopTo specify the export format explicitly runiauditor_exporter --format pdfMore than one supported formats can be exported at once e.g.iauditor_exporter --format  pdf  docx  json  csv  media  web-report-link  actionsNote:Unless you start the tool with the --loop argument, it will sync documents once and terminateOnly completed audits will be exportedOnly audits that are owned by or shared with the iAuditor user account that generated the API token will be exportedUp to 1000 audits will be exported each sync cycle. If more than 1000 audits exist they will be retrieved automatically in subsequent sync cyclesCSV ExportBulk CSV ExportFor an overview of the CSV format used, seehereAudits built from the same template will be saved in the same CSV file which is named after the template's unique ID number.
i.e.TEMPLATE_ID.csvTo export multiple audits in bulk to a CSV file, run theiauditor_exporterwith the format option set to CSV:iauditor_exporter --format csvThe format of the following CSV values do not match the format used by the SafetyCulture API Audit JSONDate/Time fieldJSON:2017-03-03T03:45:58.090ZCSV:03 March 2017 03:45 AMCheckbox fieldJSON:1or0CSV:TrueorFalseMedia List, Multiple Choice ResponsesJSON: List ObjectCSV:  Newline separated values in single cellBulk CSV Export GotchasIf you update an Audit that has already been exported, it may be appended to the CSV file a second time.If you update a template, Audits with the new format will be appended to the same CSV file.Media ExportRunningiauditor_exporter --format mediawill export all audit media files for each audit (images, attachments, signature, and drawings) to a folder named after the audit ID.Web Report Link ExportRunningiauditor_exporter --format web-report-linkwill export your Web Report Links to a CSV file namedweb-report-links.csv.The CSV file includes five columns: Template ID, Template Name, Audit ID, Audit Name, and Web Report Link.Actions ExportRunningiauditor_exporter --format actionswill export all actions to a file namediauditor_actions.csvThe actions export tool reads and writes to a file namedlast_successful_actions_export.txtto keep track of what actions have already been exported.
If it does not already exist,last_successful_actions_export.txtis created.Each time actions are exported, newly created actions are appended toiauditor_actions.csv. Additionally, any existing actions that have been modified since the last
time actions were exported will be re-appended to the CSV file.iauditor_actions.csvconsists of the following columnsactionIddescriptionassigneeprioritypriorityCodestatusstatusCodedue_datetimeauditauditIdlinkedToItemlinkedToItemIdcreatorNamecreatorIdcreatedDatetimemodifiedDatetimecompletedDatetimesitetitleThe fieldspriorityCodeandstatusCodeare number values. All other fields are string values.Seeherefor more information about the status codes and priority codes.Export settingsTo override default export settings edit config.yaml in this directory.Things you can configure:SettingDescriptionexport_pathabsolute or relative path to the directory where to save exported data tofilenamean audit item ID whose response is going to be used to name the files of exported audit reports. Can only be an item with a response type oftextfrom the header section of the audit such as Audit Title, Document No., Client / Site, Prepared By, Personnel, or any custom header item which has a 'text' type response (doesn't apply when exporting as CSV)preferencesto apply a preference transformation to particular templates, give here a list of preference idssync_delay_in_secondstime in seconds to wait after completing one export run, before running againexport_inactive_itemsThis setting only applies when exporting to CSV. Valid values are true (export all items) or false (do not export inactive items). Items that are nested underSmart Fieldwill be 'inactive' if the smart field condition is not satisfied for these items.media_sync_offset_in_secondstime in seconds since an audit has been modified before it will by syncedHere is an example customised config.yaml:API:
    token: YOUR_IAUDITOR_API_TOKEN
export_options:
    export_path: /Users/Monty/Dropbox
    filename: f3245d40-ea77-11e1-aff1-0800200c9a66
    csv:
        export_inactive_items: false
preferences:
    template_3E631E46F466411B9C09AD804886A8B4:E15A6525-EFA5-4835-92F0-D11CA9F364F3
    template_3E631E46F466411B9C09AD804886A8B4:E50645A1-2851-4E92-B4EA-60C5CE7981BE
    ...
    ...
sync_delay_in_seconds: 36000
media_sync_offset_in_seconds: 600Note: Templates for which there is no preference id listed in the config file will be exported without a preference appliedNaming the exported files(Doesn't apply when exporting as CSV - names are always the template ID.)Note that when automatic Audit Title rules are set on the template, the Audit will not contain an Audit Title field by default. Regardless, the export filename setting will still work as expected using the automatically generated Audit name.When configuring a custom filename convention in export settings (inconfig.yaml) you can provide an audit item ID from the ones below to cause all exported audit reports be named after the response of that particular item in the audit.Here are some standard item IDsItem NameItem IDAudit Titlef3245d40-ea77-11e1-aff1-0800200c9a66Conducted Byf3245d43-ea77-11e1-aff1-0800200c9a66Document Nof3245d46-ea77-11e1-aff1-0800200c9a66Client Sitef3245d41-ea77-11e1-aff1-0800200c9a66Conducted On (Date)f3245d42-ea77-11e1-aff1-0800200c9a66Conducted At (Location)f3245d44-ea77-11e1-aff1-0800200c9a66Personnelf3245d45-ea77-11e1-aff1-0800200c9a66or from any other header item of the audit created by the user (a custom header item). Tip: To find the item ID of such custom header items export one audit from the template of interest in JSON format and inspect the contents to identify the item ID of interest in theheader_itemssection.E.g. the followingconfig.yamlexport_options:
    filename: f3245d40-ea77-11e1-aff1-0800200c9a66will result in all exported files named after theAudit Titlefield.How to list available preference IDsTo list all available global preference IDs and their associated templates:iauditor_exporter --list_preferencesTo list global and template specific preference IDs associated with specific templates:iauditor_exporter --list_preferences template_3E631E46F466411B9C09AD804886A8B4Multiple template IDs can be passed, separated by a spaceHow to maintain multiple configurationsYou may want to maintain multiple export configurations in different YAML configuration files. To use a specific configuration file (other than config.yaml) doiauditor_exporter --config=/path/to/alternate_config.yamlNote that you can supply a relative or absolute path to an alternate_config.yaml if it is in another directoryArguments can be combined e.g. -iauditor_exporter --config=alternate_config.yaml --format pdf jsonTroubleshootingNothing gets exportedYour API key may be missing or has expired. Generate a new API token from the iAuditor web application or using the iAuditor API and replace it in the config.yaml file of the top-level directory of this repository. Ensure your API key corresponds to a SafetyCulture account that contains the audits you want to export.Some audits failed to transferIf an audit failed to transfer the export process will not stop, it will simply record the failure in the log file and continue. You can find the log files under the log/ directory. To retry a failed audit export you can reset the export start date as shown in "Setting the export start date" below.pdf documents have placeholder images, or docx documents won't openSometimes media on an audit can take longer to sync than the rest of the data.  Increasing the value of the media_sync_offset_in_seconds config setting can improve this.Re-setting the export start dateOnce you have successfully used this tool to extract audit reports, the next time you run it it will only export reports modified or completed since the last time it ran. To reset the export start date edit or delete the file last_successful.txt generated by the exporter tool in this directory. The time is UTC in ISO 8061 format (example: 2016-10-20T05:19:18.352Z).IMPORTANT: Exporting large numbers of audits in bulk over and over again may result in your account being throttled or your API token revoked.The Import Global Response Sets (GRS) toolThis tool helps maintain Global Response Sets up to date by importing them automatically from a Microsoft Excel spreadsheet (xls or xlsx, version 2 or higher).To import response sets from a spreadsheet file:import_grs --token <YOUR_IAUDITOR_API_TOKEN> --file <FULL_PATH_TO_SPREADSHEET_FILE>Each sheet in the Excel file will correspond to one Global Response Set. Any Global Response Set that exists in your account which has a name that does not match a sheet in the Excel file will not be affected. The name of the sheet will correspond to the name of the Global Response Set.  Please note that if you name a sheet exactly the same as a currently existing Global Response Set, that Global Response Set will be modified - including deletion of any responses that don't exist in the Excel file.The tool is case-sensitive - if you have 'city names' and 'City Names' as separate sheet names, a new Global Response Set will be created for each. Similarly, if you want to manage an existing Global Response Set, ensure you name the sheet exactly as it appears in the response set, including capitalization.
A single column per sheet is required, each cell in that column will correspond to the label of a response.To update your Global Response Set, add one or more rows to the spreadsheet. To delete from your Global Response Set, just delete the relevant rows from the spreadsheet. After your changes, save the spreadsheet and run the tool.Caveat: deleting a response, and then re-adding the same response later will result in iAuditor Analytics dashboard treating these as different responses. This is because the new response will have a different internal identifier than the deleted response had. To update a response while keeping the same internal identifier you will need to use the response set API directly, instead of this tool. See the iAuditor developer portal for more details.The Export Users toolThis tool exports a list of users and their groups from iAuditor into a CSV file namediauditor_users.csv. To use this tool you need to have Admin permissions in the organisation.To run it:
Open a command-line terminal and navigate to the directory calledsafetyculture-sdk-python/tools/export_users.
Run the following command:python export_users.py --token <YOUR_IAUDITOR_API_TOKEN>The exported CSV file will be saved in the current working directory. If the file already exists, it is overwritten.The exported CSV file columns contain the following user information and structure:emaillastnamefirstnamegroupsemaillastnamefirstnamegroupsjohnsmith@example.comSmithJohnGroup 1, Group 2johndoe@example.comDoeJohnGroup 3jasonR@example.comRJasonThe fieldgroupscontains a comma-separated list of all iAuditor groups the user is a member of. All fields are string values.
Note: Group names that contain commas are not supported. If a group name contains a comma, no user will be assigned to it and you may see errors in the logs.The Sync Users toolThis tool updates the organisation users in iAuditor from a CSV file. After running this tool, users in iAuditor and their corresponding groups will match the contents of the CSV file. The groups specified in the CSV file must have been created in iAuditor before running the tool. If a group doesn't exist, the user will not be added to that group. To use this tool you need to have Admin permissions in the organisation.Caveat: Any users added in iAuditor without using this tool which are not listed in the CSV file, will be removed from iAuditor after running this tool. If you want to keep all users, run the Export Users tool and modify the file that is generated to reflect the desired user state.The input file specified in the command line arguments has the following structure:emaillastnamefirstnamegroupsjohnsmith@example.comSmithJohnGroup 1, Group 2johndoe@example.comDoeJohnGroup 3jasonR@example.comRJasonThe first row must contain the column headings and will be ignored by the tool. Seeexample_user_listing.csvinsafetyculture-sdk-python/tools/sync_usersfor an example.Any row that contains more than one groups, must surround the list of groups with double quotes.To run the tool:
Open a command-line terminal and navigate to the directory calledsafetyculture-sdk-python/tools/sync_usersRun the following command:python sync_users.py --token <YOUR_IAUDITOR_API_TOKEN> --file <FULL_PATH_TO_CSV_FILE>If the user already exists in the organisation in iAuditor, then the user will be added to all the groups in thegroupsfield. If the user is not in iAuditor, the user will be added to iAuditor first and then added to the groups listed in thegroupsfield. If no groups are specified, the user is only added to the organisation. If the user is not in the CSV file but is present in iAuditor, the user will be deactivated in iAuditor. If a user already belongs to a group, when that group is removed from the list of groups in the relevant CSV field, the user is removed from that group in iAuditor after running the tool.Importing SafetyCulture Python SDK Modules into your own scriptsSee example scripts in./examples/Known Limitations:If two or more groups have the same name, the user will be added to only one of those groups.Adding a user in the CSV when that user exists on the server but is deactivated then the user will not be activated.Adding an already invited user will log an error and have no effect.SafetyCulture Python SDKImportsafetypyinto a Python module or Python interpreter:import safetypyCreate an instance of the SafetyCulture class:sc = safetypy.SafetyCulture(YOUR_IAUDITOR_API_TOKEN)For more information regarding the Python SDK functionalityTo open the Python interpreter, runpythonFrom the Python interpreter, import the Python SDK by runningimport safetypyFor an overview of available functionality, runhelp(safetypy.SafetyCulture)LicenseCopyright 2017 SafetyCulture Pty LtdLicensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License athttp://www.apache.org/licenses/LICENSE-2.0Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.