Chris21 Integration

Version 0.2 - August 2017

Introduction

This document outlines how the Mumba Cloud App will integrate with Chris21 and what will be required throughout the integration process.

Initial Setup

Mumba requires access to Chris21's BRE SDK (refer to Frontier Software's "User's Guide BRE SDK" document version 1.2 for chris21 version 7.2+) using POSTs over HTTPS (as opposed to the XML Web Service).

Access

If required, we will provide your IT department with the appropriate IP ranges to open in order for our servers to communicate with your Chris21 BRE SDK.

Development Environment

We will need access to a development instance of Chris21 in order to perform User Acceptance Testing of our software releases (we do not link testing environments to production servers). This instance should be configured as closely as possible to your real production instance of Chris21.

It’s a requirement that you configure a system account in order for us to connect to the BRE SDK. We recommend that you rotate the system account password on a 90-day schedule, but we can work with your internal processes.

It’s important that you configure a number of test accounts that represent the general personas that we will need to test. These could include, but are not limited to, the following examples:

  • A general employee.

  • A manager of an employee.

  • A manager of a manager.

  • A user that needs special access to a sub-system (for example, to download leave reports).

Production Environment

You’ll need to configure a system account (separate from any development system account) in order for us to connect to the BRE SDK of your production instance. We again recommend changing the system account password on a 90 day schedule but we can work to your requirements. The password should be randomly generated, unique and use the maximum number of characters allowed by Chris21 (usually 20).

It is highly recommended that Mumba is granted a user login on your production system in order to help us diagnose issues as they arise however, we understand that this is not always possible. If we cannot be provided with a production user login, all testing and user issue triage will need to occur via one of your staff.

Reading User Profiles

We provide two ways to read a user's profile from Chris21 as follows:.

  1. Using information we store in Mumba when the user logs in

  2. Using information we get by querying Chris21 live

Stored User Profiles

In order for Mumba to be performant, we need to store parts of the user profile that are used most frequently by the application. This includes, but is not limited to:

  • the user's name,

  • a unique identifier for the user within your organisation, and

  • the user's organisational title.

Refer to Appendix A for a current list of the stored profile fields.

Live User Profiles

For any user information that is not authorised to be stored by Mumba, we can pull supplemental user profile information live from Chris21. Such information will never be stored on disk but may be stored in temporary memory caches in the user's browser or mobile app.

Refer to Appendix B for additional information known to be related to users.

Updating User Profiles

Mumba can update a user's Chris21 profile in one of two ways:

  1. live update, or

  2. delayed update.

At present, all users must use one option or the other. It is possible that future Mumba updates may allow for some updates to be split between both options, or only use the delayed update during scheduled times during the week.

Live profile update

A user's stored and user profile can be updated in Chris21 when the user saves the information. In this case we update both the stored user profile and make the appropriate calls to Chris21 tables to update selected date.

Note that we can restrict the fields that are allowed to be updated by the user. For example, the user does not have the ability to change their unique identifier, names or job titles through the Mumba application.

Delayed update

A delayed update may be required where user data needs to be locked in for long running system processes like pay runs. In this case, we can temporarily cache changes in our database and then run a batch of updates during an agreed window of operation.

It must be noted that in order to support this option we must temporarily store user data in the Mumba database.

The following outlines the process of how this works:

  1. The user updates their profile using the Mumba application (for example, changing their banking details for their pay).

  2. Mumba stores the Chris21 fields in a special holding table with a timestamp for when it was created.

  3. If a user goes to their profile page again, we blend our stored and live profile information with the data in the special holding table so they only see the information as if it was already updated in Chris21.

  4. A user can update their profile as many times as they like during the day.

  5. A scheduled task will run at an agreed time (usually overnight) and look at the holding table to check if there are any unprocessed records.

  6. If there are records, we look at how many Chris21 tables need to be updated. Typically this will involve ADR for address information, DET to update a user's email and PYD to change their bank details.

  7. For each Chris21 table, we check that the data is Chris21 is older than the information we have in the holding table. If we find that our data is older than the data in Chris21, we will record an exception. If it is, we update the data in Chris21.

  8. If Chris21 returned any sort of error during a table update, we will record the error in an exception.

  9. When we are finished processing the user record, we nullify all the values in the holding table for that user regardless of whether the update was successful or not.

  10. When the scheduled task finishes, we email a nominated party a report. If any exceptions occurred, we list the records that raised an exception, including all the data that the user supplied so that administrators can triage the problems by hand. Usually it's something silly like an invalid BSB number.

Appendix A - Stored user profile fields

Note that column labels can be customised to suit in the Mumba application. For example, "department" could be replaced with "Section" to suit the local vernacular within the organisation.

At a minimum, we need to store the user's unique ID, their name and usually their job title and location.

[INSERT TABLE]

Appendix B - Data mappings

Following are non-exhaustive data mappings known to exist in Chris21. Additional built-in and custom field may be available depending on how your instance is configured. The requirements for each case vary slightly and in those cases we will consult directly with your Chris21 specialist, or we can engage our regular Chris21 consultants to provide assistance

DET Table

[INSERT TABLE]

PDT Table

[INSERT TABLE]

POS Table

[INSERT TABLE]

ADR Table

Column

Description

Example

detnumber

Employee number

123456

adrtype

Address type

H

adrline1

Address line 1

adrline2

Address line 2

adrline3

Address line 3

adrstate

Address state

adrpstcode

Address post code

adrphone

Address phone

adrmobile

Address mobile

adrcntname

Contact first name

adrcntsur

Contact last name

adrcntrel

Contact relationship

adrcntphon

Contact phone number

LAC Table

Column

Description

Example

detnumber

Employee number

123456

laclvetype

Leave type

laccurtth

Leave balance