JSON Object Operation

Summary

• Internal name: JsonObjectOperation
• Category: Tools
• Purpose: Perform read or write operations (GET, SIZE, PUT_SET, REMOVE, CLEAR) on a JSON object stored in a workflow variable.
• Task type: Normal

---

Compatibility

• Minimum AndroMate version: 1.1.0

• Maximum AndroMate version: 1.1.0

• Minimum Android: Android 13 (API 33)

• Maximum Android tested: Android 16 (API 36)

• Supported manufacturers:

  • ✅ Samsung (One UI 6.x / 7.x / 8.x)
  • ✅ Google Pixel (Android Stock)
  • ⚠️ Other manufacturers — not tested

• Required permissions:

  • None

---

Detailed description

The JSON Object Operation task operates on a JSON object (jo_input) stored as a workflow variable. It supports five operations selected by an integer code (jo_ops):

jo_ops code	Operation	Description
1	SIZE	Returns the number of keys in the JSON object
2	GET	Returns the value of the key specified in jo_param
3	PUT_SET	Sets or updates the key jo_param with the value jo_value
4	REMOVE	Removes the key jo_param and returns the removed value
5	CLEAR	Replaces the JSON object with an empty {}

Mutation operations (PUT_SET, REMOVE, CLEAR) modify the JSON object in-place and write the updated object back to the workflow context — the original variable is updated.

Read operations (GET, SIZE) do not modify the object.

---

Input parameters

Parameter	Type	Required	Possible values	Android Compatibility	AndroMate Compatibility	Default
jo_input	JSONObject	Yes	JSONObject workflow variable reference (e.g. $my_json)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	{}
jo_ops	Integer	Yes	1 (SIZE) / 2 (GET) / 3 (PUT_SET) / 4 (REMOVE) / 5 (CLEAR)	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	—
jo_param	String	No	Any string key — required for GET, PUT_SET, REMOVE — supports $variable	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	""
jo_value	String	No	Any string — required for PUT_SET — supports $variable references	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	""

---

Output parameters

Field	Type	Trigger condition	Android Compatibility	AndroMate Compatibility	Default
value_output	String	Written when the operation produces a result (SIZE, GET, PUT_SET, REMOVE) — not written for CLEAR	Android 13 (API 33) → Android 16 (API 36)	1.1.0 → 1.1.0	<ANDROMATE_NULL_VALUE>

What is written to value_output per operation:

Operation	Value written
SIZE	Number of keys in the JSON object (as a string)
GET	The value of the requested key (as a string)
PUT_SET	The new value that was set
REMOVE	The value that was removed
CLEAR	Nothing written

Note: value_output is only written if the workflow variable already exists in the execution context (declared in the Start task).

---

Exceptions

Code	Exception Name	Description
JO-OPERATION-001	Unknown Operation	The jo_ops code does not match any supported operation. Accepted codes: 1, 2, 3, 4, 5.
JO-OPERATION-002	JSON Object Exception	A JSON error occurred — key not found (for GET or REMOVE), or another JSON parsing error.
ERROR-000	Other Error	An unexpected runtime error occurred during execution.

---

Execution flowchart

The following diagram illustrates the actual implementation based on the Android code:

flowchart TD
    Start([Start JsonObjectOperationTask]) --> ResolveAll[🔄 Resolve jo_input, jo_param, jo_value\nfrom workflow context]
    ResolveAll --> ValidateOps{jo_ops code known?}
    ValidateOps -->|No| E1[❌ JO-OPERATION-001]

    ValidateOps -->|Yes| Switch{jo_ops}

    Switch -->|code 1: SIZE| SizeOp[📐 count keys\nreturn length]
    Switch -->|code 2: GET| GetCheck{key exists?}
    GetCheck -->|No| E2[❌ JO-OPERATION-002\nKey not found]
    GetCheck -->|Yes| GetOp[📖 read value\nreturn value]
    Switch -->|code 3: PUT_SET| PutOp[✏️ set key = jo_value\nupdate object in context\nreturn new value]
    Switch -->|code 4: REMOVE| RemoveCheck{key exists?}
    RemoveCheck -->|No| E2
    RemoveCheck -->|Yes| RemoveOp[🗑️ remove key\nupdate object in context\nreturn removed value]
    Switch -->|code 5: CLEAR| ClearOp[🧹 replace with empty object\nupdate object in context]

    SizeOp --> WriteOutput[💾 Write result to value_output]
    GetOp --> WriteOutput
    PutOp --> WriteOutput
    RemoveOp --> WriteOutput
    ClearOp --> Success

    WriteOutput --> Success([✅ StrTaskResult])
    E1 --> Error([❌ Exception])
    E2 --> Error

    style Start fill:#e3f2fd
    style Success fill:#c8e6c9
    style Error fill:#ffcdd2
    style E1 fill:#ffcdd2
    style E2 fill:#ffcdd2
    style ResolveAll fill:#fff9c4
    style SizeOp fill:#f3e5f5
    style GetOp fill:#f3e5f5
    style PutOp fill:#f3e5f5
    style RemoveOp fill:#f3e5f5
    style ClearOp fill:#f3e5f5
    style WriteOutput fill:#c8e6c9

