1. Field Service Management
  2. FSM Configuration
  3. FSM Configuration Reference
  4. Configuring FSM Mobile File and Image Fields

Configuring FSM Mobile File and Image Fields

Configure File and Image elements under routes/mobile.<resource ID>.element. Use these elements to display existing documents or images, or to capture and upload content for a record. Configure the matching record and field mappings under that resource's article. For the capability and file lifecycle, see FSM Mobile File and Image Fields.

This topic covers fields within records and resources. The separate Configuring FSM Mobile File Management covers the supplied files resource, its description editing and native-file deletion.

Properties and Defaults

Choose the setup combination for your intended outcome. The following table combines the elements, mappings, record setup, and synchronization requirements. The shared references define individual properties and defaults. An element alone does not create a NetSuite field or save its value.

Intended Outcome

Required Setup Combination

Configuration Example

Display an existing file or image

Load the stored file reference and its accessible address into a file or image element. No new upload is needed.

Displaying an existing document; Default JSON.

Display without allowing input

Combine element readonly: true with the loaded file value. Give the mapping no write destination when the field must also remain unchanged during other record edits.

Displaying an existing document; Displaying values without editing.

Upload a file into a record field

Combine type: "file", a writable file-reference mapping, an existing destination field and an upload-capable synchronization path.

Explicit fields and mappings.

Capture or select a photograph

Combine type: "image", a writable mapping and the upload prerequisites. Add camera: true when capture should be offered.

Explicit fields and mappings.

Generate fields from a NetSuite form

Load the appropriate form, include the file and image fields and retain Automap or supply matching article mappings.

Form-generated capture and upload.

Define fields explicitly

Supply each element and its complete article mapping. Form loading is unnecessary for this alternative.

Explicit fields and mappings.

Make the entire resource view-only

Combine resource readonly: true with read-only file and image presentation and retrieval mappings.

Displaying values without editing.

For file and image value formats, accept, camera, downsample, maxsize and their defaults and limits, see FSM Mobile Element (Block) Reference. The examples below show those controls together with the record and mapping setup for each outcome.

For form properties and permission precedence, see FSM Mobile Resource Properties Reference. For mapping syntax and Automap precedence, see FSM Searches and Field Mapping.

Default JSON

The supplied Asset resource displays the related Item's image as a read-only value. It prefers the Item's stored display thumbnail and falls back to its stored display image. This standard fragment shows the image definition and mapping. The Asset selection, other elements, and other mappings remain inherited.

            {
  "routes/mobile": {
    "asset": {
      "element": {
        "image": {
          "type": "image",
          "readonly": true
        }
      },
      "article": {
        "map": {
          "image": {
            "id": "=formulatext:nvl({custrecord_nx_asset_item.storedisplaythumbnail.id}, {custrecord_nx_asset_item.storedisplayimage.id})",
            "url": "formulatext:'mobile/file/'||nvl({custrecord_nx_asset_item.storedisplaythumbnail.id}, {custrecord_nx_asset_item.storedisplayimage.id})"
          }
        }
      }
    }
  }
}

The Asset resource displays an Item image. The displayed image is not a writable image field on the Asset. Removing readonly from this element does not provide an Item or Asset image write destination.

Changing File and Image Field Setup

The following examples are custom configuration fragments, not standard defaults or complete account configurations. Merge only the intended changes. Use Updating and Validating FSM Configuration for the shared Editor, activation, merge and Preview guidance.

Note:

The inspection examples use placeholder record and field IDs. Replace those IDs consistently with valid IDs from your account.

Displaying an existing document

This example displays the Document field of existing inspections for the current CRM Task. The inspection record, Document field, and Task-link field must already exist. The IDs are illustrative placeholders. Add inspection_documents alongside the other required resource IDs in the matching CRM Task resource rule.

              {
  "routes/mobile": {
    "inspection_documents": {
      "label": "Inspection Documents",
      "readonly": true,
      "article": {
        "record": "customrecord_example_inspection",
        "parent": "custrecord_example_task",
        "map": {
          "document": {
            "id": "=custrecord_example_document|",
            "url": "formulatext:nvl2({custrecord_example_document},'mobile/file/'||{custrecord_example_document.id}, '')"
          }
        }
      },
      "element": {
        "document": {
          "type": "file",
          "label": "Inspection Document",
          "readonly": true
        }
      }
    }
  }
}

When an inspection's Document field contains a file reference, the mapped ID and download address supply the download link. The ID mapping has no write destination, and the resource offers no create, edit or delete actions. This view reads existing files. It requires record-search and file access but does not create or attach files. The editable inspection examples below are separate resource definitions for capturing new content on the same illustrative record type.

Form-generated capture and upload

This example uses an illustrative custom inspection record for CRM Task jobs. The record and fields are account-created; their IDs are placeholders to replace consistently with the IDs from your account.

