Connect SOAP API Developer’s Guide Using the Connect Toolkit

This chapter provides information about how to use Xactly Connect to create applications, including details about Xactly objects and operations, the processing model, and suggested best practices.

Understanding the Xactly Connect WSDL File

Xactly Connect allows enterprise developers to integrate client applications with Xactly Incent and Xactly Modeling. The Xactly Connect WSDL file offers strongly typed representations of your organization’s data, and supplies information about the schema, data types, and fields to your development environment, enabling tight integration between the application and Xactly Connect Web services.

You can obtain the Xactly Connect WSDL file for Incent and Modeling from the Xactly Incent Help section. For more information, see “Downloading the Xactly Connect WSDL File”.

 

Understanding Xactly Objects

In Xactly Connect, objects are data entities that represent information in your business. For example, the OrderStageWSO object represents Staging Order Items.

An object instance refers to a particular occurrence of an object (such as a specific item that is represented by an OrderStageWSO object). An object instance is analogous to a row in a database table.

 

Object Access

Client applications can only work with objects with which they are authorized to access. Programmatic access to objects is determined by the following:

  • The objects that are defined in the WSDL file
  • The configuration of your organization
  • Your security access, which is configured by your organization’s system administrator through the granting of privileges to your role

 

Understanding ID Reference Fields

Objects can be related to other WSO objects, with the relationships captured in the following reference fields:

  • ID Reference Field. Certain objects can reference other objects by identifier using the ID Reference Field. For example, an OrderStageWSO object can contain an ID reference to a PeriodWSO object.
  • Object Reference Field. Certain objects can have a relationship with other objects through an Object Reference Field. For example, orderStageAssignments is an Object Reference Field in the OrderStageWSO object.

 

Working with Required Fields

You must populate required fields with a non-null value when performing a save operation (to create or update an object). Note, however, that you cannot change certain required fields when saving an object.

note: Xactly Connect automatically populates certain required fields, such as system fields and the object ID fields.

 

Understanding Xactly Connect Operations

Xactly Connect provides operations that client applications can invoke at runtime to perform certain tasks. For example, you can use the Xactly Connect SOAP API to per- form the following:

  • Query data in your organization
  • Create, update, and delete information
  • Obtain metadata about data in your organization
  • Invoke incentive calculations
  • Route eDocs

 

Understanding the Processing Model

Xactly Connect uses the following processing model:

  • The client application prepares a request by defining the request parameters, if applicable.
  • The client application Invokes a call, which submits the request (and parameters) to the Xactly Connect Web service for processing.
  • The Xactly Connect Web service processes the request and returns a response.
  • The client application handles the response, including performing error handling if required.

Xactly Connect operations (requests) can be either synchronous or asynchronous (depending on the operation). In the case of synchronous operations, after an operation is invoked, the client application must wait until it receives a response from the service.

In contrast, for asynchronous operations, Xactly Connect allows your application to continue processing while providing you the ability to query the status of the operation, as required.

note: Xactly Connect commits data automatically when the save and delete methods are called.

 

Understanding Modeling Scenarios

A scenario is a combination of shared setup, organization, company, and order data together with a group of compensation plans. Xactly Modeling enables you to calculate a scenario based on a set of “what if” results that you can capture in a snapshot for later use.

Scenarios use the data you specified in your last initialization of the Modeling environment. After the Comp Admin defines a scenario along with an associated name, you can use the Xactly Connect SOAP API to perform computations based on the scenario.

 

Exploring Best Practices

The following summarizes a series of best practices to consider when using Xactly Connect:

  • Structure the logic of your application to reduce the number of service requests.
  • Use the upload operation to bulk load Users, People, and Orders instead of using multiple save operations.
  • Limit the size of the request, where possible. Increases in the size of the data can result in slower responses.
  • Use a fast Internet connection, where possible. Slower connections negatively impact the response time and can lead to timeouts.
  • All search operations are performed using SQL LIKE operators similar to the Xactly Incent application. This means that you may need to iterate through search result objects and compare entities.
  • Do not use the search operations to download high volume objects such as Orders, Credits, and Commissions; use the download operations instead.