Facility Connect API: Setup & Troubleshooting. Version 1

Transcription

1 Facility Connect API: Setup & Troubleshooting Version 1 All copyright and other intellectual property rights in all text, images and course materials are owned by Advanced Learning or are included with permission of the relevant owner. You are permitted to reproduce extracts by way of printing, and by distribution to other people but, in all cases, for non-commercial, informational and personal purposes only. No reproduction of any materials may be sold or distributed for commercial gain, nor shall they be modified or incorporated in any other work or publication. No other licence or right is granted. COPYRIGHT Advanced Learning Advanced Learning owned by Advanced Business Software and Solutions Limited trading as Advanced Business Solutions part of Advanced Computer Software Group. Registered in England and Wales. No: Registered Office: Munro House, Portsmouth Road, Cobham, Surrey K11 1TF, United Kingdom. Advanced Learning, Salisbury House, Stephensons Way, Wyvern Business Park, Derby DE21 6BF f

2 Table of Contents 1 Setting up the API Editing the API.xml Testing the API The API from a client machine or externally Refreshing the Cache in the API Setting Up API Through IIS Setting up Access Through an ISA Server or Firewall Troubleshooting Error: HTTP Status Error: HTTP Status Error: HTTP 500 Internal Server Error When Accessing the getstudents() Method Error: HTTP 500 Internal Server Error When Accessing the API Web Service.. 11 Page 2 of 11

3 1 Setting up the API The API is installed with Eportal and, by default, is configured to run on the secure port for Tomcat (port 8443). The API uses IP address filtering in order to stop unauthorised access and, by default, is set to not allow any IP addresses. In order to access it you will need to edit the API.xml, which controls the IP filtering and is located in \Facility\ePortal\conf\Catalina\localhost\. 1.1 Editing the API.xml To allow an IP address, edit the API.xml file and locate the section: <?xml version="1.0" encoding="utf-8"?> <Context> <Valve classname="org.apache.catalina.valves.remoteaddrvalve" allow="0\.0\.0\.0" /> </Context> And change 0\.0\.0\.0 to an IP address. If you re testing the API from the server where Eportal installed, you will need either the server IP address or the loopback address. So the file will then look like: <?xml version="1.0" encoding="utf-8"?> <Context> <Valve classname="org.apache.catalina.valves.remoteaddrvalve" allow=" " /> </Context> Page 3 of 11

4 1.2 Testing the API To test the API: 1. Open a supported internet browser. 2. Go to A certificate warning screen will appear. 3. Click Continue Anyway. An API splash screen below will appear. This indicates the API is working ok. Page 4 of 11

5 2 The API from a client machine or externally If you are trying to access the API from a machine other than the server, for example a client machine, another server or externally, you will need to add the IP addresses of each machine into the API.xml. These IP addresses will be separated with a comma. For example, if you had a setup like the diagram below and you wanted a different server on your network, which had an IP address of , and a third party who would use to access the API. Internal Network Server Hosting Application Application Hosted at Third Party API API.xml IP Filtering Eportal Server Your API.xml file would look like this: <?xml version="1.0" encoding="utf-8"?> <Context> <Valve classname="org.apache.catalina.valves.remoteaddrvalve" allow=" , , " /> </Context> Page 5 of 11

6 3 Refreshing the Cache in the API The cache for the API is built into a file which is stored in C:\Facility\ePortal\webapps\API\WEB-INF\cache and is added to each time data is pulled through the API. To refresh the data, stop the Facility Eportal and the Facility Data Server services and start them again. This will delete the file and create a new one which will be populated with fresh data. Page 6 of 11

7 4 Setting Up API Through IIS If you already have eportal running on IIS, you can make the API also run through it by adding a certificate to IIS so that it will run over https. You will need to obtain a certificate in order to use 1. Obtain a security certificate. There are a number of certificate providers available to choose from. A quick search online for SSL certificate will list these providers who will be able to recommend the right certificate for you. 2. Configure web site to use SSL/HTTPS. Due to the security around configuring SSL, please consult the relevant Microsoft documentation for more information on how to do this. Page 7 of 11

