Applies To: 

Technical Administrators.

 

Common Causes/Issues:

• You would like to learn more about what an API connector is and how it may be of value.
• You would like to learn more about the available API calls for Pinnacle Series.
• You would like to explore use cases for Pinnacle Series API connectors.
  
  

Solution Overview:

You might have heard about APIs and how they can be used to perform certain tasks or retrieve some data.

But what are these exactly, and why were they created?

Let me explain the problem with a simple, non-IT-related example.

You interact with the waiter when you go to a restaurant and order some food. You can order food and drinks, ask questions about the menu, request and pay the bill, and much more.

In this example, the waiter is shielding you from all the complicated stuff that happens behind the scenes. You don't have to worry about stoves, ovens, dishes, managing stock, or pouring drinks. Instead, he is the interface between you and all the services that a restaurant offers. In a way, the waiter can be seen as the API of the restaurant, and through this example, you intuitively understand why they are useful.

APIs (Application Programmable Interface) are sets of definitions and protocols that allow software components to talk and interact with each other using a simple set of commands. Acting as messengers, APIs deliver one application's request to another and return a response in real-time.

• If the server (the application providing the resource) can do what the client (the requesting application) asked, then the API will bring back the resource needed or a status code that roughly translates into mission accomplished!
• If the server can't do what the client asked — maybe the client requested a resource that doesn't exist or that it doesn't have permission to access — then the API will return with an error message.
• Controlling access to the server in this way is crucial. Rather than give you all of a program's information or code, an API provides you only with data that has been made available to external users.

What is an API key?

An API key is a unique identifier used to authenticate calls to an API. The key is made up of a string of letters and numbers that identify the client (remember, this is the application or site making the request). The key can grant or deny that request based on the client's access permissions and track the number of requests made for usage and billing purposes.

• By restricting access only to those with keys, a company can control the number of calls made to its API and ensure that only a specific, trusted group of clients can access its server's resources.

How will you benefit?

There are many types of API and the reasons why they are used.

Here are 4 main reasons why they are used:

• APIs can be used to get access to data from third parties.
  • Automatic transfer of relevant data between systems to streamline administration processes.
  • Create a two-way flow of information; automate tasks between systems, and display all account and training data in one place.
    
    
• APIs allow different apps and services to exchange information.
  • Aside from just accessing data, APIs can also be used to hide complexity and perform tasks.
  • APIs also offer an opportunity to boost productivity, streamline operations, foster collaboration, and strengthen transparency.
  • Automate repetitive tasks between Pinnacle Series and other systems without relying on the need for technical resources (i.e., Zapier)
    
    
• APIs can also be used to extend functionality (User satisfaction) – rarely can one platform satisfy and anticipate every need and expectation.
  
  
• APIs can be used as gatekeepers, protecting our personal data and only giving it out to the apps we choose.

As learning and training become more of a central activity in the corporate workplace, the ability to streamline processes and deliver contextual learning is increasingly important.

It is possible to utilize API's to push and pull data between systems to perform automated functions.

 

Data transfers include: 

• Requesting data from the server (GET)
• Posting new data to the server  (POST)
• Modifying data on the server (PUT)
• Deleting data from the server (DELETE)

On the surface, an API is any method made available by a system to allow third-party access to its data and functions in a programmable way.

 

Advantages of an API for Learning Management Systems

The benefits of APIs can range from the obvious to the not so obvious.

• It could allow employees to interact with a vast array of applications and experiences without leaving their LMS.
• It could help managers track learning activity taking place 'outside' the company LMS or other systems.
• It makes it possible to compare the learning effectiveness of different activities, possibly different services, in measurable ways.
• This includes data about all their learning activities, such as courses, mobile apps, social discussion contributions, and even offline learning experiences.
• It could help manage personal and other sensitive data, which can be hard to keep track of if stored in multiple places.

API connectors for reporting

• • This ability to collect and view data from different systems offers the opportunity to measure the impact of training as the data is viewed against project output data, for example.
  • Many organizations would also be looking to automate the collection of data and then connect that with an analytics platform like Tableau or Power BI or Integrate with financial reporting and accounting systems. 
    
    

API connectors for user provisioning

• • Access reliable personnel data from one source of truth. 
  • Enable separate internal and external login accounts.
  • Provide single sign-on (SSO) to other internal systems. 
  • Integrate with Microsoft 365, SharePoint, and Teams. 
    
    

API uses in Learning

• Learner Data and Tracking
  
  • One established use is tracking learner progress across different applications or systems. This allows one system to inform another system of the user's data using an API.  The benefit of this approach is that the learning does not need to take place on your Learning Management System or be managed by it. It can take place on another system and be accessed via an API. This data can be consolidated in a central Learning Record Store.
    • In theory, you can see how you might have hundreds of data points about an individual from many different systems. Such an approach could be used to design a personalized and adaptive learning program for individuals.
    • Using APIs for learner data demands an appropriate level of privacy. APIs must be designed to ensure that privacy is taken into account throughout the process.
      
      
