Connect SOAP API Developer’s Guide Exploring the Operations
Exploring the Operations
This section describes the operations available using Xactly Connect.
addBatchEventsToQueue
The addBatchEventsToQueue operation enables you to add bulk batches to the pro- cess queue.
Table 96: addBatchEventsToQueue Operation Summary
addCommissionReleaseTemplateToQueue
The addCommissionReleaseTemplateToQueue operation enables you to add com- mission release templates to the process queue.
Table 97: addCommissionReleaseTemplateToQueue Operation Summary
addPeriodEventsToQueue
The addPeriodEventsToQueue operation enables you to add bulk period events to the queue process to delete staging/processed orders in a period.
Table 98: addPeriodEventsToQueue Operation Summary
addProcessGroupEventsToQueue
The addProcessGroupEventsToQueue operation enables you add process group events to the process status queue.
Table 99: addProcessGroupEventsToQueue Operation Summary
addReleasePartialHeldCommissionsToQueue
The addReleasePartialHeldCommissionsToQueue operation enables you to add release partial held commissions events to the queue process.
Table 100: addReleasePartialHeldCommissionsToQueue Operation Summary
addReleaseHeldResultsToQueue
The addReleaseHeldResultsToQueue operation enables you to add release held credit, commission, or bonus result events to the queue process.
Table 101: addReleaseHeldResultsToQueue Operation Summary
addSelectedItemEventsToQueue
The addSelectedItemEventsToQueue operation enables you to add staging/pro- cessed orders by identifier.
Table 102: addSelectedItemEventsToQueue Operation Summary
addSinglePeriodProcessingEventsToQueue
The addSinglePeriodProcessingEventsToQueue operation enables you to add single period processes to the process queue. The operation returns a QueueRegionRe- sponse object which contains the queue region ID.
Table 103: addSinglePeriodProcessingEventsToQueue Operation Summary
addVersion
The addVersion operation enables you to add a new version of an effective dated object, such as a Person and Position.
Table 104: addVersion Operation Summary
calculateBatch
The calculateBatch operation enables you to start the calculation process on a specified batch in Processed Orders (either credit-only or through incentives).
Table 105: calculateBatch Operation Summary
calculateBatchWithScenario
The calculateBatchWithScenario operation enables you to calculate batches with scenarios.
Table 106: calculateBatchWithScenario Operation Summary
calculateScenario
The calculateScenario operation enables you to calculate one or more scenarios.
Table 107: calculateScenario Operation Summary
delete
The delete operation enables you to delete one or more objects.
Table 108: delete Operation Summary
deleteCustomReport
The deleteCustomReport operation enables you to delete custom reports.
Table 109: deleteCustomReport Operation Summary
deleteEventsFromQueue
The deleteEventsFromQueue operation enables you to delete batch events from the queue.
Table 110: deleteEventsFromQueue Operation Summary
deleteOrderDetailsByBatchAsync
The deleteOrderDetailsByBatchAsync operation enables you to delete order details asynchronously by batch.
Table 111: deleteOrderDetailsByBatchAsync Operation Summary
deleteOrderDetailsByPeriodAsync
The deleteOrderDetailsByPeriodAsync operation enables you to delete order details asynchronously by period.
Table 112: deleteOrderDetailsByPeriodAsync Operation Summary
deleteOrderItemsByBatchAsync
The deleteOrderItemsByBatchAsync operation enables you to initiate an asynchronous operation to delete Processed Orders, specified by batch.
Table 113: deleteOrderItemsByBatchAsync Operation Summary
deleteOrderItemsByPeriodAsync
The deleteOrderItemsByPeriodAsync operation enables you to initiate an asynchronous operation to delete Processed Orders, specified by period.
Table 114: deleteOrderItemsByPeriodAsync Operation Summary
deleteOrderItemsResultsByPeriodAsync
The deleteOrderItemsResultsByPeriodAsync operation enables you to delete pro- cessed orders asynchronously, by period name. When using this operation, you can use the getOrderDeleteStatus operation to determine the status of the asynchronous delete operation.
Table 115: deleteOrderItemsResultsByPeriodAsync Operation Summary
deleteOrderStageByBatch
The deleteOrderStageByBatch operation enables you to delete orders from order staging, by batch.
Table 116: deleteOrderStageByBatch Operation Summary
deleteOrderStageByBatchAsync
The deleteOrderStageByBatchAsync operation enables you to delete orders from order staging asynchronously, by batch.
Table 117: deleteOrderStageByBatchAsync Operation Summary
deleteOrderStageByPeriod
The deleteOrderStageByPeriod operation enables you to delete orders from order staging, by period.
Table 118: deleteOrderStageByPeriod Operation Summary
deleteOrderStageByPeriodAsync
The deleteOrderStageByPeriodAsync operation enables you to delete orders from order staging asynchronously, by period.
Table 119: deleteOrderStageByPeriodAync Operation Summary
deleteProcessedOrderItemsByBatch
The deleteProcessedOrderItemsByBatch operation enables you to delete processed order items by batch.
Table 120: deleteProcessedOrderItemsByBatch Operation Summary
deleteProcessedOrderItemsByPeriod
The deleteProcessedOrderItemsByPeriod operation enables you to delete processed order items by period.
Table 121: deleteProcessedOrderItemsByPeriod Operation Summary
deleteVersion
The deleteVersion operation enables you to delete a version of an effective dated object, such as a Person and Position. Note that you can use the deleteVersion operation to delete a PositionHierarchyWSO object.
Table 122: deleteVersion Operation Summary
describeXObject
The describeXObject operation enables you to retrieve metadata for the specified object type including field list, object properties, and data types.
Table 123: describeXObject Operation Summary
download
The download operation enables you to download the file specified by the download identifier.
Table 124: download Operation Summary
downloadEx
The downloadEx operation enables you to download objects in Xactly Credit Assignment.
Table 125: downloadEx Operation Summary
downloadQueueEventErrors
The downloadQueueEventErrors operation enables you to download errors related to process queue events.
note: This operation currently only supports release commissions by template errors.
Table 126: downloadQueueEventErrors Operation Summary
downloadUploadErrorLog
The downloadUploadErrorLog operation enables you to download errors that have occurred during Order and Quota upload operations.
The UploadResponse object that is returned following an upload operation contains only the first 22 errors. You can use the downloadUploadErrorLog operation to down- load all errors encountered during an upload operation (including the first 22 returned in the UploadResponse object).
To access the upload error log, do the following:
- Perform the Order and Quota upload operation.
- Check the result field in the UploadResponse object (returned by the upload operation).
- If the result is False (indicating an error), call the downloadUploadErrorLog operation (using the uploadId available in the UploadResponse object) to download all error messages.
Table 127: downloadUploadErrorLog Operation Summary
downloadXObjectUploadErrors
The downloadXObjectUploadErrors operation enables you to download errors that have occurred during Hierarchy upload operations.
The UploadXObjectResponse object that is returned following an uploadXObject operation contains only the first 22 errors. You can use the downloadXObjectUpload- Errors operation to download all errors encountered during an uploadXObject operation (including the first 22 returned in the UploadXObjectResponse object).
To access the upload error log, do the following:
- Perform the Hierarchy upload operation.
- Check the result field in the UploadXObjectResponse object (returned by the uploadXObject operation).
- If the result is False (indicating an error), call the downloadXObjectUploadErrors operation (using the uploadId available in the UploadXObjectResponse object) to download all error messages.
Table 128: downloadXObjectUploadErrors Operation Summary
editQueueProcessingState
The editQueueProcessingState operation allows you to modify the queue processing state (either start or stop the queue processing).
Table 129: editQueueProcessingState Operation Summary
getActiveQueueRegions
The getActiveQueueRegions operation enables you to retrieve the active queue regions within a queue.
Table 130: getActiveQueueRegions Operation Summary
getBusinessIdentifierToken
The getBusinessIdentifierToken operation enables you to get the business identifier token for the user that is currently logged in.
Table 131: getBusinessIdentifierToken Operation Summary
getCalculationProcessDiagnostics
The getCalculationProcessDiagnostics operation enables you to retrieve the calcula- tion process diagnostics for the specified batch name. The getCalculationProcessDi- agnostics operation returns a CalculationResponse object.
Table 132: getCalculationProcessDiagnostics Operation Summary
getCalculationProcessDiagnostics
The getCalculationProcessDiagnostics operation enables you to retrieve the calcula- tion process diagnostics for the specified batch name. The getCalculationProcessDi- agnostics operation returns a CalculationResponse object.
Table 133: getCalculationProcessDiagnostics Operation Summary
getCreditAssignmentStatus
The getCreditAssignmentStatus operation enables you to retrieve the status of a credit assignment run.
Table 134: getCreditAssignmentStatus Operation Summary
getEnhancedCalculationDiagnostics
The getEnhancedCalculationDiagnostics operation enables you to retrieve detailed information about a batch calculation process.
Table 135: getEnhancedCalculationDiagnostics Operation Summary
getEventQueueStatus
The getEventQueueStatus operation enables you to retrieve the current queue status (whether the queue is started or paused).
Table 136: getEventQueueStatus Operation Summary
getOrderDeleteStatus
The getOrderDeleteStatus operation enables you to determine the status of the cur- rent asynchronous delete operation. The getOrderDeleteStatus operation returns a DeleteResponse object.
Table 137: getOrderDeleteStatus Operation Summary
getOrdersResultsDeleteStatus
The getOrdersResultsDeleteStatus operation enables you to determine the status of an asynchronous processed orders or staged orders delete operation.
Table 138: getOrdersResultsDeleteStatus Operation Summary
getQueueEventErrors
The getQueueEventErrors operation enables you to retrieve the process queue event errors, in cases when errors were indicated by the getQueueStatusResponse operation (use the same eventWSO parameter as you used with the getQueueStatusResponse operation).
The getQueueEventErrors operation returns a QueueEventResponse object, which contains one or more error codes, with appropriate error messages, indicating any problems with the particular queue event.
Table 139: getQueueEventErrors Operation Summary
getQueueProcessThroughErrorFlag
The getQueueProcessThroughErrorFlag operation enables you to retrieve the QUEUE_PROCESS_THROUGH_ERROR preference value for your business.
Table 140: getQueueProcessThroughErrorFlag Operation Summary
getQueueStatusByRegion
The getQueueStatusByRegion operation enables you to retrieve the queue region status.
Table 141: getQueueStatusByRegion Operation Summary
getQueueStatusResponse
The getQueueStatusResponse operation enables you to determine the status of a specific queue event based on the eventWSO parameter, which includes properties such as the transaction ID, batch name, and batch ID.
The getQueueStatusResponse operation returns a QueueEventResponse object, which has properties that indicate the status of the particular event (including whether the event has started or completed, or if the queue event has errors). If the queue event has errors, you can use the getQueueEventErrors operation to retrieve the errors.
Table 142: getQueueStatusResponse Operation Summary
getUploadXObjectStatus
The getUploadXObjectStatus operation enables you to determine the status of the current asynchronous upload operation. The getUploadXObjectStatus operation returns an UploadXObjectResponse object.
Table 143: getUploadXObjectStatus Operation Summary
getValidationErrorForTransaction
The getValidationErrorForTransaction operation enables you to retrieve the validation errors for the specified transaction ID. The getValidationErrorForTransaction operation returns a ValidationResponse object.
Table 144: getValidationErrorForTransaction Operation Summary
initiateDownload
The initiateDownload operation enables you to initiate a download by period for OrderStage, Credit, Commission, Bonus, DrawPeriod, CompOrderItem, or PaymentPeriod.
Table 145: initiateDownload Operation Summary
initiateDownloadEx
The initiateDownloadEx operation enables you to initiate the download of objects in Xactly Credit Assignment.
Table 146: initiateDownloadEx Operation Summary
isJobRunning
Xactly prevents you from running a job if it conflicts with another job already running within the system. For example, you cannot upload orders when a delete orders job is running. The isJobRunning operation enables you to determine if it is possible to per- form the job specified in the jobType parameter at the current time.
The operation returns False if there are no conflicting jobs running within Xactly, and returns True when a conflicting job would prevent you from running the specified job.
Table 147: isJobRunning Operation Summary
The following table lists the values you can specify for the jobType parameter:
Table 148: JobType Values
login
The login operation enables you to log in to the Xactly Incent application and start a client session.
note: Only Business Administrators can log into Xactly Incent using Connect. Table 149: login Operation Summary
purgeAllBatchDataAsync
The purgeAllBatchDataAsync operation enables you to delete processed orders, the order stage, and the batch definition asynchronously, by batch name. When using this operation, you can use the getOrderDeleteStatus operation to determine the status of the asynchronous delete operation.
Table 150: purgeAllBatchDataAsync Operation Summary
purgeAllPeriodDataAsync
The purgeAllPeriodDataAsync operation enables you to delete processed orders, the order stage, and the batch definition asynchronously, by period name. When using this operation, you can use the getOrderDeleteStatus operation to determine the status of the asynchronous delete operation.
Table 151: purgeAllPeriodDataAsync Operation Summary
queryDocumentStatus
The queryDocumentStatus operation enables you to query the status of a document.
Table 152: queryDocumentStatus Operation Summary
reassignOrderStageBatch
The reassignOrderStageBatch operation enables you to reassign Order Stage objects from one batch to another batch.
Table 153: reassignOrderStageBatch Operation Summary
releaseBonus
The releaseBonus operation enables you to release a specified bonus result.
Table 154: releaseBonus Operation Summary
releaseCommission
The releaseCommission operation enables you to release a specified commission result.
Table 155: Operation Summary
releaseCredit
The releaseCredit operation enables you to release a specified credit result.
Table 156: releaseCredit Operation Summary
resumeSummaryReportsRefreshProcess
The resumeSummaryReportsRefreshProcess operation enables you to resume the sum- mary reports refresh process for the business. The operation takes effect on the next report refresh run.
Table 157: resumeSummaryReportsRefreshProcess Operation Summary
routeDocument
The routeDocument operation enables you to route documents.
Table 158: routeDocument Operation Summary
runCreditAssignment
The runCreditAssignment operation enables you to trigger a credit assignment run,
Table 159: runCreditAssignment Operation Summary
Save
The save operation enables you to add or update one or more objects (except Order Stage objects). To save Order Stage objects, use the saveOrderStage operation.
Table 160: save Operation Summary
saveCustomReport
The saveCustomReport operation enables you to save a custom report in PDF and Excel formats.
Table 161: saveCustomReport Operation Summary
saveCustomReport
The saveCustomReport operation enables you to save a custom report in PDF and Excel formats.
Table 162: saveCustomReport Operation Summary
saveExternaltaskResponse
The saveExternaltaskResponse operation enables you to save the status of external processes. The saveExternaltaskResponse operation returns a ExternalTaskRespon- seWSO object.
Table 163: saveExternaltaskResponse Operation Summary
saveOrderStage
The saveOrderStage operation enables you to save an array of orders to Order Stag- ing. Note that you can use the saveOrderStage operation to create new Order Stage objects but not to update existing Order Stage objects.
Table 164: saveOrderStage Operation Summary
saveUserPersonWorkflow
The saveUserPersonWorkflow operation enables you to save User, Person, Position, and Position Hierarchy objects in a single operation.
note: This operation is intended to be used only for setting up new hires.
Table 165: saveUserPersonWorkflow Operation Summary
saveVersion
The saveVersion operation enables you to save a version of an effective dated object, such as a Person and Position.
Table 166: saveVersion Operation Summary
Search
The search operation enables you to perform a query against a specified object (using Query By Example).
You can also use the search and searchMore operations to search queue events and queue errors. To search for queue events, create a QueueEventWSO object and pass the queueRegionId and/or batchName search text values. By default, the search operation fetches 200 records.
If there are more than 200 records, you can make subsequent calls using the search- More operation using a startIndex and QueueEventWSO object. In this case, the queueRegionId parameter is mandatory and the batchName search text is optional.
To search for queue event errors, create a QueueEventErrorWSO object and pass the queueRegionId and/or batchName search text values. You can search for more than 200 records using the searchMore operation, as described earlier.
Table 167: search Operation Summary
searchMore
The searchMore operation enables you to retrieve the next batch of objects from the search query.
Table 168: searchMore Operation Summary 
submitForRankGroupPublish
The submitForRankGroupPublish operation enables you to submit a request to publish ranking data.
Table 169: submitForRankGroupPublish Operation Summary
suspendSummaryReportRefreshProcess
The suspendSummaryReportRefreshProcess operation enables you to suspend the summary report refresh process for the business. The suspension affects all upcoming report refresh runs, and remains effective until the number of hours specified in the suspendThreshold parameter has elapsed.
Table 170: suspendSummaryReportRefreshProcess Operation Summary
updateQueueProcessThroughErrorFlag
The updateQueueProcessThroughErrorFlag operation enables you to update the QUEUE_PROCESS_THROUGH_ERROR preference value for your business.
Table 171: updateQueueProcessThroughErrorFlag Operation Summary
upload
The upload operation enables you to upload Excel .xls templates for CurrencyRate, OrderStage, Named Relationship, Person, Position, Quota, RateTable, and User objects. You can also upload Draw assignments and OrderStage objects using CSV (Comma Separated Value) format.
Note that you can upload Quotas based on assignments instead of Quota objects. Similarly, you can upload Rate Tables based on assignments instead of Rate Table objects. This means that you can update Quota and Rate Table assignments across multiple Quotas and Rate Tables respectively using a single upload.
note: Unlike the Xactly Incent application, Xactly Connect does not enable you to specify the following option when uploading Quotas: Allow mid-period dates and align to period start date.
Table 172: upload Operation Summary
note: Contact Xactly Right Support for the template to upload Draw assignments.
uploadEx
The uploadEx operation enables you to perform upload operations in Xactly Credit Assignment.
Table 173: uploadEx Operation Summary
uploadXObject
The uploadXObject operation enables you to upload Excel .xls templates for Hierarchy objects.
Table 174: uploadXObject Operation Summary
validateBatch
The validateBatch operation enables you to start the validation process on a specified batch in Order Staging.
Table 175: validateBatch Operation Summary
validateBatchWithScenario
The validateBatchWithScenario operation enables you to validate batches with scenarios.
Table 176: validateBatchWithScenario Operation Summary
