jmbo-neo 0.4.5.1
Jmbo Neo Web Services integration app.
License: BSD

jmbo-neo
========

jmbo-neo provides integration with Neo Web Services for jmbo and jmbo-foundry. It syncs jmbo-foundry's Member objects with consumers
in the Neo data hubs. Syncing refers to the creation, modification and deactivation of Neo consumers as Member objects are created, modified
and deactivated.

Authentication-related actions are also performed via Neo Web Services. These include logging in and out and changing passwords. jmbo-neo also
supports a number of other Neo API calls. These, in addition to the above mentioned, can be invoked as necessary in other jmbo apps.

Requirements
------------

System libraries
****************
- libxml2-dev
- libxslt-dev

Python packages
***************
- python-lxml
- requests

*jmbo-neo uses generateDS.py (http://cutter.rexx.com/~dkuhlman/generateDS.html) to generate Python classes from Neo XML schemas.*

Usage
-----

`neo.api` contains functions for all the supported Neo API calls. Consumer calls require either a consumer ID or consumer object (or both).
If a consumer has been created for a particular Member, a corresponding NeoProfile object will be stored in the database. So to obtain the
consumer ID, use `neo.models.NeoProfile(user=member.id).consumer_id`.

A consumer object is an instance of `neo.xml.Consumer`. Consumer should not be instantiated directly. Internally, jmbo-neo uses `neo.xml.parseString(response.content)`
to create a consumer object from the XML return by Neo Web Services. This object will be returned when calling, for instance, `neo.api.get_consumer`.
To access this consumer object, you should use the wrapper class `neo.utils.ConsumerWrapper`. It has all the necessary getter and setter methods to correctly
manipulate the consumer object, ensuring the resulting XML is valid.

**When using jmbo-neo, all non-required Member fields will be null, or set to their default values. Queries on Member objects
will return incorrect results.**

Settings
********
The following settings must be added to settings.py::

    NEO = {
        'URL': 'neowebservices.com/service/'
        'APP_ID': '1',
        'VERSION_ID': '1.3',
        'PROMO_CODE': 'testPromo',  # if there is a single promo code for the website
        'BRAND_ID': 35,  # if there is a single brand for the website
        'PASSWORD': 'password',  # http basic auth password
    }

    AUTHENTICATION_BACKENDS = ('neo.backends.NeoBackend',)

To-do
-----

1. Replace generateDS.py with `lxml.objectify`.
2. Mock testing calls to Neo API using `mock`.
Authors
=======

Praekelt Foundation
-------------------

* Rizmari VersfeldChangelog
=========

0.4.5.1 (17-01-2014)
--------------------
#. Increase upper limit on jmbo-foundry version.

0.4.5 (23-10-2013)
------------------
#. Log all API calls. Uses `neo.api` logger.

0.4.4.1 (28-09-2013)
--------------------
#. Add `ModifyFlag` to empty `Answer` element. Invalid otherwise.

0.4.4 (28-09-2013)
------------------
#. Add `answer_set` to `QuestionAnswerWrapper` for adding answers in bulk.

0.4.3 (18-06-2013)
------------------
#. Don't create consumer on member load - issue for views with many members and unmigrated accounts.

0.4.2 (14-06-2013)
------------------
#. Normalize login_alias, removing bad characters and padding it.
#. Add a validation module with validators for email, mobile_number and login_alias - to be expanded.
#. Fix error on `user_logged_out` if there is no authenticated user.

0.4.1 (06-06-2013)
------------------
#. Only clean via Neo if no local errors in join form.

0.4 (23-05-2013)
----------------
#. Use random password for Neo auth instead of actual user password.
#. Only `Member.full_clean` throws ValidationError, not `Member.save` anymore.
#. Remove auth backend and middleware. The user's plain text password isn't stashed in the session or on the `member` object anymore.
#. Add `created` field to `NeoProfile` - useful for checking consumer creation limit (10 000 per day at the moment).
#. Reduce test time by re-using an immutable member where possible.

0.3 (03-05-2013)
----------------
#. Add a new management command to export members for bulk upload:
   ``members_to_cidb_dataloadtool``
#. Automatically create consumers on CIDB for members on login.
#. Consumer creation deferred until a member is complete according to `RegistrationPreferences.required_fields`.
#. Consumer fields are kept in sync with member fields over MCAL.
#. Use `login_alias` instead of `Member.username` for CIDB communications. 

0.2 (09-11-2012)
----------------
#. Create member if credentials are valid and the member does not exist.
#. Fix bug in logout.

0.1 (18-10-2012)
----------------
#. Initial release