Web Services Integration

Many hospitals and healthcare organizations store user information in an external system such as an HRIS, SRS or CRM. Dual Code's HCE learning environment allows interaction with these external systems using secure web services, which are a set of functions that can be called by an external system over a secure protocol.

Enabling Web Services

For security reasons, all web services are disabled by default in the learning environment and can only be enabled by Dual Code.

Prior to enabling the web services, a Dual Code Implementation Specialist will discuss your use cases to better understand which web service(s) you need. Dual Code will then enable the appropriate web service(s), leaving non-essential web services disabled for security reasons. Dual Code will also only enable the specific protocol that is to be used for your particular integration.

Once the web service(s) enabled, Dual Code will create a dedicated user account and authorize that account to use the enabled web service(s). A dedicated user account is typically created for each external application wishing to make remote web service calls to the learning environment. For security reasons, only these dedicated, pre-authorized user accounts will be able to make calls to the web services. Through these dedicated user accounts, you will be able to manage the web service security keys (e.g. tokens) assigned to the user account, access the documentation for the web service functions, and call the available web service functions using the enabled protocol.

List of Web Services

Dual Code's learning environment offers a wide range of web services. With dozens of web services and more than 500 function calls available, you can rest assured that our web services framework can support most use cases required by our clients. Dual Code's Implementation Services team can develop additional web services upon request.

While this public web page does not provide a complete list of web services, the following web service is a typical / popular one used by many clients who want to integrate an HRIS, SRS or CRM to the Dual Code learning environment.

Service: SRS Web Service

Functions:

core_user_create_users
core_user_get_users
core_user_update_users
enrol_manual_enrol_users
enrol_manual_unenrol_users

Supported Protocols

The learning environment web services support the following protocols:

REST. The REST service implementation accepts GET/POST parameters and return XML/JSON values.
SOAP. The SOAP service implementation is based on the Zend SOAP service, which itself is based on the PHP SOAP service. Zend publishes a Zend SOAP client.
- NOTE: The current web service implementation does not support Java/.Net. In order to add support for Java/.Net, Dual Code would need to generate a fully described WSDL for the web service.
XML-RPC. The XML-RPC service implementation is based on Zend XML-RPC server. Zend also publishes a Zend XML-RPC client.

Integrating with Web Services

All the information you need to integrate to the services are available from the "Security Keys" section of your preferences menu.

Go to User Menu > Preferences
Click on "Security keys"

If you do not see "Security Keys" in your preferences, it's because you did not log in the learning environment using the dedicated user account that has been pre-authorized to call the web service.

The "Security Keys" page allows you to:

Manage / reset your security keys (e.g. tokens)
Access the documentation for the web services

Managing Security Keys

Security keys can be generated from the browser or via curl.

To generate a security key via the browser, simply log in the learning environment using the dedicated web service account and go the Security Keys page mentioned above. The security key for each web service you have access to is displayed on the page. You can also reset the token from this page.

To generate a token via curl, you would call /login/token.php and pass in the username, password, and the shortname of the service. For example, to reset a token for a service called "srs_web_service":

$ curl "https://your.site.com/login/token.php?username=...&password=...&service=srs_web_service"

Using the example above, you would customize the parameters "username" and "password" with the credentials of the user who has the permission required to create tokens. (This function call will not work unless the user in question has elevated capabilities.)

Please note the following:

All requests must be in HTTPS.
The user making the request must have elevated capabilities.
The key is specific to the user in question.
The key is specific to the service in question.
If the key expires, you can regenerate it via the Security Keys web page or the curl function call.
You CANNOT reset your key if it was generated by another user with more administrative permissions than you. You will need to contact the "Creator" of the key (identified next to the key in question) and ask them to reset it for you.
If you change the user's password, the key will also be automatically regenerated.

Given the last bullet point above, we recommend that the dedicated user account's password be changed on a regular basis and anytime you fear the token may have been compromised. Changing the dedicated user account's password, which in turn automatically regenerates the token, will block access to any user who may have had access to the compromised token.

Accessing the Documentation

The documentation for the service will be available from the same "Security Keys" page.

Below is a sample documentation for the "iMIS Bridge Web Service", which contains 5 function calls.

By clicking on any of the functions, you can see the list of arguments that the function can accept, as well as the format of response and error messages. Below is an example of the imis_core_user_create_users using the REST protocol.