• Surfacing Content and Creating Richer Experiences
  
  
  • One primary use of an API is to surface content wherever the learner needs it, such as an intranet, app, or sales academy. These content APIs enhance a user's experience by providing more expansive content from a range of sources, personalized and timely, such as articles published today on a specific topic.
  • By using APIs, an LMS, or another system, can surface content from multiple systems seamlessly and transparently; and create a much richer experience for your user. In the old days, all the content needed to be loaded onto a particular system or LMS. This is no longer the case, as an API can pull through and surface the content relevant to the user from multiple places.

• Embedding Assessment and other features
  
  
  • The KnowledgeSmart integration is a good example of this.

Swagger

Swagger is a set of open-source tools built around the OpenAPI Specification that can help Eagle Point Software design, build, document, and consume REST APIs.

The URLs are listed below, and the user can switch between v1 and v2 sites by changing the address line from 'v1' to 'v2' and vice versa and then selecting the explore button.

 

In order to pull reporting data from Pinnacle Series, please use V1 at this time.

Pinnacle Series BETA API Swagger Site

We strongly advise using the BETA site below first to identify possible programming bugs which may cause a looping process that can have negative ramifications for production users. Once you are confident that everything is working as expected in BETA, you could switch over to production to verify that you are pulling the data as expected.

 

https://prodgenapibeta.azurewebsites.net/swagger/ui/index#/Global

 

Pinnacle Series Production API Swagger Site

https://prodgenapi.azurewebsites.net/swagger/ui/index#/Global

 

V1 API Swagger Enhancements (August 2022)

• Added more documentation to Swagger to give a better and more accurate summary of each report.
• Added additional information if other parameters are required for the endpoint and how to use them.
• ApiKey and UserAccessKey were added to each endpoint in Swagger so testing can be done.

Please access our technical guide with detailed screenshots as per the link below:

Pinnacle Series API Technical Guide - V1 Authorization and Reporting APIs (PDF)

For video guidance in support of our technical guide please see the link below:

Pinnacle Series API v1 - Authorization and Reporting Guidance and Enhancements

 

Types of Actions

Below is a summary overview of the most popular types of actions the current Pinnacle Series API functionality offers. This is not an extensive list, so please reach out to our Support team or visit our Swagger site for a more detailed analysis. Please scroll to the bottom of this article for a link to our Swagger site for the actual API calls and further guidance.

 

Asset Libraries

• Retrieve a list of Asset Libraries.
• Retrieve a list of versions and products in asset libraries.
• Retrieve a list of versions and products in the asset library (to show what an organization is subscribed to view).
• Retrieve a list of content categories - This method will retrieve a list of categories for the content belonging to the tenant or the tenant and all of its subscription tenants.
• Retrieves all content for the organization - Use this method to retrieve all content (documents, workflows, videos, etc.) for the organization. You can supply parameters to narrow the results to just a certain number of content items, the content of a certain type, or content matching the search criteria.
• Find a content item by Asset ID - Use this method to return a specific content item. You must supply the contentId parameter.
• Authoring - to retrieve content modified by the user and the latest modified date.
• Determine whether a piece of content can be downloaded.
• Retrieve all comments for a content item.
• Deletes a comment that has been captured in the discussion board of a workgroup or for a specific content item.
• Retrieve a list of experts (also available per course).
• Retrieve the prerequisite courses for an existing learning path or course enrollment (Enrollment ID is needed).
• Retrieve a list of similar content.
  • You can supply parameters to narrow the results to just a certain number of content items, the content of a certain type of content matching the search criteria.
• Add a suggestion from the current user for a content item.
• Get a list of content suggestions.
• Retrieve a list of users that have recommended a specific content item.
• Retrieve all 'My documents' for the organization. Each user has the ability to create a personal. document to capture tips, workarounds, and suggested workflows, and it is possible to get a list of this content. You can also isolate a specific document based on a content ID.
• Retrieve a list of content products.
• Get a list of content changes. The longest retrievable range is two years. Larger ranges will be reduced by pulling the endDate closer to the startDate. (API v2).
• Get all content templates.
• Get a list of summaries for all Libraries.
• Adjust library visibility - "A Library can be set to be visible to all users or specific groups. If the first mode is chosen, you can specify whether the Library is shown to or hidden from all users. If the second mode is selected, you can specify a list of Groups to whom the Library should be shown.
• Get most popular content - Returns up to the 25 most popular content.
• Get a list of most frequently accessed content - Returns up to the 25 most recently accessed pieces of content by the current user. Items are guaranteed to be in the order of last access, with the first item in the array being the most recently accessed item.

Courses

• Identify all courses for the organization.
  • You can supply parameters to narrow the results to just a certain number of content items, the content of a certain type, or content matching the search criteria.
• Retrieve a specific course based on course ID.
• Retrieve all content for a course.
• Retrieve all the tools for a specific course.

Learning Paths

• Retrieve all learning paths for the organization.
• Retrieve a specific learning path.
• Retrieve courses for the learning path item.
• Retrieve all tools associated with the learning path.

Processes/Workflows

