Transformers

What are the CompetitionLabs Transformers

      CompetitionLabs Transformers are a recommended way to integrate with the CompetitionLabs platform without having to make modifications to your message formats on your back-end systems. Using the CompetitionLabs Transformers, you can send a message to CompetitionLabs in your current format, transform the message into a form that can be accepted by the CompetitionLabs API, and push that message to CompetitionLabs. You can also transform messages before they are POSTed to your system via the CompetitionLabs WebHooks.

      CompetitionLabs Transformers are created by writing small Scala classes that extend the CompetitionLabs Transformer classes to process messages.

      Inbound events sent via RabbitMQ are transformed by extending the CLMQTransformer class. Your transformation class is run by the CompetitionLabs platform when the message is received.

       Outbound events sent via WebHooks are transformed by extending the CLWebhookTransformer class. Your transformation class is run by the CompetitionLabs platform when an action occurs that would trigger a WebHook to fire.

Common use cases for CompetitionLabs Transformers

      Beyond mapping of message fields from your platform to CompetitionLabs, below are some common uses for CompetitionLabs Transformers:

• Create a new member when CompetitionLabs receives an event from a sign-up event
• Push a message into your platform when a new Product is created within CompetitionLabs
• Retrieve customer segment information from your platform for a new member

List of operations available can be found inside the github project.

Transform incoming messages from a RabbitMQ Queue

       CompetitionLabs MQ transformer is used to transform a message received via RabbitMQ to your CompetitionLabs space. Within the transformer, you can map the fields of an incoming message to the CompetitionLabs API, trigger addition events, or implement custom business logic.

To transform an incoming message from a RabbitMQ Queue:

1. Create a class that extends the CLMQTransformer class

2. Test your class using Scala Test and theCompetitionLabsApiTestmodule

Transform outgoing WebHook messages from CompetitionLabs

      You can use CompetitionLabs WebHook transformers to modify and send messages to your WebHook endpoints. You can map field in the CompetitionLabs data model to fields already implemented in your platform. You can also use the CompetitionLabs Webhook Transformer API to trigger additional actions and events.

      You can create a CompetitionLabs WebHook transformer for any of the built in WebHook events. If you have a customer WebHook transformer configured, your custom transformer is used instead of the built in WebHook transformer.

To create a CompetitionLabs WebHook transformer:

1. Create a new class that extends CLWebhookTransformer.

2. Override one of the methods in CLWebhookTransformer with your implementation

The following are the built in WebHook transformers you can override with your own customer transformer:

• onNewProduct(): Executed when a new product is registered in your CompetitionLabs space
• onNewMember(): Executed when a new member is registered in your CompetitionLabs space
• onCompetitionCreated(): Executed when a new competition is created in your CompetitionLabs space
• onCompetitionStarted(): Executed when a competition is started
• onCompetitionFinished(): Executed when a competition finished
• onCompetitionCancelled(): Executed when a competition is cancelled
• onCompetitionRewardIssued(): Executed when a reward for a competition is issued
• onContestCreated(): Executed when a new contest is created in your CompetitionLabs space
• onContestStarted(): Executed when a contest is started
• onContestFinished(): Executed when a contest finished
• onContestFinalised(): Executed when a contest is finalised
• onContestCancelled(): Executed when a contest is cancelled
• onContestRewardIssued(): Executed when a contest reward is issued
• onAchievementCreated(): Executed when a new achievement is created
• onAchievementTriggered(): Executed when an achievement is triggered
• onAchievementRewardIssued(): Executed when a reward was awarded to a member

Example of a WebHook transformer

Below is an example of a custom WebHook transformer.

Developing and Testing Transformers

       This section covers the tools needed to begin writing and testing CompetitionLabs Transformers

System Requirements

      These are the tools you will need to develop CompetitionLabs Transformers

• Scala 2.11
• Java 1.8
• JDK
• JetBrains
• IntelliJ (Optional)

CompetitionLabs Transformer API

The CompetitionLabs Transformer API is used within your transformer classes to perform various operations like looking up members, pushing events, creating actions, etc.

You can view the methods available for CLMQTransformer and CLWebhookTransformer classes here: competitionlabs-transformers/src/main/scala/com/competitionlabs/transformers/CompetitionLabsApi.scala

You can view addition methods available for CLWebhookTransformer classes here: clabs/competitionlabs-transformers/src/main/scala/com/competitionlabs/transformers/CompetitionLabsApiExt.scala

Github project is available at - competitionlabs-transformers

Once you have got your code working, get in touch with the CompetitionLabs admin team, they will provide you with a private repository to commit and deploy your custom transformers.

Next: Transformer creation