aces

LSAC ACES2 API 2.0 client library and proxy server

Library usage

If you don't want to use the standalone proxy, just require this module as you would all CommonJS modules. The exported function requires an options object that is identical to the Configuration below, although the proxy-specific remoteAddress and localPort properties are nonsensical and therefore optional.

const aces = require('aces');
let report = await aces.fetchXML(options);

Proxy usage

1. Just make HTTP requests as if you were talking to the old ACES2 MVC API (now retired), except use the host and port of this proxy instead of LSAC's server. Other components of the request should be unchanged, including the path and headers.
2. If you are unfamiliar with the old API, just send GET requests to http://host:port/mvcAPI/Export/GetData/ and add a header whose name is your school code and whose value is your API token (the hyphen-delimited GUID one provided by LSAC). Make sure your client will accept XML responses, and that your proxy is configured correctly for the report and condition set you want.
3. Parse and process the XML report results any way you like. If you want to add filters or change the output, edit the report and condition criteria in the ACES2 web interface, in the Reports section.

Proxy installation

1. Install git (optional), node, and npm if you haven't.
2. Download the package using npm or git, or download the archive directly from github.
3. Run npm install to download any dependencies.
4. Copy the settings.example.json file to settings.json and edit it according to the Configuration section below.
5. Run npm start to start the proxy server.

Configuration

For the standalone proxy, all configuration is done in a settings.json file; a template is provided called settings.example.json. To make calls from within other code instead, pass this as an object argument to the fetchXML exported function. Its content is a (strictly parsed) JSON object with the following members:

• FQDName (string): a fully qualified domain name of a client host, without a trailing dot, as provided to LSAC.
• Token (string): a GUID-style hexadecimal secret token, as provided by LSAC.
• ServerAddress (string): a hyphen-delimited MAC address of a client host, as provided to LSAC.
• OSName (string): the (Windows?) operating system of a client host, with OS edition, as provided to LSAC. Probably the same as the output of msinfo32 without the "Microsoft " prefix.
• APISecurityKey (string): a (base64?) shared secret, as provided by LSAC.
• ls (string): an integer LSAC school code (public ID number), as provided by LSAC. Can also be found on LSAC's site for any school.
• rid (string): an integer report ID for a precreated ACES2 report. Can be found in the ACES2 web interface if you select "API template" when running the report.
• cid (string): an integer condition ID for a precreated ACES2 report condition. Can be found in the ACES2 web interface if you select "API template" when running the report.
• ot (string): an integer output type ID used by LSAC. Pick from: 1 (Fixed Text), 2 (CSV), 3 (Excel), 4 (Quote Comma Delimited), 5 (PDF (Crystal Report)), 6 (XML). Currently only XML is supported.
• du (boolean): whether to send the DataUpdate flag with this request. This marks the records as fetched so you can do incremental fetches, but it can't be undone, so this defaults to false. Labeled as a "Data Sent to University" option in other interfaces.
• wsURL (string): the base URL for the ACES2 API, as provided by LSAC. There exist training and production servers at different subdomains, but the functionality should be the same for each.
• remoteAddress (string or string[]): The unproxied IP address(es) (v4 or v6) that will be used to make requests of the API proxy. If you can't get this to work with an IPv4 address, make sure you're not accidentally making your requests over IPv6. On a mostly-IPv4 LAN, those might look like ::ffff:10.11.12.13.
• localPort (number): the port that the proxy will listen on. This probably should not be a privileged port unless you really know what you're doing.