WMTOOL. Technical Specification. Date: 10/2012 Version: APITechSpecv1.4CRO0512 WMTOOL 1. Technical Specification

Transcription

1 WMTOOL Date: 10/2012 Version: APITechSpecv1.4CRO0512 WMTOOL 1

2 Contents 1. WMTOOL Overview 4 2. How to run WMTOOL 5 3. Available Commands 6 4. Making shorter commands 7 5 Importing Jobs CSV Files JSON Files Uploading 10 WMTOOL 2

3 WorkMobile Tool (WMTOOL) WMTOOL is a stand-alone utility that provides a user interface to the WorkMobile Business API. Currently, only a command-line interface is provided for a limited set of functions. WMTOOL is a Java application. It will run on Windows, MacOS and Linux. A Java Runtime Environment must be installed first this can be downloaded at: WMTOOL Overview Your Organisation WMTOOL + WorkMobile Business API CSV Files CSV Files CSV Files Internal Databases SAP, Oracle, mysql, MS SQL, Access CRM Server FTP Server WMTOOL 3

4 2.0 How to run WMTOOL Open a command-line interface or shell. E.g. in Windows Type command from Run From the command line: java -jar wmtool.jar command [ options ] For a list of supported commands: java -jar wmtool.jar help For help on a specific command: java -jar wmtool.jar command --help The process will return 0 (zero) for success, or 1 (one) for any error. In a Windows command prompt, this is available as the ERRORLEVEL. WMTOOL 4

5 3.0 Available Commands COMMAND addform addjobtype addnotification allocatejob closejob deallocatejob describejobtype exportform exportjobs exportjobtype exportusers formdata help importjobs importjobtype importusers jobdata listforms listgroups listjobhistory listjobtypes listusers setlogonform shred uploaddatabase uploadfileattachment uploadimage DESCRIPTION Create a new form Create a new job type Create a new notification Allocate (or re-allocate) a job to a mobile user Close a job Deallocate a job Retrieve description for specified jobtype Export a Form definition as XML Display or export a list of jobs Export a job type definition as XML Display or export all mobile user details Download data for a specified form Display this help Import jobs for the specified jobtype from CSV Import a job type, as exported by exportjobtype Import mobile users from a CSV file Retrieve the data for a job Display or export a list of forms List mobile user groups Display the history for a specified job Display or export a list of job types Display or export a list of mobile users Set a mobile user group's logon form Permanently delete any data marked as downloaded for a specified form Upload data for data-linked dropdown lists(csv/xml) Upload file attachments for jobs. Upload image files for the image control. WMTOOL 5

6 4.0 Making a shorter command If you want to use WmTool extensively from the command line by hand, you might want to make a small batch file or shell script to simplify using it. A Windows example, wmtool.bat, contains one -jar c:\apps\esay\wmtool.jar %* Then run as: wmtool help Or, include any parameters you always use, to avoid keying them in each -jar c:\apps\esay\wmtool.jar --username bob@esay-mobile.co.uk %* For security reasons, you should not include the password. wmtool listusers --password esay 4.0 Batch Processing For example, create a text file with a list of Job IDs (one on each line), called "jobs.in" Then execute WmTool in a batch. for /f %j in (jobs.in) do java -jar wmtool.jar allocatejob --username bob@esay-mobile.co.uk --password esay --mobileuserid jobid %j WMTOOL 6

