UBX getting started education and resources for IBM ecosystem ISVs

Resources for ISV business partners to use to get started working with UBX, understand key integration use cases, key concepts for endpoint/events/audiences, how to use UBX APIs, how to get started building a UBX endpoint:

Learn UBX:

1. Key UBX integration use cases for social media marketing, mobile marketing and paid advertising.

Learn the key UBX concepts and terminology

2. Technical education session replays - UBX introduction, key use cases and concepts

• For event publish/subscribe, refer to module 2, 3 and 4; for audience sharing refer to modules 2, 3 and 5;

3. Use  UBX Test Drive to syndicate events and audiences using the built-in Test Drive Publisher and Test Drive Destination endpoints

• You can set up event syndication between the UBX Test Drive Publisher and the UBX Test Drive Destination endpoints and start publishing events including email, conversion and cart events.   Note that when you click on an event received in the Destination endpoint window, the JSON payload of the event is displayed in the window below. 
• Once your endpoint is implemented you can also set up event publishing from your UBX endpoint to the UBX Test Drive Destination endpoint as a subscriber to start testing and inspecting results of event publish and event payloads.  
• The UBX "partner tools" Test Drive to work with UBX APIs for audience sharing as in the screenshot below - walkthru tutorial

4. UBX Documentation - Users Guide, Integration Guide

Get started implementing your UBX endpoint:

1. Create your solution's UBX endpoint application using UBX Integration Manager - Use UBX Integration Manager to register your endpoint, specify publish/subscribe behavior and event types, identifiers, deployment URLs, provisioning and authentication:  education session replay and presentation

Hands-on lab to create and test a UBX endpoint for a sample application performing UBX event publishing - part 1 and part 2

2. Once your UBX endpoint is created, you must implement UBX public APIs and test your solution in the UBX Pilot environment. The exact steps depend on the IBM Commerce applications with which you want to syndicate event and audience data through UBX.  Guidance for using the UBX API's for each type of event or audience syndication is in specific sections of the UBX Integration Guide and in UBX education session replays:

• All UBX event publishing endpoints publish event data to UBX as a PUSH-type event publisher.
• A UBX event subscriber endpoint that will receive UBX events to your endpoint URL as soon as it is published is considered a PUSH-type event consumer.
• A UBX event subscriber endpoint that will receive UBX events on-demand/batch mode only when the endpoint specifically requests the data from UBX is considered a PULL-type event consumer.
• PULL-type audience producer. UBX calls APIs that are hosted and implemented by the source endpoint. When the source endpoint indicates that data is available, UBX pulls audience data from the source endpoint.

• PUSH-type audience producer. The source endpoint calls APIs that are hosted by UBX. When the source endpoint determines that it can make audience data available, the source endpoint pushes data to UBX.

• PULL-type audience consumer. The destination endpoint calls APIs that are hosted by UBX. When the destination endpoint is ready to accept audience data, it pulls data from UBX.
• PUSH-type audience consumer. UBX calls APIs that are hosted and implemented by the destination endpoint. UBX pushes audience data to the endpoint when the data is shared by an audience source.

3. For UBX event publisher endpoints, determine which UBX event types your solution will publish and register these event types for your UBX endpoint application:

• UBX provides a set of pre-defined recognized events in the UBX Event Catalog that span many categories used with marketing, social, mobile, web and other customer engagement use cases.
• Register the event types that your UBX endpoint is to be publishing using either the UBX Integration Manager (which is the recommended and preferred method) or the UBX event type API.
• If your solution requires additional, new event types not already in the UBX taxonomy, IBM will work with you to determine what are the appropriate event type definitions.  Approval by UBX product management is required for extending the UBX recognized event definitions, and the participating IBM Commerce solution endpoints that would be using these new events with your solution would need to implement support for the new event types.  You can also choose to use custom event types which does not require approval by UBX product management.

4. For all UBX endpoints, your solution must specify the types of customer identifiers used with events or audiences your UBX endpoint publishes or subscribes to.  The recommended identifier types are published in the UBX Integration Guide.  You should use the proper UBX identifier types that match the corresponding identifier type for the other UBX endpoints that you will be syndicating UBX events or audiences with.  This is essential to enabling the UBX Identity Service to perform customer identity matching across UBX solution endpoints - the Identity Service looks for matches of the actual customer identifier values in its identifier store based on the same identifier type being used between publishing and subscribing endpoints.  Note that when you specify the identifier types used for your UBX endpoint in Integration Manager, in the Marketing Database step, you provide the customer identifiers that your UBX endpoint will be using in the "Identifier for <Endpoint_name> Marketing Database", as in the screenshot below.  Note that the "Identifier" value provided in the first column is the identifier name that the UBX business user sees when mapping identifiers in event subscriptions or audience sharing, the second column is the identifier type, which is not exposed to the UBX business user.  IBM Commerce solutions including IBM Marketing Cloud, Campaign, Interact, Digital Analytics, Mobile Customer Engagement, Tealeaf use UBX identifier types specific to each IBM Commerce product, as documented in the recommended UBX identifier types in the UBX Integration Guide.

