Work Order REST API

Work Order REST API

Overview

The Work Orders REST API allows Customers to manage Work Orders (Standard, Workflow or Shared Form). See the article on Shared Forms for more information on how to create and use Shared Forms.

Base URL 
https://fieldconnect.field2base.com/v2/api

Header (Required)
Authorization: Basic {CompanyID}:{Username}:{Password}:{API Sync Key}
Content-Type: application/json

Note: Authorization Header is the standard for all F2B REST API calls.

F2B API Prerequisites

To use the Sent Forms REST API, you need the following:
  1. An API Sync Key  for the Company
  2. A User Account with the ability to submit to the API (Mobile Forms Administrator role)

Supported Operations

The following operations are supported by the REST web service.

Endpoint
Method
Description
workorders
GET
Return a list of up to 1000 Work Orders (sorted by descending submitted time)
workorders
POST
Submit a new Work Order
workorders/{work order ID}
GET
Return info on a single Work Order
workorders/{work order ID}
POST
Edit an individual existing Work Order
workorders/{work order ID}
PUT
Edit an individual existing Work Order (while retaining all previously entered values)
workorders/{work order ID}
DELETE
Cancel individual Work Order
workorders/{work order ID}/data
GET
Return Region Data from a specific Work Order (in XML format)
workorders/{work order ID}/assignment
GET
Return the Username of the User that the Work Order is assigned to (if any)
workorders/{work order ID}/assignment
POST
Edit individual Work Order User Assignment
workorders/?minTimestamp=[datetime]
GET
Return all Work Orders created after a specific datetime (ISO 8601 format)
workorders/?maxTimestamp=[datetime]
GET
Return all Work Orders created before a specific datetime (ISO 8601 format)
workorders/?minTimestamp=[datetime]&maxTimestamp=[datetime]
GET
Return Work Orders created between specific datetimes (ISO 8601 format)

JSON Definition

  1. {
  2.         "ID": {guid},
  3.         "Name": {string},
  4.         "Submitted": {string},
  5.         "Type": {string},
  6.         "AssignedTo": {string},
  7.         "SubmittedBy": {string},
  8.         "Status": {string}
  9. }

API Samples

 

Get All Work Orders

You will get a list of up to 1000 work orders in company sorted by descending submit time.

Work Order Type: Standard, Workflow, or Shared Form

Request: GET

Response: 200 OK

Submitted time format: ISO 8601

  1. [
  2.   {
  3.     "ID": "0e70bc0b-6292-4d1d-9ac3-90e8172166cb",
  4.     "Name": "My First Work Order",
  5.     "Submitted": "2018-04-03T15:09:01.183",
  6.     "Type": "Standard",
  7.     "AssignedTo": "qa",
  8.     "SubmittedBy": "HowardChen",
  9.      "Status": "Active"
  10.   },
  11.   {
  12.     "ID": "54adfd10-aecc-409c-9b42-5004a284fae5",
  13.     "Name": "this is a sample prefill",
  14.     "Submitted": "2018-04-03T11:25:29.947",
  15.     "Type": "Standard",
  16.     "AssignedTo": "qa",
  17.     "SubmittedBy": "MaryMorvan",
  18.      "Status": "Active"
  19.   }
  20. ]
  

Submit a new Work Order (Standard)

Before you can generate a Standard Work Order, you must take the following steps:
  1. Confirm that the Form that will be used to generate the Work Order is published to your Company
  2. Get the Form Template ID of the Form that will be used to generate the Work Order

Request: POST

Body:
  1. {
  2.   "Name": "Test 5/17/2018 12:32:12 PM",
  3.   "FormTemplateID": "66980572-22bd-48fb-9b4a-2e94ecf15c01",
  4.   "AssignedTo": "kermit",
  5.   "Address": {
  6.     "Line1": "101 J Morris Commons Ln",
  7.     "City": "Morrisville",
  8.     "State": "NC",
  9.     "PostalCode": "27560"
  10.   },
  11.   "RegionData": {
  12.     "Page1@Text1": "region value",
  13.     "Page1@Text2": "another region value"
  14.   }
  15. }
  1. Name (required) - used as the work order name
  2. FormTemplateID (required)
  3. AssignedTo (optional) - may be either a username or a user GUID
  4. Address (optional) - when present, Line1 is required to be set
  5. PaymentAccount (not supported)
  6. Priority (optional) - can be set to 1 - 5
  7. Child prefills (not supported)
  8. Zipped datasource files (not supported)
  9. RegionData (optional) - camera and other binary data regions can be populated with base64 binary data 

