Managed deployment

Porticol reads a policy when it starts. The policy can preset the server people sign in to, require single sign-on, turn off workspaces on the computer and exporting, hold crash and usage reports on or off, and pin the update channel. In Settings, every setting the policy holds shows "Managed by your organisation" and can't be changed.

Each platform keeps the policy where its own device management puts it:

Platform	Where	Written by
macOS	`/Library/Managed Preferences/com.porticol.desktop.plist`	A configuration profile
Windows	`HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Porticol`	Group Policy, or the MSI's install properties
Linux	`/etc/porticol/policy.json`	Your configuration management

No policy means an unmanaged computer: every choice is the person's own.

Keys

The keys have the same names on every platform.

Key	Type	Effect
`ServerUrl`	text	The only server Porticol signs in to, such as `https://porticol.example.com`. The sign-in form shows it read-only. It must be an `https://` address.
`RequireSso`	true or false	Signing in has to go through your organisation's single sign-on. A sign-in the browser made with a password is refused, and the device it registered is removed from the account again.
`LocalWorkspaces`	true or false	`false` stops Porticol from copying a server's workspace into a new workspace on the computer.
`Export`	true or false	`false` turns off exporting collections, environments, run and performance reports, and backing up.
`CrashReports`	true or false	Holds crash reports on or off. Left out, the person chooses.
`UsageReports`	true or false	Holds usage reports on or off. Left out, the person chooses.
`UpdateChannel`	`stable` or `beta`	The channel Porticol updates from.

Booleans are <true/> and <false/> in a property list, true and false in JSON, and a DWORD in the registry, where any value other than 0 is on. Text is <string> in a property list and REG_SZ in the registry. Keys Porticol doesn't know are ignored, so one policy works across releases.

RequireSso needs a Porticol server that tells the app how the browser signed in. A server from before that release never does, so every sign-in to it is refused while the key is on.

A policy Porticol can't apply

If the policy is there but a key has the wrong type or value, Porticol starts but doesn't open any data. It shows where the policy is and which key is wrong, and asks the person to contact IT:

Porticol can't apply your organisation's policy in /etc/porticol/policy.json: Export must be true or false (a DWORD in the registry). Ask your IT administrator to correct it.

Porticol never ignores a policy it can't read, so a typo can't quietly turn a lock off. Check a new policy on one computer before you roll it out.

macOS

With a configuration profile

Deliver a profile with a custom settings payload (com.apple.ManagedClient.preferences) for the domain com.porticol.desktop. Most device management tools call this "Custom settings" or "Application & custom settings". The payload holds the keys above:

<key>PayloadContent</key>
<dict>
  <key>com.porticol.desktop</key>
  <dict>
    <key>Forced</key>
    <array>
      <dict>
        <key>mcx_preference_settings</key>
        <dict>
          <key>ServerUrl</key>
          <string>https://porticol.example.com</string>
          <key>RequireSso</key>
          <true/>
          <key>Export</key>
          <false/>
        </dict>
      </dict>
    </array>
  </dict>
</dict>

macOS writes the settings to /Library/Managed Preferences/com.porticol.desktop.plist, which is where Porticol reads them.

Windows

With Group Policy or the registry

Write the keys as values under HKEY_LOCAL_MACHINE\SOFTWARE\Policies\Porticol:

reg add HKLM\SOFTWARE\Policies\Porticol /v ServerUrl /t REG_SZ /d https://porticol.example.com /f
reg add HKLM\SOFTWARE\Policies\Porticol /v RequireSso /t REG_DWORD /d 1 /f
reg add HKLM\SOFTWARE\Policies\Porticol /v Export /t REG_DWORD /d 0 /f

With the MSI's install properties

The MSI writes the same values when you pass these properties. It installs for every user on the computer, so it runs elevated.

Property	Writes
`PORTICOL_SERVER_URL`	`ServerUrl`
`PORTICOL_REQUIRE_SSO`	`RequireSso` (1 or 0)
`PORTICOL_LOCAL_WORKSPACES`	`LocalWorkspaces` (1 or 0)
`PORTICOL_EXPORT`	`Export` (1 or 0)
`PORTICOL_CRASH_REPORTS`	`CrashReports` (1 or 0)
`PORTICOL_USAGE_REPORTS`	`UsageReports` (1 or 0)
`PORTICOL_UPDATE_CHANNEL`	`UpdateChannel` (`stable` or `beta`)

msiexec /i Porticol-1.2.0-x64.msi /qn PORTICOL_SERVER_URL=https://porticol.example.com PORTICOL_REQUIRE_SSO=1 PORTICOL_EXPORT=0

A property you leave out writes nothing. The values stay when Porticol is upgraded or removed, as Group Policy's do; change or delete them with Group Policy or reg. Only the MSI takes these properties. The NSIS installer installs for one person and has none.

Linux

Write /etc/porticol/policy.json, owned by root and readable by everyone (mode 0644):

{
  "ServerUrl": "https://porticol.example.com",
  "RequireSso": true,
  "LocalWorkspaces": false,
  "Export": false,
  "CrashReports": false,
  "UsageReports": false,
  "UpdateChannel": "stable"
}

What people see

Settings shows the held settings with a lock and "Managed by your organisation": the crash and usage report switches, the update channel, the server address on the sign-in form, and Back up when exporting is off.
An export or a copy of a workspace to the computer that the policy turns off is refused with "Your organisation turned off" and what it turned off.
A sign-in to any server but ServerUrl is refused, naming the server the computer signs in to.

Porticol reads the policy once, as it starts. People pick up a changed policy the next time they open Porticol.