Group Update API

1. Overview

The Group Update API lets you define and run automation campaigns that execute the same set of tasks (set/get parameter, RPC method, diagnostic, install/uninstall, reboot, reprovision, factory reset, backup/restore, download/upload, update software, set attributes) on multiple devices grouped by manufacturer and model.

A campaign is described by an UpdateGroup structure containing:

  • Activation settings (online-only, stop-on-fail, failure threshold, push, execution periods)

  • Optional Reactivation settings (recurrence and termination rules)

  • One or more Configs — per-model task sets selecting target devices by All, Condition (existing filter view) or Individual serial numbers

  • Optional global execution Period and Random count

  • ScheduledStart — campaign scheduled start time

The lifecycle of a campaign is:

Diagram

Conditions used by campaigns with SourceType=Condition are managed independently via CreateGroupUpdateCondition / DeleteGroupUpdateCondition.

2. Common Request Fields

All Group Update endpoints inherit the standard authentication envelope from BaseRequest:

Field Type Description

Creator

string

API user name

AppId

string

Application identifier

CreatorPassword

string

API user password

For brevity these fields are omitted from per-endpoint request examples below.

3. Base URL

All endpoints live under the /api path of the Northbound API service, e.g. http://<server>/iot-webservice/api/CreateGroupUpdate.

The full per-method JSON schemas (including all nested TaskDto variants and their fields) are available in the interactive Swagger UI at http://<server>/iot-webservice/swagger-ui/index.html.

4. CreateGroupUpdate

Create a new Group Update campaign.

HTTP Method

PUT

URL

/api/CreateGroupUpdate

4.1. Behavior

  • Request is delegated to ACS via the FT ACS API client; on ACS error the call fails with 204 / ACS_EXCEPTION.

  • On success the campaign is persisted in ACS and the ID of the newly created campaign (last record in update_group table) is returned in GroupUpdateTaskID.

  • The campaign is created in inactive state. Use GroupUpdateActivate to start it.

  • Activation is required and defines online-only execution, stop-on-fail behavior, failure threshold, push flag and execution periods.

  • Reactivation is optional; when present it defines recurrence (Minutely/Hourly/Daily/Weekly/Monthly/Yearly) and termination (EndsNever, EndsOn, or EndsAfter). Exactly one repeat option and exactly one end condition must be specified.

  • Configs[] defines per-model task sets. SourceType controls the target audience:

    • All — all devices of the given manufacturer/model;

    • Condition — devices matching the referenced ConditionID (created via CreateGroupUpdateCondition);

    • Individual — devices listed by serial number in Sn[].

  • At least one task (TasksList) is required per Config.

4.2. Request Fields

Field Type Required Description

UpdateGroup.Name

string (1-255)

yes

Campaign name

UpdateGroup.Activation.OnlineOnly

boolean

yes

Update only devices that are currently online

UpdateGroup.Activation.StopOnFail

boolean

yes

Stop the campaign if a task fails

UpdateGroup.Activation.Threshold

integer (0-100)

no

Stop the campaign when this percentage of CPEs fail

UpdateGroup.Activation.Push

boolean

yes

Issue a connection request to each device

UpdateGroup.Activation.Period[]

array (1-2)

no

Execution windows (From/To HH:MM, DevicesAmount, Interval in minutes)

UpdateGroup.Reactivation.StartsOn

ISO-8601

yes (within Reactivation)

Reactivation start time

UpdateGroup.Reactivation end condition

EndsNever / EndsOn / EndsAfter

exactly one

Reactivation termination rule

UpdateGroup.Reactivation repeat

RepeatMinutely (1-59) / RepeatHourly (1-23) / RepeatDaily (1-31) / RepeatWeekly (array of 1-7) / RepeatMonthly (1-12) / RepeatYearly

exactly one

Reactivation recurrence rule

UpdateGroup.Reactivation.ReactivateOnlyFailed

boolean

yes

Reactivate only for CPEs that failed previously

UpdateGroup.Configs[].Manufacturer

string

yes

Target manufacturer

UpdateGroup.Configs[].ModelName

