Overview

IBM Cloud Object Storage is a cloud storage platform that makes it possible to store practically limitless amounts of data, simply and cost effectively. It can be used for scalable and persistent storage for any type of data. When it is combined with Acoustic Exchange and the Acoustic Exchange Ecosystem, any number of business uses cases can be addressed. For example, you could store historical customer advertisement interactions in IBM COS and share that data through Acoustic Exchange to an analytics platform to gain insight on those interactions.

In this integration, Acoustic Exchange pulls event data stored in IBM Cloud Object Storage as batch JSON payloads, TSV, or CSV files. Acoustic Exchange then shares the event data with any application in the Acoustic Exchange Ecosystem. To do this, Acoustic Exchange uses address and account credential information, that you provide, to look for new event data in your IBM COS account. If it finds new event data, it downloads it, maps the data by using a mapping file that you provide, and sends the data to Acoustic Exchange. The event files are then moved to a /processed/ path in IBM COS. Acoustic Exchange generates a report file for each JSON, TSV, or CSV file that was processed. Acoustic Exchange then shares the data as events to an application endpoint that you designate.

Integration process overview

1. Configuring your IBM COS bucket for the integration
2. Creating your mapping file and adding it to your bucket (Optional) Note: If you do not create a mapping file, then you can upload batch event JSON files only. The events in the JSON file must be events that are recognized by Acoustic Exchange.
3. Uploading data to your bucket
4. Registering the IBM COS endpoint in Acoustic Exchange
5. Subscribing your IBM Cloud Object Storage endpoint to events

Follow the steps listed in this guide to walk through and enable the Acoustic Exchange and IBM COS integration.

Acoustic Exchange

• You must have an Acoustic Exchange account.
• You must be a licensed user of an Acoustic Exchange or an Acoustic Exchange Business Partner solution.

IBM COS

Ensure that you have a IBM COS account and that you have configured your account according to IBM COS requirements and your business needs.

1. Configure your IBM COS bucket

2. Create your mapping file (Optional)

<?xml version="1.0" encoding="UTF-8"?>
<UBX_EVENT_MAPPING dataFileFormat="CSV" sourceEvent="offerAccepted">
   <UBX_EVENT sourceEvent="offerAccepted">
       <code>offerAccepted</code>
       <channel>Paid Media / AdTech</channel>
       <timestamp sourceIndex="1" sourceType="timestamp" sourceFormat="yyyy-MM-dd HH:mm:ss"></timestamp>
       <attributes>
           <attribute>
               <name>eventName</name>
               <value>Accepted Offer</value>
               <type>String</type>
           </attribute>           
           <attribute sourceIndex="3">
               <name>USERAGENT_TYPE</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="4">
               <name>USERAGENT_FAMILY</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="5">
               <name>USERAGENT_DEVICETYPE</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="6">
               <name>USERAGENT_OS</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="7">
               <name>LANGUAGE</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="8">
               <name>GEO_CITY</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="9">
               <name>GEO_CITYCONF</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="10">
               <name>GEO_POSTAL</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="11">
               <name>GEO_POSTALCONF</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="12">
               <name>GEO_AREACODE</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="13">
               <name>GEO_REGION</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="14">
               <name>GEO_COUNTRY</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="15">
               <name>GEO_GMTOFFSET</name>
               <type>String</type>
           </attribute> 
		   <attribute sourceIndex="16">
               <name>GEO_DMA</name>
               <type>String</type>
           </attribute>
		   <attribute sourceIndex="17">
               <name>QUERYSTRING</name>
               <type>String</type>
           </attribute>
       </attributes>
       <identifiers>
           <identifier sourceIndex="2">
               <name>USERID</name>
               <type>cookieID</type>
           </identifier>          
       </identifiers>
   </UBX_EVENT>
</UBX_EVENT_MAPPING>

In the root element <UBX_EVENT_MAPPING>, you define the input data file format and where the source event type can be found. Because the event mapping is based on the source event type, UBX needs to know what the source event type is, and where to look for it. If the data file format is UBXEventBatchJSON (Batch event JSON payloads), then Acoustic Exchange reads the JSON field. If the data file format is TSV or CSV, the source event type can come from the bucket name, file name, column name or column index.

