Adelya::api How to import bulk data

Ok so you have a fairly amount of data (say 1K members or events) and you don't want to (or you can't) send them one by one.
First, yes we provide a csv uploader. Second, sometimes the good old csv is a far much better and performant solution, so let's go.
The required steps are :

format your csv file correctly (see format page) with the right headers
push your file to the uploader URL with your authentication in BasicAuth
manage what is returned by the uploader

Format your file

You can push any Object Type and sub object as long as you respect some rules.
By default, the file must be encoded in UTF-8, fields separated by semi-colon (;), and optionally enclosed by double quote ("). There is a file limit of 3000K if you have bigger import file, contact our support.

Now the headers

The first line of your file will be use to declare with data go where. To accomplish this, you must entered the property name as the column value for the first row. Example :


				idExternal;name;firstname;mobile;address.line1;address.zip;address.town;dummycol;email

Notes :

As you can see on address.line1, we will take care of sub-object creation for you (here in the example, the address)
you can enclose property that are not linked to a Adelya object property, it will be ignored. This cool for integrating existing files output, but it also means that if you misspell a attribute it will not be integrated. Remember that properties name are case sensitive !

Headers for both creation, update and attachment

It is more than common, that you will need to send both creation and update requests. more over, you'll need to "attach" the data to an existing object (e.g. a member or a sale will be linked to the shop - aka. Group - it pertains).
Both features are handle with the sharp sign (#).

If the sharp sign is used on an object property it means : load this object according to this key first, because this line is an update.
If the sharp sign is used on a sub-object it means load this other object and use it.

But be careful ! It is not possible to do this on several fields (whether for an object or a sub-object). You can therefore only use the sharp sign (#) once per object / sub-object.

Example 1 :


                    #idExternal;#group.idExternal;name;firstname;mobile;address.line1;address.zip;address.town;dummycol;email
                    memberref1;groupref;doe;John;+33661234567;"easy street";75009;Paris;not interesting;joe.doe@test.com
                    memberref2;groupref;doe;Mary;+33661244568;"easy street";75009;Paris;not interesting;marry.doe@test.com

In this example, on the 2nd line (first is header), if a member pre-exists in your database with the idExternal memberref1, it will be created, otherwise it will be updated.
Moreover if you have more than one account (Group), we will try to attach this data to the account, whose idExternal is "groupref". If none exist this will produce an error. Note : As for now you can use only one first level key (this limitation may be remove in future release).

Example 2 : Import Sales


                    #idExternal;#member.idExternal;#group.idExternal;type;value;univers;comment
                    yoursalesref1;memberref1;groupref;addCA;120.0;;
                    yoursalesref2;memberref2;groupref;addCA;13.5;;

In this example we provide a basic layout for a multi sales import file.

Push your file !

prepare on your favorite programming language or shell command line, what is necessary to upload a file to an URL.
Add the basicAuth header to your call as for any api call. call the following url

URL : https://asp.adelya.com/loyaltyoperator/manager/fidelity/processCSVUpload.jsp

it acts as a form uploader, so it expects MultipartForm. Other parameters are :

userfile : your file
encoding : UTF-8 (default) or UTF-8
separator : field separator, default is ";" if omitted.
delimiter : field delimiter for text input, default is "\"" if omitted.
className : the kind of object you send identified by its class name (like the first line of a api call)
- FidelityMember : for customer data
- AdEvent : for customer events (like sales, notes, point or credit update)
- Sent : for creating or modifying a message or coupon sent to a customer
continueOnError : whether the importer has to continue when errors occurs, default is false if omitted (the importer stop on the first error found).
outpmode : output mode --> 3 possible values : HTML, JSON or XML (deprecated)

For import to impact loyalty members counters (or to send automatic communication, for example), please ask your Adelya project manager to provide you extra parameters. Please also notice that to provide a className it will be safer to provide the full prefix or the class (eg: com.adelya.common.AdEvent). Your can ask your Adelya Project Manager to provide these information. Submit and you're done

Test & check

Testing is mandatory. We encourage you to create a HTML page with the above fields, in a form that is going to submit everything to processCSVUpload.jsp.
Of course, we all love when a plan comes together. But, sometimes it doesn't. The page output will have lots of indications (lines, error type, file) on how to fix everything.

Note that you'll be able to get these indications in 3 different formats (see outpmode parameter) :

HTML (default format)

JSON

Success


			{
				"status":"SUCCESS",
				"code":1,
				"message":"Import successful",
				"nb_lines_updated":25
			}

Error


			{
				"status":"ERROR",
				"code":-1,
				"message":"{line1=[(0:0) : Error message on line 1, line2=[(1:0) : Error message on line 2], line3=[(X+1:0) : Error message on line X]}",
				"nb_lines_updated":25
			}

XML (deprecated)