string

yes

Target model

UpdateGroup.Configs[].SourceType

enum

yes

All, Condition or Individual

UpdateGroup.Configs[].ConditionID

integer

when SourceType=Condition

Reference to an existing condition view

UpdateGroup.Configs[].Sn[]

array

when SourceType=Individual

Serial numbers of target devices

UpdateGroup.Configs[].TasksList[]

array (min 1)

yes

Tasks to execute. Supported taskType values are listed in Supported Task Types

UpdateGroup.Period[]

array (1-2)

no

Global execution windows

UpdateGroup.Random

integer (>= 1)

no

Randomization count

UpdateGroup.ScheduledStart

ISO-8601

yes

Campaign scheduled start time

4.3. Supported Task Types

The taskType enum accepts: SET_VALUE_TASK, GET_TASK, RPC_METHOD_TASK, DIAGNOSTIC_TASK, INSTALL_TASK, REBOOT_TASK, RE_PROVISION_TASK, FACTORY_RESET_TASK, BACKUP_TASK, RESTORE_TASK, DOWNLOAD_TASK, SET_ATTRIBUTES_TASK, UNINSTALL_TASK, UPDATE_SOFTWARE_TASK, UPLOAD_TASK.

Each task supports optional TaskConditions (EQUAL, NOT_EQUAL, LESS, LESS_EQUAL, GREATER, GREATER_EQUAL, CONTAINS, STARTS_WITH, REGEXP) and a task-specific payload (Parameters, RPCMethod, InstallFile, File, UpdateFile, DeleteFile, cpeParamAttributeList, etc.). The full payload schemas are available in Swagger UI.

4.4. Request Example

{
  "UpdateGroup": {
    "Name": "Firmware Update Q1 2025",
    "Activation": {
      "OnlineOnly": true,
      "StopOnFail": true,
      "Threshold": 100,
      "Push": true,
      "Period": [
        { "From": "11:00", "To": "12:00", "DevicesAmount": 100, "Interval": 1 }
      ]
    },
    "Reactivation": {
      "StartsOn": "2026-07-23T15:15:54.259",
      "EndsAfter": 5,
      "RepeatDaily": 1,
      "ReactivateOnlyFailed": true
    },
    "Configs": [
      {
        "Manufacturer": "Friendly",
        "ModelName": "FT-1000",
        "SourceType": "All",
        "TasksList": [
          {
            "taskType": "REBOOT_TASK",
            "TaskConditions": { "TaskCondition": [] }
          }
        ]
      }
    ],
    "ScheduledStart": "2026-07-23T15:15:54.259"
  }
}

4.5. Response Fields

Field Type Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

GroupUpdateTaskID

integer

Identifier of the created campaign

4.6. Response Example

{
  "ErrorCode": 100,
  "Message": "",
  "GroupUpdateTaskID": 42
}

5. DeleteGroupUpdate

Delete an existing Group Update campaign.

HTTP Method

PUT

URL

/api/DeleteGroupUpdate

5.1. Behavior

  • Verifies that the campaign exists in update_group table; returns UPDATE_GROUP_NOT_FOUND when absent.

  • Delegates physical deletion to ACS via the FT ACS API client; on ACS error the call fails.

  • Deletion removes the campaign together with all associated configs, conditions linkage and pending executions on ACS side. Already-executed tasks recorded on devices are not rolled back.

  • This operation is irreversible.

5.2. Request Fields

Field

Type

Required

Description

GroupUpdateTaskID

integer (>0)

yes

Identifier of the campaign to delete

5.3. Request Example

{ "GroupUpdateTaskID": 42 }

5.4. Response Fields

Field

Type

Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

6. CreateGroupUpdateCondition

Create a reusable Condition (filter view) that selects target devices for Group Update campaigns. The condition is persisted as a view of type GroupUpdateView together with its column-condition tree, and its ID can later be referenced from UpdateGroup.Configs[].ConditionID when SourceType=Condition.

HTTP Method

PUT

URL

/api/CreateGroupUpdateCondition

