Midwinter Financial Services Developer Guide 3.0

API Program – Data Services Version: 3.0 Midwinter Financial Services Pty Ltd for AdviceOS

Andrew McClelland 19/03/2016

Document control Company

Title

Name

Role

MW

Head of Technology

Andrew McClelland

Approver

MW

Digital Product Manager

Halie Samson

Approver

MW

Senior Developer

Mark Farr

Approver

MW

Solution Architect

Scott Munro

Reviewer

(MW – Midwinter)

Document history Version

Date

Author(s)

Description

1.0

26 / 06 / 2014

Andrew McClelland

Initial Draft

1.2

10 / 07 / 2014

Andrew McClelland

Added Client web services

1.3

16 / 09 / 2014

Scott Munro

Added enterprise specific web services (ToE/ RFA

Midwinter Financial Services Pty Ltd

Page 1 of 56

Midwinter Financial Services Developer Guide 3.0 Update) 1.4

21 / 12 / 2014

Andrew McClelland

Document web services

1.5

31 / 03 / 2015

Halie Samson

Initial Calculator Output API Design

2.1

09 / 06 / 2015

Andrew McClelland

Updated Client web services

2.2

15 / 09 / 2015

Negar Ghanbari

Updated examples and Authentication wording

2.3

06 / 10 / 2015

Negar Ghanbari

Added info for example Authorisation project

2.4

15 / 10 / 2015

Andrew McClelland

Added test harness and further instructions

2.5

02 / 11 /2015

Andrew McClelland

Added File and File Data

2.6

19 / 11 / 2015

Negar Ghanbari

Finalised file data calls

3.0

19 / 03 / 2016

Sam Khanjar

Date

19/03/2016

Version

3.0

Author

Andrew McClelland

Status

Live version

Midwinter Financial Services Pty Ltd

Added FSGVersion / FSGDate and Segment to client group and individual services

Page 2 of 56

Midwinter Financial Services Developer Guide 3.0

Contents API Program – Data Services .................................................................................................................. 1 Version: 3.0 ..................................................................................................................................... 1 Midwinter Financial Services Pty Ltd for AdviceOS ........................................................................ 1 Andrew McClelland ......................................................................................................................... 1 19/03/2016 ...................................................................................................................................... 1 Document control ................................................................................................................................ 1 Document history ................................................................................................................................. 1

Overview...................................................................................................................................................... 5 Intended audience ............................................................................................................................... 5 Glossary............................................................................................................................................... 5 Authorisation ........................................................................................................................................ 7 Client access permissions ................................................................................................................... 8 Partner application process ................................................................................................................. 9 Sample project and code for authorisation .......................................................................................... 9 Sample project ................................................................................................................................ 9 Sample code ................................................................................................................................. 10 About the sample code and testing ............................................................................................... 10 Testing and development .................................................................................................................. 14

Midwinter API - Test Harness .............................................................................................................. 16 Using the tool ..................................................................................................................................... 16 Hints and tricks .................................................................................................................................. 17 Final warning on testing in the 1443 environment ............................................................................. 18 Working with Files and the API .......................................................................................................... 19 To get a list of files - FileData........................................................................................................ 19 To get data from one file (no user selection in source application) .............................................. 19 To retrieve a file - DownloadURI ................................................................................................... 19 To create (lodge) a new File – File................................................................................................ 20 Important notes when creating a file in AdviceOS ........................................................................ 21 To Replace a File – File (with ID) .................................................................................................. 21

AdviceOS CRUD services ....................................................................................................................... 23 Other Services ................................................................................................................................... 25 Client group ....................................................................................................................................... 26 Individual............................................................................................................................................ 28 Non-Individual .................................................................................................................................... 30 Member.............................................................................................................................................. 32 Manager approval .............................................................................................................................. 34 Relationship ....................................................................................................................................... 36

Midwinter Financial Services Pty Ltd

Page 3 of 56

Midwinter Financial Services Developer Guide 3.0 SOA (ToE Advice) ............................................................................................................................. 38 Terms of Engagement ....................................................................................................................... 40 User Account ..................................................................................................................................... 42 FileData ............................................................................................................................................. 45 File ..................................................................................................................................................... 48 Error Result messages ...................................................................................................................... 51

Midwinter Financial Services Pty Ltd

Page 4 of 56

Midwinter Financial Services Developer Guide 3.0

Overview The Midwinter Data Services API is a web services based API for integrating Midwinter’s AdviceOS software with 3rd party data sources. The services are written in C# and are hosted on the Amazon Web Services platform (in Sydney region). Currently the API supports Request Response and RESTful calls.

