@connectk12/ik12

This library provides a convenient way to connect to Informed K12's APIs.

Note: This library is not officially supported by Informed K12. Use at your own risk.

Installation

To install the library, run the following command:

npm install @connectk12/ik12

Usage

To use this library, you need to set your Informed K12 API Key as an environment variable on the server. You can do this by creating a .env file in the root of your project and adding the following variables:

WARNINGS:

• Do not expose this API Key publicly on the client side.
• Do not commit the .env file to your repository and make sure it is added to your .gitignore file.
• Make sure to keep your API key secure and do not share it with others.

IK12_API_KEY=your_api_key

Then you can import the getCampaignResponses function or other available functions in your code:

import { getCampaignResponses } from '@connectk12/ik12';

API Documentation

For detailed information on the available API methods from Informed K12, please refer to the API documentation.

Get Started

Here are some examples to get you started:

Example 1: Get responses from Campaign Responses API

import { getCampaignResponses } from '@connectk12/ik12';

Inside an async function, call the function with the campaign ID (Example: 123)

const responses = await getCampaignResponses(123);

Example 2: Get archived responses from Campaign Responses API

import { getCampaignResponses } from '@connectk12/ik12';

Inside an async function, call the function with the campaign ID (Example: 123) and status as archived

const responses = await getCampaignResponses(123, {
  status: 'archived'
});

API Details

getCampaignResponses

This function retrieves responses for a specific campaign.

getCampaignResponses(campaignId, options)

Required Parameters

• campaignId: The ID of the campaign to retrieve responses for.

Options

Parameter	Type	Description
status	String	The status of the responses to retrieve. Possible values are active or archived. Default is active.
completedAtStart	Date	Return responses that were completed after this time.
completedAtEnd	Date	Return responses that were completed before this time.
firstSubmittedAtStart	Date	Return responses where step 1 was submitted after this time.
firstSubmittedAtEnd	Date	Return responses where step 1 was submitted before this time.
lastSubmittedAtStart	Date	Return responses that were last submitted after this time.
waitingOnStep	String	Return responses that are currently pending on the specified step.
page	Number	The page number to retrieve. Default is 1.
retrieveAllPages	Boolean	Paginate through all available pages (max: 20 pages).

To update the soft max pages limit, set the IK12_MAX_PAGES environment variable to the desired number of pages.

IK12_MAX_PAGES=10

Example

const responses = await getCampaignResponses(123, {
  status: 'archived',
  completedAtStart: new Date('2021-01-01'),
  completedAtEnd: new Date('2021-02-01'),
  page: 2
});

Helpers

getValueFromField

This function retrieves the value of a field from a response.

getValueFromField(form, fieldNumber, opts)

Required Parameters

Parameter	Type	Description
form	Object	The form object from the response.
fieldNumber	Number	The field number to retrieve the value from.

Options

Parameter	Type	Description
sanitize	Boolean	If true, the value will be sanitized to remove any symbols and special characters. Default is true
sanitizeOpts	Object	Options for sanitize function. Possible keys are removeSpecialChars (boolean), removeWhitespace (boolean), and uppercase (boolean)

getValueFromFieldAsNumber

This function retrieves the value of a field from a response and returns it as a number (with parseFloat).

getValueFromFieldAsNumber(form, fieldNumber, opts)

Required Parameters

Parameter	Type	Description
form	Object	The form object from the response.
fieldNumber	Number	The field number to retrieve the value from.

getArrayFromField

This function retrieves an array of values from specified fields in a response. For example, this function can be used to aggregate and then sum all input numbers in a form.

getArrayFromField(form, fieldNumber, opts)

Required Parameters

Parameter	Type	Description
form	Object	The form object from the response.
fieldNumbers	Array of Integers	The field numbers to retrieve the values from.

Options

Parameter	Type	Description
sanitize	Boolean	If true, the value will be sanitized to remove any symbols and special characters. Default is true
sanitizeOpts	Object	Options for sanitize function. Possible keys are removeSpecialChars (boolean), removeWhitespace (boolean), and uppercase (boolean)

Debug Mode

To enable debug mode, set the IK12_DEBUG environment variable to true:

IK12_DEBUG=true

To set debug mode to verbose (showing all requests and responses), set the IK12_DEBUG_MODE environment variable to verbose:

IK12_DEBUG_MODE=verbose

Contributing

Contributions are welcome! If you find any issues or have suggestions for improvements, please open an issue or submit a pull request on the GitHub repository.

License

This library is licensed under the MIT License.