Work Order REST API

Work Order REST API

Overview

The Work Orders REST API allows you to manage the Work Orders for your company. It also allows API Developers the ability to mimic the functionality of the Enterprise Dispatch Module (EDM) using their own code. API Developers can create and assign Work Orders

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 above is the same as all other Mobile Forms REST API calls. 
Note: API Developers can use OAuth 2.0 Authentication instead of the Basic Authentication. The OAuth 2.0 Authentication uses the Client Credentials Grant Type and requires the Company have a Client ID and a Client Secret generated in the Mobile Forms Portal to make web service calls to the REST API Endpoints. You can contact the Professional Services team at f2bps@field2base.com to implement OAuth 2.0 Authentication.

Supported Operations

Append to the base URL: https://fieldconnect.field2base.com/v2/api 
  1. GET workorders
    1. Retrieve a list of up to 1000 Work Orders (sorted by descending submitted time)
  2. GET workorders/?minTimestamp=[datetime]
    1. Retrieve all Work Orders created after a specific datetime (ISO 8601 format)
  3. GET workorders/?maxTimestamp=[datetime]
    1. Retrieve all Work Orders created before a specific datetime (ISO 8601 format)
  4. GET workorders/?minTimestamp=[datetime]&maxTimestamp=[datetime]
    1. Retrieve Work Orders created between specific datetimes (ISO 8601 format)
  5. GET workorders/{workOrderID}
    1. Retrieve details for a single Work Order
  6. GET workorders/{workOrderID}/data
    1. Retrieve  Region Data from a specific Work Order (in XML format)
  7. GET workorders/{workOrderID}/assignment
    1. Retrieve the Username that the Work Order is assigned to
    2. If the Work Order is unassigned, null will be returned
  8. POST workorders
    1. Create a new Work Order
  9. POST workorders/{workOrderID}/assignment
    1. Edit an individual Work Order User Assignment
  10. POST workorders/{workOrderID}
    1. Edit an individual existing Work Order
    2. Does not retain previously entered values. Any previous values that are not updated with a new value will be updated to no value.
  11. PUT workorders/{workOrderID}
    1. Edit an individual existing Work Order
    2. Retains all previously entered values
  12. DELETE workorders/{workOrderID}
    1. Cancel an individual Work Order

API Samples

 

Get All Work Orders

Work Order Type: Standard, Workflow, or Shared Form

Request: GET

  1. https://fieldconnect.field2base.com/v2/api/workorders

Response: 200 OK
  1. [
  2.     {
  3.         "ID": "1c2ca4f5-4693-4bfa-8dc2-9a1b7f15f290",
  4.         "Name": "08/18/23 INSTALL",
  5.         "Submitted": "2023-09-21T10:21:35.767",
  6.         "Type": "Standard",
  7.         "AssignedTo": "test@field2base.com",
  8.         "SubmittedBy": "test@field2base.com",
  9.         "Status": "Active"
  10.     },
  11.     {
  12.         "ID": "cb8e334f-cfc4-45ef-bd40-a490a80a3130",
  13.         "Name": "TEST Site Visit - FARM 2",
  14.         "Submitted": "2023-09-13T15:38:02.337",
  15.         "Type": "Workflow",
  16.         "AssignedTo": "test@field2base.com",
  17.         "SubmittedBy": null,
  18.         "Status": "Active"
  19.     },
  20.     {
  21.         "ID": "bd7bf2af-9c2e-479f-adbc-93fb126b92c0",
  22.         "Name": "F2B PS Contract for Acme 9/12/2023",
  23.         "Submitted": "2023-09-12T10:29:45.85",
  24.         "Type": "SharedForm",
  25.         "AssignedTo": null,
  26.         "SubmittedBy": null,
  27.         "Status": "Active"
  28.     },
  29. ]
 

Get Work Orders Within a Date Range

Request: GET

Time format: ISO 8601
Return all Work Orders created after March 1, 2021 3:30PM:
  1. https://fieldconnect.field2base.com/v2/api/workorders/?minTimestamp=2021-03-01T15:30:00Z
Return all Work Orders created before March 1, 2021 3:30PM:
  1. https://fieldconnect.field2base.com/v2/api/workorders/?maxTimestamp=2021-03-01T15:30:00Z
Return all Work Orders created between February 1, 2021 12:00AM and March 1, 2021 3:30PM:
  1. https://fieldconnect.field2base.com/v2/api/workorders/?minTimestamp=2021-02-01T00:00:00Z&maxTimestamp=2021-03-01T15:30:00Z

Get Individual Work Orders

Work Order Type: Standard, Workflow, or Shared Form

Request: GET

  1. https://fieldconnect.field2base.com/v2/api/workorders/1c2ca4f5-4693-4bfa-8dc2-9a1b7f15f280