6.1. Behavior

  • Persists a ViewEntity of type GroupUpdateView scoped to the creator’s domain (or super-domain when domain is null/0).

  • The Name must be unique within the domain for views of this type; otherwise PARAMETER_NOT_UNIQUE is returned.

  • Saves the condition tree (logic, columnKey, compare, conditionString, etc.) in column_condition table. Existing conditions not present in the request are removed.

  • Builds an SQL specification from the supplied conditions and stores the generated query and its parameters in custom_view_query / custom_view_query_parameter so the condition can be applied to device selection later.

  • Returns the persisted view identifier as GroupUpdateConditionID.

6.2. Request Fields

Field Type Required Description

Condition.Name

string (1-255)

yes

Condition (view) name, unique within domain

Condition.Configs[]

array (non-empty)

yes

Filter tree: column keys, comparison operators, values, AND/OR logic, optional nested items

6.3. Response Fields

Field

Type

Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

GroupUpdateConditionID

integer

Identifier of the created condition view

7. DeleteGroupUpdateCondition

Delete an existing Condition.

HTTP Method

PUT

URL

/api/DeleteGroupUpdateCondition

7.1. Behavior

  • Looks up the view by ID and verifies that its type is GroupUpdateView; otherwise UPDATE_GROUP_NOT_FOUND is returned.

  • Removes the view from view table and cascades deletion of all related rows in column_condition.

  • Campaigns that referenced this condition via Configs[].ConditionID will no longer resolve devices through it; running ACS execution is not affected, but future re-selection will fail until the campaign is reconfigured.

7.2. Request Fields

Field

Type

Required

Description

GroupUpdateConditionID

integer

yes

Identifier of the condition view to delete

7.3. Response Fields

Field

Type

Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

8. ViewGroupUpdateList

Return a flat list of all Group Update campaigns.

HTTP Method

POST

URL

/api/ViewGroupUpdateList

8.1. Behavior

  • Reads all rows from update_group table; no filtering by status, creator or domain is applied.

  • Order of results is the natural persistence order returned by the repository.

  • Each entry contains only the campaign identifier and name; use ViewGroupUpdateDetails to retrieve the full configuration of a specific campaign.

  • This operation does not contact the device or trigger ACS execution.

8.2. Request Fields

Only the common authentication envelope (Creator, AppId, CreatorPassword).

8.3. Response Fields

Field Type Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

GroupUpdateTasks[]

array

Campaign list

GroupUpdateTasks[].id

integer

Campaign identifier

GroupUpdateTasks[].name

string

Campaign name

9. ViewGroupConditionList

Return a flat list of all Conditions (filter views).

HTTP Method

POST

URL

/api/ViewGroupConditionList

9.1. Behavior

  • Reads all views of type GroupUpdateView via ViewRepository#getGroupUpdateConditions.

  • Results are sorted alphabetically by Name (case-sensitive).

  • Each entry contains only identifier and name; use ViewGroupUpdateConditionDetails to retrieve the full condition tree.

9.2. Request Fields

Only the common authentication envelope.

9.3. Response Fields

Field Type Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

GroupUpdateConditions[]

array

Condition list

GroupUpdateConditions[].id

integer

Condition identifier

GroupUpdateConditions[].name

string

Condition name

10. ViewGroupUpdateDetails

Return the full configuration of a specific Group Update campaign.

HTTP Method

POST

URL

/api/ViewGroupUpdateDetails

10.1. Behavior

  • Looks up the campaign in update_group table by GroupUpdateTaskID; returns UPDATE_GROUP_NOT_FOUND when absent.

  • Maps the persisted UpdateGroup entity (with its actions, conditions and serial-number lists) to the API UpdateGroup structure.

  • This operation does not contact the device or trigger ACS execution; it returns the stored configuration only.

  • Field values reflect the state at request time.

10.2. Request Fields

Field

Type

Required

Description

GroupUpdateTaskID

integer (>0)

yes

Identifier of the campaign to fetch

10.3. Response Fields

Field Type Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

UpdateGroup

UpdateGroup

Full campaign configuration — same shape as CreateGroupUpdate request body

