Follow

Migrating from 4.4.1 to 5.0.0

  1. Mambo.IO
  2. Migration Guides

This article contains the steps needed to migrate from the latest 4.4.1 version of the Mambo Platform to version 5.0.0. The article is split between API, SDK and JavaScript Widget changes.

It is advised that a staging / test environment be used in order to migrate your integrations safely before upgrading your production servers.

 

API Changes 

This section provides a high level overview of the changes in terms of APIs. The code migration details can be found in the SDK and JavaScript Widget sections.

  1. Events and Transactions APIs have been merged into a single Activities API. The Activities API offers the same functionality that was previously split over two APIs. The idea behind the Activities API is that any action which can modify the user's state will be chanelled through this API. This changes makes it possible to create all the activities through the JavaScript APIs. See below for the security settings.
  2. Coupon Redeem and Refund APIs have been merged into the Activities API. Redeeming and refunding a coupon is now done by creating a new activity.
  3. User Events and Transactions APIs have been merged into a single User Activities API. This can be used to retrieve a list of all the activities involving the user.
  4. User Notifications API has had the withEvents flag updated to withActivities.
  5. Notifications API have had all the withEvents flags updated to withActivities.
  6. Notification Event API, which returned notifications for a specific event, has been replaced by the Notification Activity API. This API can be used to retrieve notifications about all activities (including transaction based activities).
  7. Activity Bounty APIs have been added to the JavaScript APIs. It is now possible to cancel or award a bounty directly from the JavaScript Widgets.
  8. Create User API has been added to the JavaScript APIs so that users can be created directly from the JavaScript Widgets.
  9. API Security has been added in order to control access to the sensitive JavaScript APIs. This allows you to determine which Activities or other sensitive JavaScript API calls can be made directly from the browser. This feature enables the Mambo Platform to be integrated into an even larger number of 3rd party systems. If you are currently tracking behaviours via the JavaScript API / Widgets, then ensure you visit Configuration > Security in the Administration Panel and enable behaviour activities.

 

SDK Updates

This section provides code samples of how to migrate from the latest version 4.x to version 5.x. The guide below details the migration path between the current API and the new API. The guide below is not intended to show case all the new features and functionality which are listed in the Changelog.

The code samples below use the Java SDK as a basis. However, as our SDKs are extremely similar, it is straight forward to apply these same changes to them.

EventsService and TransactionsService

All the calls made to the EventsService and TransactionsService should be replaced with calls to ActivitiesService.

Version 4.x

AggregateId id = EventsService.create( "acme.com", evtData );
TransactionDto transaction = TransactionsService.create( "acme.com", txData );

Version 5.x

AggregateId id = ActivitiesService.create( "acme.com", data );

The ActivitiesService returns an AggregateId representing the activity object created in the Mambo Platform. If you require the full object to be returned you can use the new synchronous Activities API.

For most of the API end-points it should be sufficient to run a find and replace to exchange the two services for the new ActivitiesService.

EventRequestData and TransactionRequestData

The EventRequestData and TransactionRequestData objects have been merged into a single ActivityRequestData. The new data object is a mix of the previous data objects. Some of the fields of both objects have been moved into Attribute classes explained in the subsections below.

Version 4.x

EventRequestData data = EventsService.newEventRequestData();
data.setUUID( "user_unique_id" );
data.setVerb( "purchase" );
data.setUrl( "http://domain.com/path/where/event/took/place" );
data.addMetadata( "brand", "Sony" );
data.addMetadata( "category", "Laptop" );
data.setContent( content );
data.setTarget( target );

TransactionRequestData data = TransactionsService.newTransactionRequestData();
data.setUuid( "john@doe.com" );
data.setTagIds( Arrays.asList( "507f1f77bcf86cd799436543" ) );
data.setTagTags( Arrays.asList( "hr_dept" ) );
data.setPoints( point );
data.setAttrs( attrs );

Version 5.x

ActivityRequestData data = ActivitiesService.newActivityRequestData();
data.setUUID( "user_unique_id" );
data.setUrl( "http://domain.com/path/where/activity/took/place" );
data.setTagIds( Arrays.asList( "507f1f77bcf86cd799436543" ) );
data.setTagTags( Arrays.asList( "hr_dept" ) );
data.setAttrs( attrs );
data.setContent( content );
data.setTarget( target );

The behaviour specific properties of the EventRequestData have been moved into an appropriate activity attribute (shown below). The point specific properties of the TransactionRequestData have been also moved into their appropriate activity attributes.

Transaction Attributes

The existing transaction attributes continue to exist although they have been renamed and now include the point specific information (which was removed from the TransactionRequestData). Below is a list of the old vs. new attributes.

