Custom Integration for DSR
The custom integration allows you to extend the DSR handling workflow with your own code. This is especially useful for applying custom business logic, handling internal home-brew systems or preventing external connections to internal databases. This is extremely easy to implement with your own API endpoint (such as a cloud function) or even no-code automation tools, such as Zapier or Integromat.
The custom integration allows you to register API endpoints that will be called as part of the DSR workflow. Just like Mine's built-in integrations, custom integration supports any request type (Delete, Copy, etc.), allows previewing user data, and supports advanced operations such as handling failures and performing long-running async operations.
The custom integration supports the following operations. Each operation requires an endpoint URL in order to be used:
Operation | Description |
---|---|
Delete | An endpoint designed to handle any request that is mapped to the delete workflow. It supports both async and sync flows. |
Copy | An endpoint designed to handle any request that is mapped to the copy workflow. It supports both async and sync flows. |
Preview | This is an optional endpoint allowing you to handle record previews when handling tickets through the UI. This is handled in a synchronous way. |
Note: while Preview is optional, at least one of the copy or delete endpoints has to be defined.
To see specific implementation guides on each of the operations, use the following links:
Adding Custom Integrations
Custom integration is available for custom systems in your data inventory. To more than one custom integration simply add multiple custom systems.
When multiple custom integrations are used, the integrationId field is used for updating the status of a specific integration.
Request Payload
Every time MineOS makes an HTTP call to your endpoint, regardless of the operation, the following JSON payload is sent as the request body:
{
// usefull for logging
"traceId": "123456789abcdefghijklm",
// used for the CustomIntegrationStatus endpoint
"integrationId": "0c36xnykgewwbzfukh1jkq",
// indicates this is just a test event, actual processing should be skipped
"isTest": true,
// the request object is not always available:
// its available when handling a DSR but not handling when handling a user search
"request": {
// used for the CustomIntegrationStatus endpoint
"id": "ABCDEFGHIJKLMNOPQRSTUV",
// type of request. Possible values: Delete,GetCopy,DoNotSell,Undetermined,RightToEdit,DoNotMail
"type": "Delete",
// the channel from which the request was sent. Possible values: Form,MineApp,Api,EmailForwarding,Manual
"source": "Form",
// the main domain of the workspace to which the request was sent
"domain": "test.com",
"createdAt": "2023-07-28T11:35:21.7528109Z",
// type of request V2. The possible values can be viewed in the Portal under DSR Handling -> DSR setup tab
// for backwards compatability the id is the same as the "type" field lowercased.
"requestType": {
"id": "delete",
"name": "Delete"
}
},
"userInfo": {
"name": "Test User",
"email": "[email protected]",
"isVerified": false,
"countryOfResidence": "TestCountry",
// fields set through UpdateMetadata endpoint
"customFields": {
"testCustomKey": "Custom value"
}
}
}
Logging And Storing Information
At any time while processing a request, you might want to store information on the request:
- Logging/documenting important business information, for example: the type of customer, the underlying system etc. This can be done with Add a note API. In the UI this information is visible in the notes section on the right side.
- Storing metadata/state information, for example: internal user Id, URI of related resources or other metadata about the handling flow. This can be done with Update metadata API. This information is not visible in the UI but can be retrieved with Get metadata API.
Security
When receiving requests to your endpoint, its best to perform a security check before processing the event. There are a number of supported security mechanisms, you can use any one of them, or a combination of more than one:
- API Key - the requests can include a header with a name and value of your choice. By setting a secret value as a custom header, you can verify in your code that the header contains the value your would expect, similar to using an API Key. This is the best and easiest option.
- IP Whitelisting - we use static IPs that you can whitelist in your firewall / ACL. See the list of IPs here.
- Verifying signature - this is another option instead of the API Key. Each request MineOS makes to your endpoint contains a HTTP header called:
x-mine-signature
. This header contains the event signature, which can be verified to make sure the request originated from your MineOS account. See the example code for verifying the signature: - VPN Tunneling - The custom system integration supports MineOS VPN Tunneling so you can securely connect to endpoints running in your internal endpoint.
var key = "YOUR VERIFICATION KEY";
var data = "JSON PAYLOAD OF THE EVENT";
var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(key));
var rawSignature = hmac.ComputeHash(Encoding.UTF8.GetBytes(data));
var signature = BitConverter.ToString(rawSignature).Replace("-", "").ToLower();
var key = "YOUR VERIFICATION KEY";
var data = "JSON PAYLOAD OF THE EVENT";
var crypto = require('crypto');
var signature = crypto.createHmac('SHA256', key).update(data).digest('hex');
To test whether your implementation is correct, you can use an online HMAC calculator.
Updated 4 days ago