Exchange provides an integration with Microsoft Azure as an event publisher to share event data with any application in the Exchange ecosystem. In this integration, Exchange pulls event data stored in Azure as batch JSON payloads, TSV, or CSV files.
Before you begin
- You must have an Acoustic Exchange account.
- You must be a licensed user of Acoustic Exchange or an Acoustic Exchange Business Partner solution.
- Ensure that you have a configured Azure account.
Configure your Azure share
For this integration, it is a best practice to create a new share.
- To create Azure Storage account and log in to the console here: https://docs.microsoft.com/en-us/azure/storage/common/storage-quickstart-create-account?tabs=azure-portal
- After creating your account, navigate under Files and create a new share.
- Obtain the access key by going to: Storage Account > Settings > Access Key. Get the access keys which is used to register endpoint here: https://docs.microsoft.com/en-us/azure/storage/common/storage-account-manage
- Copy the access key as this will be used for authentication.
- Keep a record of the share name, account name, and access keys as these are the credentials for authentication.
Now that you’ve created a share, and if you created a mapping file, you’re ready to add the mapping file and other objects to your share. An object can be batch JSON Payloads, TSV, or CSV files.
Batch event JSON payloads
A batch event JSON payload is multiple events in a JSON payload as a series of event descriptions. Each event description defines the identifiers that Exchange can use to identify the specific individual associated with the event, such as an email address or cookieId. Each line must contain one complete event batch JSON payload.
Each event description must also specify the event code that indicates the type of event, a time stamp, and various attributes that describe the event. The event description can also identify the channel in which you detected the event. You can also define the channel at the batch level if all of the events in the batch are observed in the same channel.
Batch event JSON payload example:
{
"events":[
{
"code":"<UBX event code>",
"timestamp":"<time ISO-8601 format>",
"channel":"<channel type>",
"attributes":[
{
"name":"<attribute name>",
"value":"<value detected during the event>",
"type":"<data type>"
},
{
"name":"<attribute name>",
"value":"<value detected during the event>",
"type":"<data type>"
}
],
"identifiers":[
{
"name":"<UBX identifier name>",
"value":"<value detected during the event>"
},
{
"name":"<UBX identifier name>",
"value":"<value detected during the event>"
}
]
},
{
"code":"<UBX event code>",
"timestamp":"<time ISO-8601 format>",
"channel":"<channel type>",
"attributes":[
{
"name":"<attribute name>",
"value":"<value detected during the event>",
"type":"<data type>"
},
{
"name":"<attribute name>",
"value":"<value detected during the event>",
"type":"<data type>"
}
],
"identifiers":[
{
"name":"<UBX identifier name>",
"value":"<value detected during the event>"
}
]
}
]
} TSV and CSV files
Configure TSV and CSV files as usual, no special configuration is required. However, you will need to create a mapping file for the content of the TSV or CSV files.
"DATETIME","USERID","USERAGENT_TYPE","USERAGENT_FAMILY","USERAGENT_DEVICETYPE","USERAGENT_OS","LANGUAGE","GEO_CITY","GEO_CITYCONF","GEO_POSTAL","GEO_POSTALCONF","GEO_AREACODE","GEO_REGION","GEO_COUNTRY","GEO_GMTOFFSET","GEO_DMA","QUERYSTRING"
"2017-10-16 22:29:26","452fa06fd0bf55f4777f2c2033525eb7","SM-J700T","Chrome Mobile","Smartphone","Android","","los angeles","65","90009","35","310/424","CA","US","-25200","803","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:29:26","36d17521808c1452a7de76c5e38b2421","SM-G955U","Chrome Mobile","Smartphone","Android","","los angeles","60","90044","30","323","CA","US","-25200","803","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:31:9","f2743713a4f97075e6ea55ad755d7f28","Browser","Chrome","Personal computer","Mac OS X","","ft worth","65","76137","30","817/682","TX","US","-18000","623","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:32:12","5712ee8ecee794715a7bd3e9c3cbed1a","Browser","Chrome","Personal computer","Windows","","college station","70","77840","40","979","TX","US","-18000","625","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:31:10","362e5148306a6294ae92fc4f07ae16a4","SAMSUNG SM-G930A","Chrome Mobile","Smartphone","Android","","san marcos","60","78666","30","512/737","TX","US","-18000","635","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:32:14","14e6e35bf5c47fd540d9041f6dac9732","iPhone","Mobile Safari","Smartphone","iOS","","coral gables","65","33134","35","305/786","FL","US","-14400","528","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:29:28","cedb350ba0f334eeeba416156e03f196","iPhone","Mobile Safari","Smartphone","iOS","","van nuys","95","91405","90","818","CA","US","-25200","803","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:31:13","85331dbfbb736a9ffc84fb3d99531d2f","SM-G930P","Chrome Mobile","Smartphone","Android","","jarrettsville","90","21084","90","410/443/667","MD","US","-14400","512","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"
"2017-10-16 22:29:29","dc19b0b414773aa1aa5d2cd6e0236c0f","SAMSUNG SM-G890A","Chrome Mobile","Smartphone","Android","","moreno valley","65","92555","35","951","CA","US","-25200","803","p=XXX&g=Y&cpid=123&plid=456&stid=789&crid=101112&j=0"Register your endpoint
To exchange data from Azure through Exchange, you must register Azure as an endpoint with Exchange. You must have a valid license and access credentials for products and solutions that you register.
Register the Azure endpoint with the endpoint registration wizard on the Endpoints tab or through the navigation menu.
Exchange accepts the address and credential information as permission from you that the endpoint provider can interact with Exchange on your behalf. In turn, the endpoint provider requires credentials from you as permission that Exchange can interact with the endpoint on your behalf. During the registration process, you must provide the user credentials that the endpoint provider requires.
Azure can deploy business solutions on one or more servers or data centers. You must specify a deployment when you register Azure as an endpoint for your account.
- On the Endpoints tab in Acoustic Exchange, select Register new endpoint.
- Select Microsoft Azure as the endpoint that you want to register and click Next.
- Enter the information the endpoint provider requires as part of the registration request, including:
- Account name
- Account key
- Mapping file name
- Share name
- Secret key
- Hidden value: Exchange provides “datafilePrefix “ option in integration manager for users that want to arrange their files in separate directories within Azure.
- Endpoint alias (optional): If you have multiple endpoints with the same configuration but different purposes, enter an endpoint alias for your endpoint. It is a designation that differentiates one endpoint from another. If you do not define an endpoint alias, Exchange will create one you.
- Endpoint description (optional): Enter a description for the endpoint to differentiate multiple endpoints of similar configuration, but different purposes. If you do not define an endpoint description, then we use the default endpoint description.
- Click Register.
Exchange transmits the information from the registration wizard to the endpoint provider so that the provider can complete the registration. The endpoint status displays on the Endpoints tab as Pending. When Exchange and the endpoint provider complete the registration, the status changes to Active.
Subscribe to events in Acoustic Exchange
You must register the publishing and subscribing endpoints. As part of the endpoint registration, the endpoint provider registers provided events. Depending on the information from the provider, Exchange can display a description of the event and related event attributes.
- On the Events tab, click Subscribe to events. The Event subscription window displays.
- In the Select events column, select a provider > endpoint > event.
- In the Select destinations column, select one or more endpoints to receive the event notification. The endpoint displays in the Pending subscriptions column.
- Review the pending subscriptions. You can change the subscriptions as necessary.
- Click Subscribe. Refresh the list of available event syndications.
When will Exchange pull event data from Azure?
Every 8 hours, or three times over a 24-hour cycle, Exchange looks into your Azure bucket to check for 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 folder in Azure. Acoustic Exchange generates a report file for each JSON, TSV, or CSV file that was processed.