Migrating from earlier versions

The intent of this Migration Guide document is to help existing businesses seamlessly port their integrations with Stems API to Stems One API.

While Stems and Stems One are very similar products, there are some important changes that you will need to address before pointing your existing API Clients to Stems One.

1. Stems Accounts

As you probably already know, Stems One relies on Stems Accounts which is an implementation of the OpenID Connect 1.0 standards as identity layer that simplifies authentication, authorization and integration with Stems applications. In some cases, it also allows for Single-Sign-On (SSO) and Single-Logout (SLO).

If you were a user of previous versions of Stems, then all your business application data have already been migrated to Stems Accounts and Stems One. However, if your business had any API Client integration, you will need to create a new set of credentials before your integration can work with Stems Accounts.

The sections below explain how to migrate your existing API Client integrations to function with Stems One API.

2. Creating an API Client

The first migration step is to create a brand-new set of credentials that will allow you to obtain an Access Token and in some cases also a Refresh Token. The quickest way to port your existing integration to Stems One is by creating an API Client that uses the Resource Owner authentication flow.

However, the Resource Owner authentication flow is not the most robust (security-wise) authentication flow; other authentication flows such as Authorization Code and PKCE are more robust but they do require more effort to implement. To create an API Client, please follow the instructions on the Developer Guides.

This document will focus on migrating a Stems API client to integrate with Stems One API using the Resource Owner authentication flow.

2.1 Client Secrets

When creating a new API Client from your profile in Stems Accounts that uses the Resource Owner authentication flow, you will notice that after creating it you will not be able to choose a client secret; you will need to go back to the API Client details and generate a client secret.

Unlike previous versions of Stems, client secrets can only be seen in plain-text once and that is right after it has been created. You need to make sure you keep that plain-text secret in a safe location because Stems Accounts will not be able to retrieve an already-created client secret, at least not in plain-text format. If you ever lose a client secret, you can always generate a new secret.

2.2 Scopes

Scopes are an integral part of API Clients that grant certain permissions or privileges to the client. When creating or updating an API Client, you can register the scopes your client will need to request. If during an Authentication Request, you request a scope that hasn't been registered with the API Client you will receive an error.
For example, your API Client will (most-likely) need to retrieve user details and/or business details from Stems Accounts API. Therefore, you will need to register the resources_accounts_api scope in the API Client details page and then request that scope in the Token Request.

For more information on how to request a particular scope or multiple scopes, check the Authentication Request section

3. Migrating your API Client

This section guides you through the steps needed to migrate an existing Stems API client to a Stems One API client that uses the Resource Owner authentication flow.

3.1 Re-pointing URLs

Once you have registered your new API Client as described in (link here), you want to make sure your application code is pointing to correct Token Endpoint... 

https://accounts.stems.com.au/auth/connect/token

This is the URL you will use everytime you want to request an Access Token and it is the same url used to renew an Access Token

In addition to re-pointing the Token Endpoint url, you will need to change the URL of all calls to Stems One API to 

https://api.stemsone.com

For example, your API Client was retrieving a list of courses using the following URL in Stems API 

https://api.stems.com.au/courses

You will need to change the URL to point to Stems One API 

https://api.stemsone.com/courses
3.2 Business Information

Because all endpoints in Stems One API require the X-Company-Context header, you will need to know the IDs of the businesses your user account is associated with and set the X-Company-Context header value with one of these IDs...only one ID can be used at a time. This will ensure that your API calls are properly authenticated.

To retrieve a list of businesses your user account is associated with, you will need to make sure that:

  • Your API Client has been registered with the resources_accounts_api scope
  • You've included that scope in the scope parameter of the Token Request

Once you've done that and have received an Access Token successfully you can make an API call to the following endpoint in Stems Accounts API 

https://accountsapi.stems.com.au/companies/me

This will retrieve a list of all your companies/businesses and you can use one of their IDs to set the X-Company-Context header. Feel free to explore the rest of the endpoints available at Stems Accounts API

For more information about the X-Company-Context header, please read the Company Context documentation

Request Authentication

Note that unless it is explicitly stated that a specific endpoint can be called anonymously, all endpoints from all Stems applications' APIs need to be properly authenticated with a valid Access Token. For more information, please read the Authentication section of the Developer Guides.

4. Breaking Changes

If you are migrating from any version of Stems API and your API Client is using/calling any of the endpoints listed below, you might need to make some modifications to your application code based on the changes listed for that particular endpoint/operation and version.
Please note that some of the changes below might not apply to the version of Stems API you are currently using.

