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.