Setting up and managing third-party API integrations in Arbor

What is an API?

An API is a method third-parties use to integrate with Arbor and access information, most will be a one-way integration (feeding data from Arbor into the third-party) but there are some that work both ways (information updated in one system will automatically update in the other).

You can connect your API to many different third-parties including Wonde, Groupcall, ParentPay, CPOMS, LGFL, OTrack, Cunninghams, Classcharts, Studybugs, Scopay and many more. You can see a list of all the third parties that we work with below!

The way we connect with third-party apps gives you the ability to manage apps that can access your data. For each app, you can inspect what data it uses and what it can do with this data.

If you are not happy with the data an app is requesting or would like to find out more about how and why this data is being used, please contact the app’s company directly.

Permissions

To be able to manage API links, including managing Single Sign-On (SSO) settings, managing MIS users and viewing user’s login history, you'll need the:

  • School: User Accounts: Administer permission on the School MIS - if you don't have the permission, you'll need to ask your admin team to give you permission using these instructions.
  • User Details: Manage All Users permission on the MAT MIS - if you don't have the permission, someone will need to assign you a new Business Role that contains this permission.

 

Before setting up integrations

Arbor’s process to connect to apps requires you to contact the app's company directly before any integration can take place, regardless of whether the app is one of our current partners or not. For more information, see the section below called Connecting to a new app.

 

How to get set up

Apps you can connect to using this process

You can find a list of our current Integrated Partners on this page.

Connecting to a new app

If you know the app is one of our current partners (please refer to this list), please contact the app's company directly to let them know you would like to work with them. They will set up the new connection. 

If the app is not one of our current partners, or you're not sure, please let us know the name of this app, and contact the app's company directly to let them know you would like to work with them.

We will let you know if the app is a partner, and will ask you some additional questions about why you want to connect with this app to help us decide whether we would like to establish a connection with the app. If we do, we will work with the app's company to try and get you connected. They should follow these instructions: How can we set up our own API Integration with Arbor?

Please note that our API is only available to apps that are not competitors to our products and that the process of making a connection can take some time, as the app will need to build their part of the integration before connecting.

Approving a third party connection 

Once the app's company have set up the connection to your Arbor site, you will be notified within Arbor that there is a pending request that requires your attention. Go to System > Partner Apps (API Users) on a school MIS site, or System > Partner Apps (API Users) on a MAT MIS site and approve the request for it to be able to access your data.

For each 3rd party app that wants to connect, or is already connected with your data, you can:

  • View the details of what data the app is requesting access to or already uses.
  • Approve the app to enable it to access your data.
  • Reject the app, so it cannot access your data.

An explanation of key terms can be found at the bottom of the page.

To view an app that is trying to connect with you, select Pending requests from the left-hand menu.

Screenshot_2022-12-01_at_14.08.30.png

 

Click the row containing the app in question and you will be presented with a slide-over showing the permissions requested.

Screenshot_2022-12-01_at_14.12.14.png

 

In this example, an app is requesting to be able to view and update all the data for ‘email addresses’, shown by ticks. However, it cannot delete the data, shown by a cross in the table. This means the app cannot create data, or delete any data that is in Arbor regarding email addresses.

  • If you are happy with the access the app is requesting, you can confirm the access of the 3rd party app by clicking Approve.
  • If you do not want an app to access the data, click Reject.
  • If you would like to put off the decision, click Cancel.

Top tip: You can download a list containing all the data the app is using or has requested to use. Helpful if parents are wondering what information about their child is available to partners!

 

Alternative Connection Option

Some third-party apps (e.g. Hodder, Groupcall) that have already established a connection with Arbor may offer you an alternative way of integrating with your MIS site. Using this method, there is no need for the app to send a request for your approval.

You will instead be sent a link by the app's developers, which will take you to a page where you can input your Arbor credentials (the email and password associated with your Arbor MIS account).

Please note that there are certain requirements to be able to use this method, otherwise an error message will pop up: Invalid credentials error message when setting up API integrations

alternative_connection_option.png

 

After authorization, you will be able to check what data the App will be able to access and approve this. You will then be connected to the app, and the app will appear as an Approved app on the Approved Apps page. 