How it works:

1. Resolve parameters: jo_input, jo_param, and jo_value are resolved from the workflow context
2. Validate operation: if jo_ops code is unknown, throws JO-OPERATION-001
3. Execute operation:
4. SIZE: counts the keys, writes count to value_output
5. GET: reads the value of jo_param, throws JO-OPERATION-002 if key absent
6. PUT_SET: sets jo_param = jo_value, updates object in workflow context
7. REMOVE: removes jo_param, updates object in workflow context, throws JO-OPERATION-002 if key absent
8. CLEAR: replaces object with {}, updates in workflow context
9. Result: writes output to value_output and returns StrTaskResult

---

Code examples

Example 1 — GET a value from a JSON object

{
  "JsonObjectOperation": [
    {
      "id": "1",
      "title": "Read status field",
      "jo_input": "$response_json",
      "jo_ops": 2,
      "jo_param": "status",
      "value_output": "$status_value"
    }
  ]
}

Reads the "status" key from $response_json and stores its value in $status_value.

---

Example 2 — SIZE of a JSON object

{
  "JsonObjectOperation": [
    {
      "id": "2",
      "title": "Count fields",
      "jo_input": "$my_json",
      "jo_ops": 1,
      "value_output": "$field_count"
    }
  ]
}

Counts the number of top-level keys in $my_json and stores it in $field_count.

---

Example 3 — PUT_SET a key

{
  "JsonObjectOperation": [
    {
      "id": "3",
      "title": "Set result field",
      "jo_input": "$report_json",
      "jo_ops": 3,
      "jo_param": "ping_result",
      "jo_value": "$ping_output",
      "value_output": "$set_result"
    }
  ]
}

Sets "ping_result" to the value of $ping_output in $report_json. Updates $report_json in the workflow context.

---

Example 4 — REMOVE a key

{
  "JsonObjectOperation": [
    {
      "id": "4",
      "title": "Remove temp field",
      "jo_input": "$my_json",
      "jo_ops": 4,
      "jo_param": "tmp",
      "value_output": "$removed_value"
    }
  ]
}

Removes the "tmp" key from $my_json. Returns the removed value in $removed_value.

---

Example 5 — CLEAR a JSON object

{
  "JsonObjectOperation": [
    {
      "id": "5",
      "title": "Reset JSON",
      "jo_input": "$my_json",
      "jo_ops": 5
    }
  ]
}

Replaces $my_json with an empty {}.

---

Input parameter details

1. Input parameter: jo_input

Reference to the workflow variable that holds the JSON object to operate on. Must be declared as a JSONObject variable in the Start task (e.g. variableValue: "{}"). Mutation operations (PUT_SET, REMOVE, CLEAR) write the modified object back to this variable in the workflow context.

• Default: {} (empty object)
• Supports variables: Yes

2. Input parameter: jo_ops

Integer code selecting the operation to perform on the JSON object.

Code	Operation	Mutates object?	Writes to value_output?
1	SIZE	No	Yes — number of keys
2	GET	No	Yes — value of jo_param
3	PUT_SET	Yes	Yes — the new value set
4	REMOVE	Yes	Yes — the removed value
5	CLEAR	Yes	No

• Default: — (required, no default — triggers JO-OPERATION-001 if unknown)

3. Input parameter: jo_param

The JSON object key to operate on. Required for GET, PUT_SET, and REMOVE. Ignored for SIZE and CLEAR. Supports $variable references.

• Default: ""
• Supports variables: Yes

4. Input parameter: jo_value

The value to assign to jo_param when using PUT_SET. Ignored for all other operations. Supports $variable references. Always stored as a String.

• Default: ""
• Supports variables: Yes

Output parameter details

1. Result variable: value_output

Stores the string result of the operation in the specified workflow variable.

Operation	Value written
SIZE	Number of top-level keys (e.g. "3")
GET	Value of the key jo_param (as string)
PUT_SET	The new value that was set
REMOVE	The value that was removed
CLEAR	(not written)

The variable is only updated if it already exists in the workflow context (declared in the Start task).

---

Complete JSON example

{
  "JsonObjectOperation": [
    {
      "id": "1",
      "title": "Store ping result in JSON",
      "jo_input": "$report_json",
      "jo_ops": 3,
      "jo_param": "ping_result",
      "jo_value": "$ping_output",
      "value_output": "$set_result"
    }
  ]
}