Loading...

home implementation

Implementation

Getting SIMS ready

In order to use the API effectively, you will need to make some small additions to your SIMS setup. The API uses 8 groups, all named with the prefix of HUB:

The purpose of the groups is security. Only staff within the groups listed are able to make API requests.

Either use the table below and manually add in the groups, or alternatively you can download and import them from the file here (right click and select save target as). To import, in SIMS follow the route: Focus > System manager > Import Groups and select the downloaded file.

#NameDescription
1HUB: Admin userAble to pull miscellaneous student reports.
2HUB: Attendance officerCan pull all reports relating to attendance. Access to the watch list.
3HUB: Bully LogHas full read/write access to the bully log. Other users can report incidents, but can only see their own logged and cannot change state of an incident.
4HUB: HRHas access to staff related reports.
5HUB: Isolation managerIs able to add/remove/edit isolation incidents.
6HUB: Isolation userCan see isolations and reports on them but cannot add/edit/delete incidents.
7HUB: LThas access to various assessment and general schooling reports
8HUB: System managerAccess to all reports and data both read/write.


Implementation of the API using PHP is pretty straight forward. Firstly, you will need to download the api class. This can be downloaded in ZIP format from here.

Once you have downloaded the file, extract the php file within the zip to your working folder for your project, keeping the name as dAPI.php


Including the class

You will need to include the dAPI file you downloaded earlier into your project. This can be done simply using:

include( './dAPI.php' );

be sure that the dAPI.php file is in the root of your project. If not, you'll need to adjust the path accordingly when you include the file.


Initializing the class

Now that you have the class included, you are going to want to start using it.

Before you continue, please ensure that you know a valid API ID and key you wish to use. Using an invalid ID/Key pair will cause any subsequent request to fail. Once you have this information, the following code will initiate the class:

$api = new api( 'APP-ID', 'APP-KEY', 'http://api.dalp.org.uk' );

Replacing APP-ID and APP-KEY with the App ID and Key respectively.


Authenticating a user

Now that we have the class setup to the object $api we are nearly ready to start making API calls. Firstly you will need a valid SIMS account to authenticate a users requests. This can be done with the aide of one of the guest API calls.

$sims_auth = $api->sendRequest(
  array( 
      'controller'    => 'Staff',  
      'action'        => 'sims_authenticate',  
      'username'      => 'USERNAME',  
      'password'      => 'PASSWORD' 
    )
  );

Be sure to replace USERNAME and PASSWORD with a valid pair of SIMS credentials.

The API server will check the credentials, and so log as they are valid will return the below...

Array
(
    [result] => Success
    [data] => Array
        (
            [user_id] => 123
            [person_id] => 4567
            [login_name] => TestUsername
            [USER_KEY] => 838093cda3690a107d7afe779a0592cf
            [USER_TOKEN] => 973883f942
        )

)

Above tells us the result of the request - that is, the server was able to validate the credentials and so Success was returned as a result instead of Fail.

it also shows us some useful information. The user_id and person_id both which are used in other API calls. login_name or username which was checked and validated and then the main parts we are interested in, the USER_KEY and USER_TOKEN. These two pieces of information can now be used to authenticate a user for use of API. We can do this by the following:

$api->auth_user( 'USER-TOKEN', 'USER-KEY' );

Putting it all together we could use:

include('./dAPI.php');

$sims_auth = $api->sendRequest(
  array( 
    'controller'    => 'Staff',  
    'action'        => 'sims_authenticate',  
    'username'      => 'TestUsername',  
    'password'      => 'mypassw0rd' 
  )
);

if ( $sims_auth['result'] == 'Success' ){
  $api->auth_user( $sims_auth['data']['USER_KEY'], $sims_auth['data']['USER_TOKEN'] );
  echo "User validated.";
}else{
  echo "Invalid username/password specified.";
}

This will check the supplied user credentials, and so long as they are valid set the API class up for authentication.


Footnotes

Source code provided is provided as is. It has not been optimised for running in a none development environment and is used as demonstration purposes only.

A user key/token can be hard-coded into a project source code. However this is not considered best practise for security, and should never be done if the information is stored in plain text, or there is any chance no matter how slim that the key/token can be compromised by other parties.

Please ensure that the API ID and Key that you use in your project has no risk of being made public or is discoverable by other parties. You should always consider the use of encryption to ensure both API ID and key pairs are kept safe.

Coming soon...