11. ViewGroupUpdateConditionDetails

Return the full configuration of a specific Condition.

HTTP Method

POST

URL

/api/ViewGroupUpdateConditionDetails

11.1. Behavior

  • Looks up the view by ID; if not found or its type is not GroupUpdateView, DEVICE_PROFILE_NOT_FOUND is returned.

  • Maps the persisted ViewEntity to GroupUpdateView and rebuilds the full hierarchical conditions tree from column_condition (parent/child relations).

  • Localization id is fixed to EN for condition labels.

11.2. Request Fields

Field

Type

Required

Description

GroupUpdateConditionID

integer (>0)

yes

Identifier of the condition view to fetch

11.3. Response Fields

Field Type Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

Condition

GroupUpdateCondition

Full condition configuration with hierarchical filter tree

12. GroupUpdateActivate

Start execution of a previously created Group Update campaign.

HTTP Method

PUT

URL

/api/GroupUpdateActivate

12.1. Behavior

  • Delegates the start command to ACS via FtAcsApiClient#startUpdateGroup; on ACS error the call fails with ACS_EXCEPTION.

  • Activation transitions the campaign from inactive/paused/stopped state to running. The exact transition rules are enforced by ACS.

  • For campaigns with ScheduledStart in the future, ACS schedules execution rather than starting immediately.

12.2. Request Fields

Field

Type

Required

Description

GroupUpdateTaskID

integer (>0)

yes

Identifier of the campaign to activate

12.3. Response Fields

Field

Type

Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

13. GroupUpdatePause

Pause execution of a running Group Update campaign.

HTTP Method

PUT

URL

/api/GroupUpdatePause

13.1. Behavior

  • Delegates the pause command to ACS via FtAcsApiClient#pauseUpdateGroup; on ACS error the call fails with ACS_EXCEPTION.

  • Pause transitions the campaign from running to paused state. The exact transition rules are enforced by ACS.

  • Pause does not delete already-queued tasks; subsequent activation continues from the current execution position.

13.2. Request Fields

Field

Type

Required

Description

GroupUpdateTaskID

integer (>0)

yes

Identifier of the campaign to pause

13.3. Response Fields

Field

Type

Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

14. GroupUpdateStop

Stop a Group Update campaign.

HTTP Method

PUT

URL

/api/GroupUpdateStop

14.1. Behavior

  • Delegates the stop command to ACS via FtAcsApiClient#stopUpdateGroup; on ACS error the call fails with ACS_EXCEPTION.

  • Stop transitions the campaign from running/paused to stopped state. The exact transition rules are enforced by ACS.

  • Stop does not delete the campaign or its configuration; use DeleteGroupUpdate to remove the campaign entirely.

  • In-flight device interactions already dispatched by ACS may still complete; only further task dispatching is halted.

14.2. Request Fields

Field

Type

Required

Description

GroupUpdateTaskID

integer (>0)

yes

Identifier of the campaign to stop

14.3. Response Fields

Field

Type

Description

ErrorCode

integer

100 success, 20X failed

Message

string

Error description

15. Errors

All Group Update endpoints return the standard Northbound error envelope (see API & Integration → Error Response Format). The most common codes relevant to Group Update are:

Code Enum Trigger

100

SUCCESS

Operation succeeded

200

FAIL

Generic failure

203

INCORRECT_REQUEST

Request validation failed (e.g. missing required field, non-unique condition name, invalid reactivation combination)

204

GENERAL

Unexpected server-side error (ACS_EXCEPTION is reported with this code together with the upstream message)

205

NO_ACS

ACS is unreachable

Specific service-level errors (visible in Message):

Error Meaning

UPDATE_GROUP_NOT_FOUND

GroupUpdateTaskID or condition view.id does not exist, or the view is not of type GroupUpdateView

PARAMETER_NOT_UNIQUE

Condition (view) name already exists within the domain

DEVICE_PROFILE_NOT_FOUND

Condition view requested in ViewGroupUpdateConditionDetails is missing or not a GroupUpdateView

ACS_EXCEPTION

ACS rejected the operation; upstream error is propagated in Message