Design Acoustic Exchange Endpoints

Prerequisites

You must complete a design and approval process in order to appear in Acoustic Exchange as an endpoint.

In Exchange, an endpoint represents a product or business solution that is part of the Acoustic Exchange Partner ecosystem. Exchange provides marketers with new ways to match and combine the capabilities and outputs of these products to solve business problems. As a result, appearing as an endpoint in Exchange increases a product’s value to a marketer.

To use a product from the Exchange Partner ecosystem in their Exchange user account, marketers must register the product as an endpoint in their account. To be able to register a product as an endpoint, Exchange users must have an open account or valid license to the product and be able to provide valid access credentials. This is how Exchange encourages marketers to patronize members of the Exchange Partner ecosystem.

In Exchange, endpoints are based on a set of metadata that is referred to as an Exchange application. An application serves as a blueprint that defines how your product or solution appears in Exchange, what it provides or accepts, and the authentication that it requires to interact with Exchange.

To help build your application, Exchange provides the Integration Manager. The Integration Manager provides a single, intuitive interface to define your data syndications and data center deployments, and also guides you through testing, validation, and promotion as a publicly available Exchange endpoint.

The initial partner provisioning and application design takes place in the Exchange Pilot environment. When your application is ready to go to market and Exchange approves your solution for Exchange, your application can move to the Production environment so that it is available to Exchange users.

Step-by-step

1. Access the Exchange integration manager

You must have an Exchange partner account to access the Integration Manager. The link to the Integration Manager is accessible only through the Exchange interface.

Log in to Exchange.
Click the navigation menu and select Integration Manager. Integration Manager opens with the My Applications page. The page lists the applications that were created previously.
Create a new application or edit one of the applications in the list. If you create a new application, you must create the application with a unique name before you can proceed to edit the application.
Optional: Integration Manager provides a read-only summary view of your application.

Use the summary to quickly view your progress towards defining how the application exchanges data with Exchange, how it describes the data, where the application is deployed, and the event types and features that it supports. You can view the list of event types and features, organized by event type or by the features that contain event types.
Summary displays the unique Application ID that the Integration Manager assigns to the application. This is the only place where this value displays.
When you open the application for editing, the Integration Manager always opens the application in the Summary view.
After you finish editing the application, review the Summary for completeness before you proceed to the Implementation phase.

2. Edit the application

Describe the application.
Provide a name and description for the application. Exchange displays the name and description to Exchange users in the endpoint registration wizard.

Your Exchange application forms the basis for the endpoint that Exchange users register for use in their Exchange user account. Exchange users rely on the description that you provide to understand how the endpoint that is based on your application can help them solve business problems. Describe your Exchange application clearly and concisely.

Your application is represented in the Exchange user interface among all of the applications that are available in the Exchange partner ecosystem. Being added to the list of Exchange endpoints gives you an opportunity to be seen by Exchange users who might not yet own your product or solution. A clear description can improve your chances of wider adoption among new users.

Specify syndication types.
Syndication refers to the exchange of event or audience data through Exchange. Specify the types of data that your application can provide or receive and how it moves the data to or from Exchange.

Depending on the capabilities of your product or business solution, your application might support some or all of the following data syndication methods.

Event publisher
Event consumer
Audience publisher
Audience consumer

With the exception of event publishers, Exchange supports applications that can push data to Exchange or pull data from Exchange. Event publishers can only push event data to Exchange. Exchange never attempts to pull event data from an event publisher.

The combination of the type of data being exchanged and the method used to connect to Exchange determines the specific Exchange public APIs that you must call or implement. The Integration Manager lists the required APIs in the Implementation phase, based on the selections that you make when you specify syndication types.

The distinction between exchanging data as PUSH or PULL depends on how the data moves between an endpoint and Exchange. The way that data flows between endpoints and Exchange determines how the Exchange APIs are called or implemented by the endpoint.

Exchange recognizes the following syndication types. Depending on the types of data exchanges that your product or solution supports, you can select more than one data syndication type.

