iSAMS Rest API

[CyBeRkId2002]

I am pretty familiar with how to pull info from a batch API, but for some of the bits I need to access from our MIS (iSAMS) I need to access via REST API.  Does anyone have a quick way of explaining how this differs, and what I need to do to connect.  I am only trying to pull info, not write-back.

 

Thanks in advance.

[dhicks]

36 minutes ago, CyBeRkId2002 said:

Does anyone have a quick way of explaining how this differs, and what I need to do to connect.

 

This is the kind of thing where AI assistance can work really well, both in explaining how-it-works to you and, if you have a suitible coding agent, writing the code for you. If I remember correctly, iSAMS uses an OpenAPI/Swagger REST API interface - you might have seen other services offer the same thing, where you get a handy documentation and live try-it-out box all in one. You are basically doing HTTP(S) calls to a given endpoint, with defined parameters - the Swagger UI willl let you try out values and show you the URL strings (and even examples in Javascript / Python / etc) as you type. You authenticate via OAuth - I can't remember setting up a REST API with iSAMS, I suspect it was a while ago and I probably had to do a log-in-with-Google step in the browser the first time.

[Juba]

Hi, coming from Batch, I'd think of the change as moving from a configured extract to requests for particular resources. iSAMS describes Batch as standardised data extraction and REST as real-time access for reads and writes. You don't have to use the write operations just because they're available.

For your first test, I'd pick one small read request and check three things: the REST authentication setup for your school, the relevant GET endpoint and its filters, and whether the results are paginated. That last bit matters when you move from a successful test to an actual extract.

iSAMS also publishes its own REST example application here:
https://github.com/iSAMS/REST-API-Example-App

It's a VS2017-era example, so I'd use the current developer documentation for the exact connection details rather than assume an old sample or your Batch API credentials will carry across.

What are you using to pull the data — PowerShell, Power BI, Python, or something else — and which data are you trying to get that Batch isn't giving you? That would help narrow this down to a useful first request. No API keys or real pupil details needed.

[CyBeRkId2002]

Our main thing is a couple of bits from the medical centre (what we need is slightly less sensitive and security measures on where it will be downloaded will be tight).

 

I imagine the requests might be ok (using the Swagger guide) but I really don't understand the authentication process.  If anyone could provide a quick walkthrough on connecting (preferably via Powershell or, at a push, python) it would be really appreciated.

[Juba]

Thanks, that helps. Before writing a PowerShell example, has REST access already been configured for your script, or are you still at that initial setup stage?

Could you also say which authentication scheme/flow and field names your Swagger guide lists? Just the labels, no values. The current iSAMS developer guide requires sign-in, so I can't verify the exact request publicly and don't want to guess the connection details.

If you've already tried a request, the HTTP status and short error code would help too. Please leave out credentials, tokens and any pupil or medical data.

[dhicks]

58 minutes ago, CyBeRkId2002 said:

If anyone could provide a quick walkthrough on connecting (preferably via Powershell or, at a push, python) it would be really appreciated.

 

I have secrets (REST API keys, etc, that you get from the iSAMS Control Panel) in a simple JSON file, loadable by a script:

# Load the configuration file.
config = json.loads(dataLib.readFile("config/config.json"))
for requiredConfigParameter in requiredConfigParameters:
	if not requiredConfigParameter in config.keys():
		print("Error - required value " + requiredConfigParameter + " not set in config.json.")
		sys.exit(1)

Something like:

{
"iSAMSAPIDomain":"exampleschool.isams.cloud",
"iSAMSRESTAPIID":"12345678-1234-1234-1234-123456789012",
"iSAMSRESTAPISecret":"12345678-1234-1234-1234-123456789012",
}

Then a couple of functions to call the REST API:

