Developer introduction

This document is intended to be a gentle introduction for programmers writing code that will interact with the OMS core system. It may also be useful for others wanting an overview of how OMS technical architecture enables organisations to extend it to meet their specific requirements.

OMS data is stored in a relational database, however to guarantee auditability and a consistant and sane business state no application ever directly connects to it.

Instead all access is via transactions that pass through several layers of logic running in OMS Java Enterprise (J2EE) server

The lowest layer modules provide the general algorithms, persistence and data integrity for a specific technical scope, such as "accounting".

Above this a business rules layer contains modules providing comprehensive transactions for business processes, such as renewing a subscription. Each transaction at this level is tested to ensure it is sane and the authenticated user is permitted to perform the transaction, then logged for audit purposes.

Above this are several standards based Web Service APIs. These wrap and bundle the transactions provided by the business layer to suit specific application purposes. All applications including core OMS utilities and the OMS Administration Client operate by transacting with them.

The OMS Administrative Client and OMS core utilities provided as part of the core OMS offering, are capable of performing the core financial and membership functions of a union.

However, because all the functionality they provide is done through documented web service APIs they can be replaced or augmented by other programs written in almost any modern programming language.

Since business rules and security are enforced within the OMS core these can be as simple as a short script or simple webpage.

This means a union can develop their own batch processes and custom workflows for administrative convenience and efficiency.

They can also integrate tools developed and contributed by other unions to provide entirely new capabilities, ranging from simple mailmerge templates to industrial case trackers.

It is necessary to authenticate with a username and password for all access to the APIs.

If you don’t already have one you can connect to the demo system as

The core OMS offering comes with several SOAP and REST web service APIs.

REST interaces use standard HTTP mechanisms and are particularly easy to use.

They can return data in a wide range of formats including: JSON, XML, PDF, HTML, spreadsheet.

Accessing data exports and reports is possible from any web browser & REST’s light weight makes it well suited to building user interfaces and simple batch scripts.

All the OMS REST APIs are documented in a single application.wadl and the associated schema definitions are available in an associated xsd.

SOAP interaces use HTTP POSTS to make transaction requests and receive the replies and status messages in SOAP XML. This formality makes them harder to use but well suited to complex business processes and business to business (B2B) exchanges.

OMS SOAP APIs are also self documenting in Web Service Description Language (WSDL). There are however two important differences to WADLs

While the OMS WSDLs and XSDs can be retrieved online, they need to be downloaded and slightly modified for use by your code.

To get you started this site contains some simple examples of using REST & SOAP in various platforms.

Every entity and relationship is assigned a universally unique identifier (UUID). This enables any extension or 3rd party system to unambuguously reference it.

Every entity and relationship can be assigned user defined extended attributes (name:value pairs) eg: "Nationality: Australian" for a person. This enables easy customisation of what the OMS core records

Every entity and relationship can be tagged with user defined keywords. These can be used for simple boolean attributes like "activist" against a person leveraged to set triggers for administrative processes such as "sending out a membership card.

While OMS primary role is as a membership system for unions, the data model does not revolve around "members"!

People can be recorded in OMS for any purpose: membership, contacts, employers, staff, politicians …​

Core attributes include things like: name, DOB, email, address …​

Groups can be created for any purpose: membership, delegates, committees, employers, supporters, …​ Groups only need a name, but OMS tracks extra data for some special types of groups.

Associations record periods when a person is a member of a group. They may have many relationships with many groups over many periods.

By recording a persons association with a group we know who is or was a member of that group at any point in time. OMS can have more than one membership group if required to cover many branches.

Accounts are the things OMS tracks money against. Usually some person is reponsible for paying it.

A current subscription may be required to access entitlements associated with some group.

The rate, period, account to be billed and payment method for a subscription renewal are determined by that persons current subscription agreement which itself may vary over time.

In OMS a persons union membership is modeled as an association between a person and a group at a period in time.

The membership will require a subscription that is renewed periodically & billed at an agreed rate for an agreed period to an account that a person (usually but not necesaarily the same person) is responsible for paying.

OMS utilities automatically renew lapsing subscriptions and bill the associated account.

Ideally the member will have provided an authority and EFT credentials so the OMS EFT systems can automatically collect and receipt payments from their bank account or credit/debit card.

All subscriptions and payments are recorded in an accounts receivable journal, that fully implements the accounting principles of: double entry, item offsets and reversal only.

This data enables a union to definitively determine whether a person was or wasn’t a financial member at any point in time according to its own financiality rules.

Like membership, employers are an extension of the group class. People may be associated with an employer in an employment

Worksites are an extension of an address. People can be associated with a worksite through an employment.

An OMS instance covers one or more Organisations.

There is no data shared between organisations so it is possible for two or more unrelated Unions to share the same infrastructure yet keep their data private.

Within an organisation there will be one or more administration units arranged in a hierachical branch structure.

While real entities like people and addresses are unique and shared across all branches of an organisation, business records such as branch membership accounts exist in the scope of a particular admin unit.

Each Administration Unit maintains user accounts with a password and authorisations. All transactions require an authenticated user account with the appropriate authority.

A user accounts scope is also restricted so it can only access membership data belonging to its own Administration Unit or one of its subordinate branches

While the relational database is only ever accessed within the core business rules the schema can provide a useful insight for OMS application developers into the underlying data abstractions.