To configure form-generated file and image fields:

  1. Provide the inspection record type, a Document field and an Image field in NetSuite. The example IDs are customrecord_example_inspection, custrecord_example_document and custrecord_example_image. The record must support native file attachments, and the synchronization role must be able to create files and save and attach to the inspection record.

  2. Provide a field linking the inspection to the CRM Task. The example uses custrecord_example_task. Make the document and image fields available on the form loaded for that record.

  3. Define the inspection resource as shown below. article.parent supplies the Task link for new inspections and restricts retrieval to that Task when no custom article.filters are supplied. If you supply custom article.filters, include the Task restriction in those filters. article.parent does not add the restriction to supplied filters.

                        {
  "routes/mobile": {
    "inspection": {
      "label": "Inspection",
      "article": {
        "record": "customrecord_example_inspection",
        "parent": "custrecord_example_task"
      },
      "form": {
        "include": [
          "custrecord_example_document",
          "custrecord_example_image"
        ]
      },
      "automap": true,
      "element": {
        "custrecord_example_document": {
          "type": "file",
          "label": "Inspection Document",
          "required": true,
          "accept": "application/pdf,.pdf",
          "maxsize": 2048
        },
        "custrecord_example_image": {
          "type": "image",
          "label": "Inspection Photograph",
          "camera": true,
          "downsample": 1600
        }
      }
    }
  }
}

  4. Include inspection alongside the required existing resource IDs in the matching CRM Task rule at routes/mobile.event.article.task.resources. For rule structure and array preservation, see Selecting Resources.

The document is required in FSM Mobile. The picker offers PDF selection, and the non-bitmap size limit is 2,048 KB. The selected file must be smaller than this limit. The optional photograph requests camera capture and resizes supported bitmap images to a maximum width or height of 1,600 pixels. These input choices do not change the NetSuite field types or capacity.

The form supplies the fields. The explicit elements apply the document and photograph settings in this example. For generated types, properties, initial values and field-ID suffix recognition, see Form Field Translation.

Automap generates each field's file-reference mapping from its element name. An existing matching article.map entry takes precedence, so retain a complete compatible mapping if one is already configured. If another field or initial value is required to save the inspection, supply it through the form, elements, or article defaults as appropriate. The example's two-field include array is not a substitute for those record requirements.

This Task-link example applies to CRM Tasks. A Project Task requires its own valid relationship field and selection rule. A Task reference cannot be assumed to accept Project Task IDs.

Explicit fields and mappings

This alternative defines the same two inputs without loading a form. Use it in place of the preceding inspection definition, retaining the record, field, attachment and resource-selection prerequisites. The element names now differ from the NetSuite field IDs, so the map identifies each destination explicitly.

Important:

When switching between these alternatives in custom JSON, replace the earlier resource definition rather than combining both sets of element names. Object merging otherwise retains the earlier elements and mappings. Keep any other account-specific fields required by the record.

              {
  "routes/mobile": {
    "inspection": {
      "label": "Inspection",
      "form": false,
      "automap": false,
      "article": {
        "record": "customrecord_example_inspection",
        "parent": "custrecord_example_task",
        "map": {
          "document": {
            "id": "=custrecord_example_document",
            "url": "formulatext:nvl2({custrecord_example_document},'mobile/file/'||{custrecord_example_document.id}, '')"
          },
          "photo": {
            "id": "=custrecord_example_image",
            "url": "formulatext:nvl2({custrecord_example_image},'mobile/file/'||{custrecord_example_image.id}, '')"
          }
        }
      },
      "element": {
        "document": {
          "type": "file",
          "label": "Inspection Document",
          "required": true,
          "accept": "application/pdf,.pdf",
          "maxsize": 2048
        },
        "photo": {
          "type": "image",
          "label": "Inspection Photograph",
          "camera": true,
          "downsample": 1600
        }
      }
    }
  }
}

Each map loads the file ID and download address together. Its id entry writes the uploaded file ID to the destination field. The formula for the download address is read-only. Retain both entries so an existing document or photograph loads with its identity and link. For the primary-ID syntax and the syntax for reading and writing, see FSM Searches and Field Mapping.

Displaying values without editing

To make the resource in Explicit fields and mappings view-only, merge the following fragment. The fragment removes resource actions and both field write destinations. It also changes both inputs to read-only links. The mappings for the download address, record selection and parent context remain inherited.

              {
  "routes/mobile": {
    "inspection": {
      "readonly": true,
      "article": {
        "map": {
          "document": {
            "id": "=custrecord_example_document|"
          },
          "photo": {
            "id": "=custrecord_example_image|"
          }
        }
      },
      "element": {
        "document": {
          "readonly": true
        },
        "photo": {
          "readonly": true
        }
      }
    }
  }
}

If only one field should be view-only while other inspection data remains editable, apply its element readonly and read-only ID mapping without the resource-level readonly. A value supplied by a search or expression must still have the File or Image object shape. For a search supplying one value, return the single mapped object rather than an array; see Selecting One Search Result. Do not construct upload data from a file name or bare ID.

Dependencies and Customization Limits