Event publisher: PUSH. All Exchange endpoints publish event data to Exchange as a PUSH-type event publisher. Publishing events to Exchange also requires an API call to Exchange.
Event consumer: PUSH. An endpoint that receives event data that Exchange sends as soon as it is available is considered a PUSH-type event consumer.
Event consumer: PULL. An endpoint that receives event data only when it specifically requests the data from Exchange is considered a PULL-type event consumer.
Audience producer: PULL. Exchange calls APIs that are hosted and implemented by the source endpoint. When the source endpoint indicates that data is available, Exchange pulls audience data from the source endpoint.
Audience producer: PUSH. The source endpoint calls APIs that are hosted by Exchange. When the source endpoint determines that it can make audience data available, the source endpoint pushes data to Exchange.
Audience consumer: PULL. The destination endpoint calls APIs that are hosted by Exchange. When the destination endpoint is ready to accept audience data, it pulls data from Exchange.
Audience consumer: PUSH. Exchange calls APIs that are hosted and implemented by the destination endpoint. Exchange pushes audience data to the endpoint when the data is shared by an audience source. Often, cloud-based business applications (also called SaaS applications) connect to Exchange as a push-type audience consumer.

When Exchange users share audience data, Exchange can modify a destination audience in several ways. Audience consumer endpoints must specify the methods that they support.

When Exchange business users share audiences, the Exchange user interface presents an audience sharing wizard that gives the Exchange user the following options to add source audience data to a destination audience.

Add new records. Exchange adds audience data to the specified destination audience, either as a new audience or by adding the records to existing records in the destination audience.
Replace existing records. Exchange replaces all existing data in the destination audience with new audience data from the source audience.
Remove existing records. Exchange removes existing records that match the shared records. Exchange matches records based on the value of the identifier specified in the record.

The destination audience is a segment of a database that is maintained in your business systems. As an audience consumer, you must indicate the degree to which you allow Exchange to modify records on the database by indicating which of the audience delivery options you support. Use the Integration Manager to make that choice.

When you edit your application in the Integration Manager, the Specify syndication types section provides options to indicate how you want to consume audience data and metadata. In the Audience Consumer quadrant, you specify support for the Add, Replace, or Remove options to update destination audience records. You can select any or all of the options, depending on how much database control you allow.

The options that you select in the Integration Manager determine the options that Exchange enables for Exchange business users in the audience sharing wizard. For example, if you want to allow Exchange users to only add or delete audience records (not update), select only the Add and Remove options in Integration Manager. In the audience sharing wizard, Exchange disables the Replace option.

The Integration Manager also gives you an option to specify the default audience sharing action that Exchange enables for business users. The Add option is preselected in the Integration Manager, but you can change this selection.

When Exchange users create a new destination audience, Exchange always enables the Add option.

3. Specify database description.

In Exchange, a database definition specifies identifiers and attributes that are expected in the audience and event data that you exchange through Exchange. Exchange calls this the marketing database definition.

When users share audiences, they can map identifier and attribute names between source and destination endpoints. In the Specify database definition section of the Integration Manager, you define the identifiers and attributes that Exchange users see when they share an audience.

The identifiers and attributes that you define in the Specify database definition section display on the Source to destination mapping screen of the Share audience wizard in Exchange. Users must map an identifier that is defined in the source audience to a corresponding identifier in the destination audience. For example, emailAddress in the source might map to email in the destination.

Exchange users have the option to map one or more audience attributes in the source audience to corresponding attributes in the destination audience. For example, zip code in the source might map to postal code in the destination.

Using the Integration Manager to define the marketing database for your endpoints enables you to save time and to maintain consistency across endpoints. However, if you need to vary the definition for the different endpoints that you create, you can use the following Exchange APIs, to set the definitions individually.

PUT /v1/endpoint/application
PUT /v1/endpoint/{applicationid}/{deploymentid}

4. Add features.

In Exchange, a feature serves as a way to group related event types that your application provides. Grouping event types by feature is optional.

Each feature can contain different combinations of event types. An application can contain multiple features. An application can also support event types outside of features.

Because each feature is associated with an application, it is possible to define events and event attributes for all endpoints that are based on the application. Changes or additions that you define for the feature propagate to all endpoints that contain the feature.

You can enable or disable metadata that you define in a feature for individual Exchange user accounts. For example, you can define product options as features and enable the Exchange feature only for your customers who pay a premium for the various options.

5. Add event types

If your endpoint provides or accepts event data, your application must specify the various types of event data that your product or solution can manage.

Exchange supports a diverse taxonomy of event types. The taxonomy is organized around several categories. Each category contains several related event types.

