Get Started

Enterprise API

Setup your environment and authentication

The table of contents for this tutorial

What you will learn in this tutorial
Terms and condition of use
Prerequisite knowledge and system permissions
Step 1: Create a new report suite in the SiteCatalyst UI
Step 2: Get web service access to Enterprise API
Step 3: Download the Online Marketing Suite WSDL
Step 4.1: Understand the provided solution files for PHP
Step 4.2: Understand the provided solution files for Java
Step 4.3: Understand the provided solution files for C#

What you will learn in this tutorial

In this tutorial, you will learn how to obtain web service access to the Enterprise API and how to download and authenticate against the related WSDL files in Java, PHP and C#. You will also learn how to create a new report suite in the SiteCatalyst UI and to understand how to use the provided solution files for each article in the series.

Terms and condition of use

The Adobe Online Marketing Suite Developer Connection contains confidential information that is the property of Adobe Systems, Inc. Permission to use the information in the Developer Connection is described in, and governed by, the Enterprise Terms of Use.

Additionally, use of the Online Marketing Suite APIs are subject to the Online Marketing Suite API Terms of Use, and the Branding Guidelines and Usage Requirements.

Prerequisite knowledge and system permissions

This series of tutorials and articles are for PHP, Java or C# developers with web experience, who are customers of the Adobe Online Marketing Suite. Directions assume Eclipse as the IDE for PHP and Java development and Visual Studio for C# development.

Note: Your organization's Adobe Online Marketing Suite administrator must grant you web services access privileges before you can use the Enterprise API.

Step 1: Create a new report suite in the SiteCatalyst UI

SiteCatalyst data is stored in customer-specific repositories called report suites. In this section you will create a new report suite for this series of articles and tutorials.

Note: If you do not have authenticated access to the Adobe Online Marketing Suite, you will need to ask your administrator to set up a report suite for this series and to give you the report suite ID.

Log in to the Adobe Online Marketing Suite if you haven’t already.
Select Admin > Report Suites in the upper left corner of your browser.

Figure 1. Look for the Admin dropdown menu in the upper left corner
Select Create New > Report Suite in the Report Suite Manager (see the lower right corner of the following screenshot).

Figure 2. The Create New dropdown menu appears on the right of this figure
Make sure the first dropdown list is set to Create from a Template and then select Genesis Basic Commerce.

Templates set default settings and features for report suites. The Genesis Basic Commerce template is a standard template for e-commerce sites. If you do not see this template, select the Commerce template.
Locate the Report Suite ID field and set the value to jjesquire.

You will see your new report suite ID previewed below the Report Suite ID field. It should include an automatic prefix, which is often the company name.
Set the Site Title to JJEsquire Getting Started Suite.

You will see this title used within the SiteCatalyst UI. You will need the report suite ID in your code.
Select a Time Zone from the dropdown.

All data that comes into this report suite will be recorded based on this defined time zone.
Leave the Base URL and Default Page fields empty.

These two values are only used from the Adobe Online Marketing Suite interface
to link to your web site. The fields are not required.
Leave the Go Live Date set to today.

The Go Live Date determines the day when the report suite is activated.
In the Estimated Page Views Per Day field, type 100.

Use this field to estimate the number of page views you anticipate for your web site per day. This estimate allows Adobe to put in place the appropriate amount of hardware to process the data you will be collecting.
Select a Base Currency from the dropdown.

All currency data that comes into this report suite will be converted and stored in this currency format.
Click Create Report Suite.

You should see the page refresh with a message that your report suite has been successfully created.

An important note about the data and report suite for this series

If you plan to explore only the Collect visitor analytics using SiteCatalyst JavaScript Tagging tutorial or the Collect visitor analytics using the Data Insertion API, you can stop here because these tutorials do not require authenticated access to the APIs.

If you plan on executing the provided code in the other articles, you will need to finish the steps in this tutorial to setup authenticated access to the APIs. You will also need to follow the steps in the Collect visitor analytics using SiteCatalyst JavaScript Tagging tutorial so that you will have data in your report suite for the other articles.

Step 2: Get web service access to the Enterprise API

In this section, you will add web service access to your user login for the Enterprise API. You should work with your Adobe Online Marketing Suite administrator to get access.

In the Adobe Online Marketing Suite, navigate to Admin Console > User Management.
Select Edit Users
Locate your Login name in the Users table, and click the Edit link in the Manage column.
In the Access section, add Web Service Access.
Click Save Changes

When the administrator turns on web services access for a user, the system generates a User Name and Shared Secret unique to that user. You will need these credentials to run the code files for each article.

For more information, see “User Management” in the Administration Console User Guide.

Step 3: Download the Online Marketing Suite WSDL

In this section, you will download the Adobe Online Marketing Suite WSDL and save it to your computer. You will use it in the next sections of this setup guide.

In the Adobe Online Marketing Suite, navigate to Admin Console > Company.

Figure 3. The Company menu item in the Admin Console
Select Web Services.
Click the Web Services Description Language (WSDL) link, in the introductory text.

Figure 4. The WSDL link is in the text of the paragraph

You will see your browser prompt to download the file.
Save the OmnitureAdminServices.wsdl file to your computer.

What you have just downloaded is the latest version of the WSDL file. You will use it to replace the WSDL provided in the solution files discussed in the Step 4 of this article.

Step 4.1: Understand the provided solution files for PHP

For each article in this series, you can download the solution files provided in the Download code files for this article section. Each of the solution files contain the complete PHP code for the article.

In this section you will learn some highlights about the provided PHP code.

Replace the WSDL file in the provided solution code