Create users.

Arguments
users (Required)

General structure

list of (
object {
username string //Username policy is defined in Moodle security config.
password string Optional //Plain text password consisting of any characters
createpassword int Optional //True if password should be created and mailed to user.
firstname string //The first name(s) of the user
lastname string //The family name of the user
email string //A valid and unique email address
auth string Default to "manual" //Auth plugins include manual, ldap, imap, etc
idnumber string Default to "" //An arbitrary ID code number perhaps from the institution
lang string Default to "en" //Language code such as "en", must exist on server
calendartype string Default to "gregorian" //Calendar type such as "gregorian", must exist on server
theme string Optional //Theme name such as "standard", must exist on server
timezone string Optional //Timezone code such as Australia/Perth, or 99 for default
mailformat int Optional //Mail format code is 0 for plain text, 1 for HTML etc
description string Optional //User profile description, no HTML
city string Optional //Home city of the user
country string Optional //Home country code of the user, such as AU or CZ
firstnamephonetic string Optional //The first name(s) phonetically of the user
lastnamephonetic string Optional //The family name phonetically of the user
middlename string Optional //The middle name of the user
alternatename string Optional //The alternate name of the user
preferences Optional //User preferences
list of (
object {
type string //The name of the preference
value string //The value of the preference
}
)customfields Optional //User custom fields (also known as user profil fields)
list of (
object {
type string //The name of the custom field
value string //The value of the custom field
}
)}
)

REST (POST parameters)
users[0][username]= string users[0][password]= string users[0][createpassword]= int users[0][firstname]= string users[0][lastname]= string users[0][email]= string users[0][auth]= string users[0][idnumber]= string users[0][lang]= string users[0][calendartype]= string users[0][theme]= string users[0][timezone]= string users[0][mailformat]= int users[0][description]= string users[0][city]= string users[0][country]= string users[0][firstnamephonetic]= string users[0][lastnamephonetic]= string users[0][middlename]= string users[0][alternatename]= string users[0][preferences][0][type]= string users[0][preferences][0][value]= string users[0][customfields][0][type]= string users[0][customfields][0][value]= string

Response
General structure
list of (
object {
id int //user id
username string //user name
}
)
XML-RPC (PHP structure)
Array ( [0] => Array ( [id] => int [username] => string ) )
REST
<?xml version="1.0" encoding="UTF-8" ?> <RESPONSE> <MULTIPLE> <SINGLE> <KEY name="id"> <VALUE>int</VALUE> </KEY> <KEY name="username"> <VALUE>string</VALUE> </KEY> </SINGLE> </MULTIPLE> </RESPONSE>

Error message

REST
<?xml version="1.0" encoding="UTF-8"?> <EXCEPTION class="invalid_parameter_exception"> <MESSAGE>Invalid parameter value detected</MESSAGE> <DEBUGINFO></DEBUGINFO> </EXCEPTION>

Restricted to logged-in users
Yes

Callable from AJAX
No

Simple REST Request Example

To quickly test that a web service has been properly configured and is accessible, you can: visit the service end point from your browser, invoke the web service method from the command line using curl, or use your preferred web services test client (such as Postman).

For example, to make a REST call to a function from the command line using curl:

$ curl "https://your.site.com/webservice/rest/server.php?wstoken=...&wsfunction=...&moodlewsrestformat=json"

In the example above, you would customize the parameters "wstoken" and "wsfunction" to match the server-side setup. You can also append additional parameters for the function call as needed with "&parameter_name=param", or if your parameter is an array then use "&array_name[index][parameter_name]=param". With the core_user_create_users function's (required) parameters for example:

$ curl "...&moodlewsrestformat=json&wsfunction=core_user_create_users&moodlewsrestformat=json&users[0][username]=testuser&users[0][firstname]=Jane&users[0][lastname]=Smith..."

The moodlewsrestformat query string parameter can be used to specify whether the response should be returned in XML (default) or JSON format.

Auditing Web Service Events

Various event logs are generated whenever web services are used. These logs can be seen in the Extended Log Search report by filtering on the following events:

Web service created
Web service deleted
Web service function called
Web service login failed
Web service token created
Web service token sent
Web service updated
Web service user added
Web service user removed

As an example, if a dedicated user account called "Web Service API" were to create a user called "Jane Smith", the following event logs would be available and visible via the Extended Log Search report.

HCE Standard