<attribute sourceIndex="10">
  <name>subChannel</name>
  <valueMap>
    <entry sourceValue="1">web</entry>
    <entry sourceValue="4">web</entry>
    <entry sourceValue="2">video</entry>
    <entry sourceValue="3">social</entry>
    <entry sourceValue="10">social</entry>
    <entry sourceValue="6">search</entry>
    <entry sourceValue="7">email</entry>
    <entry sourceValue="8">app</entry>
  </valueMap>
</attribute>

<identifier sourceName="cid" sourceMinLength="5">
  <name>connected_id</name>
</identifier>

4. Register your endpoint

To exchange data from IBM Cloud Object Storage through Acoustic Exchange, you must register IBM Cloud Object Storage as an endpoint. You must have a valid license and access credentials for products and solutions that you register.

Register the IBM Cloud Object Storage endpoint with the endpoint registration wizard on the Endpoints tab or through the navigation menu.

IBM Cloud Object Storage can deploy business solutions on one or more servers or data centers. You must specify a deployment when you register IBM Cloud Object Storage as an endpoint for your account.

Use the registration wizard to provide required address and credential information about your organization and Acoustic Exchange account.

Acoustic Exchange accepts the address and credential information as permission from you that the endpoint provider can interact with Acoustic Exchange on your behalf. In turn, the endpoint provider requires credentials from you as permission that Acoustic Exchange can interact with the endpoint on your behalf. During the registration process, you must provide the user credentials that the endpoint provider requires.

1. On the Endpoints tab in Acoustic Exchange, select Register new endpoint.
2. Select IBM Cloud Object Storage as the endpoint that you want to register and click Next.
3. Provide the information that the endpoint provider requires as part of the registration request. To register the endpoint your will need to provide your:
   • Region Name

     You can find your Region Name on the buckets listing page in your IBM COS account.

   • Bucket Name
   • Service API Key
   • Resource Instance ID
   • Mapping File Name
   • Optional: If your business needs require it, enter an Endpoint alias for your endpoint.

     An endpoint alias is a designation that differentiates one endpoint from another. Defining an endpoint alias is useful in cases where you have multiple endpoints with the same configuration but have different purposes. If you do not define an endpoint alias, one is generated for you.

   • Optional: Enter a description for the endpoint.

     By entering a description for the endpoint, you can provide better insight to the purpose or goal of the endpoint. Again, this is useful when you have multiple endpoints of similar configuration, but different purpose. If you do not define an endpoint description, then Acoustic Exchange uses the default endpoint description.

4. Click Register.

If you entered registration information into the registration wizard, Acoustic Exchange transmits the information to the endpoint provider so that the provider can complete the registration. The endpoint displays on the Endpoints tab as Pending. When Acoustic Exchange and the endpoint provider completes the registration, the endpoint status changes to Active.

5. Subscribe to events in Acoustic Exchange

You must register the publishing and subscribing endpoints. As part of the endpoint registration, the endpoint provider registers the events that it can provide. Depending on the information that the provider supplies, Acoustic Exchange can display a description of the event and related event attributes.

1. On the Events tab, click Subscribe to events. The Event subscription window displays.
2. In the Select events column, select a provider > endpoint > event. View details about the event.
3. In the Select destinations column, select one or more endpoints to receive the event notification. The endpoint displays in the Pending subscriptions column.
4. Review the pending subscriptions. You can change the subscriptions as necessary.
5. Click Subscribe. Refresh the list of available event syndications.

When will Acoustic Exchange pull event data from IBM COS?

Every 8 hours, or three times over a 24 cycle, Acoustic Exchange looks into your IBM COS bucket to see if there is any new event data that has not been previously shared. If it finds new event data, it downloads it, maps the data by using a mapping file that you provide, and sends the data to Acoustic Exchange. The event files are then moved to a /processed/ path in IBM COS. Acoustic Exchange generates a report file for each JSON, TSV, or CSV file that was processed.