Response: 200 OK
  1. {
  2.     "Message": "Work Order 0e70bc0b-6292-4d1d-9ac3-90e8172166cb edited"
  3. }

Submit a new Work Order (Shared Form)

Before you can generate a Shared Form Work Order, you must take the following steps:
  1. Confirm Shared Forms is enabled for your Company
  2. Confirm that the Form that will be used to as a Shared Form is published to your Company
  3. Create a Shared Form Link for the selected Form
  4. Copy the Shared Form Link Token for the appropriate Link Type (F2B Header vs. Embedded)
    1. Navigate to Admin > Form Templates > Shared Forms 
    2. Click on Select an Action > Details to view the URLs with the Link Token included  

             
            

Request: POST

Body:
  1. {
  2.   "Name": "Shared Form PreFill 5/17/2018 12:32:14 PM",
  3.   "TemplateLinkToken": "d03be4df-9b0f-42be-9942-10155ffffb0d",
  4.   "RecipientEmail": "user@field2base.com",
  5.   "NotificationMessage": {
  6.     "Subject": "New Shared Work Order",
  7.     "Body": "Go to {SharedFormWorkOrderURL} to complete your Work Order"
  8.   },
  9.   "Address": {
  10.     "Line1": "101 J Morris Commons Ln",
  11.     "City": "Morrisville",
  12.     "State": "NC",
  13.     "PostalCode": "27560"
  14.   },
  15.   "RegionData": {
  16.     "Page1@TextRegion1": "1234",
  17.     "Page1@TextRegion2": "Shared Form PreFill 5/17/2018 12:32:14 PM"
  18.   }
  19. }
  1. Name (optional) - will be used as link name; if omitted then the link name is copied from the template
  2. TemplateLinkToken (required) - identifies an existing shared form link
  3. RecipientEmail - required if notification message is present; otherwise optional
  4. NotificationMessage (optional) - when present, both subject and body must be set and body must include {SharedFormWorkOrderURL} tag
  5. FormTemplateID (disallowed)
  6. AssignedTo (disallowed)
  7. Address (optional but mapping/navigation is not implemented in Shared Forms) - when present, Line1 is required to be set
  8. PaymentAccount (not supported)
  9. Priority (not supported)
  10. Child prefills (not supported)
  11. Zipped datasource files (not supported)
  12. RegionData (optional) - camera and other binary data regions can be populated with base64 binary data 

Response: 200 OK
  1. {
  2.   "Message": "Work Order 1a860978-4879-466f-ad48-d2080d888bae created with share link token ed46aff0-c0c4-4247-a3bf-0692a594a3db",
  3.   "WorkOrderID": "1a860978-4879-466f-ad48-d2080d888bae",
  4.   "LinkToken": "ed46aff0-c0c4-4247-a3bf-0692a594a3db"
  5. }

Get Individual Work Orders

You will get information about a single work order by work order ID.

Work Order Type: Standard, Workflow, or Shared Form

Request: GET

Response: 200 OK
  1. {
  2.   "ID": "0e70bc0b-6292-4d1d-9ac3-90e8172166cb",
  3.   "Name": "My First Work Order",
  4.   "Submitted": "2018-04-03T15:09:01.183",
  5.   "Type": "Standard",
  6.   "AssignedTo": "qa",
  7.   "SubmittedBy": "HowardChen",
  8.    "Status": "Active"
  9. }
 

Get Work Order Region Data

To get all current Region values for a specific Work Order (in XML format). 

Work Order Type: Standard or Shared Form

Request: GET


Response: 200 OK
  1. <?xml version="1.0" encoding="utf-8"?>
  2.   <FormPreFill Version="2.0">
  3.     <Title>Sample for Genesis</Title>
  4.     <FormTemplateId>b6d4ef86-358d-424f-a2c1-9856dd0d927a</FormTemplateId>
  5.     <RegionValue>
  6.       <Region>Page1@CustomerText</Region>
  7.       <Value>Mary</Value>
  8.     </RegionValue>
  9.     <RegionValue>
  10.       <Region>Page1@AddressText</Region>
  11.       <Value>123 another address</Value>
  12.     </RegionValue>
  13.     <RegionValue>
  14.       <Region>Page1@AddressText2</Region>
  15.       <Value>Cary </Value>
  16.     </RegionValue>
  17.     <RegionValue>
  18.       <Region>Page1@StateListDatasource</Region>
  19.       <Value>IA</Value>
  20.     </RegionValue>
  21.   </FormPreFill>
 

