Introducing the Xactly Connect SOAP API
Xactly Connect offers a Web Services Application Programming Interface (API) that enables developers to extend the capabilities of Xactly Incent and Modeling. by pro- viding seamless system-to-system communication.
Using Xactly Connect, you can create applications that integrate key business data from human resources, product catalogs, order management, and payroll with Xactly Incent and Modeling.
For example, you can create applications to do the following:
- Automatically synchronize key data used across business systems. Updates made in the system of record can immediately be reflected in Xactly Incent, eliminating data latency issues.
- Eliminate time-consuming, error-prone manual processes. You can employ both synchronous and asynchronous communications methods to systemically link formerly manual data transmission and maintenance processes.
- Guarantee process controls. The timing and sequence of sales compensation processing is critical to producing timely, accurate results. Using Xactly Connect, you can ensure that the correct data is processed at the right time.Xactly Connect supports Java and Microsoft .NET based environments, as well as enabling access using SOAP. Figure shows how Xactly Connect integrates with Xactly Incent, Xactly Modeling, and your business applications.
Xactly Connect Architectural Overview
Understanding Xactly Connect Concepts
Xactly Connect enables you to access data objects and operations within Xactly Incent and Modeling, using the security model offered by the Xactly Incent application.
This section describes the following concepts:
- Xactly Connect Objects and Operations
- Introducing the Xactly Connect Security Model
Xactly Connect Objects and Operations
Xactly Connect enables you to access the following system components to extend the capabilities of Xactly Incent and Modeling:
- Xactly objects. Xactly Connect provides access to key data objects managing day-to-day processes within Incent, Modeling, and Territories.
- Object operations. Using Xactly Connect, you can perform read, search, create, update, upload, and delete operations on data objects. These operations are similar to those provided through Xactly Incent, Modeling, and Territories.
- Process operations. Xactly Connect Admins can start and monitor key processes such as validation, calculation, and result releases.note: Plan Design elements such as rule creation are not available through Xactly Connect.
Introducing the Xactly Connect Security Model
Xactly Connect security is managed by the role assigned to a user in Xactly Incent or Modeling. Client applications that access your organization’s Incent or Modeling data are therefore subject to the same security protections used in the Xactly Incent or Modeling user interface.
Within Incent, the application pages granted through a user’s role determines the objects that can be accessed through Xactly Connect. For example, if an Xactly Connect Admin has access to the Plan Design > Quotas page then that person can perform operations on Quotas using Xactly Connect.
User Authentication
Client applications must log in using valid credentials for an organization. The login process authenticates the credentials.
Implicit Restrictions on Objects and Fields
Certain objects such as Commissions and Payments can only be created or deleted using the Xactly Incent or Xactly Modeling application. Client applications cannot save or delete these objects.
note: You can create Manual Credit and Bonuses using Xactly Connect.
Similarly, certain fields within some objects can be specified when the object is created but not during an update. Other fields are read-only; client applications cannot specify these field values when the object is created or updated. For more information, see the respective object descriptions in “Understanding Xactly Objects” on page 62.
Exploring Xactly Connect SOAP API
The Xactly Connect SOAP Application Programming Interface enables you to manipulate Xactly data objects, including reading, searching, creating, updating, upload- ing, and deleting objects, using operations similar to those provided in Xactly Incent and Modeling.
The API also enables you to process orders (including validating and calculating batches), release results (bonuses, commissions, and credits), and retrieve metadata for specified objects.
Table 3 provides an overview of the Xactly Connect SOAP API.
Table 3: Xactly Connect SOAP Application Programming Interface Overview
| Type | Operation | Description |
|---|---|---|
| Application login | login | Log in to the application and specific module (such as Incent or Modeling) and start a client session using the API. |
| resolveGateway | Resolve the gateway to use for login authentication. | |
| Search | search | Perform a query against a specified object (Query By Example). |
| searchMore | Retrieve the next batch of objects from the search query. | |
| Data modification | delete | Delete one or more objects. |
| save | Add or update one or more objects. | |
| saveList | Add or update a list of objects. | |
| Order processing | calculateBatch | Start the calculation process on a specified batch in Processed Orders (either credit-only or through incentives). |
| calculateBatchWithScenario | Start the calculation process on a specified batch and scenario in Modeling (either credit-only or through incentives). This is valid only in the Modeling module. | |
| getCalculationProcessDiagnostics | Retrieve the calculation diagnostics for the specified batch. | |
| getCreditAssignmentStatus | Retrieve the status of a credit assignment run. | |
| getValidationErrorForTransaction | Retrieve the validation errors for the specified transaction ID. | |
| runCreditAssignment | Trigger a credit assignment run, | |
| validateBatch | Start the validation process on a specified batch in Order Staging. | |
| validateBatchWithScenario | Start the validation process on a specified batch and scenario in Order Staging. This operation is valid only in the Modeling module. | |
| Releases | releaseBonus | Release a specified bonus result. |
| releaseCommission | Release a specified commission result. | |
| releaseCredit | Release a specified credit result. | |
| Order management and setup (Incent) | deleteOrderItemsBy BatchAsync | Delete processed order items asynchronously, by batch. Use this when you need to perform delete operations on a high-volume batch. |
| deleteOrderItemsByPeriodAsync | Delete processed order items asynchronously, by Period. | |
| deleteOrderItemsResultsByPeriodAsync | Delete processed orders asynchronously, by period name. | |
| deleteOrderStageByBatch | Delete orders from Order Staging, specified by batch. | |
| deleteOrderStageByBatchAsync | Delete orders from order staging asynchronously, by batch. | |
| deleteOrderStageByPeriod | Delete orders from Order Staging, specified by period. | |
| deleteOrderStageByPeriodAsync | Delete orders from order staging asynchronously, by period. | |
| download | Download the file specified by the download identifier. | |
| downloadUploadErrorLog | Download all errors that have occurred during upload operations. | |
| downloadXObjectUploadErrors | Download errors that have occurred during Hierarchy upload operations. | |
| getOrderDeleteStatus | Determine if the order delete process is still in progress. Use this in conjunction with the deletion of processed order items in asynchronous mode. | |
| getOrdersResultsDeleteStatus | Determine the status of an asynchronous processed orders or staged orders delete operation. | |
| getUploadXObjectStatus | Determine the status of the current asynchronous upload operation. | |
| initiateDownload | Initiate a download by period for OrderStage, Credit, Commission, Bonus, Draw, CompOrderItem, or Payment. | |
| purgeAllBatchDataAsync | Delete processed orders, the order stage, and the batch definition asynchronously, by batch name. | |
| purgeAllPeriodDataAsync | Delete processed orders, the order stage, and the batch definition asynchronously, by period name. | |
| reassignOrderStageBatch | Reassign Order Stage objects from one batch to another batch. | |
| saveOrderStage | Store an array of orders from Order Staging to the database. | |
| upload | Upload Excel .xls templates for User, ExchangeRates, Person, Position, RateTable, Quota, PlanAssignments, Draw Assignments, Orders, Comporderitemdetails. | |
| uploadXObject | Upload Excel .xls templates for Hierarchy objects. | |
| Process queue management | addBatchEventsToQueue | Add bulk batches to the process queue for calculation. |
| addCommissionReleaseTemplateToQueue | Add commission release templates to the process queue. | |
| addPeriodEventsToQueue | Add bulk period events to the queue process to delete staging/processed orders in a period. | |
| addProcessGroupEventsToQueueRequest | Add process group events to the process status queue. | |
| addReleasePartialHeldCommissionsToQueue | Add release partial held commissions events to the queue process. | |
| addReleaseHeldResultsToQueue | Add release held credit, commission, or bonus result events to the queue process. | |
| addSelectedItemEventsToQueue | Add staging/processed orders by identifier. | |
| addSinglePeriodProcessingEventsToQueue | Add single period processes to the process queue. | |
| deleteEventsFromQueue | Delete batch events from the queue. | |
| downloadQueueEventErrors | Download errors related to process queue events. | |
| editQueueProcessingState | Modify the queue processing state (either start or stop the queue processing). | |
| getActiveQueueRegions | Retrieve the active queue regions within a queue. | |
| getEventQueueStatus | Retrieve the current queue status (whether the queue is started or paused). | |
| getQueueEventErrors | Retrieve the process queue event errors. | |
| getQueueProcessThroughErrorFlag | Retrieve the QUEUE_PROCESS_THROUGH_ERROR preference value. | |
| getQueueStatusByRegion | Retrieve the queue region status. | |
| getQueueStatusResponse | Determine the status of specific queue events. | |
| isJobRunning | Determine if a job of a specific type is running. | |
| saveExternaltaskResponse | Save the status of external processes | |
| updateQueueProcess ThroughErrorFlag | Update the QUEUE_PROCESS_THROUGH_ERROR preference value. | |
| Order management (Territories) | downloadEx | Download the specified file, |
| initiateDownloadEx | Initiate a download, by period, for external, credited transactions. | |
| uploadEx | Upload external transactions (using CSV and .XLS upload templates). | |
| eDocs management (Incent) | queryDocumentStatus | Retrieve the status of a document routed earlier (either through the user interface or API). |
| routeDocument | Route a document definition through a user-defined workflow. | |
| Reports management (Incent) | submitPublishRankingInfo | Start publishing a ranking group. |
| Versioning | addVersion | Add a new version of an effective dated object, such as a Person and Position. |
| deleteVersion | Delete a version of an effective dated object. | |
| saveVersion | Save a version of an effective dated object. | |
| Metadata (Incent and Modeling) | describeXObject | Retrieve metadata for the specified object type including field list, object properties, and data types. |
Exploring Xactly Incent and Modeling Objects
Xactly Connect provides access to key data objects within Xactly Incent and Model- ing, enabling you to manage day-to-day processes through client applications.
Table 4 describes the Xactly objects available using the Xactly Connect.
Table 4: Xactly Incent and Modeling Objects Overview
Understanding Xactly Connect Governance
To maintain optimum performance, Xactly balances transaction loads by limiting the number of API requests (or calls) that any one customer business may execute con- currently or within any 24-hour period.
The Xactly Connect governance policy defines the transaction limit as the lower of the following:
- 100 calls per subscriber license per 24-hour period
- 10,000 calls per business per 24-hour period