knowledgeanywhere beta

1.0.0

Home
User
Token ▸
- Instance members
- #get
CustomField
LMSAPI ▸
- Instance members
- #get
- #post
- #put
- #delete
Ping ▸
- Instance members
- #checkHealth
Auth ▸
- Instance members
- #token
Users ▸
- Instance members
- #find
- #findById
- #create
- #update
- #deactivate

Need help reading this?

Home

Knowledge Anywhere LMS API SDK

SDK for Interacting with the Knowledge Anywhere LMS API.

contact support@knowledgeanywhere.com if you would like more information.

Documentation

Installation and Getting Started

You will need Audience and Secret keys for authorization. These can be obtained by going to into the admin panel for your LMS and navigating to Site > External API keys.
run the cmd npm i knowledgeanywhere --save to get the package.
The SDK expects the constants LMS_AUDIENCE, LMS_SECRET to be present as process variables. The easiest way to accomplish this is to use an .env file that is loaded via Foreman or dotenv. If you are directed to use a different API url, use the LMS_API_URL environment variable.

Usage

Refer to Documentation to see available method calls.
All methods. return a promise and are async/await friendly.

Issues

Bugs related to the SDK should be filed under this Github Repository. Be sure to include your Node version and any relevant error information.
Issues with the LMS API itself should be emailed to support@knowledgeanywhere.com

Contributing

Clone repo onto your machine
Create a .env file with LMS_AUDIENCE, LMS_SECRET keys. Fill in LMS_AUDIENCE and LMS_SECRET from the values that are attained in the admin section of your LMS under the Site Menu. Set environment to stage.
Run npm install
To run tests run npm tests

To update documentation, run npm run-script generate-docs

Debugging in VS Code

The recommended editor for working on the SDK is Visual Studio code, which is has a debug configuration already setup. In the specs folder, modify the file manual-tests.js to run through the code you desire to debug. When you're ready, select the "debug" icon in the pane and click "launch program" and it will hit any breakpoints you set.

Pull Requests will not be considered until public availability

User

Most fields are optional. Only required fields are externalId, email, lastName, FirstName.

User

Type: User

Properties

externalId (string) : The unique identifier from the system calling the API for this user

email (string) : The email for the user.

lastName (string) : The last name for the user

firstName (string) : The first name for the user

password (string) : Plain text password (optional). There is a minimum length requirement of 6 characters.

ssoId (string) : Unique identifier utilized by the Single Sign-on system integrated with the LMS used to uniquely identify this user for sign-on. If Provisioning and SSO are handled by the same system this could be the same data passed for externalId.

active (boolean) : Make user active/inactive in the LMS

siteName (string) : The name of the microsite.

sendInitialEmail (boolean) : Send the user an email with a link to the LMS. Defaults to false

forcePasswordChange (boolean) : Make the user change thier passowrd on next login. Defaults to false

locale (string) : The 4 letter language code. If the code is not active in the LMS the user will be defaulted to the default LMS value. In most cases this is EN-US. Defaults to EN-US. If a invalid locale is passed in, the operation will continue, but will return a warning.

registrationCode (string) : If your LMS uses registration codes for users to self register use this field to assign that code to the user. The value passed in must match a value in the LMS, if no match is found the request will result in a 400 bad request.

phoneNumber (string) : The phone number for this user

businessName (string) : The company name for this user

address1 (string) : The street address, P.O. Box for this user

address2 (string) : The apartment, suite, unit building, floor, etc for this user

city (string) : The city for the user

state (string) : The 2 or 3 letter state/province abbrevation for the user.

postalCode (string) : The zip or postal code for the user

country (string) : The 2 or 3 letter ISO country code country for the user. See https://www.iso.org/iso-3166-country-codes.html for the list of valid country codes. Defaults to the country specified in your LMS configuration. If a invalid country is specified, the operation will continue, but a warning will be thrown.

customFields (Array<CustomField>)

Token

Model representing a Token

Token

Type: Token

Parameters

token (object) Response from auth server to serialize into a Token.

Properties

accessToken (string) : Access Token, used to make requests.

issued (date) : Issue date

expires (date) : Expiry date

expiresIn (number) : Seconds till expiration. Epcoch Unix Timestamp

tokenType (string) : Type of token. (Bearer)

authorization (string) : Authorization header content. Example Bearer xxxxxxxxx

isValid (boolean) : Checks to see if the token is "fresh" or expired

Instance Members

▸ get()

Retreives the token

get(): object

Returns

object: token - Token object

CustomField

Model representing a Custom Field

CustomField

Type: CustomField

Parameters

cfd (any)

CustomFieldDefinition (object) Object containing the Custom Field Definition

Properties

name (string) : String containing the name of the custom field. If the property is not matched to an existing value in the system, it will be created.

value (string) : String containing the value of the custom field. The value can be a single value or a comma seperated string. If the property is not matched to an existing value, it will be created.

LMSAPI

This module is available for use and is used by all other modules to call the API in a consistent way and handles authentication. Use the methods to manually make a request to the API using an endpoint.

new LMSAPI()

Example

`lms.api.post('v1/users', data)`

Instance Members

▸ get(endpoint)

Performs a GET request.

get(endpoint: string): Promise<Object>

Parameters

endpoint (string) to be called.

Returns

Promise<Object>: JSON payload returned from the API