Get Assigned User from Individual Work Order

Work Order Type: Standard or Workflow

Request: GET


Response: 200 OK
  1. {
  2.     "Username": "HowardChen"
  3. }
 

Edit Individual Work Order User Assignment

Work Order Type: Standard only
Request: POST

Body:

  1. {
  2.   "User": "HowardChen",
  3.   "SendUserNotification": true
  4. }
Note: The user can be either Username or User Key

Response: 200 OK
  1. {
  2.     "Message": "Work Order 0e70bc0b-6292-4d1d-9ac3-90e8172166cb reassigned"
  3. }

Cancel Individual Work Order 

Work Order Type: Standard or Shared Form

Request: DELETE


Response: 200 OK
  1. {
  2.     "Message": "Work Order 0e70bc0b-6292-4d1d-9ac3-90e8172166cb canceled"
  3. }
 

Edit Individual Work Orders 

This action will not retain any data previously Pre-Filled in the Work Order. The Body must include "Name" and "AssignedTo" along with any relevant Region Data, even if previously entered. All previously assigned values for Region Data, "Name", and "AssignedTo" will be removed if not specified.

Work Order Type: Standard or Shared Form

Request: POST
  1. {
  2.   "Name": "Test 5/17/2018 12:32:12 PM",
  3.   "AssignedTo": "kermit",
  4.   "RegionData":
  5.   {
  6.       "Page1@Title": "My First Work Order",
  7.       "Page1@StateListDatasource": "IA"
  8.   }
  9. }
The request body is the same as used to Submit a Work Order except that FormTemplateID / TemplateLinkToken are disallowed because they are inferred from the Work Order ID provided. 

Response: 200 OK
  1. {
  2.     "Message": "Work Order 0e70bc0b-6292-4d1d-9ac3-90e8172166cb edited"
  3. }
 

Edit Individual Work Orders (and retain previously entered values)


Request: PUT
Body:
  1. {
  2.   "RegionData":
  3.   {
  4.       "Page1@Title": "My First Work Order",
  5.       "Page1@StateListDatasource": "IA"
  6.   }
  7. }

The request body is the same as used to Submit a Work Order except that FormTemplateID / TemplateLinkToken are disallowed because they are inferred from the Work Order ID provided. 

Response: 200 OK
  1. {
  2.     "Message": "Work Order 0e70bc0b-6292-4d1d-9ac3-90e8172166cb edited"
  3. }


Get Work Orders Within a Date Range


Return all Work Orders created after March 1, 2021 3:30PM:
Return all Work Orders created before March 1, 2021 3:30PM:
Return all Work Orders created between February 1, 2021 12:00AM and March 1, 2021 3:30PM:

Response: 200 OK



    • Popular Articles

    • Forms Designer Quick Start Guide

      Overview Field2Base Forms Designer is the proprietary software application that allows your existing Forms to be quickly converted to an active, online, smart Form available to your end users via our Mobile Device and Web-based Applications. This ...

    • Integration Service Configuration Guide

      How To Configure Integration Services To Allow Read/Write Access on a Network Path All of our Integration Products, including the DIM, DUU, and EDM have respective Windows Services responsible for communicating with our server. Occassionally, ...

    • Data Integration Module (DIM) Migration Guide

      Overview This article provides the information necessary to migrate the Field2Base Data Integration Module (DIM) over from one server to another. Please refer to the DIM Install Guide for the initial installation of the Field2Base DIM. Once that's ...

    • Mobile Forms iOS Enterprise App Upgrade to the Mobile Forms iOS App Store

      Overview This guide will review how to switch between two versions of the Mobile Forms app, uninstalling the Enterprise build and installing the App Store Build. The primary benefits of switching over are that updates to the App Store build are ...

    • How to Check the Version of Integration Products Running on a Windows 10 Machine

      Right-click on the Start menu button. Click on Apps & Features. In the Apps & Features search bar type in the Integration Product you are looking for, eg. F2B Data Integration Module, F2B Data Upload, or F2B Enterprise Dispatch Module. Click to ...