Intended audience This document is targeted at Development staff both Internal to Midwinter and 3rd party integrators. This documentation requires an understanding of the .Net framework and in particular the C# programming language, XSD, XML and Web Services.

Glossary The following terms will be used throughout the document Term

Description

AdviceOS

The application that hosts the web services outlined in this document

Source

The client application (3rd party to AdviceOS) that is making/originating the

Application

AdviceOS call

Source

The user (username and password) of the source application that is

Application

prompting the call (Note the application user is not an administration user)

User Source

A client ID to identify the source application in AdviceOS

Application ID Source

A URL provided to AdviceOS that is used as part of the authorisation of

Application

each web service call.

URL Secret Key

A code provide to the Source Application (by AdviceOS) to use as part of

Midwinter Financial Services Pty Ltd

Page 5 of 56

Midwinter Financial Services Developer Guide 3.0 the authorisation of each web service Token

A value generated by AdviceOS (using the Source application – ID and Secret Key) when the Source Application calls the authorisation service.

AdviceOS

The corresponding user in AdviceOS (ie a Source Application user who has

user

access to AdviceOS)

OAuth

Framework used to authenticate a web service call between AdviceOS and the Source Application

Authorisation

A simple (AdviceOS hosted) page that allows a Source Application (user)

page

to authenticate against AdviceOS... granting access to clients and data that the authorisation user in AdviceOS can access.

Authorisation

A Service hosted by AdviceOS that the source application calls when a

Service

user wishes to authenticate against their AdviceOS user. The Service can be accessed via Https://Adviceos.com.au/OAuth/Authorize...

Authorisation

A sample project built by Midwinter that can be used by 3rd Party

Sample Code

Applications to see what type of code is required in the source application to authenticate a user with AdviceOS

Test Harness

A tool provided by Midwinter that allows the user to replicate services into the test site and production site (“gets” only in production). It can authenticate using forms (your username and password) or Oauth – the authentication used in production.

Midwinter Financial Services Pty Ltd

Page 6 of 56

Midwinter Financial Services Developer Guide 3.0

Authorisation AdviceOS uses the Microsoft Identity Framework and implemented OAuth Authorization framework to authenticate and authorize each web service call based on the originating source user. AdviceOS Authorize requests from the Source application, based on following process  The Source Application prepares a request for user authorization from the authorization server. This request contains the Client ID (Source Application ID) and Secret and URL of the source Application (this request should be sent to the Authorize service of the authorization server).  Note: Client Access Controls 

Each business or practice in the Source Application will need at least one of its users to have a token to ensure they can only access clients/Data in that business/practice in AdviceOS. I.e. the user that the token is created for dictates the client data that the source application can access in AdviceOS using that Token.



If the authorisation request was valid (based on the Application Source ID and provided URL), the client will be redirected to login page of AdviceOS. Where they will enter their log in details and then on press of Login they will get the following screen...

Midwinter Financial Services Pty Ltd

Page 7 of 56

Midwinter Financial Services Developer Guide 3.0  Once the user press Grant button, if the client is valid based on the Client Id and Client secret provided, the browser will be redirected to the URL of source application with access token and refresh token.  The Source client application will use this access token to Authorize calls to AdviceOS web services from this user or (possibly any other user in the business with access to the clients in AdviceOS).  The Client Application can also make a refresh Authorization request to get a new access and refresh token (the current access and refresh token should be included in that request).

Client access permissions The AdviceOS web service uses the authenticated AdviceOS user to limit/restrict access (Read/write) to clients that the AdviceOS user can access. If the AdviceOS user cannot access the client via AdviceOS – then they will not be able to access the client (info) via a web service call. I.e. the same permissions that restrict access to clients in AdviceOS are used in the web service via the token that is used in the request. This will generally mean that each adviser who has a log in to AdviceOS and a Login to the Source Application may need to authenticate and have a token generated. It is possible to have one user in the practice/business/client hierarchy be authenticated and all other user are provided that token to authenticate – however client access will always be restricted to the user that authenticated the token.

Midwinter Financial Services Pty Ltd

Page 8 of 56

Midwinter Financial Services Developer Guide 3.0

Partner application process To be able to use the Midwinter Data Services – you must first register your application with Midwinter. We will then provide details on how to authenticate your calls to AdviceOS. Item

Answer

Company Name Application Name Application return URL Expected go live date for first web service Company Contact IT Person Company Contact IT Email Company Contact IT Phone

Please send information to [email protected]

Sample project and code for authorisation To make it easier for our partners to authenticate, Midwinter has provided the following sample code which has a sample project you can access. To access the sample project – please log into AdviceOS and go to the User Admin (bottom hyperlink from the home screen). Click on the documents tab along the top and select the folder for Midwinter. In the list of files you will see 3 starting with ‘API Program’.

