Overview

Skill Level: Any

Prerequisites

Use the UBX Toolkit to make audience data generated in a locally installed application available for syndication by UBX users. The process involves updating toolkit configurations, generating or updating audience data in the source application, and running scripts to identify and upload the audience data to UBX.

Using the UBX Toolkit to make audience data available in UBX involves the following steps.

  • Create an audience file in the audience producer application. Create the file as a CSV file.
  • Register the CSV file as an available audience in UBX. Run audienceRegister.bat/sh as a scheduled job.
  • Upload the available audience to UBX so that UBX users can share the data with a destination endpoint. Run the audienceUpload.bat/sh script as a scheduled job.

Step-by-step

  1. Registering audience data with UBX

    Registering an audience with UBX enables the UBX Toolkit to recognize changes in the audience data that is available from the audience source. Run the audienceRegister script to register the description of the audience with UBX.

    A. During routine business operations, marketers update existing audiences and create new audiences. The audience data must be saved in a CSV file and saved in a specific directory that is identified in the toolkit configuration properties. Specify the folder with the ubx.audience.producer.audiencePublishFolder property in config.properties.

    B. Run the audienceRegister script to examine the directory that you have reserved for audience data. The script looks for new CSV files. The audienceRegister script ignores files that do not follow the required naming convention. If you do not save audience data to this directory as UBXSegment_<AudienceName>.csv, the UBX Toolkit does not upload the new audience data to UBX. Run the audienceRegister as a scheduled job so that you can regularly monitor the audience source directory for new audience data. Doing so helps to ensure that you are working with the most current data available.

    The script scans the folder that is reserved for published CSV files to determine if new CSV files are present. If a CSV file with the name format in UBXSegment_< AudienceName>.csv is found, the script parses the file name to get the audience name. It reads the first line of the CSV file and uses the column headers as the audience attributes.

    C. The script checks the audience name against the list of current audiences in UBX. The script calls GET /v1/endpoint?segment=true&source=true&loadSegments=true&endpointId={endpointid} to get a list of existing audiences for the endpoint. If the audience name matches an existing audience name, it updates the audience. Otherwise, the audienceRegister script creates a new audience.

    D. After the script processes all CSV files, it calls the UBX API to update or add the audiences. The API call must specify the endpoint ID of the endpoint that acts as the source of the audience data.

    • To update audiences, the script calls PUT /v1/endpoint/{endpointid}/segments
    • To register a new audience, the script calls POST /v1/endpoint/{endpointid}/segments

    After it completes the API calls, the script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencePublishFolder configuration property. The script moves the processed CSV files to the published folder.

     

    The script examines CSV files that have been added or updated in the folder that you specify with the ubx.audience.producer.audiencePublishFolder configuration property.

    Procedure

    Run %CU_HOME%\bin\audienceRegister.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceRegister.sh.

    Optional parameter

    -c <custom config filepath> Specify this path if you did not install the bin directory in the default installation location.

    The script creates the published folder as a sub-folder to the directory for audience data that you specified with the ubx.audience.producer.audiencePublishFolder configuration property. The script moves the processed CSV files to the published folder.

    UBX users must request an audience through the UBX user interface. Upon receipt of the user request, UBX begins the process that is required to share the audience data between the source and destination endpoints.

  2. Audience sharing by UBX users

    UBX users make selections in the UBX user interface to initiate the actual exchange of audience data between an audience source endpoint and an audience destination endpoint. The process is called audience sharing.

    UBX users select audiences in the UBX user interface and indicate when they want the data to be sent from the source to the destination. They can request that the audience source endpoint send the data immediately, at a future time, or on a recurring basis.

    When a UBX user requests audience data from your endpoint, UBX creates a job to provide the data through UBX to the destination that the user specifies. New and updated audiences appear in UBX as Waiting for data.

    To ensure that the latest audience data is displayed and made available when UBX users request it, you must schedule the audience upload script to run repeatedly to make API calls to UBX to detect when UBX has created an audience upload job.

  3. Upload audience data to UBX

    As an audience source endpoint, run the audience upload script repeatedly to respond to audience sharing requests from UBX users and to get the corresponding audience upload job that is waiting for audience data from you.

    When UBX users share an audience through the Audiences tab in the UBX user interface, UBX creates the job that it will use to receive the data from the source endpoint. As the audience source endpoint, you must make API calls to UBX to determine when such jobs have been created. Since users can request that audience source share audience data immediately, good practice demands that you schedule the audience upload script to make the API calls frequently, to avoid delays in responding to the user requests.

     

    A. The audienceUpload script calls GET /v1/jobs/SEGMENT_EXPORT?endpointId={endpointId}&status={status} with the status set to WAITING_TO_RECIEVE_DATA to get a list of jobs that are available to receive uploaded audience data.

    B. If a job is returned, the segment upload script uses the audience name to locate the CSV file that provides the audience data. If the required CSV file exists, the script calls POST /v1/jobs/{jobid}/data to upload data to the job.

    If the CSV file does not exist, the script reports an error and tries again on the next round. The script ignores the job if the CSV file is still not found after the period of time that you specify in the ubx.audience.producer.jobWaitingForDataTimeoutInMinutes configuration property.

    Run the audienceUpload script as a scheduled job to make audience data available to UBX users for download to an audience destination endpoint.

    Procedure

    1. Specify timeout for missing audience data. Enter a value, in minutes, for the following configuration property in config.properties.ubx.audience.producer.jobWaitingForDataTimeoutInMinutes
      Default: 1440 minutes (24 hours)
    2. Run %CU_HOME%\bin\audienceUpload.bat as a scheduled job. For Linux or UNIX, run %CU_HOME%/bin/audienceUpload.sh.

      Optional parameter
      -c <alternate config.properties> Use this option to define alternate configurations. When you specify this option, properties in the alternate configuration file override the toolkit default configuration. Specify the path to the alternate location and file name. Do not rename the default properties file.

    The UBX scheduler creates a job to export the audience. On the Audiences tab in UBX, users can see the job listed as Waiting for data.

    The audience data is uploaded to the destination endpoint through UBX, where UBX users can use the data for various analytical and retargeting activities.

  4. Archiving the local copy of the audience data after upload

    After the upload script finishes, the UBX Toolkit can either move the CSV file to a new location or leave it in place for possible reuse.

    The UBX Toolkit creates the Published folder and the Delivered folder to store the CSV files that are created to provide audience data for upload to UBX.

    By default, after it uploads the audience data to UBX, the UBX Toolkit moves the CSV file to the Delivered folder. However, you can change a configuration setting to keep the CSV file in the Published folder.

    Procedure
    In configuration.properties, indicate where to locate the CSV file after uploading data to UBX by setting the following property.

    • To move the CSV file that defines the audience data to the Delivered folder, set ubx.audience.producer.moveFileToDeliveredFolder to true. This is the default behavior.

      The script calls DELETE /v1/endpoint/{endpointid}/segments/{segmented} to delete the audience data after copying the CSV file to the Delivered folder.

    • To keep the CSV file in the Published folder and available for reuse, set the property value to false.

      Keeping the CSV file in the Published folder allows you to reuse the audience data.

Join The Discussion

Your email address will not be published. Required fields are marked *