Version 4.x: Manual Transaction Attributes

ManualTransactionAttrs attrs = new ManualTransactionAttrs();
attrs.setAction( "increment" );
attrs.setReason( "Why is the user earning points?" );

Version 5.x: Point Activity Attributes

ActivityPointAttrs attrs = new ActivityPointAttrs();
attrs.setAction( "increment" );
attrs.setReason( "You get these points for being amazing!" );
attrs.addPoints( points );

Version 4.x: Gifted Transaction Attributes

GiftedTransactionAttrs attrs = new GiftedTransactionAttrs();
attrs.setTargetUuid( "target_unique_user_id" );
attrs.setReason( "To my best friend!" );

Version 5.x: Gifted Activity Attributes

ActivityGiftedAttrs attrs = new ActivityGiftedAttrs();
attrs.setTargetUuid( "target_unique_user_id" );
attrs.setReason( "To my best friend!" );
attrs.setPoints( points );

Version 4.x: Bounty Transaction Attributes

BountyTransactionAttrs attrs = new BountyTransactionAttrs();
attrs.setReason( "Best answer wins the bounty!" );
attrs.addPoints( points );

Version 5.x: Bounty Activity Attributes

ActivityBountyAttrs attrs = new ActivityBountyAttrs();
attrs.setReason( "Best answer wins the bounty!" );
attrs.addPoints( points );

Version 4.x: Behaviour Transaction Attributes

N/A - This could not be used for creating transactions

Version 5.x: Behaviour Activity Attributes Version 5.x

ActivityBehaviourAttrsData attrs = new ActivityBehaviourAttrsData();
attrs.setVerb( "purchase" );
attrs.addMetadata( "brand", "Sony" );
attrs.addMetadata( "category", "Laptop" );

Version 4.x: Coupon Transaction Attributes

N/A - This could not be used for creating transactions

Version 5.x: Coupon Activity Attributes Version 5.x

ActivityCouponAttrs attrs = new ActivityCouponAttrs();
attrs.setCode( "COUPONCODE" );
attrs.setAction( "redeem" );

The RewardTransactionAttributes has been completely removed as the rewards are now part of the ActivityDto (shown below).

ActivityBehaviourAttrsData

The BehaviourTransactionAttrs object has been been converted into two separate objects: ActivityBehaviourAttrs and ActivityBehaviourAttrsData. The first object is used when we retrieve an ActivityDto from the Mambo Platform and it will contain the all the information found in the data object plus the list of behaviours that were awarded to the user.

The original BehaviourTransactionAttrs contained the behaviourId and eventId that it was tracking. Today the behaviourId is contained by the list of behaviours found in the attribute and the eventId is the ID of the activity that contains the attributes.

RejectTransactionRequestData 

This has been renamed from RejectTransactionRequestData to RejectActivityRequestData. Please refer to the Activities Reject API documentation in the Administration Panel to see how this API works.

EventDto and TransactionDto

The EventDto and TransactionDto objects have been merged into a single ActivityDto object. The ActivityDto is a merge of the two barring the differences shown above in the data objects (i.e. the points and behaviour information being in the relevant attributes).

The other difference is that the TransactionDto contained information about the expiry date of the transaction. This field has been moved from the new ActivityDto into the relevant SimplePointDto associated to the activity attributes. There are two reasons for this: 1) not all activities have points associated to them; 2) activities with points can now contain multiple points which means that one expiry date will not work as each point will have it's own expiry date.

Below is an example of how to retrieve the expiry date for behaviour and point based activities.

Version 4.

TransactionDto tx = TransactionsService.get( txId );
tx.getExpiryOn();

Version 5.x

// Point based activity i.e. Point / Bounty / Gift
ActivityDto activity = ActivitiesService.get( pointActivityId );
List<SimplePointDto> points = ((ActivityPointAttrs)activity.getAttrs()).getPoints();
for(SimplePointDto point : points ) {
    point.getExpiryOn();
}

// Behaviour activity
ActivityDto activity = ActivitiesService.get( behaviourActivityId );
List<AwardedBehaviourDto> behaviours = ((ActivityBehaviourAttrs)activity.getAttrs()).getBehaviours();
for(AwardedBehaviourDto behaviour : behaviours ) {
    for(ExpiringPointDto point : behaviour.getPoints() ) {
        point.getExpiryOn();
    }
}

UsersService

The UsersService has had a few changes to it's API. The events and transactions related APIs have been merged into a single activities API.

Version 4.x

List<EventDto> events = UsersService.getEvents( options );
List<TransactionDto> transactions = UsersService.getTransactions( options );

