This document describes the recommended value formats for setting object form fields in plugins, APIs, or scripts.

General Rules

• Pass null for empty values.
• For number, currency, and percentage fields, pass numeric strings and avoid formatted symbols.
• For date, datetime, and time fields, pass millisecond timestamp strings.
• For lookup fields, pass both the field value and fieldName__r; otherwise, the page may not display the name.
• For file fields, pass an array of file objects.

Text Fields

Field Type	Example Value	Description
Single-line text	"test"	Plain string
Multi-line text	"This is multi-line text"	Use \n to separate lines when line breaks are needed
Mobile phone	"15810172396"	Phone number string
Email	"fxi@fxiaoke.com"	Email string
URL	"https://www.fxiaoke.com"	"www.fxiaoke.com" is also supported
Long text	"This is long text"	Use \n to separate lines when line breaks are needed
Rich text	"<p style='font-size:18px'><span style='color:red'>Test rich text data</span></p>"	HTML string

Multi-line text or long text line-break example:

"1. Procurement process\n2. Online reporting\n3. Procurement process"

Collaborative rich text example:

{
  "text": "Test rich text data",
  "__xt": {
    "__json": {
      "type": "doc",
      "content": [
        {
          "type": "paragraph",
          "attrs": {
            "textAlign": "left"
          },
          "content": [
            {
              "type": "text",
              "marks": [
                {
                  "type": "bold"
                },
                {
                  "type": "textStyle",
                  "attrs": {
                    "color": "rgb(51, 51, 51)",
                    "fontSize": false
                  }
                }
              ],
              "text": "Test rich text data"
            }
          ]
        }
      ]
    },
    "__summeryNodeCount": 1,
    "version": 2
  }
}

Numeric Fields

Field Type	Correct Example	Incorrect Example	Description
Number	"1000.00"	-	Pass a numeric string
Currency	"1000.00"	"1,000.00", "$1000.00"	Do not pass thousands separators or currency symbols
Percentage	"90"	"90%"	"90" means 90%

Date Fields

Field Type	Correct Example	Incorrect Example	Description
Date	"1729244925956"	"2024/10/18"	Pass the millisecond value for the corresponding date
Datetime	"1729244997591"	"2024/10/18 17:50"	Pass the millisecond value for the corresponding date and time
Time	"1729244997591"	"17:50"	Pass the millisecond value for the corresponding date and time

Option Fields

Field Type	Example Value	Description
Single select	"options1"	Pass the option value
Multi select	["options1", "options2", "options3"]	Pass an array of option values
Boolean	true	true means yes; pass false when the default selected value is no

File Fields

Images, signatures, attachments, and large attachments all use arrays of file objects.

Image or signature example:

[
  {
    ext: "jpg",
    filename: "sample-image.jpg",
    path: "N_1243.jpg",
    size: 433390
  }
]

Attachment or large attachment example:

[
  {
    create_time: 1729246925703,
    ext: "jpg",
    filename: "sample-image.jpg",
    path: "N_1243.jpg",
    size: 433390
  }
]

Data Fields

Lookup

For a single-select lookup field, pass the target data ID and the display name field.

Example with account_id:

{
  account_id: "xxxxxx",
  account_id__r: "Display name"
}

If account_id__r is not passed, the page may not display the name.

Multi-select Lookup

For a multi-select lookup field, pass an ID array and a display object array in fieldName__r.

Example with contact_ids:

{
  contact_ids: ["xxxxxx1", "xxxxxx2"],
  contact_ids__r: [
    {
      _id: "xxxxxx1",
      name: "Display name 1"
    },
    {
      _id: "xxxxxx2",
      name: "Display name 2"
    }
  ]
}

Personnel and Department Fields

Field Type	Example Value	Description
Personnel	["1000"]	1000 is the personnel ID
Multi-select personnel	["1000", "1001"]	Pass an array of personnel IDs
External personnel	["1000000000000001"]	Pass an array of external personnel IDs
Department	["1005"]	Pass an array of department IDs
Multi-select department	["1005", "1006"]	Pass an array of department IDs
External department	["30000000000001"]	Pass an array of external department IDs

Map Fields

Field Type	Example Value	Description
Location	"114.086027#%$23.017722#%$20 meters southwest of the intersection of Wenming Road and Youyi Road, Dongguan, Guangdong"	Join longitude, latitude, and detailed address with #%$
Country	"248"	Corresponding country code
Province	"321"	Corresponding province code
City	"456"	Corresponding city code
District	"1000"	Corresponding district code

Common Mistakes

Scenario	Incorrect Value	Recommended Value
Currency with formatting	"1,000.00", "$1000.00"	"1000.00"
Percentage field with percent sign	"90%"	"90"
Date passed as a formatted string	"2024/10/18"	"1729244925956"
Datetime passed as a formatted string	"2024/10/18 17:50"	"1729244997591"
Time passed as hour and minute only	"17:50"	"1729244997591"
Lookup with only ID	{ account_id: "xxxxxx" }	{ account_id: "xxxxxx", account_id__r: "Display name" }