Each event type, including custom event types, defines various attributes. Each attribute provides a value that can be used to describe the event or the individual who initiated the event. The Exchange event taxonomy recognizes the following types of attributes:

Recommended attributes. Acoustic Exchange recommends certain attributes for use with a particular event type, based on general business practice and the collective experience of Exchange users. Each event type contains one or more recommended attributes. For example, the attribute subjectLine is a recommended attribute for the Email Open event type.
General attributes. A general attribute describes a characteristic that is not typically associated with a particular event type. For example, the general attribute deviceType might be useful for several different types of events.
Custom attributes. If the recommended or general event types in the taxonomy do not meet your needs, you can define a custom event that accepts data that your business systems can provide or accept. A custom attribute is available only in the event type in which you create it.

You can change the attributes associated with an event type.
You can modify the event types that you add to the application by removing recommended attributes that you do not use, adding attributes from the list of general Exchange attributes, or creating custom attributes. The changes apply only in the application in which you make the modification.

If you do not find an event type in the Exchange event taxonomy that meets your needs, you can create a custom event type. A custom event type is available only in the application in which you define the custom event type.

Creating custom event types

If you do not find the type of event that you need, you can create a custom event type. A custom event type is available only in the application in which you define the custom event type. Because custom event types are available to only one application instead of many, other Exchange ecosystem members are less likely to replicate it for use in their applications. In turn, this reduces the likelihood that marketers will include your endpoint in their data syndications because there are no other endpoints that accept your custom event data.

In the Add event types section of the Integration Manager, click Add a new event type.
Click the link to custom event type.
Define the new event type. You must enter a name and a unique event code. Entering a description is optional, but recommended, so that Exchange users who register endpoints based on the application can see what the event type provides.
The other fields are optional.

Namespace. Enter a different namespace if you define a custom event with a code that duplicates an event code that is already registered with Exchange If Namespace is empty, Exchange assumes a default value.
Scope. Exchange recognizes two types of events.
Individual. Events initiated by a single individual who can be identified by a unique identifier that is included in the event payload that the event publisher sends to Exchange.
Aggregate. Events that are initiated by or affect multiple individuals. Aggregate events do not contain a unique identifier in the event payload.
Registration type. You can choose either Publish or Subscribe.
PUBLISH: Identifies an event that the registering endpoint publishes to Exchange.
SUBSCRIBE: Identifies an event that the registering endpoint receives from Exchange.

Optional: Add features to the event type. (optional)
Add attributes to the event
Click Apply to create the custom event type

Creating custom attributes

If you do not find the type of attribute that you need in the taxonomy, you can create a custom attribute. You create a custom attribute by modifying the definition of an event. The custom attribute is available only for the event in which you define the custom attribute.

On the Add event types screen, select an event.
In the Attributes section of the event definition, click + Add other attribute.
Click the Create a custom attribute link at the top of the Add attribute screen.
On the Attribute details window, you must enter a Code, Type, and Display name. Entering a description is optional, but recommended, to make it easier for Exchange users to understand what the attribute provides.
Click Create. The new custom attribute appears in a separate section of the list of attributes that are associated with the event.

Specify deployments
A deployment in Exchange defines where and how to access the software that supports the product or solution that is provided by the Exchange partner and that is represented by an Exchange endpoint.

Exchange applications are not software that is hosted by Exchange. Business solutions that are represented in Exchange as endpoints are actually hosted on servers and data centers outside of Exchange. To enable Exchange to connect to endpoints automatically, you must define how and where you have deployed the software that provides or receives data that passes through Exchange.

Exchange can connect to endpoints that are deployed on multiple servers or data centers. You must define each deployment separately.

You must define a unique deployment ID and a name for the deployment.

Depending on the types of data that you plan to exchange, you must provide the specific URLs to where to find or deliver the data. The Integration Manager displays fields to enter source and destination URLs based on the data syndication choices that you make in the Specify syndication types section.

By default, the Integration Manager defines a single deployment in every new application. You can use this default deployment if your product or solution is deployed on a single data center.

If your product or solution is deployed on multiple data centers, you must define additional deployments.

If your product or solution is installed on a local network, you do not need to define a deployment. This type of product deployment is sometimes called an On Premise installation.