If you ever need to reject the connection, follow the instructions in the section below.

Managing existing connections

If you would like to revoke access or are no longer using an app, you can reject an app. This will immediately prevent it from using and accessing your data. To do this:

  1. Click the Approved Apps tab
  2. Select the app name
  3. Click the Reject button

The app will then move to your Rejected Apps list.

You can also give access to an app you previously rejected. This will immediately enable the app to use and access your data. To do this:

  1. Click the Rejected Apps tab
  2. Select the app name
  3. Click the Approve button

The app will then move to your Approved Apps list.

Key Definitions

Data type - The group of data the app can access e.g. if an app can access the ‘staff’ entity, this could include staff name, contract details, timetables, etc.

Specific fields - What specific pieces of data the app will be able to access e.g. it may be able to access all data regarding staff, or perhaps only staff attendance.

Read - App can access this data e.g. a timetabling app can see what lesson a staff member is teaching next.

Write - App can create this data e.g. an app can add new staff members.

Update - App can edit data e.g. app can be used to update staff details.

Delete - App can delete data e.g. app can delete a staff member.

Top tips for managing your APIs

If you're using Wonde

If you are using Wonde as a third party you need to have a subject set up for your courses. If you don’t have these set up you can do this by following these instructions: Bulk set course subjects

If you're using Hodder

If you’re using Hodder the short name for registration forms must be used, if you need to add these in or update them you can do this by going to School > Programmes > Courses > Registration forms on the left-hand side menu. You can click into the registration form and then into the short name area to add or update the short name.

 

 

FAQ

Can we set up a connection using our MAT MIS account?

Yes you can! To be able to do this, you'll need to:

  1. have the User Details: Manage All Users permission on your MAT MIS profile
  2. log into the school MIS from the MAT MIS to approve the connections
  3. accept the Terms & Conditions when logging into each school site

Please note that if you are using the alternative connection method, there are certain additional requirements, otherwise an error message will pop up: Invalid credentials error message when setting up API integrations

Getting an Application Not Live error message
Getting an Invalid Credentials error message
When will the sync start? 

If you want to know when your sync with the third party will start especially as you look towards a new academic year please contact the third party directly. They will be able to advise you on their first sync and what they may need from you.

What do we do if the integration is not working?

If you are having issues with your sync, please check first that the information needed is in Arbor, this could be short names for forms, forms linked to a year group if the information is missing in Arbor then you will need to update this so that it can pull through your sync.

If the information is showing, please follow the instructions here: How to troubleshoot or report API 3rd party integration issues

Can we change the app's permissions?

To see what data your API connection will be looking at you can head to System > Partner Apps (API Users) > Approved Apps and then click on the App Name.

Any changes to the information being read need to be made by the third party application - please contact them if you're unsure on what information is being pulled. If the third party application integrates via a data provider e.g. Groupcall or Wonde, please contact them.

Permission sets cannot be customised for individual schools or MATs, and would apply to all integrations with Arbor.

Can we approve an integration during migration to Arbor?

If you are a secondary school, you'll do a dummy data run to check your data. You can approve an integration whilst using your dummy site, and the integration will still be approved once your site is wiped and remigrated.

However, we do not recommend doing so. This is because Arbor IDs (e.g. student ID and staff ID) will change between your dummy site and your live site.

If you did do this, please contact all your third party providers to let them know, so they can use the correct IDs once you have your final site.

How do integrations with Data Providers such as Wonde and Groupcall work?

Wonde, Groupcall and other data providers have 'read' integrations with Arbor's API (they cannot have 'write' integrations) to access a wide range of data.

They pull data from Arbor in a format that is the same as data they pull from other MIS systems, meaning third party applications can build a generic API integration. The data the third party application needs is then pulled from Wonde or Groupcall, once you authorise the third party's access to this data from within Wonde or Groupcall.

Any changes to the information being read need to be made by Groupcall, Wonde etc, so please contact them for further information.

 
Was this article helpful?
0 out of 2 found this helpful
I'm still stuck!

Comments

0 comments

Article is closed for comments.