Custom file lets you upload your own configuration profile to apply settings that no built-in Factorial IT control covers. It accepts each platform's native format on macOS, iOS/iPadOS, Windows and Android. On Windows you can produce the SyncML file from the Policy CSP catalogue with CSP Builder.

Feature/Functionality

Overview

Each platform takes its own file format:

How to use

1. Go to MDM > Controls > Add new control and choose Custom file.
2. Add your configuration. Upload your configuration file: it reaches devices through MDM, like any other control.
   • On macOS and iOS/iPadOS you can paste the profile rather than upload a file. Choose Paste content and paste the XML of a configuration profile, or the JSON of a DDM declaration, into Profile content. When the content is valid, the console shows its type and the file name it will be saved as: the profile's PayloadIdentifier plus .mobileconfig, or the declaration's Identifier plus .json. Signed profiles cannot be pasted: upload the .mobileconfig file instead.
   • On Windows you can build the file with CSP Builder instead of writing it yourself. See Windows below.
   Factorial IT does not check the settings inside a custom file. On Windows it only checks that the top-level elements are <Replace>, <Add> or <Exec>. Make sure the configuration is right before you deploy it: a broken or conflicting profile can make devices behave in unexpected ways.
3. Give the control a clear name, so you can find it later.
4. Choose where the control applies: all devices, specific device groups, or a custom target.

macOS

macOS profiles (.mobileconfig) are XML files, signed or unsigned, sent as MDM payloads. Some configuration payloads can also be sent as .json.

Recommended tools to build profiles:

• iMazing Profile Editor: free, made for creating and editing .mobileconfig files.
• Apple Configurator: from the Mac App Store.

Typical uses are custom certificate payloads, VPN profiles and per-app VPN settings.

iOS / iPadOS

iPhone and iPad use the same .mobileconfig format as macOS.

Windows

Windows files use SyncML, which maps to the Windows MDM CSPs (Configuration Service Providers, the settings Windows exposes to MDM). You can set any Windows MDM policy that the built-in Factorial IT controls do not cover.

Start and end the XML with <Replace> or <Add>. Leave out the SyncML header and footer lines.

Build the file with CSP Builder

The recommended way to create the file is CSP Builder, a free tool. It produces the SyncML from Microsoft's Policy CSP catalogue, so there is no XML to write by hand.

1. Click Create in CSP Builder. The button sits below the upload area of the Windows Custom file control, until a file has been added. CSP Builder opens in a new tab.
2. Choose the settings you need and set their values. When a setting has a State, pick Enabled or Disabled. Not Configured exports a <Delete> command, and the control is rejected when you save it.
3. Leave the export format on Fleet compatible. It is the default in the Export section and the only format accepted. The other formats wrap the commands in <SyncML> or <SyncBody>, which are also rejected when you save the control.
4. Click Load on Factorial IT. A new tab opens on a Windows Custom file control with the file already added. Finish the setup there: name the control, choose the targeting and click Save.

CSP Builder can also load ADMX templates. With the default format, policies from a loaded template only apply after the template has been ingested on the device, and the file does not include that ingestion step. Contact our team at support@factorial.it before you deploy settings from an ADMX template.

Example: set the desktop and lock screen images

Step 1. Allow the Personalization CSP on Windows Pro:

<Replace>
  <!-- Allows Personalization CSPs to be deployed on non-Enterprise versions of Windows.
       Setting this value to true triggers the action to configure a device as education environment.
       Thorough testing is crucial to ensure it does not disrupt workflows or create compatibility issues. -->
  <Item>
    <Meta>
      <Format xmlns="syncml:metinf">bool</Format>
    </Meta>
    <Target>
      <LocURI>./Vendor/MSFT/SharedPC/SetEduPolicies</LocURI>
    </Target>
    <Data>true</Data>
  </Item>
</Replace>

Step 2. Set the desktop and lock screen images. The Personalization CSP works on Windows Enterprise and Education. On Windows Pro it only works once SetEduPolicies in the SharedPC CSP is set, as in step 1.

<Replace>
  <CmdID>1</CmdID>
  <Item>
    <Target>
      <LocURI>
        ./Vendor/MSFT/Personalization/LockScreenImageUrl
      </LocURI>
    </Target>
    <Meta>
      <Format xmlns="syncml:metinf">chr</Format>
      <Type>text/plain</Type>
    </Meta>
    <Data> … your URL here … </Data>
  </Item>
</Replace>
<Replace>
  <CmdID>2</CmdID>
  <Item>
    <Target>
      <LocURI>
        ./Vendor/MSFT/Personalization/DesktopImageUrl
      </LocURI>
    </Target>
    <Meta>
      <Format xmlns="syncml:metinf">chr</Format>
      <Type>text/plain</Type>
    </Meta>
    <Data> … your URL here … </Data>
  </Item>
</Replace>

SharedPC/SetEduPolicies puts the device into an education configuration. Try it on a few devices before rolling it out widely.

Android

Android files use JSON to send managed configurations to Android Enterprise devices. They are mostly used to configure work apps that support managed app configuration.

Change or switch off the control

Open the control from MDM > Controls to edit or disable it. To change the configuration, upload the file again with the new settings or, on macOS and iOS/iPadOS, paste the updated content. Paste content always opens empty, so paste the full profile. Disabling stops enforcement. It does not remove settings already applied on devices.

Troubleshooting and FAQ

Troubleshooting

• The file upload fails.
  • Check the file uses the right format for the chosen operating system.
  • Check the file is not corrupted or empty.
  • macOS profiles must be valid XML. Check the file with plutil -lint profile.mobileconfig.
• The console rejects the pasted content.
  • If the XML is not valid, check that you copied the whole profile, all the way to </plist>. Where possible, the message gives the line with the error.
  • The XML must be an Apple profile: its root is <plist>, with a <dict> inside.
  • For a DDM declaration, check that you copied the whole JSON.
  • If the content comes from a signed profile, upload the .mobileconfig file instead. Factorial IT extracts the XML from it.
• A Windows file is rejected when you save the control. The top-level elements must be <Replace>, <Add> or <Exec>. A <Delete> command (from a setting left on Not Configured in CSP Builder) or a <SyncML> or <SyncBody> wrapper is refused.
• Devices behave unexpectedly after deploying a custom file. The profile may be invalid or clash with another one. Factorial IT does not validate the contents, so review the file.
• The desktop or lock screen image does not change on Windows Pro. The Personalization CSP only works on Pro once SetEduPolicies is set. Deploy that setting first.

FAQ

1. Does it work on Linux?
   No. It supports macOS, iOS/iPadOS, Windows and Android.
    
2. Does Factorial IT check my file?
   Not the settings themselves. On Windows it only checks the top-level elements. You are responsible for making sure the configuration is correct.
    
3. How do I update the configuration?
   Open the control from MDM > Controls and upload the file again with the new settings. On macOS and iOS/iPadOS you can paste the full updated content instead.
    
4. Can I paste a profile instead of uploading a file?
   Yes, on macOS and iOS/iPadOS, unless the profile is signed. Signed profiles must be uploaded as a .mobileconfig file.
    
5. Do I have to write the Windows XML by hand?
   No. CSP Builder generates it from Microsoft's Policy CSP catalogue.
    
6. Do I include the SyncML header in Windows files?
   No. Start and end the XML with <Replace> or <Add>.