The default deployment is provisioned to use the Instructions only endpoint registration method. You can change the registration method to Direct connect when you specify the provisioning method for the application.

Specify provisioning method

For each application deployment, you must define how Exchange business users register your business solution or product as an endpoint in their Exchange account and how Exchange authenticates with your operational systems.

Specifying the provisioning method indicates to Exchange how it should provision the Exchange user accounts of users who register your product or solution as an endpoint in their Exchange account. When you specify the provisioning method, you define the following provisioning requirements.

Specify a provisioning type to indicate how Exchange users must submit endpoint registration requests.

Specify the authentication method that Exchange must use when it communicates on behalf of the user with the operational systems that support your product or solution systems.

Specify if you want Exchangeto notify you when Exchange users subscribe to events that involve endpoints based on your application. This option applies only if you are a publisher or consumer of events.

The Integration Manager changes the provisioning options available to you based on your choice of provisioning type.

Endpoint registration method

Specify how users register your endpoint by specifying a provisioning type.

Exchange users that want to register your product or solution as an endpoint in their Exchange account must already be registered users of your product or solution. Endpoint registration requires the user to provide Exchange with the access credentials that they use to access your systems. Exchange uses these user credentials to authenticate with your operational systems on behalf of the Exchange user to perform actions that the user requests in the Exchangeuser interface.

As part of the Click-to-Connect endpoint registration approach, Exchange supports two methods that users can use to register endpoints and provide their authentication credentials.

Direct connect
Instructions only
Exchange also supports registering an endpoint as a Custom Endpoint. Registering as a custom endpoint is not considered a click-to-connect registration. Acoustic Exchange does not recommend this registration method for new integrations. Registering as a custom endpoint requires various API calls and extensive communication between the endpoint provider, the user, and the Exchange provisioning team.

Direct connect registration

Exchange provides fields that allow the user to provide user credentials and other information, based on requirements that you defined in your Exchange application. Exchange passes the information to you as part of the registration request.

In the Integration Manager, you can enter static values that apply to all users who register your product as an endpoint. You can also select an option to prompt the user to enter information in the endpoint registration wizard. For example, if you require a user name and password, you can configure Direct connect to prompt users for their unique credentials. You can also define extra fields to enable Exchange users to send additional information to your systems, if you require it.

You must provide a URL to receive the endpoint registration request.

Direct connect endpoint registration requests include authentication information in the request header. You must specify the type of authentication that you require.

Instructions only registration
Exchange displays registration instructions that you provide. Typically, the instructions include guidance for a separate call to your account provisioning system.

In your instructions, describe the steps that the Exchange user must take to provide their credentials. Provide all required links and list the user information that you require.

Instructions-only registration does not require you to specify an authentication method because there is no direct communication with your systems as part of the registration request.

Authentication requirements

Specify the type of authentication that you require for Direct connect registration requests and other direct communication with your product or solution.

Exchange always includes authentication information for Direct connect endpoint registration requests. If you specify Direct connect registration, you must also specify your preferred authentication method. However, Integration Manager does not provide this option if you specify Instructions only registration.

If you request that Exchange notify you when Exchange users subscribe to events that you either produce or consume, you have the option to require that Exchange include authentication information in the header of the notification. This is optional. You must explicitly request additional authentication for subscription notifications. Additional authentication for subscription notifications is available only if you also specify Direct connect endpoint registration.

You can request that Exchange add authentication information for all other direct communications with your product, not limited to endpoint registration requests and subscription notifications. This option is available only if you also specify Direct connect endpoint registration.

Exchange supports the following authentication methods:

API Key: You specify a key value when you register for subscription notification. When Exchange reports a subscription change in an HTTP call, Exchange adds the specified key in the HTTP header. For example, Authorization : Bearer .
HTTP Basic: You specify a username and password when you register for subscription notification. When Exchange reports a subscription change, Exchange submits the credentials encoded in the HTTP header in RFC 2617 format. For example, Authorization : Basic .
OAuth: You specify a client ID and client secret when you register for subscription notification. When Exchangereports a subscription change, Exchange includes these values in the OAuth parameters that it adds to the header of the HTTP call.
OAuth with a refresh token only: You specify a client ID and client secret during account provisioning, separately from registration for subscription notification. When Exchange reports a subscription change, Exchange includes a refresh token, but not the client ID or client secret, in the OAuth authorization parameters in the HTTP header.
HMAC-SHA1: You must register the endpoint with the following attributes:

{
    "attributes":{
        "DestinationEndpoint.AuthType":"HMAC-SHA1",
        "DestinationEndpoint.AuthType.HMAC-SHA1.AuthHeader":"XXXX:%s",
        "DestinationEndpoint.AuthType.HMAC-SHA1.Key":"YYYY"
    }
}

Where:

DestinationEndpoint.AuthType allows Exchange to identify this endpoint as using HMAC-SHA1 authentication.
DestinationEndpoint.AuthType.HMAC-SHA1.AuthHeader builds the authorization header value. The generated signature will replace the % s in the value.
DestinationEndpoint.AuthType.HMAC-SHA1.Key is used to generate the signature. Exchange then generates the HMAC-SHA1 signature using javax.crypto.Mac. and encodes it with Base64.
Then, the designated URL is called with a header Authorization. The header includes the AuthHeader attribute and the generated signature values. For example, Authorization: XXXX:YYYY.

Subscription notifications

Exchange can notify you when Exchange users change their event and audience syndications, or if they remove your endpoint from their Exchange user account.

Subscription notification is optional. Over time, Exchange has released several versions of subscription notifications. Exchange supports the earlier notification versions to support applications that Exchange Partners have previously built and deployed. However, if you are building a new Exchange application, or updating an existing Exchange application, use the latest available version of subscription notifications.

You can request notifications in the Specify the provisioning method section of the Edit application phase in Integration Manager. The section provides the following notification options, depending on the notifications version that your application uses.

Publisher only (version 1.1) Exchange sends notifications only if your application publishes events.
Publisher and Consumer (version 1.2): Exchange sends notifications if your application can publish and subscribe to events. Exchange can also include additional fields in the notification that identify the endpoint and the endpoint provider that is either producing or consuming the subscribed event.
Publisher, Consumer, and Endpoint (version 1.3): Exchange sends notifications as in version 1.2 and also notifies you when an Exchange user who has registered your endpoint removes your endpoint from their Exchange user account.

If you request subscription notifications, you must provide a subscription notification URL.

For added security when Exchange communicates with your operational systems, you can request that Exchange include authentication information in the header of the notification. This is optional. Specify by checking the option to add authentication for all outbound calls, including notifications.

The option to include authentication information is available for notifications only if you specify Direct connect as the endpoint registration method and the notification uses the same authentication method that that you select for Direct connect registration.

Call Exchange public APIs

In the Implementation section, the Integration Manager specifies the various APIs that you must either call or implement to connect the application that you have designed to Exchange.

Based on the syndication type and provisioning method that you specify in the design of your application, Integration Manager presents the lists of APIs that you need to call or implement. In some cases, you call APIs that are hosted by Exchange. In other cases, you implement APIs that Exchange calls.

Test application

In the test phase of the application development, you perform the steps that Exchange users take to register and use an endpoint that is based on your application.

The steps to test include the following. Depending on the type of endpoint your application is designed to support, you complete some or all of the following scenarios.

Register an endpoint. Test the provisioning method that you specified, either Instructions only (follow the instructions that you wrote) or Direct connect.
Event publisher: Subscribe to events and examine the results on an event consumer endpoint.
Event consumer: Subscribe to events and examine the events that you receive from an event producer endpoint.
Audience publisher: Share audiences. Examine how the audience arrives at an audience destination endpoint.
Audience consumer: Share audiences. Examine the audience that you receive from an audience producer endpoint.

Exchange provides Test Drive so that you can test the performance of your application. The Partner tools tab in Test drive includes a section that provides a variety of tools that you can use to test the behavior of endpoints that you create with your application. In Test Drive, you can simulate the behavior of producer and destination endpoints.

The Integration Manager provides a direct link to Test Drive on the Test your application page.

Validate application

To make your application available to Exchange users, Acoustic Exchange must review and approve the application. Demonstrating your application is part of a larger validation process that includes several steps.

Integration manager lists the major steps that you must complete.

Complete a questionnaire that Exchange provides.
Describe a typical end-to-end use case that includes your business solution.
Meet with the Exchange Business Partner ecosystem team.
Demonstrate your application and supporting materials.