The chosen record type, destination fields, searchable field joins, permissions and attachment support must match the resource's save design. Form generation and Automap do not establish that these dependencies are valid. Required, hidden, disabled and read-only combinations must allow the necessary values to be supplied; see Property Validation Rules.

The standard record-resource upload path creates new File Cabinet files before saving the mapped record, then attaches those new files to the saved record. Uploads are recognized from new file objects containing upload data and no existing file ID. A value already carrying a file ID is not uploaded or newly attached by that path.

Important:

Use an attachment-capable destination for this path. The supplied Field Service File record (customrecord_nx_file) has attachments disabled in its record definition; do not substitute it for the inspection example and assume the native-attachment step will succeed. Its separate file-association service is described in FSM File Record.

File creation, field persistence and native attachment are separate operations. A record-save failure can leave an uploaded file without a saved reference. An attachment failure can occur after the record and its file reference have been saved. Saving locally, seeing a file name, or validating the configuration JSON does not confirm that all synchronization stages completed.

Several uploads in one synchronization

All new file and image values on one article, including values within table rows, are processed during that article's synchronization request. Each file to upload adds file creation and native-attachment work to the request. The same request also saves the record and performs other resource processing. The standard path does not automatically divide those values into separate upload requests.

NetSuite limits a Suitelet execution to 1,000 usage units for its combined operations. Many new files can exhaust that shared processing budget before the request completes; the practical count depends on the resource's other operations and the account's processing. See Script Type Usage Unit Limits.

Resource max controls article count. File maxsize and image downsample control individual input size or dimensions. These settings do not establish how many new files can finish in one synchronization. Existing values that already identify native files skip new-file creation through this path. A failed multi-file request can leave earlier files or record changes saved, as described above.

Upload storage, field references and attachments

The following table distinguishes upload storage, field references, and native record attachments.

Relationship

Standard Field-Upload Outcome

File Cabinet folder

Uses the FSM Mobile upload root, followed by the current event ID, requested Asset or event Asset, and employee ID. The standard root is /Field Service Management/upload/.

Mapped record field

Stores the native file ID through the configured write mapping. The inspection examples store it on the inspection record.

Native record attachment

Attaches each newly uploaded file to the record saved by the resource.

Field uploads and Files-tab uploads can share the upload-folder context. In the inspection examples, native attachments belong to the inspection record, rather than the CRM Task referenced by its parent field. The supplied Files tab attaches to its configured event destination.

A parent link, an Asset selected for folder context and a native attachment destination are separate relationships. These relationships do not automatically attach the file to every related Task, Case, or Asset.

A field upload can appear in the Files tab through its matching upload-folder context, even when its native attachment belongs to a different record. Appearance in the Files tab, History, or reports depends on the searches and context used by each destination. Do not assume every uploaded file appears in all three. See Configuring FSM Mobile File Management, Configuring FSM Mobile Asset History and Images and Branding for their selection and display setup.

Resource-specific boundaries

Use the synchronization behavior of the resource being configured.

Resource Arrangement

Boundary to Preserve

Standard record resource, including the supplied Details and Asset resources

File and Image inputs need compatible mappings and the record-upload prerequisites above. Adding an input alone does not add its field mapping.

Existing standard transaction resource

Its specialized processing can call the standard upload path. Preserve its transformations, fulfillment, inventory-detail handling, related-record updates, standard definition, and required mappings when extending it.

Supplied files resource

Uses specialized native-file creation, description updates, and deletion. Making its existing document element editable does not implement file-content replacement.

New resource under a different ID

Establish its own record model, maps, selection and synchronization. Copying visible Files or transaction JSON does not copy the source definition's executable operations.

Numeric-suffix instance of an existing resource

An ID such as files-1 resolves to the existing files definition. The instance reuses that definition with its own context. An independent resource under another name has a separate definition.

The supplied Contact and History resources are read-only views. Removing their read-only controls is not an upload setup. Their displayed values do not establish writable destination fields or an appropriate editable model.

Replacing, clearing and removing fields

In an editable mapped field, selecting replacement content can create a new native file and update the stored field reference. Clearing the input supplies null. A writable primary-ID mapping clears the field after the record saves successfully. The record's validation requirements still apply.

Neither action deletes the earlier native file or removes its native attachments in the standard field-upload path. A read-only mapping has no field to clear. Removing or hiding an element also does not delete saved files or their attachments.

Warning:

Deleting a file through the supplied Files tab is a separate native-file deletion action and can affect any field still referencing that file.

When Changes Apply

Element, form, and map changes apply when FSM Mobile loads the revised resource definition and data. Input choices such as camera, accept, and downsample affect subsequent selections. These input choices do not resize or move files already saved in NetSuite. Changing a map does not migrate earlier stored references or native attachments.

Saving an editable article locally and synchronizing it to NetSuite are separate stages. Successful synchronization returns the saved values used by FSM Mobile. Accessing server files and completing new uploads require a connection and the applicable permissions. For shared reload and resource-selection guidance, see Applying Resource Changes.

Related Topics

General Notices