# Retrive the cached iSAMS REST API Access Token, or request a new one if needed.
def authenticateWithiSAMSRESTAPI():
    if os.path.exists("accessToken.txt"):
        access_token = dataLib.readFile("accessToken.txt").strip()
    else:
        print("Authenticating with iSAMSREST API...", flush=True)
        requestURL = "https://" + config["iSAMSAPIDomain"] + "/auth/connect/token"
        response = requests.post(requestURL, data={"client_id":config["iSAMSRESTAPIID"],"client_secret":config["iSAMSRESTAPISecret"],"grant_type":"client_credentials","scope":"restapi"})
        if not response.status_code == 200:
            print("Error athenticating with the iSAMS API:")
            print("URL: " + requestURL)
            print("Error Code: " + str(response.status_code))
            print("Data: " +  str(response.content))
            sys.exit(1)
        access_token = json.loads(response.content.decode("utf8"))["access_token"]
        dataLib.writeFile("accessToken.txt", access_token)
    return access_token
iSAMSAccessToken = authenticateWithiSAMSRESTAPI()

# A handy function to do a call to the iSAMS REST API. Uses the global "iSAMSAccessToken" value for authentication - if that access token fails (default expiration is after 1 hour),
# it gets a fresh access token and tries again. Only does 2 tries to avoid getting stuck in a loop.
def iSAMSRESTAPICall(theMethod, theEndpoint, theData):
    global iSAMSAccessToken
    tries = 0
    while tries < 2:
        tries = tries + 1
        print("Doing " + theMethod + " to " + theEndpoint + " with data:", flush=True)
        print(str(theData).encode("utf-8"), flush=True)
        requestURL = "https://" + config["iSAMSAPIDomain"] + theEndpoint
        requestHeaders = {"accept":"application/json","authorization":"Bearer " + iSAMSAccessToken, "content-type":"application/json"}
        if theMethod == "get":
            response = requests.get(requestURL, data=json.dumps(theData), headers=requestHeaders)
        elif theMethod == "put":
            response = requests.put(requestURL, data=json.dumps(theData), headers=requestHeaders)
        elif theMethod == "patch":
            response = requests.patch(requestURL, data=json.dumps(theData), headers=requestHeaders)
        else:
            print("iSAMSRESTAPICall: Unknown request method: " + theMethod)
        if response.status_code == 200:
            return response
        elif response.status_code == 401 and tries < 2:
            print("iSAMSRESTAPICall: iSAMS authentication access token expired - retrying.")
            os.remove("accessToken.txt")
            iSAMSAccessToken = authenticateWithiSAMSRESTAPI()
        else:
            return response

Then you can do calls to the REST API:

getResponse = iSAMSRESTAPICall("get", "/Main/api/students/" + SchoolId, {})
    if getResponse.status_code == 200:
        pupilData = json.loads(getResponse.text)

 

[CyBeRkId2002]

Thanks very much! Think this may be a little out of my skille skill set but might take a final look over half term. 

 

I am trying to build a system that pulls team lists from Socs, collate with medical info into a table and then present to staff (maybe with Power apps). At present we can't get medical info into Socs which is a bit of a frustration for staff.

[dhicks]

15 hours ago, CyBeRkId2002 said:

Thanks very much! Think this may be a little out of my skille skill set but might take a final look over half term.

 

The Python code is, hopefully, fairly generic - a little clunky / step-by-step in the way it does things, but hopefully that makes it easier to read through if you don't generally use Python. This is the kind of thing an AI coding assistant can be very good at helping with - you can probably just copy-and-paste the above into any chatbot asistant and ask it to re-write in the language of your choice.

 

15 hours ago, CyBeRkId2002 said:

I am trying to build a system that pulls team lists from Socs, collate with medical info into a table and then present to staff (maybe with Power apps). At present we can't get medical info into Socs which is a bit of a frustration for staff.

 

