Version 2.1, last updated: 25/11/2019

Ausmed 'Document CPD' Button - API Documentation

Ausmed's API provides an open endpoint for external websites and developers to integrate with so that users can submit activities directly to their Ausmed portfolio from third party websites.



Overview

The purpose of this service is to enable learners to document CPD gained from external websites in one click. This is an open API, no authentication is required. However, the user will be required to login in to their Ausmed account to document CPD upon landing on Ausmed.

This documentation covers the Ausmed websites and the smartphone apps.

There are three methods for integration:

  1. Javascript method (Recommended)
  2. HTML method
  3. Plugins

Supported Parameters

The following parameters are supported by both HTML and JavaScript integration.

URL ParameterData TypeValue/FunctionExample
titlestringTitle of resource being documented as a string.'Diabetes Lecture'
durationnumberDuration of time in minutes of activity (CPD/CE) being documented.30
providerstringName of provider as a string.'Ausmed'
typestringType of resource, matching one of the following values only (capitalisation matters): competency, event, inservice, meeting, mentoring, online, other, peerConsultation, postgraduate, procedure, reading, research, teaching.'procedure'
topicsstringA comma-separated list of topics or tags.'wound care,diabetes'
certificateURLstringThe direct download url of the user's certificate.'https://cdn.ausmed.com/cpd-button/Sample_Certificate.pdf'
educatorsstringA comma-separated list of educators.'Dr Jane Smith,Robert Johns'
resourceURLstringCanonical URL to the resource being documented.'https://www.samplewebsite.com/resource-one.html'

Important Information

The most important parameter is "resourceURL". If other params are provided except for "resourceURL", "document.referrer" will be used to get the previous website but it is not 100% accurate.

The more information provided the more accurate the documentation will be. If any parameter is not provided, we will try to get it through your webpage’s metadata but this may fail because of potential page protections (secure or logged in resources).

Called directly without any parameter? Because of technical limitations, if the URL "button/landing" is called directly without any parameter, a blank doc-flow will be opened and we will not try to get the previous website.

All URLs("resourceURL", "certificateURL") sent through query params must be encoded to ensure the URL is accurate. To encode the URL in javascript, use this function: encodeURIComponent().

Certificate sent through the URL must be public Otherwise, we cannot access and it will not be attached to the activity.

If the request is coming from a CPD button on our third-party resource and the provided "resourceURL" is 100% the same with the one stored in our third-party system, the website can match the URL with the third-party resource. The review will be stored under the id of the third-party resource.

Third-party resources are linked to the activity Currently, third-party resources are linked to the activity but external resources (from entities that are not content partners) will not be linked to activities.

The default domain used for documentation request is "ausmed.com". Re-login is required in some special situation. For example, if the customer is using a UK account in Australia and has logged into our website on domain 'ausmed.co.uk', then this customer clicks on the documentation button which uses default domain "ausmed.com". Since this customer is in Australia, this request will not be redirected to "ausmed.co.uk" automatically according to IP. This customer needs to log into the UK account again to redirect the request.

When providing a list of educators or topics Spaces should only be used in a name or a topic, such as "Jane Smith", "Mechanical Ventilation". However, no space should be placed between two names or two topics after ','. Here are some examples:
  • "Jane Smith,Jack Wang,Lucy Brown" (educators)
  • "Mechanical Ventilation,Clinical Nurse Specialist,Lipids and Metabolic" (topics)

JavaScript Method (Recommended)

The JavaScript method is the most popular way to integrate with Ausmed.



This method utilises similar technology to social media platforms whereby it extracts page meta data to facilitate documentation. It uses a basic JavaScript function to trigger the Ausmed 'Documentation Flow' (Docflow). It supports multiple layers of redundancy, including:

  1. Direct parsing of all Docflow attributes
  2. Page meta data
  3. Default Docflow

Note to Content Partners: The JavaScript method is recommended if you wish to collect reviews about your content.

Implementation

Step 1: Load the CSS by placing the following code in the <head> section of your website:

<link rel="stylesheet" href="https://cdn.ausmed.com/cpd-button/cpdButtonV1.css">

Step 2: Load the document JavaScript in the <head> section of your website:

function document(title, duration, provider, type, topics, certificateURL, educators, resourceURL) {
    // Encode URL so that the parameters don't get lost
    certificateURL = encodeURIComponent(decodeURIComponent(certificateURL));
    resourceURL = encodeURIComponent(decodeURIComponent(resourceURL));
    const url = `https://www.ausmed.com/button/landing?title=${title}&duration=${duration}&provider=${provider}&type=${type}&topics=${topics}&certificateURL=${certificateURL}&educators=${educators}&resourceURL=${resourceURL}`;
    window.open(url, '_blank');
}
document.getElementById("ausmedDocButton").onclick = function() {
    document('Sample Resource', 5, 'Sample Provider', 'online', 'sample topic', 'https://cdn.ausmed.com/cpd-button/Sample_Certificate.pdf', 'Jane Smith', 'https://www.samplewebsite.com/resource1');
};

3) Apply your preferred button style using the design options supplied below.

4) Ensure that your data/attributes are mapped to the correct fields in the document function.

5) Load the Ausmed button inline on your website where you wish to have it appear. Make sure you have the class="ausmed-document-cpd-btn" wrapper around your selected button.

<div class="ausmed-document-cpd-btn">

    // Your choice of button here...
    <a role="button" target="_blank" href="https://www.ausmed.com/button/landing?title=Diabetes%20Lecture&duration=32&provider=Ausmed&type=e-Learning&resourceURL=https%3A%2F%2Fwww.ausmed.com" class="ausmed-btn ausmed-btn-cpd" id="ausmedDocButton">Document CPD</a>

</div>

HTML Method

The HTML method is the simplest implementation. It uses a standard <a href=""> element to trigger the Ausmed Documentation Flow or "Docflow".



Implementation

The HTML method allows for unique values to be parsed to the Docflow using parameters appended to the end of the URL.

Step 1: Load the CSS by placing the following code in the <head> section of your website:

<link rel="stylesheet" href="https://cdn.ausmed.com/cpd-button/cpdButtonV1.css">

Step 2: Load the document CPD button using HTML inline on your website where you would like it to load.

<div class="ausmed-document-cpd-btn">
    <a role="button" target="_blank" href="https://www.ausmed.com/button/landing?title=Diabetes%20Lecture&duration=32&provider=Ausmed&type=e-Learning&resourceURL=https%3A%2F%2Fwww.ausmed.com" class="ausmed-btn ausmed-btn-cpd" id="ausmedDocButton">Document CPD</a>
</div>

Please note: we strongly recommend that you supply the resourceURL parameter. In cases where no parameters are provided, the Docflow will fall back to the standard manual CPD documentation process.

Button Examples

The CPD button has multiple styles and options all available from the linked CSS stylesheet.



Variations

We have provided a set of button styles to suit different website looks.

<a role="button" target="_blank" class="ausmed-btn ausmed-btn-primary" id="ausmedDocButton">Primary</a>
<a role="button" target="_blank" class="ausmed-btn ausmed-btn-dark" id="ausmedDocButton">Dark</a>
<a role="button" target="_blank" class="ausmed-btn ausmed-btn-light" id="ausmedDocButton">Light</a>

Badges

You have the choice if it is preferable to have a CPD or CE badge on your button.

<a role="button" target="_blank" class="ausmed-btn ausmed-btn-cpd" id="ausmedDocButton">CPD badge</a>
<a role="button" target="_blank" class="ausmed-btn ausmed-btn-ce" id="ausmedDocButton">CE badge</a>

Sizes

Depending on where the CPD button is place you might need to adjust the size of the button.

<a role="button" target="_blank" class="ausmed-btn ausmed-btn-primary ausmed-btn-lg" id="ausmedDocButton">Large button</a>
<a role="button" target="_blank" class="ausmed-btn ausmed-btn-dark" id="ausmedDocButton">Normal button</a>
<a role="button" target="_blank" class="ausmed-btn ausmed-btn-light ausmed-btn-sm" id="ausmedDocButton">Small button</a>

Please do not modify the button styles, logo or colours. Further information is available here: Brand Guide

Plugins

Wordpress

The wordpress plugin automatically integrates your website with Ausmed. Simply download the plugin from wordpress, and activate it to begin.

The 'Document CPD' button will appear at the end of any pages and posts in wordpress.

To download, please visit: https://en-au.wordpress.org/plugins/ausmed-document-button/#description.