Importing Jobs

One of the most common uses of WMTool is to import batches of job details.

You can import jobs from either a CSV file  or JSON file. If you need the file processed at UTF-8 then you'll need to prefix your file with the Byte Order Mark character (U+FEFF) otherwise it'll be processed using the operating systems default character encoding.

CSV Files

To create a blank CSV file template for a specific job type. (Tip : user the --bom option to add the Byte Order Mark character for you).

1
2
wmtool describejobtype --username [e-mail] --password mypassword --
jobtypeid 263 --bom --output jobtype263.csv

Your will obviously vary based upon your own jobtype however it will resemble something like:

1
2
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.

Tip

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 a

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": "2012-02-29",
        "JobAllocateToMobileUser": "bob",
        "New_x0020_Textbox": "blah blah blah",
        "New_x0020_Numberbox": 123,
    },
    {
        "ExternalJobId": 2,
        "JobDescription": "descriptive text for job 2",
        "EstimatedJobStartDate": "2012-02-29",
        "JobAllocateToMobileUser": "bob",
        "New_x0020_Textbox": "some text here",
        "New_x0020_Numberbox": 789,

    },
]

You can also pre-populate a sub-form. In terms of JSON structure, this is essentially an array of sub-form objects.

[
    {
        "ExternalJobId": 1,
        "JobDescription": "descriptive text for job 1",
        "EstimatedJobStartDate": "2012-02-29",
        "JobAllocateToMobileUser": "bob",
        "New_x0020_Textbox": "blah blah blah",
        "New_x0020_Numberbox": 123,
        "Subform": 
        [
            {
                "Subform_New_x0020_Textbox": "subform2 text",
                "Subform_New_x0020_Numberbox": 123,
            },
            {
                "Subform_New_x0020_Textbox": subform2 text",
                "Subform_New_x0020_Numberbox": 321,
            },
        ],
    }
]

Hint

The subform array object should have the same name as the subform field on the parent form

Uploading

To actually upload and allocate the jobs.

1
wmtool importjobs --username [e-mail] --password mypassword --jobtypeid 263 --input jobtype263.csv

Tip

Use the --dryrun option first to check the validity of your data file without actually uploading an real 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 interpreted correctly.
Comment: any diagnostic message from WmTool or from the WorkMobile server. Will be blank,
unless there was a problem.

Possible StatusCodes are:

Status Code	Status	Description
0	Not Uploaded	Process has not started
1	Invalid	The job was not processed because it was invalid. See comment for reason.
2	Ready to upload	The job was validated but hasn't been uploaded yet because of the --dryrun option.
3	Failed to Upload	The job was rejected by the server. See comment for reason.
4	Uploaded	The server accepted the job.
5	Failed to Allocate	The job was accepted by the server but was unable to allocate to a user. See comment for reason.
6	Allocated	The server uploaded the job and successfully allocated it.