Configuration

Prerequisites

Before starting, gather:

• ☐ OpenAPI specification file (JSON or YAML)
• ☐ API credentials (username and password for Basic Auth)
• ☐ API base URL
• ☐ Endpoint paths for:
  • Record metadata (schema/fields)
  • Record fetch (get by ID)
  • Record create
  • Record update
  • Attachments upload (optional)
• ☐ Admin access to Field Nation integrations

Step 1: Access REST Connector

Navigate to Field Nation's Integration Broker:

Sandbox: ui-sandbox.fndev.net/integrations Production: app.fieldnation.com/integrations

Step 2: Upload OpenAPI Specification

The OpenAPI spec enables automatic endpoint discovery and field mapping.

Prepare Your Spec File

Supported Formats:

• OpenAPI 3.x (JSON or YAML)
• OpenAPI 2.x / Swagger 2.0 (JSON or YAML)

Where to Get It:

• API documentation portal
• /swagger.json or /api-docs endpoint
• API provider's developer resources
• Tools: Postman, Swagger UI, Stoplight

Validate Before Upload:

# Using Swagger Editor (online or local)
https://editor.swagger.io/

# Or CLI tools
swagger-cli validate openapi.json

Upload Process

What Happens:

• Broker parses spec to discover endpoints
• Extracts request/response schemas
• Populates endpoint dropdown menus
• Enables field discovery

Step 3: Configure Endpoints

Select which API endpoints to use for each operation.

Record Metadata Endpoint

Purpose: Get field definitions and schema information

Required: Yes - enables field mapping UI

Example Endpoints:

• GET /api/v1/tickets/metadata
• GET /api/v1/schema/ticket
• OPTIONS /api/v1/tickets (if returns schema)

Configuration:

1. Click "Record Metadata" dropdown
2. Select endpoint from list (populated from OpenAPI spec)
3. Select HTTP method (usually GET)

Dropdown Contents:

• All endpoints from uploaded OpenAPI spec
• Filtered to relevant operations
• Shows path + method (e.g., GET /api/v1/metadata)

Record Fetch Endpoint

Purpose: Retrieve single record by ID

Required: Yes - fetches data for inbound sync

Example Endpoints:

• GET /api/v1/tickets/{id}
• GET /api/v1/records/{ticket_id}
• GET /api/v1/workorders/{wo_id}

Configuration:

1. Click "Record Fetch" dropdown
2. Select endpoint with ID parameter
3. Method: GET

ID Parameter:

• Endpoint must accept ID parameter (path or query)
• Example: /tickets/{id} or /tickets?id={id}
• Broker substitutes actual ID at runtime

Record Create Endpoint

Purpose: Create new records in external system

Required: Yes - core functionality

Example Endpoints:

• POST /api/v1/tickets
• POST /api/v1/workorders/create
• PUT /api/v1/records (if PUT creates)

Configuration:

1. Click "Record Create" dropdown
2. Select creation endpoint
3. Method: usually POST (sometimes PUT)

Request Body:

• Broker constructs body from field mappings
• Format determined by OpenAPI spec (JSON, XML, etc.)
• Uses schema defined in spec for validation

Record Update Endpoint

Purpose: Update existing records

Required: Recommended (enables bidirectional sync)

Example Endpoints:

• PUT /api/v1/tickets/{id}
• PATCH /api/v1/tickets/{id}
• POST /api/v1/tickets/{id}/update

Configuration:

1. Click "Record Update" dropdown
2. Select update endpoint
3. Method: PUT, PATCH, or POST

PUT vs PATCH:

• PUT: Full record replacement
• PATCH: Partial update (only changed fields)
• Check your API's behavior - configure accordingly

Attachments Upload Endpoint

Purpose: Upload files/documents to records

Required: Optional - only if file sync needed

Example Endpoints:

• POST /api/v1/tickets/{id}/attachments
• POST /api/v1/files/upload
• PUT /api/v1/records/{id}/documents

Configuration:

1. Click "Attachments Upload" dropdown
2. Select file upload endpoint
3. Method: usually POST

File Handling:

• Multipart/form-data or base64 encoding
• Determined by OpenAPI spec
• Broker handles encoding automatically

Step 4: Set Authentication

REST Connector supports Basic Authentication only.

Enter Credentials

Format: username:password

Examples:

api_user:secure_password_123
integration@company.com:MyP@ssw0rd!
client_12345:abc123xyz789

Configuration:

1. Locate "Authentication" section
2. Enter credentials in format: username:password
3. Broker encodes automatically to Authorization: Basic base64(username:password)

Security Best Practices

Step 5: Test Connection

Verify REST Connector can communicate with your API.

Common Connection Errors

Step 6: Refresh Fields

Discover available fields for mapping.

Field Discovery Includes:

• Field names and API keys
• Data types (string, integer, boolean, etc.)
• Required/optional status
• Enum values for picklists
• Nested object structures

Step 7: Configure Field Mappings

Map data between Field Nation and your external system.

Inbound Mappings (External → Field Nation)

Map external system fields to Field Nation work order fields:

Example:

External Field → Field Nation Field
──────────────────────────────────
ticket_title → title
ticket_description → description
priority_level → priority (with Array Map)
customer_name → location.company.name
scheduled_date → schedule.start (with Date Convert)

Outbound Mappings (Field Nation → External)

Map Field Nation fields to external system updates:

Example:

Field Nation Field → External Field
────────────────────────────────────
status.name → ticket_status (with Array Map)
assignee.user.email → technician_email
completion_notes → resolution_notes
approved_amount → final_cost

Complete field mapping guide →

Field Mapping Actions

Use standard transformation actions:

Sync: Direct copy

{
  "source": "external_field",
  "target": "fn_field",
  "action": "sync"
}

Array Map: Status mapping

{
  "source": "status",
  "target": "fn_status",
  "action": "array_map",
  "mappings": [
    { "compare": "open", "value": "1" },
    { "compare": "in_progress", "value": "2" },
    { "compare": "completed", "value": "5" }
  ]
}

Date Convert: Date formatting

{
  "source": "scheduled_date",
  "target": "schedule.start",
  "action": "date_convert",
  "input_format": "YYYY-MM-DD",
  "output_format": "YYYY-MM-DD HH:mm:ss"
}

All transformation actions →

Step 8: Save & Test

Troubleshooting