Skip to main content

[DRAFT] Process: Store and Use Apteryx Online Capture Settings in the Cloud

Michael Satterfield
Updated

Overview

This process describes how Apteryx users and administrators store device plugin settings in the cloud and apply them in the Capture application. It consolidates behavior across the child work items of epic AIR-489, including API endpoints, Apteryx administration UI, and Capture client integration.

Endpoint: POST /api/plugins/settings/{fileid}/ (Apteryx Online Capture-2130)

  • Body includes siteId and settingsJson (the JSON payload).

  • Validation (400) if siteId ≤ 0 or null, or settingsJson is empty/invalid JSON.

    • 201 Created: a new record was added.

    • 204 No Content: an existing record was updated.

    • 500: unexpected errors.

Screenshot: Successful POST to settings API

The following image confirms a successful POST for FileId Simulator_Simulator returning 201.

3) Storage and schema (platform)

Uploaded settings are stored centrally per site and FileId (Apteryx Online Capture-2151).

  • PluginSettings

    • Columns: Id (PK, bigint), SiteId (bigint, not null), FileId (varchar(100), not null), CreateDate (datetime, default UTC), SettingsData (JSON, not null)

    • Unique constraint on (SiteId, FileId)

Screenshot: Database table structure

4) Detect and apply cloud settings in Capture (operator)

Operators apply cloud settings from within the Capture Device Settings screen (Apteryx Online Capture-2129).

  • Validate settings exist for device

    • Hub calls HEAD /api/plugins/settings/{fileid}/sites/{siteid}/ (Apteryx Online Capture-2176) via /cloudsettingsenabled.

    • If 200 OK, the “Apply Cloud Settings” button is shown; 404 hides the button.

  • Download settings for device

    • Hub calls GET /api/plugins/settings/{fileid}/sites/{siteid}/ (Apteryx Online Capture-2128) via /cloudsettingsdownload.

    • Capture saves the returned JSON locally as {FileId}.json (same path and conventions as manual Save).

    • The UI refreshes to reflect the applied settings.

Acceptance tests passed for: showing the button when settings exist and successfully applying the cloud settings, validated on Capture 7.11.0-beta.14 (per Apteryx Online Capture-2129 comment).

API reference (for admins and integrators)

HEAD plugin settings

  • Endpoint: HEAD /api/plugins/settings/{fileid}/sites/{siteid}/

  • Auth: Policies.CaptureApp

    • 200: settings exist

    • 404: not found

    • 400: validation failure (bad siteId or invalid fileId)

    • 500: unexpected error

    • siteId must be > 0

    • fileId may include letters, numbers, underscore, and dash only

GET plugin settings

  • Endpoint: GET /api/plugins/settings/{fileid}/sites/{siteid}/

  • Auth: Policies.CaptureApp

  • Response: JSON payload of the settings file (200), or 404/400/500 as above.

POST plugin settings

  • Endpoint: POST /api/plugins/settings/{fileid}/

  • Auth: Policies.ApteryxAdminJwt (requires admin claim; Apteryx Online Capture-2133)

  • {
  "siteId": 123,
  "settingsJson": { /* plugin settings JSON */ }
}

    • 201: record created

    • 204: record updated

    • 400: invalid siteId or settingsJson (including non-JSON)

    • 500: unexpected error

Operating procedures

Procedure A: Create cloud settings file (Apteryx Catpure Admin)

  1. Open Apteryx and sign in

  2. Navigate to Capture Settings → Device Settings Edit Screen

  3. Select the device from the drop down and update necessary settings

  4. Save the changes

Procedure B: Upload cloud settings (Apteryx Admin)

  1. Open Apteryx and sign in with a Site Admin or Capture role.

  2. Navigate to Capture Settings → Plugin Settings Edit Screen.

  3. Navigate to the setting file created in Procedure A

  4. Upload the file

    • On success you should see a confirmation notice; the settings were saved or updated.

Procedure C: Apply cloud settings in Capture (Operator)

  1. Open Apteryx and sign in

  2. Navigate to Capture Settings → Device Settings Edit Screen

  3. Select the device whose settings were uploaded to the cloud.

  4. Click the Apply Cloud Settings button

    • If you do not see the button, verify with your admin that settings were uploaded for your site.

  5. Review and if necessary, save any workstation specific changes

Troubleshooting and validation

  • Button not visible in Capture

    • Confirm Apteryx upload completed successfully for the same Site and FileId.

    • HEAD request must return 200. Check hub connectivity and authorization (Policies.CaptureApp).

    • Verify FileId uses only allowed characters and matches Capture’s naming convention.

  • POST rejected (400)

    • Ensure siteId is a positive integer.

    • Provide well-formed JSON in settingsJson.

  • GET returns 404

    • No record stored for the specific Site + FileId combination. Re-upload or correct parameters.

  • Auth failures

    • POST requires ApteryxAdminJwt with admin claim (Apteryx Online Capture-2133).

    • GET/HEAD require Policies.CaptureApp.

Security and platform notes

  • Managed identity and KeyVault configuration was completed for Capture API app services (DEVOP-3741) to securely access secrets.

  • The settings store enforces uniqueness per Site + FileId to prevent duplicates.

FAQs

Use the exact identifier that Capture expects for the device’s settings file. The downloaded file is saved as {FileId}.json, so ensure your upload filename matches this convention (e.g., Simulator_Simulator.json).

No. Only Site Admin or Capture roles can access the Apteryx Plugin Settings Edit Screen and perform uploads. The POST endpoint requires ApteryxAdminJwt with an admin claim.

The POST endpoint returns 204 if the existing Site + FileId record is updated. Capture clients will receive the updated JSON the next time operators click “Download Cloud Settings.”

References

Release notes highlights:

  • Capture 7.11.0 includes the Device Settings UI button to apply cloud settings (per Apteryx Online Capture-2129).

  • Apteryx 6.4 introduces the admin screen for uploading plugin settings (Apteryx-3151).