▸ post(endpoint, data, JSON)

Performs a POST request.

post(endpoint: string, data: any, JSON: object): Promise<Object>

Parameters

endpoint (string) to be called.

data (any)

JSON (object) data to be sent to the server

Returns

Promise<Object>: JSON payload returned from the API

▸ put(endpoint, data, JSON)

Performs a PUT request. You can also send in a blank object and append a path param to the endpoint.

put(endpoint: string, data: any, JSON: object): Promise<Object>

Parameters

endpoint (string) to be called.

data (any)

JSON (object) data to be sent to the server

Returns

Promise<Object>: JSON payload returned from the API

▸ delete(endpoint, data)

Performs a DELETE request.

delete(endpoint: string, data: any): Promise<Object>

Parameters

endpoint (string) to be called. Should include the path params or a query string with the resource you intend to delete.

data (any)

Returns

Promise<Object>: JSON payload returned from the API

Example

lms.$.delete('api/posts/delete/123456');

Ping

The ping module is a utility class used to determine service availability. WARNING: This module may be deprecated or subject to change. It's primary usage at this stage is for testing. Documentation will most certainly be dropped beyond the initial full release.

Ping

Extends LMSAPI

Instance Members

▸ checkHealth()

Checks service health. If a exception is returned then the service may not be available.

checkHealth(): Promise<string>

Returns

Promise<string>: Promise resolves to a string containing a success message

Example

lms.ping.checkHealth()
               .then(res => {
                 // Server is responding
                 })
               .catch((ex) => console.log(ex));

Auth

Methods for handling authentication. Usage of this module may not be needed. When making calls to the API using other modules in this sdk, authorization is handeled for you. This module is available if you would like to use it to make standard restful calls to the API outside of the SDK.

Auth

Instance Members

▸ token()

Creates a new token from the LMS API Authorization server and stores it on disk. Calling the method will return a promise containing the token. Subsequent calls will check the freshness of the token and create a new one if needed.

token(): Promise<Token>

Returns

Promise<Token>: Promise resolves to a Token

Example

lms.auth.token()
             .then((token) => {
                   //use token.authorization in a a Authorization header when making a restful API call.
                   })
              .catch((ex) => console.log(ex));

Users

The users module contains functions related to creating, reading, updating and deactivating users.

Users

Extends LMSAPI

Instance Members

▸ find(searchParams)

Search for users. If you only want to return 1000 users at a time, use the offset parameter. Otherwise all users will returned.

find(searchParams: Object): Promise<Array<User>>

Parameters

searchParams

(Object
            = {})

Object containing search parameters. See properties.

Properties

startdate (string) : Filter users by the date they were created. Should be a unix timestamp (ms) . Optional. Defaults to 0 (midnight 1970, UTC)

enddate (string) : Filter users by the date they were created. Should be a unix timestamp (ms) . Optional. Defaults to the current UTC time. (same as calling new Date().getTime() )

externalds (Array<string>) : Filters users by their externalId

ssoIds (Array<string>) : Filters users by their ssoId

emails (Array<string>) : Comma separated list of emails to return. Commas must be escaped for HTML. Each item will be executed as a fuzzy search, not an exact match. This means searching for @knowledgeanywhere.com will return any users with @knowledgeanywhere.com in their email.

includeInactive (boolean) : When true, inactive users will be included in the results set.

offset (int) : num of records to offset. Returns the first 1000 records of the collection by default ( offset: 0 ). A offset of 1000 ( offset: 1000 ) will return the next 1000 records.

Returns

Promise<Array<User>>: Resolves to a promise containing an array of users.

▸ findById(externalId)

Finds a single user by externalId. Resolves to a promise containing the user. If a user is not found with the specified externalId a 404 will be returned in the catch block.

findById(externalId: string): Promise<User>

Parameters

externalId (string) externalId of the user to be looked up.

Returns

Promise<User>: Promise resolves to a object containing the user.

Example

fortuna.user.findById()
               .then((res) => console.log(user))
               .catch((ex) => console.log(ex));

▸ create(user)

Creates a new user.

create(user: object<User>): Promise<Object>

Parameters

user (object<User>) User object to create. @see User

Returns

Promise<Object>: Promise resolves to a object. The warnings array will contain additional info about invalid data.

Example

fortuna.user.create(user)
            .then(res => {
                 // {
                 //  message: "USER_PROVISION_SUCCESS",
                 //  hasWarnings: false,
                 //  warnings: []
                 // }
             })
               .catch((ex) => console.log(ex));

▸ update(user)

Update a user. Partial updates are allowed and only the fields passed in will be updated. Note, updating email and externalId is not supported at this time. @see User

update(user: object<User>): Promise<Object>

Parameters

user (object<User>) User object to update. fortuna.user.create(user) .then(res => { // { // message: "USER_UPDATE_SUCCESS", // hasWarnings: false, // warnings: [] // } }) .catch((ex) => console.log(ex));

Returns

Promise<Object>: Promise resolves to a object. The warnings array will contain additional info about invalid data.

▸ deactivate(externalId, user)

deactivates a user.

deactivate(externalId: any, user: string): Promise<string>

Parameters

externalId (any)

user (string) externalId fortuna.user.deactivate(externalId) .then(res => { // user is deactivates } }) .catch((ex) => console.log(ex));

Returns

Promise<string>: Promise resolves to a success message.