7 5.0 Importing Jobs Jobs are imported from either a CSV file or a JSON file. Prefix the file with the Byte Order Mark character (U+FEFF) if you want the file processed as UTF-8. Otherwise it will be processed in the operating system's "default" character encoding. Saving the file in Windows Notepad will usually put it in the right format. 5.1 CSV Files To create a blank CSV template for a specific job type: wmtool describejobtype --username bob@esay-mobile.co.uk --password esay -- jobtypeid bom --output jobtype263.csv Hint: use the "--bom" option to add the Byte Order Mark character for you. Output will resemble: ExternalJobId,JobDescription,EstimatedJobStartDate,JobAllocateToMobileUser, New_x0020_Checkbox,New_x0020_Dropdown,New_x0020_Textbox The first columns are always: ExternalJobId: you can provide any information you want in this column. It is used to report back the status of creating and allocating jobs. JobDescription: identical to the "Job Description" field when creating a job on the website. This must be supplied. EstimatedJobStartDate: in the format "YYYY-MM-DD" or "YYYY-MM-DD hh:mm". If time is omitted, midnight is assumed. You must include this. JobAllocateToMobileUser: optionally, a mobile user name to whom to allocate the job after creation. Other columns will be the job's operator-editable items. Note that spaces and some other characters will be encoded. Hint: EstimatedJobStartDate can also be in your computer's local format, such as DD/MM/YYYY or MM-DD-YYYY, according to your regional settings. WmTool will try to interpret the date in the ISO formats specified above first, then the local format if that fails. If the job's form contains subforms, you can add multiple subforms by including multiple rows in the CSV. The first row is the main row, and must contain the special job fields (listed above) and the data for the parent form. If there are subforms, this row also contains the data for the first subform. For additional subforms, add them in extra rows, with the same ExternalJobId as the parent row. And other Job fields or parent fields will be ignored in these "subform" rows. WMTOOL 7

8 5.2 JSON Files JSON (JavaScript Object Notation) files can also be used for data uploads, by adding the command line option: "--inputformat json". Like CSVs they are just simple text files, but the JSON format is more suited to storing hierarchical data. Values are included as key/value pairs, in the form "<key>": <value>. Objects are enclosed with curly brackets: <key/value pairs> }. Arrays are enclosed with square brackets, with elements separated by commas: [ <element 1>, <element 2>, <element 3> ]. JSON input files should contain an array of job objects, each of which needs to include the same set of fields as the CSV files. Here is an example of a JSON file to create two jobs: [ "ExternalJobId": 1, "JobDescription": "descriptive text for job 1", "EstimatedJobStartDate": " ", "JobAllocateToMobileUser": "bob", "New_x0020_Textbox": "blah blah blah", "New_x0020_Numberbox": 123, }, "ExternalJobId": 2, "JobDescription": "descriptive text for job 2", "EstimatedJobStartDate": " ", "JobAllocateToMobileUser": "bob", ] "New_x0020_Textbox": "your text here", "New_x0020_Numberbox": 321, }, Pre-populated subforms take the form of an array of subform objects. For example: [ "ExternalJobId": 1, "JobDescription": "descriptive text for job 1", "EstimatedJobStartDate": " ", "JobAllocateToMobileUser": "bob", "Subform": [ "Subform_New_x0020_Textbox": "a field on subform 1", "Subform_New_x0020_Numberbox": 123, WMTOOL 8

9 ] } }, "Subform_New_x0020_Textbox": "a field on subform 2", "Subform_New_x0020_Numberbox": 321, }, ], Hint: The subform array object should have the same name as the subform field on the parent form. 5.3 Uploading To upload and allocate the jobs: wmtool importjobs --username bob@esay-mobile.co.uk --password esay -- jobtypeid input jobtype263.csv Note, you must specify the job-type ID again. Hint: use the --dryrun option first, to check the validity of your data file without uploading any data to the server. Output comes in the form of a table, or (optionally) a CSV file. Specify "--output filename" to get CSV. Output columns are: ExternalJobId: as provided in the input file for this job. StatusCode: result of processing this job (see below). Status: result of processing this job (in more human-readable form). EsayJobId: the JobId in WorkMobile, if the job was uploaded (otherwise, zero). Note that this will always be zero with --dryrun. EstimatedJobStartDate: the same date you specified in the input file. This allows you to check that your date format was interpretted correctly. Comment: any diagnostic message from WmTool or from the WorkMobile server. Will be blank, unless there was a problem. Code Meaning 0 "not uploaded" - processing has not started 1 "invalid" - the job was not processed because it was not valid (see "comment" for reason) 2 "ready to upload" - the job was validated by WmTool, but has not been uploaded yet (because of -- dryrun option) 3 "failed to upload" - the job was rejected by the server (see "comment" for server's response) 4 "uploaded" - the server accepted the job 5 "failed to allocate" - the job was accepted by the server, but the server refused to allocate the job (see "comment") 6 "allocated" - the server accepted the job and allocated it successfully WMTOOL 9