Is "Socs" a section / module in iSAMS? You could, potentially, write medical information back to iSAMS if that is coming from a separate system somewhere. If you're writing pupil records via the iSAMS REST API, be aware that the API writes blank values - if you define a record, write the value you want to a particular field but leave the rest of the fields blank, the API will happily overwrite those blank values to the database. You need to do a GET request first, populate the record with any existing values, make any additions / changes, then do a POST to write back to iSAMS.

 

If the data the staff require is static (I'm guessing a list-of-medical-conditions per child per club / society), I find generating a viewable / printable PDF works quite nicely - you can have a script go through the data, match up pupils with any medical conditions and produce a formatted PDF you can then upload to OneDrive / Googel Drive / etc. Again, the sort of thing (with suitible safeguards for data handling) an AI assistant can pretty much write for you in a few minutes now.

[CyBeRkId2002]

Thank you for all the help... I managed to get most of the way there on a proof of concept.  Contacted iSAMS to setup a REST API key and they wanted £2k for the privilege!  Looks like it is dead in the water for us, at least for now :(

 

[dhicks]

15 hours ago, CyBeRkId2002 said:

Contacted iSAMS to setup a REST API key and they wanted £2k for the privilege!

 

I suspect that means you need to upgrade your iSAMS subscription to a version where REST API keys are a thing, otherwise possibly the person you were talking with didn't understand what you were asking for. On our instance of iSAMS we can simply add REST API keys ourselves from the Control Panel. If you already sync your data from iSAMS to Wonde you could maybe look at Wonde's API instead - I've foundthem very helpful inthe past, they have a whole proper developer relations department for dealing with this kind of thing.

[dhicks]

2 hours ago, dhicks said:

On our instance of iSAMS we can simply add REST API keys ourselves from the Control Panel.

 

As an added bonus: iSAMS are changing the way their Batch API is implemented, moving to a (more common) dual "ClientID" and "ClientSecret" values rather than a single "API Key" value. Today (as we're preparing reports for the first time with the new school portal and wanting to be able to write a script that sorts out the reports for us) is the day that the changeover occurs, hence I now need to go back and re-implement how the Batch API call works.

[TechMonkey]

Check your emails, I had one that said they were stalling the change and the enforcement for a bit with no current dates set.

[dhicks]

11 minutes ago, TechMonkey said:

Check your emails, I had one that said they were stalling the change and the enforcement for a bit with no current dates set.

 

That's the thing - I don't remember seeing any email directly from iSAMS, or it simply passed me by. I did see an email fom Wonde last week saying there would be a "first brownout" for the old-style keys, which is what I've assumed is happening today.

[River]

The brownouts have also been delayed, no date set for when they will now occur

[dhicks]

5 minutes ago, River said:

The brownouts have also been delayed, no date set for when they will now occur

 

Ah - but I don't currently seem to be able to get data from the iSAMS Batch API.

[2ilent8cho]

1 hour ago, dhicks said:

 

Ah - but I don't currently seem to be able to get data from the iSAMS Batch API.

iSAMS Batch API is broken today (and iTeacher app that still uses it) , they are doing an emergency release later today. REST API is fine though. 

[River]

So no communications from iSAMS on this (not surprising). Still having problems getting one of our APIs to work. Anyone else still having API problems? Getting very fed up with iSAMS and their API issues

[TechMonkey]

I had an email earlier setting up incident details with a link to the incident page

 

Looks to be all closed so if you are still having issues I'd yell at support

 

[River]

1 hour ago, TechMonkey said:

I had an email earlier setting up incident details with a link to the incident page

 

Looks to be all closed so if you are still having issues I'd yell at support

 

Thanks for the link. MSP have just sorted out the sync we needed so all good now

[dhicks]

1 hour ago, River said:

Still having problems getting one of our APIs to work. Anyone else still having API problems?

 

We have a bunch of batch-processing scripts (import new users, that sort of thing) run at about 3am. It still couldn't get to the iSAMS Batch API at 3am this morning. I've now added new code to failover to the REST API instead, which seems to work okay.