Mosyle Device Integration Setup

The Mosyle integration allows IT teams to view all devices and users within their organization. With this data within FMX, these IT teams can create tickets on behalf of staff/students and audit what devices they have available.

This article will explain how to set up your Mosyle integration with FMX for your devices. These instructions are for users who have purchased the Mosyle integration and have already had the integration added to their FMX site.
If you are interested in adding this integration, please contact your FMX account manager. Once an FMX team member contacts you, you can begin the process with the following steps. 

**The Mosyle device integration needs to be set up before user integration is set up.***

Business or Manager API?

Mosyle has two products, one geared towards businesses and the other geared towards schools. These are called the Business API and the Manager API, respectively. This integration supports both, but you’ll want to ensure you know which one you’re using while configuring your integration. If you log in to Mosyle using a URL like “https://mybusiness.mosyle.com,” then you are using the Business API. Otherwise, if you log in to Mosyle using a URL like “https://myschool.mosyle.com”, you are using the Manager API.

These two APIs are mostly the same, but there are differences. The most significant difference is that the Business API does not support accounts. To use Mosyle accounts, you must utilize the Manager API and have at least one account in Mosyle. Using accounts is optional, even for the Manager API.

Some fields are also only available from one API and not the other. These are talked about in more detail below.

Create Mosyle Access Token

*This is the same token you will need for the user setup. 

Before starting the integration setup in FMX, you must create an access token in Mosyle. To do this in your Mosyle site, go to My District > Integrations > Activate New Integration > Add new token. You need to use "Restricted by Server IP" and put these two IP addresses in: 3.132.205.2043.139.185.169

After you select save, you can proceed to the next steps. You will need this token in the "Configuration" section of the integration set-up process. 

Add Equipment Types

Please ensure you have the equipment types in FMX updated for the Mosyle OS groups you would like them to map to. If they are not then you will have to go back in to reconfigure the integration for those types to be an option in prismatic.  See this support center article on how to add equipment types. 

Add an Integration User

You will need to dedicate a user in FMX that will perform the necessary actions taken by the integration. It is recommended to create a new, "fake" user for this purpose. This user can be named anything, but something like "Mosyle Integration" is recommended to identity where certain edits and actions in FMX came from. When creating the new user, it is important to keep a note of that user's email and password. The email can be something made up, or a real email that collects notifications related to the integration.
When selecting a user type for this user, you may either set them as an administrator or create a dedicated user type for this purpose.

To create a new user type click the “Admin Settings" in the left sidebar then select the” User Types" tab at the top of the page. You can either select add “User Type” at the top of the page or click the vertical 3 dots next to a user type that may have full access like “FMX Administrator” and click “copy”. Name the user type something identifiable like “FMX Integration”.

For more information on user types go to this support center article.

Next go to the following setting and make sure the user type has the following permissions:

• Building & Resource Access
  • Read - Any
• Equipment Access
  • Create
  • Read - Any
  • Update- Any
  • Retire - Any
  • Permitted Equipment Types Includes All Desired
    • If the user type does not have access to an equipment type you would want to sync with Mosyle then those devices would not sync.

• User & Contact Access
  • Administer
  • Read Users
  • Read Contacts
  • Delete
• Permitted Access to All Desired Custom Fields

Add Custom Fields

Add the required custom fields to your FMX site before starting the integration steps. The custom fields need to be in FMX before the steps are completed so that you can map the correct Mosyle field to the correct FMX field. 

Add the following fields:

• Mosyle Serial Number- add this text custom field for Equipment. Make sure your newly created integration user, and all desired equipment types have access to this custom field. 
• Mosyle udid - add this text custom field for Equipment. Make sure your newly created integration user, and all desired equipment types have access to this custom field. This field is used to assign users in FMX to the device. 

The fields above are required for the integration to work. Additionally, there are optional custom fields you can map over from Mosyle to FMX. See the table below for fields you can add before the integration setup. These fields can be added later.

The FMX custom fields need to be text fields unless otherwise noted in the name of the Mosyle field in parenthesis. These need to have the integration user as a permitted user type. They also need to be available for the equipment types you are syncing with Mosyle. 

* These fields are only available if you have at least one account in Mosyle.

** These fields should be mapped to a date field in FMX.

*** These fields should be mapped to a checkbox in FMX.

**See this support center article for how to add custom fields in FMX**

Go to the Integrations Settings

When the integration has been added to your FMX site, a member of the FMX team will contact you.