Enable business user provisioning and authentication for your UBX solution endpoint:

9. UBX requires that users register your solution or product as a UBX endpoint in their UBX account. During registration, UBX requires that UBX users provide the credentials that they use to access your solution or product.  Rather than requiring the business user to separately login and provide access credentials for your solution, UBX can automatically submit these credentials to authenticate with your application on behalf of the user.  When defining your UBX application endpoint with the UBX Integration Manager, you must give UBX your authentication requirements such as access credentials and authentication method that your endpoint requires.  It is highly recommended to use the UBX Integration Manager to specify your UBX endpoint application deployments, provisioning details and authentication requirements.  As an alternative you can use the UBX API for specifying this information for your endpoint.

UBX supports the following authentication methods: API key, HTTP Basic authentication, OAuth and OAuth with a refresh token

UBX supports two ways for business users to enter their access credentials:

• Direct connect:  UBX displays fields in the UBX endpoint registration wizard to enable business users to directly enter their user credentials. It is highly recommended that you use the Direct Connect provisioning method as it is the preferred method for UBX solution endpoints to provision and authenticate endpoint solutions.  It provides UBX business users with the best experience for registering and provisioning UBX endpoint solutions without involving assistance from IT.  Business users are able to click and connect to activate your solution endpoint in their UBX account easily and quickly, using the UBX console UI.
• Instructions only:  UBX displays instructions that you provide, that describe the steps that the UBX user must take to provide their credentials to log in to their account for your solution, as well as how they would provide their UBX account authentication key to so that you can register your UBX solution endpoint for their UBX account.  The UBX endpoint registration API is used to perform this registration step when using instructions-only endpoint provisioning.  Typically, your solution would provide a user interface or business process that enables UBX business users to submit their UBX authentication key to you when they request that you register your endpoint with UBX on their behalf.  You can view this UBX technical education module on endpoints showing how business users register new endpoints for their UBX account. 

Register and test your UBX endpoint in your UBX Pilot account

1. You can get started testing your new UBX endpoint by first registering your UBX endpoint in the UBX console UI.  Select your new UBX endpoint from the "Other endpoint" selections in UBX Test Drive Partner Tools and register using your UBX pilot account authentication key.

2. You can start testing your endpoint using UBX Test Drive endpoints to syndicate events and audiences using the built-in Test Drive Publisher and Test Drive Destination endpoints.  Essentially, your UBX endpoint would take the place of either the UBX Test Drive Publisher or UBX Test Drive Destination endpoint, depending on your integration use case. 

3. Simulate resting in a production use case as a UBX business user would do so using the UBX console UI.  Set up event syndication or audience sharing between your UBX endpoint and either the Test Drive Publisher endpoint or Test Drive Destination endpoint as appropriate, and start sending events or audiences between the connected endpoints.

4. You can use the "Partner Tools" tab of UBX Test Drive to inspect the actual JSON payload of request and response from use of the UBX API, to help assist with testing.

Validate your UBX enabled solution for Ready for IBM Commerce partner program

10. Once you've developed and tested your integration, validating your solution helps ensure your integration is ready for prospective clients. The Ready for IBM Commerce validation indicates your solution is readily deployable with minimal cost and risk to a client.  The Ready for IBM Commerce program is designed to maximize value for our customers by working with Independent Software Vendors (ISVs) who are interested in building repeatable, easy-to-consume integrations between their complementary solutions and IBM Commerce solutions. You can join the open UBX partner ecosystem with UBX and you are encouraged to join to help promote your integrated solution as part of the IBM Commerce ecosystem.

Sample UBX Event Publisher Application

This Bluemix sample UBX application demonstrates publishing UBX events from a Cloudant database by a Node.js application, for reference.  You can use it with your UBX Pilot account by entering the UBX Pilot API URL in the appropate places in the instructions provided. Note that a Bluemix account is required in order to deploy and run the application.  You can register for a free trial Bluemix account here: https://console.ng.bluemix.net/registration/