You must coordinate with the Exchange provisioning team to arrange for demonstrations and approvals.

Acoustic Exchange will either approve promoting the application to the Exchange Production environment or request adjustments and further testing to resolve issues that were discovered during the validation process.

Promote application to Exchange production

The final step towards making your application available to Exchange users for registration as a Exchange endpoint involves moving your application from the Pilot environment to Exchange Production.

Until you promote your application, only you can register endpoints that are based on the application in the Exchange production environment. Your application is not visible to other users in Exchange Production. In Integration Manager, the visibility of your application is marked PRIVATE and the application approval status is marked PENDING. The link to make the application public is disabled and remains so until Exchange explicitly approves your application for promotion.

You decide exactly when to promote your application and make it public. At a time of your choosing, go to the Promote section in Integration Manager to submit the authentication key. When you submit the authentication key, your application becomes visible to Exchange users, who can begin registering your product or solution as endpoints that are based on the public application.

Changes to your application in Exchange Production

You cannot modify your Exchange application in the Exchange Production environment.

If you must make changes to your application after you promote it to Exchange Production, you must make the changes in your Pilot account and then promote the application again to Production.

You do not need to complete the validation process again to promote your application after the initial approval by Acoustic Exchange. The Promote link remains active in Integration Manager after Acoustic Exchange approves your application.

Selectively promote applications

You can create multiple Exchange applications in the Exchange Pilot environment. When you promote to Exchange Production, you can specify which of the applications are promoted to Production.

By default, every application that you create in Integration Manager deploys to Exchange Production when you promote to Production. However, you can specify individual deployments that do not deploy to Exchange Production when you promote to Production.

You control the production deployment of your Exchange applications in the Specify deployments section of the Edit application phase in Integration Manager. The Specify deployments section provides the following options:

Will deploy to Production The deployment is promoted to Production when you promote.
Will not deploy to Production The deployment is not promoted to Production if you promote.
If you select Will deploy to Production, you cannot modify the application in Exchange Production after you promote. If you select Will not deploy to Production, you can continue to make changes to the application.

Accept endpoint registration requests from Exchange users

When your application is available to the public, Exchange users access your solution or product by registering your application as an endpoint in their Exchange account. You must process the registration requests.

To enable Exchange users to register endpoints in their account, Exchange provides an endpoint registration wizard in the Exchange user interface. Users access the registration wizard through the Register new endpoint link on the Endpoints tab in Exchange.

Although each registration request creates an endpoint registration that is unique to the Exchange user that requests it, all of the endpoint registrations for your product or solution are based on the same Exchange application. This one-to-many relationship makes it possible for you to update your application and quickly propagate the changes and updates to all users who register your endpoint.

Select an application to register as an endpoint. The wizard lists all Exchange applications that are available for registration, including yours. Users learn about your application by reviewing a brief description that you defined as part of your Exchange application.
Enter user credentials.
If you implemented the Direct Connect registration method (and configured the application to prompt the user), the wizard prompts the user to provide the information that you require to access your user authentication systems.
If you implement Instructions only, the wizard displays the instructions that you provided as part of your application definition.
Submit the registration request. When an Exchange user requests an endpoint registration in the Exchange user interface, Exchangegenerates a unique authentication key. The authentication key must be in the authorization bearer of each API call, including registration requests.

Example

When the Exchange user submits the registration request, Exchange generates a unique authentication key that is specific to the Exchange user account and the request to register your application as an endpoint in that account. Exchange makes an HTTPS POST call to your provisioning system that includes the authentication key in the request header. Your provisioning system must be able to accept and process the call. The call provides registration information that resembles the following example.

Authentication: {<authentication credentials as defined for the <<ex-short>> application>}
{
 "onboardingType" : "<DIRECTCONNECT | INSTRUCTIONSONLY>",
 "authKey" : "{<endpoint-level authentication key>}"
 "endpointId" : {<endpoint id>},
 "extraFields" : [ {extra name-value pairs that users can populate} ],
}

After you validate the request and completing other account provisioning tasks that your systems require, you make an API call back to Exchange to complete the registration.

The Implementation page in the Integration Manager describes the required API calls, based on the provisioning method that you specify in your application design. Confirming in advance that this process works for Exchange users is part of the testing phase that you perform prior to being approved by Acoustic Exchange during the validation phase.