In your FMX site, go to your admin settings. Then go to the tab that says “Integrations”. In this section, you will see all of the integrations you have on your FMX. To access your integration to begin the setup process, select the integration you would like to work on. If you do not see the Mosyle integrations, contact your primary contact at FMX.

Mosyle Devices

Go to the integrations settings tab in your admin settings. To set up the Mosyle integration for your devices select “Mosyle Devices" in this tab. To start this process, click the “Reconfigure” button.

1. Authentication

Fill out the following fields in the FMX API Connection section:

• Hostname - this is your FMX hostname. This can be found in the URL of your site and it is the text before “.gofmx.com”. For example: https://fmxschool.gofmx.com/. The bolded text is your hostname.
• Password - this is the password of the FMX integration user you added (see details above)
• API User Email - this is the email address of the integration user you added (see details above)

Next, fill out the fields in the Mosyle Connection field section:

• accessToken
  • See steps above on how to create the token
• Email
  • Email address for your Mosyle account
• Password
  • Password for that Mosyle account
• Mosyle API Base URL
  • See steps above for determining which option you should use for this.

After you have entered in all the information in the authentication fields click the next button. 

2. Device Mapping

In this section,, you will choose which operating systems (OS) you want to include in the integration and their respective equipment type. Only the OS's selected below will be synced with FMX.

Click the "+ Add to OS Mapping" button to start mapping. Then, in the "Mosyle OS" field, you will choose an OS to map to an FMX Equipment Type from the equipment type field.

Choose to "Override Existing Equipment Type" or not by checking the box. When the box is checked, the above equipment type selection will be applied to existing equipment in FMX belonging to this Mosyle OS. Otherwise, they will only be applied to new equipment.

Then, check the box to "Override Existing Building" or not. When the box is checked, the building mapping below will be applied to existing equipment in FMX belonging to this Mosyle OS. Otherwise, it will only be applied to new equipment.

Then, continue this process by selecting "+ Add to Os Mapping".  

In the "Account Mapping" section,, select which accounts you want to include in the integration and their respective building. Only accounts selected below will be synced with FMX. Select the Mosyle Account and match it to the FMX Building from their fields. (This section will only be usable if you are using the Manager API and have at least one account in Mosyle.) 

3. Field Mapping

In this section, you will map Mosyle fields to custom fields in FMX. 

In the "Equipment Tag," choose the Mosyle field to match records from Mosyle to FMX. This field should contain a unique identifier that will be used as the equipment tag in FMX. Changes made to Mosyle will be automatically reflected in the mapped equipment types and buildings in FMX. Any changes made to mapped equipment types or buildings in FMX will be overridden by what is in Mosyle. 

Next, choose the FMX custom field to map to the "Mosyle Device udid" field and the "Mosyle Device Serial Number Custom Field."

***When setting up the integration, if you already have devices in FMX that you would like to have sync with what is in Moysle, then, those equipment items in FMX need to have the equipment tag in FMX updated to the Mosyle field you will be using for the equipment tag.***

For example, if you are choosing the serial_number field (from Mosye) for the FMX equipment tag field, then you will need to bulk update your FMX equipment items to have that as the tag name in FMX. Or the Mosyle udid field needs to be updated to match what is in Mosyle through a bulk update.

For steps on how to bulk update equipment in FMX see this support center article.*

Next, choose the optional custom fields from Mosyle that you want to bring into FMX. Select the "Add to Optional Custom Fields" button to add a field. These custom fields need to be in FMX when doing this phase. They can be mapped at a later time by selecting reconfigure in the integrations section of FMX. Then skip to the field mapping section. The fields will update on the equipment that is already synced in FMX. 

All custom fields added need to have at least the API user type as one of the permitted user types and available for equipment types you are syncing with Mosyle. The custom fields need to be text fields unless otherwise noted in the section above that lists all the Mosyle fields you have to choose from. For example, the field you map “lostmode_status” to needs to be a checkbox custom field in FMX for this field to be properly mapped. Use the "open_direct_device_link" to have a link back to the device in Mosyle.    

Below, you may optionally set a field for the lost mode enabled date to be mapped to in FMX.

Finally, you should set a default building for a Mosyle device to be mapped to if one cannot be found. Setting this is required if you are using the Business API or do not have any accounts in Mosyle.

Click the finish button when you are done. 

Updating the Integration

If your integration needs to be updated, you can do so at any time. To do this, go back to the Integration Settings tab in FMX. Then, find the integration and select "reconfigure." 

***Once you have enabled the Mosyle device integration, you may begin the setup for the Mosyle User integration. See this support center article for details.***