4.1 Classes

There has been a few schema changes to the Class and Student json schema

Schema Change Description Version
Class siteId property removed Replaced with orgStructureId 1.0, 3.1, 3.2
Class siteName property removed Can be replaced with orgStructurePath or you can fetch a list of all Org Structures to retrieve the name and other properties 1.0, 3.1, 3.2
Student employeeId property removed Replaced by personnelId 1.0, 3.1, 3.2
4.2 Employees

Since Stems API v4.0, the Employees resource and all its endpoints have been replaced with the Personnel resource in Stems One API. Please refer to the API Reference for more details.

The Personnel json schema is very similar to the Employee schema. The following describes the differences between Personnel and Employee json schemas and other changes related to the rest of the json schemas used by this resource.

Schema Change Description Version
Personnel lineManagerId property added This is a new property of the Personnel json object that represents the ID of another personnel acting as a Line Manager 1.0, 3.1
EmergencyContact employeeId property removed This has been replaced with the personnelId property 1.0, 3.1, 3.2
Payroll employeeId property removed This has been replaced with the personnelId property 1.0, 3.1, 3.2
WorkHistory employeeId property removed This has been replaced with the personnelId property 1.0, 3.1, 3.2
WorkHistory changedToRecordId property added This a new property of this json schema 1.0, 3.1
TrainingRecord employeeId property removed This has been replaced with the personnelId property 1.0, 3.1, 3.2

We have also added new endpoints to this resource...

Endpoint Description Version
POST /personnel/{id}/history Creates a new work history record for the specified personnel 1.0
PUT /personnel/{id}/history Update personnel work history on a specified date All
DELETE /personnel/{id}/history Removes a specific work history date from personnel record All

Please be aware that there were also some breaking changes to the Personnel resource. These are described in 4.7 Personnel section.

4.3 Org Structures

The following is a list of all schema changes to the json objects used by all endpoints in this resource

Schema Change Description Version
OrgStructure isDefault property added A boolean value indicating whether the org structure is the user's default or not All

In addition to the schema changes above, some endpoints have been added/removed

Endpoint Description Version
GET /orgstructures/sites This endpoint has been removed from Stems One API. You can use either the GET /orgstructures or the GET /orgstructures/hierarchy endpoints to retrieve Org Structures of type Site All
GET /orgstructures/hierarchy New endpoint to retrieves the current user's selectable organisation structure information in a hierarchy format All
GET /orgstructures/items Retrieves all orgsanisation structure items that are active (not archived) 1.0
GET /orgstructures/items/{id}/trainingrequired Retrieves all courses required for the specified Organisation Structure Item 1.0

For more information, please visit the Org Structure Resource documentation on the API Reference.

4.4 Training

The following is a list of all schema changes to the json objects used by all endpoints in this resource

Schema Change Description Version
Training employeeId property removed This property has been replaced by personnelId 1.0, 3.1, 3.2

For more information, please visit the Training Resource documentation on the API Reference.

4.5 Users

Users have now been moved to Stems Accounts and many of the functionalities exposed by this resource have been moved to Stems Accounts API. If your integration relies on User-related data, you will need to fetch it from Stems Accounts API and register the resources_accounts_api as explained in the 3.2 Business Information section.

The only endpoints exposed by this resource are related to Stems One permissions associated to the current user.

4.6 Events

This is a new resource that has been added in Stems API v3.1 to expose read-only data related to safety Event records.
The following is a list of all schema changes to the json objects used by all endpoints in this resource

Schema Change Description Version
Event supervisorEmployeeId property removed This property has been replaced by supervisorPersonnelId 3.1, 3.2
Event reportedByEmployeeId property removed This property has been replaced by reportedByPersonnelId 3.1, 3.2
EventGroup personInjuredEmployeeId property removed This property has been replaced by personInjuredPersonnelId 3.1, 3.2
4.7 Personnel

This resource was added in Stems API v4.0 as a replacement for the Employees Resource. In Stems API v.4.1, some important breaking changes were introduced.

Some of the properties of the request schema of PUT /personnel/{id} has been removed:

  • OrgStructureId
  • OrgStructurePath
  • LineManagerId
  • JobTitle
  • EmploymentLevel
  • EmploymentStatus
  • DateFrom

To update a personnel's work history now you can use PUT /personnel/{id}/history. For more endpoints and operations, please check the Personnel Resource in the API Reference.