Version 5.x

List<ActivityDto> activities = UsersService.getActivities( options );

The options of the UsersService Notification API have been updated to align with the renaming of events to activities.

Version 4.x

UsersServiceOptions options = new UsersServiceOptions();
options.setWithEvents( true );

Version 5.x

UsersServiceOptions options = new UsersServiceOptions();
options.setWithActivities( true );

NotificationsService

The NotificationsService APIs have been updated to align with the renaming of events to activities. This took place in the function calls and options.

Version 4.x

List<NotificationDto> notifications = NotificationsService.getByEventId( eventId );

Version 5.x

List<NotificationDto> notifications = NotificationsService.getByActivityId( activityId );

Version 4.x

NotificationsServiceOptions options = new NotificationsServiceOptions();
options.setWithEvents( true );
options.setEventId( true );

Version 5.x

NotificationsServiceOptions options = new NotificationsServiceOptions();
options.setWithActivities( true );
options.setActivityId( true );

CouponsService

The CouponsService has had the redeem and refund APIs removed and replaced by the relevant calls to the Activities API.

Version 4.x: Coupon Redeem

Status status = CouponsService.redeem( "acme.com", "user_unique_id", "coupon_code" );

Version 5.x: Coupon Redeem

ActivityCouponAttrs attrs = new ActivityCouponAttrs();
attrs.setCode( "coupon_code" );
attrs.setAction( "redeem" );

ActivityRequestData data = ActivitiesService.newActivityRequestData();
data.setUUID( "user_unique_id" );
data.setUrl( "http://domain.com/path/where/activity/took/place" );
data.setAttrs( attrs );

AggregateId id = ActivitiesService.create( "acme.com", data );

Version 4.x: Coupon Refund

Status status = CouponsService.refund( "acme.com", "user_unique_id", "coupon_code" );

Version 5.x: Coupon Refund

ActivityCouponAttrs attrs = new ActivityCouponAttrs();
attrs.setCode( "coupon_code" );
attrs.setAction( "refund" );

ActivityRequestData data = ActivitiesService.newActivityRequestData();
data.setUUID( "user_unique_id" );
data.setUrl( "http://domain.com/path/where/activity/took/place" );
data.setAttrs( attrs );

AggregateId id = ActivitiesService.create( "acme.com", data );

ActivityDto

The BehaviourDto and BehaviourRequestData both contained an ActivityDto object which was related to the activity stream JavaScript widget. This object has been renamed to ActivityStreamDto.

Version 4.x

ActivityDto

Version 5.x

ActivityStreamDto

 

JavaScript Widget Updates

This section describes how to migrate the JavaScript widgets from the latest 4.x version to version 5.x.

Initialisation Options

The initialisation options have been updated:

Version 4.x Version 5.x
notifications: { withEvents: false } notifications: { withActivities: false }

Event Listeners

The following JavaScript events have been updated:

Version 4.x Version 5.x
mambo.track.event mambo.create.activity
mambo.data.events mambo.data.activities

Manual API Calls

The method used to manually retrieve and create data have been updated:

Version 4.x Version 5.x
Mambo.getUserEvents() Mambo.getUserActivities()
Mambo.trackEvent() Mambo.createActivity()

Profile Widget

The initialisation properties for the Profile Widget have been updated:

Version 4.x Version 5.x
hasEvents hasSummary

Custom Template

The template used to customise events has been updated:

Version 4.x Version 5.x
Mambo.Templates.events Mambo.Templates.activities

Language Object

The language object has been updated to merge the activities object and the events object. See below:

Version 4.x

activities: {
	widgetTitle: "Recent Activities",
	prebadge: "unlocked the",
	prelevel: "reached level",
	premission: "completed the",
	badge: "badge",
	level: "",
	mission: "mission",
	prebehaviour: "has performed the behaviour"
},
events: {
	reward: "Reward",
	behaviour: "Behaviour",
	how: "How",
	points: "Points Earned",
	type: "Type",
	when: "When"
}

Version 5.x

activities: {
	widgetTitle: "Recent Activities",
	prebadge: "unlocked the",
	prelevel: "reached level",
	premission: "completed the",
	badge: "badge",
	level: "",
	mission: "mission",
	prebehaviour: "has performed the behaviour",
	how: "How",
	earned: "Points Earned",
	type: "Type",
	when: "When",
	points: "points were manually",
	updated: "updated",
	redeem: "redeemed",
	refund: "refunded",
	bounty: "awarded a bounty to",
	gift: "gave a gift to"
}

 

0 Comments

Please sign in to leave a comment.