# aces

> A client library for the LSAC ACES2 API

Latest version **0.2.3** (published 2019-07-29) · ISC license · 0 weekly downloads

## Install

```sh
npm install aces
pnpm add aces
yarn add aces
bun add aces
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.2.3 |
| Published | 2019-07-29 |
| First published | 2018-05-09 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | 10.x |
| Dependencies | 6 |
| Unpacked size | 14.1 KB |
| Known vulnerabilities | 0 (+17 in 2 direct dependencies) |
| Install scripts | no |
| Author | Benjamin P. Burhans |
| Maintainers | bburhans |

## Links

- npm: https://www.npmjs.com/package/aces
- Repository: https://github.com/bburhans/aces
- Homepage: https://github.com/bburhans/aces#readme
- Issues: https://github.com/bburhans/aces/issues
- npm.io page: https://npm.io/package/aces

## Dependencies (6)

- [xpath](https://npm.io/package/xpath.md) 0.0.27
- [xmldom](https://npm.io/package/xmldom.md) ^0.1.27
- [express](https://npm.io/package/express.md) ^4.16.3
- [request](https://npm.io/package/request.md) ^2.88.0
- [express-async-wrap](https://npm.io/package/express-async-wrap.md) ^1.0.0
- [request-promise-native](https://npm.io/package/request-promise-native.md) ^1.0.5

## Recent versions

- 0.2.3 (latest) — 2019-07-29
- 0.2.2 — 2019-06-25
- 0.2.1 — 2019-01-11
- 0.2.0 — 2018-05-10
- 0.1.1 — 2018-05-09
- 0.1.0 — 2018-05-09

## README

# 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](#Configuration) below, although the proxy-specific `remoteAddress` and `localPort` properties are nonsensical and therefore optional.

```javascript
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](https://aces2.lsac.org/N/Default.aspx).

## Proxy installation
1. Install [git](https://git-scm.com/) (optional), [node, and npm](https://nodejs.org/) if you haven't.
2. Download the package using [npm](https://www.npmjs.com/package/aces) or [git](https://github.com/bburhans/aces), or [download the archive directly from github](https://github.com/bburhans/aces/archive/master.zip).
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](#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](http://www.lsac.org/transcriptkeys/igugs-search.aspx) for any school.
- **rid** (string): an integer report ID for a precreated ACES2 report. Can be found in the [ACES2 web interface](https://aces2.lsac.org/N/Default.aspx) 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](https://aces2.lsac.org/N/Default.aspx) 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](https://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers#Well-known_ports) unless you really know what you're doing.

---
_Source: https://npm.io/package/aces · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._