Integration Events Best Practices
The iCIMS Talent Acquisition Platform can generate real-time HTTP POST requests to an endpoint provided by a 3rd party for certain user actions. The endpoint should be designed to handle multiple customers and multiple event notification types to minimize the variability in the setup of the integration across multiple customers.
All event notifications provide, as part of the payload, customer id and event type. The customer id uniquely identifies an iCIMS customer’s platform and should be used to allow the endpoint to serve multiple customers. The event type property can be used to allow a single endpoint to serve multiple event notification type. It is up to the 3rd party to determine if a single endpoint will handle multiple event types, but it is required that a single endpoint be able to serve multiple customers.
iCIMS requires that all communication is done over https with a valid SSL certificate. Self-signed certificates cannot be used. OAuth 2.0, HMAC, and Basic Authentication are available for outbound event notifications.
To support OAuth 2.0 the Access Token URL, Client ID and Client Secret must be provided. The OAuth server token endpoint must adhere to the OAuth 2.0 client credentials grant flow.
An example of the expected Authorization Response is below.
HTTP/1.1 200 OK
Content-Type: application/json
{
"access_token":"eyJz93a...k4laUWw",
"token_type":"Bearer",
"expires_in":86400
}
iCIMS requires all event notifications to be processed with the fail-fast pattern. We have identified scenarios that an integration must handle to provide a reliable user experience.
Scenario 1: Successfully Processed Event Notification
iCIMS expects the 3rd party to process the event notification in a single transaction. The transaction should be ACID compliant.
Scenario 2: Duplicate Request
A user can generate multiple event notifications for the same action. The 3rd party system must handle duplication requests and not treat each request as a new request. Each event notification has identifiers that can be used to detect duplicate requests.
Scenario 3: Failure Caused by User Action (Missing Fields, Incorrect Package Selection, Etc.)
If the 3rd party platform cannot validate information provided by the user, it must return 400 for user error with a user actionable error message in the response’s payload. If the error cannot be corrected by the user, the system must return a 500 error. Please refer to Error Handling and Reporting for more details.
The user is expected to fix the issue and try again or reach out to support.
Scenario 4: Failure to Connect to 3rd Party Platform
If iCIMS is not able to communicate with the 3rd party platform, it will record the failure and notify the user. The user is expected to try again, but if the failure persists, the user will need to reach out to support.
Scenario 5: Failure to Receive Confirmation from 3rd Party Platform
If iCIMS is not able to receive the confirmation message to the event notification, it will record the failure and notify the user. The user is expected to try again but if the failure persists, the user will need to reach out to support.
It’s important for the 3rd party to recognize this type of a failure and for the 3rd party’s duplicate request checking logic to account for this scenario. The record in the 3rd party platform will already exist, but the user, upon trying again, will be notified that the request was processed. Duplicate check should prevent duplicate records from being created.
Scenario 6: Unknown Failure
If unusual behavior is observed, iCIMS will record the failure and notify the user. The user is expected to try again, but if the failure persists, the user will need to reach out to support.
Upon retrying, either the transaction will have been processed by the 3rd party—in which case, it will be treated as a duplicate request—or it will be the first time the 3rd party has encountered the request, in which case, it will be treated as a new transaction.
iCIMS expects event notifications to be processed within 30 seconds. If iCIMS does not receive a response within 30 seconds, it will treat it as an unknown failure. Users at this point will be asked to try again and the 3rd party is expected to prevent duplicate records from being created.
To prevent excessive response times, the 3rd party should do the minimal work required to be processed synchronously. Additional work that does not impact user experience should be scheduled asynchronously.
When developing an integration based on event notifications, you should keep in mind who the actor is. Some event notifications will be triggered by recruiters and others will be triggered by candidates and new hires. When the system is unable to process the event notification, it should present an error message appropriate to the actor. Integrations should not ask candidates and new hires to fix things that they will not have access to. The application complete event notification enhances the application process. This event notification should be built as failsafe as possible. Presenting errors during this process will degrade the candidate experience, ultimately resulting in the recruitment organization to observe an increase in candidate drop off rate.
The party writing the integration is ultimately responsible for the correctness and reliability of the integration. The following are recommended guidelines based on best judgment of those responsible for the documentation.
Here we describe how an ACID compliant transaction to handle event notifications can be implemented. The strategy described below relies on a Relational Database Management System (RDBMS) that is ACID compliant.
We start the transaction by reading from remote systems and validating the input before any data is written. Once input has been validated, appropriate records are created and/or updated. If actions need to be taken on systems outside of the RDBMS’ transaction, a scheduler that can schedule tasks within the RDBMS’ transaction should be used. Tasks to update systems outside of the RDBMS transaction should be scheduled within the RDBMS’ transaction. If no issues occur, the transaction is committed. Otherwise, it is rolled back.
Quartz is an example of a scheduler that can schedule tasks within a RDBMS transaction. The input validation should ensure that systems outside of the RDBMS transaction will not run into validation issues when the scheduled tasks execute. The scheduled task should be executed asynchronously and retry logic with failure handling should be implemented.
- An ACID compliant RDBMS is used and a transaction is started.
- Within the transaction, the system checks to see if it has processed this event notification before. We recommend creating a “record table” with unique identifiers as primary keys to ensure that each event notification is processed only once. The system will react accordingly depending on if the duplicate request is detected or not. Refer to the “Reliably Handling Event Notifications” section for more information.
- Information is gathered from systems outside of the RDBMS’ transaction.
- Information is gathered from systems inside of the RDBMS’ transaction. This is done after external systems are read to reduce the time that read locks are held.
- Information is validated to ensure that this system and any downstream systems will be able to process the information.
- Records are created and updated and a new row is created in the “record table” to prevent duplicate processing of the event notification. If another transaction that has processed the event notification has successfully committed, the RDBMS will fail this transaction and rollback changes due to primary key violation.
- If additional systems that resides outside of the RDBMS’ transaction need to take action (e.g., email system), a scheduling tool can be used schedule the task within the transaction and trigger the action outside of the transaction asynchronously.
- The transaction is committed.