13 Introduction to Customer Engagement APIs

Data in Customer Engagement can be accessed through a set of application programming interfaces for Customer Engagement’s web services. Each application programming interface (API) provides a set of methods that can be imported into an object-oriented language (such as Java or C#) that will then allow a developer to work with data on a Customer Engagement system.

About this Chapter

This chapter includes the following information:

• Using APIs

• Creating an Customer Engagement Java Archive for an API Interface

• Using Customer Engagement APIs

• Authentication

• Common Objects

• Web Service Tracking

Using APIs

To access an API, users must instantiate the API class in the program, project, or class using it. To do this, the API class must be packaged and the package imported into the project.

Depending upon the interface used by a programmer, the interface may take care of many of the details automatically, or the user may need to perform several steps to create a package file that can then be imported.

Once the package has been imported, the web service object is used like any other object.

Creating an Customer Engagement Java Archive for an API Interface

Note:

Many programming environments will not require this procedure; an API interface will be imported simply by entering the URL for the WSDL in the proper field. Check the documentation for importing a web service API for your programming environment before performing this procedure.

This procedure uses commands for Java programmed in a Windows environment. Because WSDLs are not language-specific, the Customer Engagement API can be imported into many other languages. See the documentation for your programming environment and language for more information.

To create a Customer Engagement API interface for Java, do the following:

1. Open a command prompt.

2. In the command prompt, change to a working directory where a temporary directory can be created.

3. Create a temporary directory:

   mkdir temp

4. Change the working directory to the just-created temporary directory:

   cd temp

5. Create the stubs and proxies for the API.

   wsimport <WSDL_URL>

   where <WSDL_URL> is the URL for the API’s WSDL.

   These URLs can be found in “Overview” section of each service chapter in this manual.

   A com directory is created, containing all the stubs and proxies for the API.

6. Archive the stubs and proxies into a .jar file

   jar cvf <service_name>.jar com

   Where <service_name> is a descriptive name of the API.

   The resulting .jar file can be imported into the Java programming environment.

Using Customer Engagement APIs

To access an API, users must instantiate the API class in the program, project, or class using it. To do this, the API class must be packaged and the package imported into the project.

Depending upon the environment used by the programmer(s), the environment may take care of many of the details automatically, or the user may need to perform several steps to create a package file that can then be imported.

Once the package has been imported, the web service object is used like any other object.

Example

The example below demonstrates how a programmer retrieves a customer with card number "1000", through a user with an ID of "1". Then, using the retrieved customer record, the programmer retrieves the customer’s image.

In this example, Java will access methods on a Customer Services version 2.2 API connecting to an instance of Customer Engagement running on the local machine, using an organization ID of "mcs".

If you are using a language other than Java, you should still be able to use the example below as a template for your own implementation of the same functionality.

	CustomerServicesApiService apiService;	URL serviceURL;	try {		// Connecting to the service on localhost, using the mcs organization.		serviceURL = new			URL("http://localhost:<portNumber>/OrceWebServices/mcs/v2_2/CustomerServices?wsdl");		apiService = new CustomerServicesApiService(serviceURL);		CustomerResponseType customer;		// Retrieving the customer with Card ID of "1000" through User ID "1".		//   Note that the Card ID and User ID are strings rather than integers.		customer =			 apiService.getCustomerServicesApiPort().retrieveCustomer(null,					 null, "1000", "1");		CustomerImageType customerImage;		// Getting the image for the retrieved customer.		customerImage = 			apiService.getCustomerServicesApiPort().getCustomerImage("1", 			customer.getCustomerID());	} catch (Exception ex) {		// Error behavior.		...	}

Authentication

If message authentication is enabled in Customer Engagement, you must include authentication information in the HTTP header for the message. This authentication information is specific to Customer Engagement.

Create and Implement an Authentication Key

To create and implement an authentication key:

1. Use a Base64 encoding tool to encode the following string:

   [orgname]:[userid]:[password]

   where:

   • orgname is the name of your organization.

   • userid is the user ID of a Customer Engagement user.

   • password is the password for the Customer Engagement user.

   The command outputs the authentication string.

   Note:

   The user ID and password must be for a currently active user, and the password must be the password for that user.

   If the user is deactivated, authentication will fail, and the messages will fail.

   If the user’s password changes, and the string is not updated, authentication will fail, and the messages will fail.

   In the case of an authorization failure, a 403 error response is returned with the message Invalid Authentication Credentials Supplied.

   Setup example:

   For an organization with an Organization name of ABC, a user with the ID johndoe and a password of Password123, the string to encode would be:

   ABC:johndoe:Password123

   and the Base64-encoded string would be:

   QUJDOmpvaG5kb2U6UGFzc3dvcmQxMjM=

2. Copy the authentication string.

3. Add a line such as the following to the HTTP header for each message sent to Customer Engagement, such that:

   Authorization is in the Header field

   Org-User <encodedOrgUserPwd> is the Value, where <encodedOrgUserPwd> is the authentication string

   The resulting Header example would be:

   Authorization: Org-User QUJDOmpvaG5kb2U6UGFzc3dvcmQxMjM=

Common Objects

There are some objects that are used widely across all the APIs. These common objects are described below.

AttributeException

The AttributeException element contains the following elements:

Type	Element	Description
errorProperty[]	errProperties	Properties of the error.
exceptionCode	exceptionCode	ID for the error.
string	faultDetail	Detailed information about the fault.
string	message	Error message.
RelateProcessingException	relateExceptionCode	ID for the error in Customer Engagement.

errorProperty

The errorProperty class contains the following elements:

Type	Element	Description
string	key	Error property key.
string	value	Error property value.

RelateProcessingException

The RelateProcessingException class contains the following elements:

Type	Element	Description
string	faultDetail	Detailed description of the fault, including any debugging information.
string	message	Error message.
RelateProcessingException	relateExceptionCode	ID for the error.

Web Service Tracking

The Web Service Tracking pages in the user interface enable you to review the activity for each API on a daily, weekly, or monthly basis.

Figure 13-1

You can double-click the totals to open a window displaying a breakdown of operations by version, including the total number of successful and failed operations for each.

Figure 13-2 Detailed Web Service Tracking Window

See the User Guide for more information on these pages.