8 5 Setting up Access Through an ISA Server or Firewall The configuration of ISA servers or firewalls is not supported by Advanced Learning as they are products of Microsoft or other companies; however, there are a few requirements in order to successfully access the API. The URL to the API must always stay on https. If the API is accessed on http, it will route to the tomcat secure port (8443). There must be access to only having access to will not allow access. Finally, any IP masking or forwarding will cause problems the IP filtering. A different IP will access the API from the one you expect and have entered in the API.xml. There is a file called IP.jsp, which will show you what IP address is accessing the API, which will help diagnose access issues. This is available on the first line support site, and needs to be added to \Facility\ePortal\webapps\eportal. If you then go to it will show you the IP address that the API is seeing. Page 8 of 11

9 6 Troubleshooting 6.1 Error: HTTP Status 403 Cause: The IP address of the machine accessing the API is not listed in the API.xml The API uses IP filtering in order to stop unauthorised machines accessing data through the API. This filtering is done using the API.xml file located in C:\Facility\ePortal\conf\Catalina\localhost (for default installation). If the IP address is not listed in this file, the 403 error page will show. If the IP address has been listed in the API.xml file but the 403 error page is still showing, it is likely the IP address of the Third Party is being changed by a firewall or ISA server in front of the API. In the example below, the API.xml is set to allow , which is the IP address of the Third Party, however, the ISA server is changing the IP address to an internal IP address, which is then trying to access the API. As the address is not in the API.xml, the Third Party will receive the 403 error page. API 403 Error API.xml IP Filtering - allowing ISA Server / Firewall Third Party Application Server In these cases, the Third Party s route to the API must either not be masked, so they re IP address doesn t change, or the IP address of the ISA server or firewall must be entered into the API.xml and all IP address filtering must be done at the ISA server or Firewall. Servers running Server 2008 may be running IIS 7 or 7.5. If you have setup the API through IIS and are getting 403 when trying to access IIS will trying to access the API using an IP address of ::1, not Therefore, you will still not be able to access the API even though is in the API.xml. In this case, use to test the API. Page 9 of 11

10 6.2 Error: HTTP Status 404 Causes: Incorrect address. Syntax error within API.xml. Problem with API pages. If you re testing access to the API splash screen using and are getting a 404 page, first check the address that you are using. The /API in the URL must be in capitals and must not have anything before the /API. For example, will not work. If you are using an ISA server, please make sure there are no rules forwarding all traffic to localhost to localhost/eportal, as this may result in the API localhost/api being forwarded to localhost/eportal/api. Please note, if you are using eportal through IIS you will not need to specify the port number. If the address you are using is correct, there could be an issue with the API pages. The pages can be rebuilt to a default state by stopping the Facility data server and Eportal service, going to x:\facility\eportal\webapps and moving the API folder out to a new location (e.g. the desktop). Once this is done, start the Facility data server service, then the Eportal service and the API folder will be rebuilt. You may have to stop and start the services again in order for the certificate in the API folder to be picked up by IIS or Tomcat. If you are still getting a 404 page after this, it could indicate a problem within the API.xml, or with the file itself. Go to C:\Facility\ePortal\conf\Catalina\localhost and edit the API.xml. Make sure all IP addresses are separated with a comma, and no odd characters exist. The file will allow * as a wildcard for a range of IP address (i.e *) but not 0/25 to range from If the file looks ok, please download the default API.xml from the support site and overwrite the existing file. Restart the Facility data server and Facility Eportal services and check you can get the 403 page. If you do, then edit the API.xml to enter the IP addresses required, then test again. If the problem still persists, please contact the support desk. Page 10 of 11

11 6.3 Error: HTTP 500 Internal Server Error When Accessing the getstudents() Method Cause: Missing core data items from a student record To be pulled through in the getstudents, all students must have their core information fields populated. These fields are Name, Course, Year, Form or Tutor Group and their Date of Birth. If a student records is missing one or more of these fields it will cause the getstudents method to fail. The best way to identify the student record causing the error is to go into Facility and to go Students>Student List Window, then click Select>All Records. Sort each column in turn to indentify any missing data. Once the data has been added, stop the Eportal services and go to x:\facility\eportal\webapps\api\web-inf\cache (hidden by default) and delete the file in here. Start the services again and the error should be resolved. 6.4 Error: HTTP 500 Internal Server Error When Accessing the API Web Service Cause: Files existing in the x:\facility\eportal\common\endorsed\ folder If you are seeing an "Error 500" window from the Facility API when you go to Stop your Facility eportal and Facility dataserver services, Go to your Facility eportal server and Browse to x:\facility\eportal\common\endorsed and delete any files that exist in here. Start your services again - the error should now have gone. Page 11 of 11