Response: 200 OK
  1.  {
  2.      "ID": "1c2ca4f5-4693-4bfa-8dc2-9a1b7f15f280",
  3.      "Name": "08/18/23 INSTALL",
  4.      "Submitted": "2023-09-21T10:21:35.767",
  5.      "Type": "Standard",
  6.      "AssignedTo": "test@field2base.com",
  7.      "SubmittedBy": "test@field2base.com",
  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

  1. https://fieldconnect.field2base.com/v2/api/workorders/1c2ca4f5-4693-4bfa-8dc2-9a1b7f15f298/data

Response: 200 OK
  1. <?xml version="1.0" encoding="utf-8"?>
  2.   <FormPreFill Version="2.0">
  3.     <Title>Sample</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

  1. https://fieldconnect.field2base.com/v2/api/workorders/1c2ca4f5-4693-4bfa-8dc2-9a1b7f15f298/assignment

Response: 200 OK
  1. {
  2.     "Username": "Test.User@Field2Base.com"
  3. }
 

Create a 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

  1. https://fieldconnect.field2base.com/v2/api/workorders
Body:
  1. {
  2.   "Name": "Test 5/17/2022 12:32:12 PM",
  3.   "FormTemplateID": "66980572-22bd-48fb-9b4a-2e94ecf15c01",
  4.   "AssignedTo": "kermit",
  5.    "Priority": "1",
  6.   "Address": {
  7.     "Line1": "101 J Morris Commons Ln",
  8.     "City": "Morrisville",
  9.     "State": "NC",
  10.     "PostalCode": "27560"
  11.   },
  12.   "RegionData": {
  13.     "Page1@Text1": "region value",
  14.     "Page1@Text2": "another region value"
  15.   }
  16. }
  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. Priority (optional) - can be set to 1 - 5
  5. Address (optional) - when present, Line1 is required to be set
  6. RegionData (optional) - camera and other binary data regions can be populated with base64 binary data 

Response: 200 OK
  1. {
  2.     "Message": "Work Order 3f169ecd-26b4-42c7-9457-6ae9181b1841 created",
  3.     "WorkOrderID": "3f169ecd-26b4-42c7-9457-6ae9181b1841"
  4. }

Submit a new Work Order (Shared Form)

Before you can generate a Shared Form Work Order, you must take the following steps:
  1. Confirm that the Form that will be used to as a Shared Form is published to your company.
  2. Create a Shared Form Link for the selected Form. See the article on Shared Forms for more information on how to create and use Shared Forms.
  3. 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

  1. https://fieldconnect.field2base.com/v2/api/workorders
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. Address (optional but mapping/navigation is not implemented in Shared Forms) - when present, Line1 is required to be set
  6. 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. }

Edit Individual Work Order User Assignment

Work Order Type: Standard only
Request: POST
  1. https://fieldconnect.field2base.com/v2/api/workorders/ 0e70bc0b-6292-4d1d-9ac3-90e8172166cb/assignment

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. }

Edit Individual Work Orders (Overwrite all values)

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. https://fieldconnect.field2base.com/v2/api/workorders/0e70bc0b-6292-4d1d-9ac3-90e8172166cb
Body:
  1. {
  2.   "Name": "Test 5/17/2018 12:32:12 PM",
  3.   "AssignedTo": "kermit",
  4.   "RegionData":
  5.   {
  6.       "Page1@Title": "My Edited Work Order",
  7.       "Page1@StateListDatasource": "IA"
  8.   }
  9. }

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

Edit Individual Work Orders (and retain previously entered values)

Work Order Type: Standard or Shared Form
Request: PUT
  1. https://fieldconnect.field2base.com/v2/api/workorders/0e70bc0b-6292-4d1d-9ac3-90e8172166cb
Body:
  1. {
  2.   "RegionData":
  3.   {
  4.       "Page1@Title": "My Edited Work Order",
  5.   }
  6. }

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

Cancel Individual Work Order 

Work Order Type: Standard or Shared Form

Request: DELETE

  1. https://fieldconnect.field2base.com/v2/api/workorders/0e70bc0b-6292-4d1d-9ac3-90e8172166cb

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

    • Popular Articles

    • Forms Designer Quick Start Guide

      Overview Field2Base Forms Designer is the proprietary software application that allows your existing paper forms to be quickly converted to a smart E-form available to your end users via our mobile and web-based Mobile Forms applications. This ...

    • Portal 11.28.2023 Release Notes

      Overview Our release notes offer brief descriptions of product enhancements and bug fixes. We include links to the current articles for any affected features. Those articles will be updated shortly after the Portal release to include new ...

    • 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 ...

    • 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 ...