Each of the solution files provided in the articles contains a WSDL file. However, since this file does occasionally change, you should replace the OmnitureAdminServices.wsdl in the wsdl folder with the one you downloaded in Step 3.

Review the SOAP security header code

The SOAPRequest.php file contains the the following functions:

getSecurityHeader() function: Creates the SOAP security header to access the SiteCatalyst API’s.
The sendRequest() function: Sends the SOAP request with the security header to SiteCatalyst.

You will need to replace the auth_login and auth_password values with your own authentication information.

PHP Code

/* Generates the security header required to access the SiteCatalyst API */
function getSecurityHeader()
{
  $auth_login = '';
  $auth_password = '';
  $company = '';
  $nonce_part = 0;
  /* seed random */
  list($usec, $sec) = explode(' ', microtime());
  /*srand((float) $sec + ((float) $usec * 100000));*/
  /*$nonce = md5(rand());*/
  $nonce = $nonce_part . '-' . $sec . '-' . $usec ;
  /*echo "NONCE: $nonce\n";*/
  $created = date("Y-m-d H:i:s");
  $combo_string = $nonce . $created . $auth_password;

/* Note: the sha1 command is not available in all versions of PHP. If your version of PHP does not support this command, you
can use openssl directly with the command:
echo -n | openssl dgst -sha1 */
  $sha1_string = sha1($combo_string);
  $pwDigest = base64_encode($sha1_string);
  $headers = '

  '.$auth_login.'
  '.$pwDigest.'
  '.$nonce.'
  '.$created.'

  ';
  if($company){
    $headers .= '
    '.$company.'
    ';
  }
  # echo "headers: $headers\n";

  return $headers;

}/* getSecurityHeader()*/

/**
* send a SOAP request to SiteCatalyst
*
* @param string $report_type
* @param array $params Contains the Report Description for the request
*
* @return array $response Data Structure containing report description and data requested
*/
function sendRequest($report_type, $params )
{
  global $soap_client, $debug;
  $response = $soap_client->call(
    $report_type,
    $params,
    'http://www.omniture.com', //namespace
    '', //Soap Action
    getSecurityHeader()
  );

  if($debug) echo "\n=== REQUEST ===\n" . $soap_client->request . "\n";

  if($debug) echo "\n=== RESPONSE ===\n" . $soap_client->response . "\n";

  /* Check the request response for issues */
  if($err = $soap_client->getError())
    throw new Exception("sendRequest(): SOAP ERROR: $err", 0);

  return($response);
}
?>

Review the code to connect to the WSDL

The provided PHP code uses the NuSOAP toolkit to create a client application to connect with the Adobe web service API.

Each main PHP file uses the following code to connect to the local WSDL.

PHP Code

require_once('nusoap.php');
/* Include the common functions to send a SOAP request to SiteCatalyst. */
require_once('library/SOAPRequest.php');

/* Set the variables for the environment */
ini_set('memory_limit', -1);
$debug = true;

/* Set a variable for the local copy of the wsdl file */
$wsdl = 'wsdl/OmnitureAdminServices.wsdl';

/* Error if wsdl file not found */
if ( !is_file($wsdl) ) throw new Exception('WSDL not located.', 0);

/* Setup Data Center Soap Client object */
$soap_client = new soap_client($wsdl, TRUE);
?>

Step 4.2: Understand the provided solution files for Java

For each article in this series, you can download the solution files provided in the Download code files for this article section. For Java, each of the solution files contain the code except for the proxy classes that you must generate for the WSDL.

In this section you will learn some highlights about the provided Java code.

Replace the WSDL file in the provided solution code

Each of the solution files provided in the articles contains a WSDL file. However, since this file does occasionally change, you should replace the OmnitureAdminServices.wsdl in the wsdl folder with the one you downloaded in Step 3.

Set WSDL authentication
The following files are part of solution files that you can download in each article and contain the authentication information that you need to replace:

omtr_api_config.wsdd - This is the XML-based deployment descriptor file in which you set your user for authentication.
PWCallback.java - You use this class file, and the setPassword() convenience method within it, to set your shared secret.

omtr_api_config.wsdd user parameter

PWCallback.java setPassword() method

pc.setPassword("");

Generate your Java proxy classes

Use the WSDL2Java tool to generate all the java proxy classes that interface between your application and the WSDL that you downloaded.

To match the solution files, use the package structure of com.omniture.api when creating the proxy classes using the WSDL2Java tool.

Note: WSDL2Java is a command line tool that generates Java classes from an existing WSDL document. Generated classes represent client stubs, server skeletons and data types that will helps you write client-side and server Java programs for Web services defined in the WSDL document. WSDL2Java is distributed as part of the Axis2 package developed by Apache.

Review the code to create an Adobe web service client for Java

For Java you must create an instance of the web service port class to create a client application to connect with the Adobe web service API. The web service port class is generated by the WSDL2Java utility.

The following code block is provided in each of the solution files that you can download for each article.

Java code

/* EngineConfiguration contains the necessary information for Axis to generate the appropriate SOAP headers for authentication/authorization */
EngineConfiguration config = new FileProvider("src/com/omniture/api/omtr_api_config.wsdd");

/* OmnitureWebService is an interface generated by WSDL2Java that extends the javax.xml.rpc.Service, and OmnitureWebServiceLocator is an implementation of OmnitureWebService. */
OmnitureWebServiceLocator service = new OmnitureWebServiceLocator(config);

/* OmnitureWebServicePortType is a Java Bean generated by WSDL2Java to represent XML types defined in the WSDL schema.*/
OmnitureWebServicePortType port = (OmnitureWebServicePortType) service.getOmnitureWebServicePort();

Step 4.3: Understand the provided solution files for C#

Coming soon.