Retrieving and Saving Settings

• Retrieving Settings
  • Return Data Format
  • Download All Current Settings
  • Config Difference Tool
• Saving Changes

Retrieving Settings

General Identity Panel settings are included with the home page HTML as a JSON structure embedded in the HTML. This payload has all of the standard settings that are available to all authenticated users, including: Theme, Licenses, Translations, Views, Dashboards, and PageDefaults.

All settings including the above can also be retrieved from /api/settings or /api/settings/{path} where {path} represents the type of setting being fetched.

To retrieve the enumerated settings above simply being an authenticated user is sufficient. Other settings require specific Read|<type> permissions. These settings include:

• AccessPanel
• Email
• Extensions
• Joins
• Providers
• Roles
• Schedules (Environment Variables)
• ServicePanel
• UpliftSettings

Return Data Format

{
  "Providers": { // TypeName, e.g. "Providers" or "Email"
    "$type": "SoftwareIDM.PanelModel.Models.Providers, SoftwareIDM.PanelModel",
    ...
  },
  ...
}

Download All Current Settings

As of Identity Panel v6.2 a Download All Current Settings button has been included on the Settings History page.  This is a shortcut alternative to downloading each of the configuration sections separately via the corresponding Settings menu, which would achieve a similar outcome.

This downloads a single ZIP file which contains the complete set of settings files described in the above section, along with the following additional items (.json extension):

• A Report_<guid> file per installed report definition
• A Schedule_<guid> file per configured schedule definition

This file export mechanism is designed for migrating Identity Panel configuration across all applications from one environment to another, or saving to a source control library (e.g., GIT repository).  Each file can then be imported (one file at a time) to a target Identity Panel instance via the corresponding Settings menu's upload button on the floating toolbar.  There presently is no facility to import all settings in a single action.

Note that the import of the Schedules (Environment Variables) file is a special case, whereby only settings not already present in the target will be overridden.  This is a safeguard against overwriting configuration in higher environments with data applicable only to a lower one, e.g. server names and aliases.

Config Difference Tool

New to Identity Panel v6.3 is a Choose Settings for Diff feature.

Clicking on the button will allow selection of a .json file containing configuration for import to Identity Panel, such as those downloaded via the above mechanism,

This product feature is designed to provide the following new capabilities:

• deploying promoted configuration to a higher environment selectively, such as individual rules or rule sets in HyperSync, or individual provider configurations.
• deploying selectively from a source control archive.
• back-porting configuration from a higher environment, e.g., where changes have been made in Production which are not possible in a lower one because of the absence of a connected system.
• working in a multi-developer lower environment where there is a high risk of configuration overwriting by one person over changes made by another (a 30 second delay is enforced before successive changes being imported to safeguard against inherent latency issues).

Saving Changes

General JSON settings may be saved by POST request to /api/settings or /api/settings/{path} where the path represents a particular type of settings, e.g. providers, pagedefaults, etc.

Saving settings requires the Write|JsonSettings permission.

NOTE: Even though the Writer role has the Write|* permission, this role is explicitly excluded from making changes to settings, Schedule objects, MIM Test action configuration, or Uplift settings. This allows separation of duty for Panel Service roles and admin roles.

It is possible to POST the complete set of all settings data, or individual settings sections may be posted. The settings JSON upload feature works by posting to this UI using the REST API feature which copies the first uploaded file to the body stream.

When uploading multiple settings types at once, each setting section is authorized separately in case scoping rules have been applied to only allow the role to submit particular settings.

A successful submission will return a 204 No Content result.

All settings changes are also recorded in version control history (which uses a git repository).

Documenting valid settings JSON for posting to the API is beyond the scope of this documentation. Settings documents may be obtained using browser tools by inspecting settings.attributes

A json payload may be obtained by running settings.attributes.<TypeName>.toJSON();