3rd Party Content Connectors

NOTE: This is only for customers that have opted to license one or more Rustici Engine 3rd Party Content Connectors.

Installing

Content Connectors rely on the database schema as defined by Engine, so no additional database installation/upgrade steps need to be performed.

Loading

To enable the Content Connector(s) the Plugins configuration value in the RusticiEngineSettings.configRusticiEngineSettings.properties file needs to be added or updated to include a value based on the licensed connector name, i.e. ContentConnector.Go1. The value is a comma delimited string accepting a list of plugin names.

Content Connectors must be configured at the system level because the code is loaded at startup. Engine will fail to start if either there is an invalid value for the Plugins setting, or if the setting is valid but a plugin that is intended to be loaded is not found. Because plugins rely on core functionality available in Engine, each plugin has a minimum required version of Engine that it needs to function properly. If this minimum version is not detected when the plugin loads, then Engine will not start. You can contact Rustici support to get an Engine upgrade that will work with the given plugin version.

When properly loaded by Engine, there will be a contentConnectorTypes entry in the /about API resource response for each type of Content Connector.

Configuring

Each Content Connector may require specific configuration values to be provided in order for it to function.

Go1

Before setting up the Go1 connector, you will need to obtain the following from Go1:

• API keys
• A list of content group IDs for the content to be made available through the connector
• We recommend ensuring Go1 has enabled "password grant" authentication for the client associated with your API keys. This allows the connector to connect to existing portals (otherwise it can only connect to a portal created with the connector), and to automatically re-connect if something goes wrong during an authentication key refresh. In order for this to work you will also need to set up the recommended Go1PortalAdminEmail and Go1PortalAdminPassword settings.
• If you are going to connect to any existing portals, ensure that the user with the email Go1PortalAdminEmail is an administrator on those portals.

-For the Go1 Content Connector to function the following configuration values should be set:

• Go1ApiKey - API consumer key (required)
• Go1ApiSecret - API consumer secret (required)
• Go1PortalAdminEmail - Email for a user to be added as an administrator to each portal created. (recommended)
• Go1PortalAdminPassword - Password associated with the user added to portals upon creation, used to reconnect to portal if there is a token refresh issue. (recommended)

The above setting values are used to communicate with the Go1 API through the Engine interface.

Below is an example of the configuration to be passed when setting up a Go1 connector (see "Creating a Content Connector Instance"). This includes all the information needed to create a portal, and should be used both for connecting to an existing portal, and for when a new portal should be created.

{
    "contentConnectorType": "ContentConnector.Go1",
    "configuration": {
        "sort" : <sort order for results connector returns in remote search call. Defaults to "relevance:desc, title" See Go1 API documentation for valid values>,
        "collection" : <"default" to limit results to default collection (as set up in the portal), otherwise leave this property out>,
        "portalSetup": {
            "customer": {
                "industry": "<industry of company this portal is being set up for, API will return valid list in error message>",
                "name": "<name of company this portal is being set up for>",
                "country": "<country of company this portal is being set up for>"
            },
            "creation_path": "integration",
            "portal": {
                "domain": "<domainPartForCompanyPortalIsBeingSetUpFor>.mygo1.com",
                "seats": <integer expected number of learners to use portal being set up>,
                "content_group_ids": [<comma delimited list of IDs provided to you by Go1>]
            },
            "user": {
                "first_name": "<first>",
                "last_name": "<last>",
                "email": "<email of user from your customer who will own the portal you are setting up for them>",
                "consent": {
                    "term_collection": true,
                    "term_privacy": true,
                    "term_tos": true
                }
            }
        }
    },
    "enabled": true
}

Creating a Content Connector Instance

In order to use the functionality of a Content Connector, you must create an instance of it. To create an instance of a Content Connector, make a POST request to the /api/v2/contentConnectors resource. This request should include the type of Content Connector, whether or not the instance is enabled, and any Content Connector specific configuration required. The response for this request will contain an identifier that should be tracked in your application so that you can make additional API calls for this instance.

Content Connector instances can be queried, updated, and deleted through the normal REST conventions.

Searching for Content

With one or more instances available, you can search for content using a POST request to the /api/v2/contentConnectors/remoteSearch resource. This resource can be used to search for content from all available instances (multiple content vendors) or from a single instance at a time. This search can also be made on a per-tenant basis, or for content specifically configured on a system-wide basis.

When a search using this resource is initiated, an API call is made to the content partner APIs, and the results are aggregated into a single list. This list may be paginated if there are a large number of results. If a particular content partner's API doesn't return results quickly enough, then that content partner's results will be left out of this query.

The results returned by this API call include a list of objects that contain details for each specific piece of content and the content connector instance providing it. The details for the content include an identifier for the content that will be used in the import process, as well as metadata about the content, such as title, description, duration, keywords, etc. Additionally, it may include plugin-specific metadata with a format that depends on the content connector type associated with the content item.

Importing Content

Once you've found a piece of content from a connector that you want to use, take the identifier value for that content and make a POST request to the /api/v2/courses resource. The body of that request must include an object in the connectorReferenceRequest property whose properties include the Content Connector instance identifier (connectorId), as well as the identifier for the content (connectorIdForContent). This request is similar to other Engine import requests and must also include a courseId value in the URL parameters.

Once the content has been imported through this mechanism, it can be launched, played, and tracked through Engine in the same way any other standards-based content is handled.