• Retrieve all processes, steps, or tasks for the organization.
• Isolate a specific workflow, process, task, or step.
• Retrieve the diagram view for the process or workflow item.
• Retrieve a list of tools associated with the workflow, process, task, or step.

Quizzes

• Retrieve all quizzes for the organization.
• Retrieve quiz questions and answers.

Videos

• Retrieve all videos for the organization.
• Retrieve a specific video.
• Retrieve videos for the learning path item.
• Retrieve all videos associated with the learning path.
• Retrieve all bookmarks for a video.
• Retrieve all tools related to a video.
• Retrieve the transcription for a video.

Enrollments

• Enroll the current user in the specified course.
• Retrieve all enrollments for the current user.
• Retrieve enrollments by content item (course, learning path, videos, workflows, live events, documents.
• Retrieve a specific enrollment.
• Retrieve a list of dropped enrollments.
• Retrieve the certificate of completion for a user (to maybe store that in another internal system).
• Bulk edit the due date of enrollments.
• Add multiple enrollments for multiple courses.

 User Provisioning

• SSO authentication.
• AD Synchronization for users and groups and set a sync schedule.
• Synchronize a user attribute.
• User profile – default settings i.e. language preference.
• Apply password policies.
• Authorize password reset requests.
• Translate languages.
  • Retrieve available languages for translation.
  • Translate text to a given language.
•  User information.
  • This method will retrieve some general information about a user based on their email address. Of the information returned, the most important is the list of valid tenants (databases) the user has permission to log into.

User Administration

• Get a list of notifications for the current user (perhaps you want to display the notification feed in your LMS).
• Retrieve a list of unread notifications for the current user.
• Retrieve job roles for the current tenant.
• Retrieve a list of users for the current tenant.
• Retrieve user information for a specific user (incl. whether they are excluded from SSO or AD sync).
• Retrieve user external data (user attributes).
• Retrieve frequently used content for the current user.
• Retrieve settings for the current user.
• Retrieve a transcript for a specific user - A transcript summarizes all courses a user has been enrolled in. It will give the Learning Path and Course names, the enrollment status (Completed, Dropped, In Progress), Date of Completion, and Viewing Time for the course materials. Use this method to return the transcript for the current user. The returned string will be the blob storage location of the PDF transcript file.
• Retrieve a list of workgroups that a specific user is enrolled in.
• Get a list of users that have the right to add external users to a workgroup.
• A list of users with editor/owner rights in work groups.
• Get a list of groups (API v2) - There are two levels of detail available when listing all groups: Micro, or Mini.
  • "Micro\" provides name, type, and identifier data about a group.
  • "Mini\" provides additional basic information that allows a list of groups to be sorted, searched, and filtered.
• Retrieve a specific group - There are three levels of detail available for groups:
  • Micro - provides name, type, and identifier data about a group.
  • Mini - provides additional basic information that allows a list of groups to be sorted, searched, and filtered.
  • " - provides all information about the group and is suitable for detailed views.
• Modify group-associated learning.
• Add children to a group (API v2).
  • Groups can be organized in a hierarchy to facilitate career paths, shared inheritance, and content discoverability. A group may only have one parent but can have any number of children. If you specify a group that already has a parent, the current parent will be replaced. You cannot set any ancestor of this group as a child of this group.
• Remove a child from a group.
• Add members to a group.
• Get all group permissions.
• Get or modify group properties from a tenant.
• Get or modify user properties from a tenant.
• Get a full list of settings.
• Get general settings of the current tenant.
• Get a detailed list of users based on three levels. (API v2).
  • Micro - provides name, type, and identifier data about a group.
  • Mini - provides additional basic information that allows a list of groups to be sorted, searched, and filtered.
  • " - provides all information about the group and is suitable for detailed views.
• Get a list of associated Learning for the current user.
• Creates, Modifies, and Deletes users from import.
• Retrieve and modify a list of synchronized groups.
• Add a rule set based on user attributes.
• View a list of all rule sets.

Live Events

• Get a list of prerequisites a user has not completed.
• Get the responses provided for a session.
• Retrieve registration information.
• Retrieve survey responses.

Workgroups

• A list of work groups for the current tenant.
• Asset usage for the current work group.
• Completed learning for the current work group.
• Retrieve a list of content in the current work group.
• Retrieve the order of content in the current work group.
• Retrieve a list of members for the current work group.
• Retrieve a list of external members for the current work group.
• Update member permissions.
• Remove a member from a work group.

 

Related Article(s):

KnowledgeSmart API guidance

Configure Pinnacle Series for KnowledgeSmart Integration

Managing Assessments for Personalized Learning

 

Pinnacle Series Resources:
Pinnacle Series API Technical Guide V1 Authorization and Reporting (PDF)
Pinnacle Series API v1 - Authorization and Reporting Guidance and Enhancements

Configure Pinnacle Series SSO (OpenID - Okta)
Configuring Synchronization with Microsoft AzureAD - Browser Admin
Creating Azure App and SSO
Configuring KnowledgeSmart Integration - Browser Admin

 

Still Need Help? 

Log a support ticket