Sample project If you do not have the sample project please contact Midwinter to request a zipped file. We will send you the file, which may aid in the OAuth process.

Midwinter Financial Services Pty Ltd

Page 9 of 56

Midwinter Financial Services Developer Guide 3.0 The sample project (which this sample code is based on) is written using visual studio and can be accessed by unzipping the file and opening using visual studio. This sample code uses DotNetOpenAuth library (if using in visual studio – please ensure you have a reference to this library).

Sample code The code below shows what you will need to develop in the source application to authenticate with AdviceOS. The following steps and sample code outline the requirements (which are in the sample project).

About the sample code and testing  The clientID and secrets in the examples will not work – you must contact Midwinter to get a client ID and secret - specific for your application  The clientgroupID in the example will not work – you must first call api/member to get a list of memberID’s and clientgroupIDs that will work with your particular user authentication.  The URL ports that you call will determine whether you are working in - staging (...:1443) or production (...:443 – or nothing)  

Midwinter recommends the use of 1443 at all times during testing. Note that the data in 1443 can and will reset back to the live data on a regular basis  For example – if you create a client in :1443 (post clientgroup) – this client will be removed when a deployment to production occurs (approximately every 2 weeks)  It is removed by replacing the data with the live data from production.  Midwinter recommends using 1443 (https://tartarus.adviceos.com.au:1443) at all times for testing.

First an instance of WebServerClient should be prepared. This instance should contain Client ID, secret and URL for AdviceOS Authorisation service.

Then a request to Authorisation server should be made to authorise the user.

Midwinter Financial Services Pty Ltd

Page 10 of 56

Midwinter Financial Services Developer Guide 3.0

Then the authorisation response from an authorisation server should be processed. The return type of ProcessUserAuthorization is the authorisation state that contains the details of the authorization like access and refresh token and expiration datetime for the access token.

Figure

1:

(overleaf)

–

is

a

picture

showing

the

results

of

making

the

ProcessUserAuthorization call. By putting the access token in web services request, that request will be authorised against AdviceOS and web service response will be returned. Figure 2. Shows a sample project screen after making a get by Id service call for a ClientGroup

Access tokens have short lifetime. These tokens can be refreshed by using long-lived refresh tokens and making RefreshAuthorization call. For refreshing token, client ID and secret should also be in the request.

Midwinter Financial Services Pty Ltd

Page 11 of 56

Midwinter Financial Services Developer Guide 3.0

Figure 1: Sample project after getting tokens from Authorization State (below). Shows sample project screen after making the ProcessUserAuthorization call. The user has entered the clientID and Client secret then pressed ‘Authorised’.

Figure 2: Sample project after make a Get service call for a ClientGroup

Midwinter Financial Services Pty Ltd

Page 12 of 56

Midwinter Financial Services Developer Guide 3.0 Note that to obtain a list of all available client codes – change the service URL to api/member – then use this list for gets on Clientgroup.

Midwinter Financial Services Pty Ltd

Page 13 of 56

Midwinter Financial Services Developer Guide 3.0

Testing and development Midwinter provides secure testing environments that uses real data (copy of live DB during a deployment). The authentication mechanisms are the same with just different URL’s for testing. The URL for the test environment is... https://tartarus.adviceos.com.au:1443 The URL for production is... https://tartarus.adviceos.com.au When a secret is requested – Midwinter will provide access to this testing environment only. A second request will be required to “open up”/allow the service to work in production for a particular partner. For approved groups the following resources are made available:  Documentation (this document) that includes calls and call parameters with example XML  Test URL’s to real data (copy of live data based on release cycles)  Test harness – a small application that (once authenticated) provides functionality to test XML Gets and posts etc.  Developer/BA support to assist (at call) Process for establishing a 3rd Party application as an approved partner to the AdviceOS web services  Request Approval to become a partner of Midwinter’s API program  Provide Midwinter with an Application Return URL  Midwinter will provide a Source Application ID  Midwinter will Provide a Source Application Secret Key  Midwinter will provide an authorisation service (URL) for the Partner to use – (staging environment  After the testing has been successful (for the partner application) – Midwinter will provide access to the production environment (i.e. same URL without the ‘:1443’ at the end). Although Midwinter provides a public (open) API – it is required that every partner has a relationship with Midwinter before access will be granted (to the 3rd party application). When developing a 3rd Party Application to consume AdviceOS web services – the following should be known/analysed first...

Midwinter Financial Services Pty Ltd

Page 14 of 56

Midwinter Financial Services Developer Guide 3.0  Is the data required from the service, mastered in AdviceOS (or synchronised from 3rd party)?  Will the 3rd party require identifiers (typically client identifiers) from 3rd party system to be persisted in AdviceOS – or will it adopt AdviceOS identifiers?  User/adviser hierarchy – will the 3rd party system force each user in a business to authenticate or have one user authenticate and other users in the business use that certificate? To view the XSD for Midwinter services refer to this document. You can also log into AdviceOS and click on the following... https://tartarus.adviceos.com.au/XSD/midwinter.xsd

Midwinter Financial Services Pty Ltd

Page 15 of 56

Midwinter Financial Services Developer Guide 3.0

Midwinter API - Test Harness The Midwinter test harness is a great resource to initiate your integration work and to aid in testing. To access the test harness – please log into AdviceOS and go to the User Admin (bottom hyperlink from the home screen). Click on the documents tab along the top and select the folder for Midwinter. In the list of files you will see 3 starting with ‘API Program’. The tool provides authenticated access (via Oauth or Forms) to the staging environment and the production environment. To limit any unforeseen or unintended data manipulation – the tool is limited to read only in production.... this means you can perform ‘Get’ or read operations in production (using the tool) but not post or deletes. If you would like to test posts and deletes – you must use the staging URL as this is uses a copy of production data – and if you make a mistake you will not be impacting your live data.

Using the tool Follow these steps to use the tool  Select the environment (Production – Https://adviceOS.com.au) or (Staging Https://adviceOS.com.au:1443) – remember you can only do ‘Get’ actions in production\  Select and enter the authentication details (Oauth or Forms)  Select the type of call required – refer to the CRUD services section for more info on each call

Midwinter Financial Services Pty Ltd

Page 16 of 56

Midwinter Financial Services Developer Guide 3.0  If you are testing a post (i.e. create or update) – enter the XML in the white box  Press the action button to the right  The yellow section will show the outcomes – it will provide a feedback message for Posts and deletes and the data (in XML format) for a Get.

Hints and tricks The test harness is used internally for testing all our web services and response messages.  If you are new and do not have your OAuth set up – you can use your user name and password under the forms authentication. This will allow you to get and post XML that you can check against the XML that you will be reading/writing to integrate with AdviceOS  We do not recommend you use forms to authenticate your web services – because any change of password will render the calls unusable.  To get started the best way to do it is to call a Get and then use that data as a post.  If you want to know all the Client and ClientgroupIDs - call the api/member to get a list of all clients that the user (used in the authentication) can access in AdviceOS In the example below – the user (Andrew.logs) has just entered the password and pressed get – which provides a list of all clients that can be accessed in AdviceOS (under that username).

Midwinter Financial Services Pty Ltd

Page 17 of 56

Midwinter Financial Services Developer Guide 3.0

Final warning on testing in the 1443 environment The data in the test environment is reset (back to the production state) approximately once per week. If you create clients or make any changes to data in this test environment – IT WILL BE LOST approximately once per week.  This may cause some confusion around testing – so please be on the look at for it.  if you have created or changed data in test environment today, and you go back in tomorrow to do a “GET” and the data is no longer there - it maybe because a production release has gone out overnight (which automatically resets the data in the test environment).

Midwinter Financial Services Pty Ltd

Page 18 of 56

Midwinter Financial Services Developer Guide 3.0

Working with Files and the API AdviceOS document storage (called ‘client records’) is exposed through the API via two services – FileData and File. If you want to retrieve a file or a list of files to choose from – use the FileData service. If you would like to update/create a file in AdviceOS – use the File service.

To get a list of files - FileData Make a Get request to the FileData service. This list can be filtered by clientID/ClientgroupID and/or Folder or Adviser. This can be achieved by adding the filter details in the call. This is generally used to provide a list of files that the source application user can then select (one) file to actually retrieve to the source application. For example API/FileData?ClientGroupID = X & Folder = SoAs This will retrieve all the SoA Files for the Clientgroup X. This list of Files can then be exposed in the source application for the user to select the actual file they would like to retrieve. Once the file is selected you can use the relevant URI to retrieve the file.

To get data from one file (no user selection in source application) If the source application knows the FileID (i.e. this is persisted in the source DB) – then a request to... API/FileData/X ...can be made which will return information about the file and a singular URI that can be used to retrieve the file (see below on how to download the file). This can only be used if the source application has previously retrieved the FileID. Generally, it is envisaged that the source application will call to display a list of files that can be selected for download and/or upload into the source application.

To retrieve a file - DownloadURI The filedata object that is returned from the Get request with ID parameter will include a DownloadURI. The DownloadURI can then be used to retrieve the file that is selected by the user in the source application. The URI is in the format of... Midwinter Financial Services Pty Ltd

Page 19 of 56

Midwinter Financial Services Developer Guide 3.0 https://midwinter-reasonablebasis-files-development.s3-ap-southeast2.amazonaws.com/98c42dd0-96bf-439e-bdfa080d99e2377f.docx?AWSAccessKeyId=AKIAJ6EJ7FNHW2CKFPBQ&Expires=1447308850 &Signature=QgYKJW4mjgPxIj3XcZ6fYH0eAXc%3D The source application can then download this file (like a hyperlink). You never need to create or build the URI – it will always be provided upon request. It is important to note that the hyperlink is only valid for ten minutes. I.e. – you cannot persist the hyperlinks/URIs in the source application and use to retrieve on demand. You can (however) persist the ID of the file and use the API/FileData/X format to get the URI for a specific file (without a selection process).

To create (lodge) a new File – File Creating a new file through AdviceOS Web Service is a three step process. The process is as follows 1. Source application make a Get request to api/file/GetURI/{fileName} (fileName Parameter contains Name of the file and extension for example api/file/GetURI/TestFile.docx In response AdviceOS provides a URI for uploading the file which is valid for 10 minutes. This URI is something like https://midwinter-adviceos-webserviceuploads-development.s3-ap-southeast2.amazonaws.com/TestFile.docx?AWSAccessKeyId=AKIAJ6EJ7FNHW2CKFPBQ&a mp;Expires=1447310289&Signature=bD%2BrPD00QKxQY%2BSa%2B8B1%2 FHTEslE%3D Note that if the media type of request header for this service call is “application/xml” or “text/xml”, in response “&” character would be replaced by “&”. 2. The source application uploads the file via provided URI. The file upload operation can be done with a PUT http method as follow

Midwinter Financial Services Pty Ltd

Page 20 of 56

Midwinter Financial Services Developer Guide 3.0

3. Now that the file is uploaded – an api/file Post call needs to be made to add the file data to the AdviceOS database which will link to the file that was uploaded. To update the database – the client application makes a post File service call, with the information such as name, description, extension, status, ClientGroupID and etc. this service will create the file record and search for the file in storage based on given information in the service call. api/file

Important notes when creating a file in AdviceOS  If source application does not make a post file call (step 3) after uploading the file (step 2), the file would be deleted from AdviceOS Storage (daily).  Uploading a file and then not creating a file record will have no impact in AdviceOS – the file and the file data must be set to create a valid file record in AdviceOS

To Replace a File – File (with ID) This process is exactly the same as creating a file (above) – except the file data includes a FileID in the header. The call will look something like this... API/File/X In this instance the file data will be updated – irrespective of whether a file has been uploaded or not. I.e. you can update the data of a file record – without needing to lodge a new file in the temporary location. If a file can be can be found, the service will replace (re-version) the current file with the new file and update the details of the file with the information in the body of the call. Warning – temporary storage bucket

Midwinter Financial Services Pty Ltd

Page 21 of 56

Midwinter Financial Services Developer Guide 3.0 Files uploaded in the step 2 of creating file process (in preparedness for doc storage) – will be routinely deleted. This location should not be relied upon for any redundancy or future access of documents in AdviceOS. Once a ‘post file’ call is made – and successfully matched to a file in the temporary bucket – it is moved to the permanent document storage section (as part of the post file service). Each day the temporary storage is deleted – hence any document uploaded that does not have a successful (and subsequent) post file call – will not be available in AdviceOS.

Midwinter Financial Services Pty Ltd

Page 22 of 56

Midwinter Financial Services Developer Guide 3.0

AdviceOS CRUD services The following table summarises the services available through the Midwinter APIs. Each service or resource can be consumed in different ways. Get (ID) – reads the resources based on the ID provided Get (without ID) – retrieves a full list of records for the resource Post (without ID) – create a new record for that resource Post (ID) – update an existing record – or create a new one (with that identifier) if it does not exist Delete (ID) – delete the record for that resource AdviceOS

Description

Get (id )

Get()

Service

Post()

Post(id)

Delete(i

create

Update

d)

New ClientGroup

Main “house hold” 









a 









SMSF/Trust/ 









all 









3rd 









advice

–

client

primary

spouse

and other entities Individual

A

person

in

client group Non Individual

A

Company

in

a

client group Member

List

of

members (individual/nonindividual) Manager

Requests party

to

task

Midwinter Financial Services Pty Ltd

Page 23 of 56

Midwinter Financial Services Developer Guide 3.0 Approval

management

for

compliance approvals / SoA etc Non advice client 

Associates

persons

























































and

organisations Relationship

Associates

and 

links to individuals and

non

individuals SoA

(ToE Status of advice 

Advice) Terms Engagement

(based on SoA) Of Status

of

client 

services agreement

UserAccount

Adviser or admin  staff in a practice/ licensee

FileData

File and file data  including filter by client, user, folder

File

Uploading a file to  AdviceOS

doc

storage

Midwinter Financial Services Pty Ltd

Page 24 of 56

Midwinter Financial Services Developer Guide 3.0

Other Services There are other services calls available – the following outline the more common ones. Service Signature

Summary

SplitClient (string id )

Call SplitEntity service for the Entity with specified ID

SwapClient(string id )

Call SwapIndividuals service for the Entity with specified ID

Midwinter Financial Services Pty Ltd

Page 25 of 56

Midwinter Financial Services Developer Guide 3.0

Client group Name

ClientGroup

Description

This is the core client group for a household – it is required to create a client (i.e. cannot create a client without a clientgroup). The group consists of one or maximum two individuals plus dependants plus non-individuals (Company/trust/SMSF).

Important – A client group consists of partner and spouse only i.e. clients that you can provide joint advice to. Parameters ID CRUD

Get(), Get(ID), Post(), Post(ID), Delete(ID)

operators

ClientGro up XSD



Midwinter Financial Services Pty Ltd

Page 26 of 56

Midwinter Financial Services Developer Guide 3.0

ClientGro up Example XML



Midwinter Financial Services Pty Ltd

Page 27 of 56

Midwinter Financial Services Developer Guide 3.0

Individual Name

Individual

Description

A person in a client group. All CRUD operations for individuals can be called directly or from the related client group.

Parameters ID CRUD

Get(ID), Post(), Post(ID), Delete(ID)

operators

Individual XSD



Midwinter Financial Services Pty Ltd

Page 28 of 56

Midwinter Financial Services Developer Guide 3.0

Individual Example XML



Midwinter Financial Services Pty Ltd

Page 29 of 56

Midwinter Financial Services Developer Guide 3.0

Non-Individual Name

NonIndividual

Description

A SMSF/Trust/Company in a client group. All Read/Update/Delete operations for non-individuals can be called directly or from related client group. Non-individuals can be created just from the client group.

Parameters ID CRUD

Get(ID), Post(ID), Delete(ID)

operators

NonIndividual XSD



Midwinter Financial Services Pty Ltd

Page 30 of 56

Midwinter Financial Services Developer Guide 3.0

NonIndividual



Midwinter Financial Services Pty Ltd

Page 31 of 56

Midwinter Financial Services Developer Guide 3.0

Member Name

Member

Description

List of (individual/ SMSF/Trust/Company) for current logged in user. This is generally used to match clients and client organisations in the Source application. Ie click on a client and the match button to bring up a list of members to select. Then persist the member identifier against the client in the source application.

Parameters ID CRUD

Get()

operators

Member XSD



Member Example



Midwinter Financial Services Pty Ltd

Page 33 of 56

Midwinter Financial Services Developer Guide 3.0

Manager approval Name

Manager Approval

Description

Requests to 3rd party task management for compliance approvals/SoA etc. Update, Read and delete operations can be called for a manager approval record.

Parameters ID CRUD

Get(ID), Post(ID), Delete(ID)

operators

Manager Approval XSD



Manager

Midwinter Financial Services Pty Ltd

Page 34 of 56

Midwinter Financial Services Developer Guide 3.0 Approval



Midwinter Financial Services Pty Ltd

Page 35 of 56

Midwinter Financial Services Developer Guide 3.0

Relationship Name

Relationship

Description

Links individual, non-individual and associates based on different types of relationship. PrimaryClientID determined the first side of relationship (Individual/non-individual ID), the second side of relationship is in “RoleMember” complex type, and it can be associate, individual or non-individual.

Parameters ID CRUD

Get(ID), Post(), Delete(ID)

operators

Relations hip XSD



Midwinter Financial Services Pty Ltd

Page 36 of 56

Midwinter Financial Services Developer Guide 3.0

Relations hip XML



Midwinter Financial Services Pty Ltd

Page 37 of 56

Midwinter Financial Services Developer Guide 3.0

SOA (ToE Advice) Name

SOA (ToE Advice)

Description

Status of advice (based on SOA). Update operation can be used to change the advice status to one of the valid SOA statuses.

Parameters ID CRUD

Post(ID)

operators

SOA (ToE Advice) XSD





Midwinter Financial Services Pty Ltd

Page 38 of 56

Midwinter Financial Services Developer Guide 3.0

SOA (ToE Advice) XML



Midwinter Financial Services Pty Ltd

Page 39 of 56

Midwinter Financial Services Developer Guide 3.0

Terms of Engagement Name

Terms of Engagement

Description

Status of client services agreement. Update operation can be used to change the terms of engagement status to one of the valid ToE statuses.

Parameters ID CRUD

Post(ID)

operators

ToE XSD



Midwinter Financial Services Pty Ltd

Page 40 of 56

Midwinter Financial Services Developer Guide 3.0

ToE XML

Midwinter Financial Services Pty Ltd

Page 41 of 56

Midwinter Financial Services Developer Guide 3.0

User Account Name

User Account

Description

Adviser or admin staff in a practice/ licensee. All CRUD operations can be done on user account from this service. Note the use of creating new users may result in costs being levied (for the new users being created). The use of this web service may be restricted to some applications.

Parameters ID CRUD

Get(), Get(ID), Post(), Post(ID), Delete(ID)

operators

User Account XSD



Midwinter Financial Services Pty Ltd

Page 42 of 56

Midwinter Financial Services Developer Guide 3.0





UserAcco unt XML



Midwinter Financial Services Pty Ltd

Page 43 of 56

Midwinter Financial Services Developer Guide 3.0

Midwinter Financial Services Pty Ltd

Page 44 of 56

Midwinter Financial Services Developer Guide 3.0

FileData The document storage functionality in AdviceOS is exposed through two resources – ‘FileData’ and ‘File’. FileData is used to Get (files and Data) whilst File is used to create or replace files. When you wish to retrieve a file from AdviceOS – the FileData call will provide a DownloadURI which has a ten minute window. I.e. after ten minutes the URI will no longer work (this is a security feature). So to get a file – determine the file(s) you need from the filedata call and then use the URI from the selected file. Refer to the section “Working with files and the API above for full instructions”. Name

FileData

Description

FileData is used for read access to the document storage in AdviceOS. All files are located in ‘Client records’ and this service allows read access to the data and to actually retrieve files/documents stored in AdviceOS. This is generally used to get the record/data for a list of files (filtered by client, client group, user, and or folder) and then make a secondary call to actually retrieve the file using the FileID. Note that you can only retrieve one file at a time – so a get call against FileData service with FileID parameter – will retrieve file data and an actual file URI whilst a get call against FileData service with ClientID,ClientGroupID, Folder,User filter parameters – will return just the data for the collection/list of files that meet the criteria. Note there is another service/resource called ‘File’ that will allow you to lodge/create files in the AdviceOS document storage.

Parameters Retrieve File Parameter = FileID Filter Parameters = ClientID, ClientgroupID, Username, Folder, CRUD

Get(ID), Get()

operators

FileData XSD



Midwinter Financial Services Pty Ltd

Page 45 of 56

Midwinter Financial Services Developer Guide 3.0





Midwinter Financial Services Pty Ltd

Page 46 of 56

Midwinter Financial Services Developer Guide 3.0

FileData XML



Midwinter Financial Services Pty Ltd

Page 47 of 56

Midwinter Financial Services Developer Guide 3.0

File

Name

File

Description

File service is used for create/update a file in the AdviceOS document storage. First source application should send a Get request to this URI api/file/GetURI/{fileName}. In response file upload URI would be provided. Then source application should send a Put request to File UploadURI with the file content. Then source application should notify AdviceOS about uploaded file via make a post request with the related information.

Parameters FileName FileID CRUD

Get(),Post(), Post(ID)

operators

File XSD



Midwinter Financial Services Pty Ltd

Page 48 of 56

Midwinter Financial Services Developer Guide 3.0





Midwinter Financial Services Pty Ltd

Page 49 of 56

Midwinter Financial Services Developer Guide 3.0



File XML

Midwinter Financial Services Pty Ltd

Page 50 of 56

Midwinter Financial Services Developer Guide 3.0

Error Result messages If there was an error in executing services, the error description will be presented in response. The list below is the list of possible common errors in web services. Service

Error Description

Cause

Name/mehtod Common Errors Get(ID)

No link record exists for For Get(ID) calls the provided ID does externalId { } for this user

not exist or user has not permission to access it.

Post(ID)

Entity to be updated from ID { For Post(ID) calls, there is no entity } does not exist for this user

based on provided ID to be updated from XML or user has not permission to access it.

Delete(ID)

No Entity found for ID {}

For Delete(ID) calls, there is no entity based on provided ID or user has not permission to access it.

Client Group Post() / Post(ID)

The defined Office Name {} There is no matching record for office does not exist.

based on provided office name in “OfficeName” property

Post() / Post(ID)

ClientGroup.FsgDate

is

required

when for the ClientGroup, FsgDate should

field

FsgVersion is specified. Post()

ClientGroup.Name required field.

Post() / Post(ID)

is

a When there is a FsgVersion property also exists. a Name property should be provided in creating client group.

Dependants ID should be Each client group can have a list of

Midwinter Financial Services Pty Ltd

Page 51 of 56

Midwinter Financial Services Developer Guide 3.0 unique

dependents. For these dependants unique ID should be provided.

Post() / Post(ID)

NonIndividuals ID should be Each client group can have a list of unique

non-individuals. individuals

For

unique

these ID

non-

should

be

provided. Post() / Post(ID)

The clientgroup cannot be When Creating a new client group or created

for

nominated

the

adviser updating an existing one, if an adviser

(mismatch

authenticated user)

with is provided in AdviserUser property, that adviser should be in the same practice with the current logged in user. Otherwise this error result will be returned as a response.

Post()

There is an existing Client When creating a new client group, Group link for ID {}.

provide ID should be unique in a database.

Post() / Post(ID)

The defined FSG Version {} When there is a value provided for does not exist.

FsgVersion property, that value should exist for one of the existing FSGs.

Post() / Post(ID)

The defined Adviser Name {} When Creating a new client group or does not exist.

updating an existing one, if an adviser is provided in AdviserUser property, that adviser username should exist in the database.

Post() / Post(ID)

The defined Marital Status {} When does

not

exist

for

creating

new

client

or

a updating an existing one, the value

relationship (2 clients) / a MaritalStatus non-relationship (1 client)

a

matched

property

with

the

should

be

number

of

individuals in the clientGroup and also exists in database.

Midwinter Financial Services Pty Ltd

Page 52 of 56

Midwinter Financial Services Developer Guide 3.0 Individual Post() / Post(ID)

The Individual {} Birthdate The birth date for the individual should must be at least one year be at least one year before the current ago.

Post()

date

There is an existing Individual When link for ID {}

creating

a

new

Individual,

provide ID should be unique in a database.

Post() / Post(ID)

The defined Health Type {} The value provided for the “Health” does not exist.

Post() / Post(ID)

The

defined

property should exist in database. Employment The

value

provided

“EmploymentType”

Type {} does not exist.

for

property

the should

exist in database. Non Individual Post() / Post(ID)

Non-Individual

type

required field.

is

a The type of non-individual should be provided

in

“NonIndividualType”

property. Post() / Post(ID)

The defined Non Individual The type of non-individual should be Type {} does not exist.

one of company/ Self-Managed Super Fund/Trust.

Post() / Post(ID)

The defined Trust Type {} If non individual type is trust the value does not exist.

provided

for

“TrustType”

property

should exist in database. Manager Approval Post(ID)

Manager Approval ID {} does For not parse as a GUID.

updating

current

manager

approval record, the ID Type is GUID and the value provided should be

Midwinter Financial Services Pty Ltd

Page 53 of 56

Midwinter Financial Services Developer Guide 3.0 parsed as this type. Post(ID)

The

defined

Manager The value provided for “Type” property

Approval Type {} does not should exist in database. exist. Post(ID)

The

defined

Manager The

value

provided

for

“Status”

Approval Status {} does not property should exist in database. exist. Relationship Post()

There

is

an

Relationship for ID {}.

existing When creating a new relationship, provide ID should be unique in a database.

Post()

There is not any matching When creating a new relationship, the member with ID {}

value provided for “PrimaryClientID” property

is

the

id

of

member

(individual/nonindividual) and should exist in database. TermsofEngagement Post(ID)

The modifier user of {} does When updating ToE from this request, not exist

value of “ModifiedByUser” property should be exist in database.

User Account Post() / Post(ID)

The defined Primary Office {} When creating a new member or does not exist.

updating an existing one, value of “PrimaryOffice” property should exist in database

Post() / Post(ID)

The defined User Status {} When creating a new member or does not exist.

updating an existing one, value of

Midwinter Financial Services Pty Ltd

Page 54 of 56

Midwinter Financial Services Developer Guide 3.0 “UserStatus” property should exist in database

FileData Get(ID)

No Entity found for ID []

There is no file based on given identifier or user does not have access to it.

File Get

– File Extension {} is not known

GetURI/{FileName}

The

extension

parameter

is

in not

the

FileName

recognized

by

AdviceOS. The value should be one of the

defined

values

in

the“ContentType” type. Get

– File Name should contain FileName

GetURI/{FileName} extension Post

format

should

be

{Name}.{Extension}

The specified key does not In exist.

creating

new

file,

AdviceOS

searches temporary bucket for finding file based on name and extension provided in the body of the post request. If it could not find any, it returns this error.

Post

To Lodge a file ClientID or In creating new file, if folder is ClientGroupID provided.

should

be specified in the body of the request, then at least one of ClientID or ClientGroupID should be specified.

Midwinter Financial Services Pty Ltd

Page 55 of 56

Midwinter Financial Services Developer Guide 3.0

Midwinter Financial Services Pty Ltd

Page 56 of 56