Response Schema
The table below outlines the response schema for all integration configurations.
| Property | Description |
|---|---|
id number |
The unique identifier of the integration. |
status string |
The status of the integration. Statuses include createError, creating, deleteError, deleting, editError, editing, enabled, migrateError, and migrating. See the statuses table below for descriptions. |
validationResults object |
The results of the validation tests. See the object description for details. |
config object |
The integration configuration. See the integration configuration payload for Amazon S3, Azure Synapse Analytics, Databricks Unity Catalog, Google BigQuery, Redshift, or Snowflake for details. |
Integration statuses
The status property in the response schema shows the status of the integration. The table below provides definitions for each status and the state of the integration configuration.
| Status | Description | State |
|---|---|---|
| createError | Error occurred during creation of the integration. | In use |
| creating | Integration is in the process of being created and set up. | In use |
| deleted | Integration is deleted. | Not in use |
| deleteError | Error occurred while deleting the integration. The integration has been rolled back to the previous state. | In use |
| deleting | Integration is in the process of being disabled or deleted. | In use |
| editError | Error occurred while editing the integration. The integration has been rolled back to the previous state. | In use |
| editing | The integration is in the process of being edited. | In use |
| enabled | The integration is enabled and active. | In use |
| migrateError | Error occurred while performing a migration of the integration. The integration has been rolled back to the previous state. | In use |
| migrating | Migration is being performed on the integration. An example of a migration is a stored procedure update. | In use |
Validation results object
The validationResults object provides details about the status of each test Immuta runs to validate the the integration configuration.
| Attribute | Description | Possible values |
|---|---|---|
status string |
Whether or not the connection validation passed. |
|
validationTests array[] |
This array includes the validation tests run on the integration connection. | - |
validationTests.name string |
The name of the validation test. | See the section corresponding to your integration type for a list of test names and messages: |
validationTests.status string |
The status of the validation test. |
|
validationTests.message string |
When a test fails, the message provides context and guidance for addressing the failure. | See the section corresponding to your integration type for a list of test names and messages: |
Amazon S3 validation tests
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
| Test name | Description | Message |
|---|---|---|
| There is no existing integration matching this configuration | Verifies that the integration configuration does not match an existing one. | - |
| The provided integration name is unique across Immuta S3 integrations | Verifies that the name of the integration does not match an existing S3 integration name. | "The Immuta service account does not end with expected value." |
| The provided access grants location role is a valid ARN format | Verifies that the access grants location role is in the correct format. | "The specified access grants location role is not a valid ARN format." |
| The provided AWS credentials allow fetching the caller's identity via the AWS STS API | Verifies that the integration can use the AWS STS API to get the caller's identity using the provided credentials. | "Found user ID [], ARN [] using STS." |
| An AWS Access Grants instance is configured in the provided AWS account and region | Verifies that an Access Grants instance has been created in the specified AWS account and region. | "AccessDenied: Unable to retrieve the access grants instance for account, region: AWS responded with code [403], name [AccessDenied] and message [Access Denied] for request ID []." |
| The provided S3 path exists and Immuta can list prefixes | Verifies that Immuta can access and list prefixes for the provided S3 path. | "Immuta does not have access to the requested path [s3://]. Without access, Immuta will be unable to assist with S3 path discovery during data source creation." |
| An AWS Access Grants location does not yet exist for the provided path | Verifies that an Access Grants location has not already been registered for the specified S3 path. | "AccessDenied: Unable to list S3 access grants locations for account [], location scope []: AWS responded with code [403], name [AccessDenied] and message [Access Denied] for request ID []." |
Azure Synapse Analytics validation tests
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
| Test name | Description | Message |
|---|---|---|
| Initial validation: connect | Verifies that Immuta can connect to Azure Synapse Analytics. | "Unable to connect to host." |
| Initial validation: delimiters test | Verifies that the delimiters are unique. | "Hash delimiter and array delimiter must not have the same value." |
| Validate automatic: impersonation role does not exist | Verifies that the user impersonation role specified in the request payload does not already exist. | "Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name." |
| Validate Immuta system user can manage database | Verifies that the specified user can manage the database. | "User does not have permission to manage database." |
Databricks Unity Catalog validation tests
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
| Test name | Description | Message |
|---|---|---|
| Basic connection test | Verifies that Immuta can connect to Databricks Unity Catalog. | "Could not connect to host, please confirm you are using valid connection parameters." |
| Manual catalog setup | Verifies that the catalog and tables used by Immuta are present and have the correct permissions. This test is run when autoBootstrap is false in the Databricks Unity Catalog integration configuration. |
"Encountered an error looking up catalog metadata for catalog." |
| Metastore validation | Verifies that the Unity Catalog metastore is assigned to the specified workspace. | "No metastore is assigned to workspace." |
Google BigQuery validation tests
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
| Test name | Description | Message |
|---|---|---|
| Basic validation: connection can be made to BigQuery | Verifies that Immuta can connect to Google BigQuery. | "Could not connect to the remote BigQuery connection." |
| Basic validation: Immuta service account postfix | Verifies that the service account ends with the expected value of @<projectId>.iam.gserviceaccount.com. |
"The Immuta service account does not end with expected value." |
| Basic validation: non-matching service account in key file | Verifies that the service account matches the one provided in the keyfile. | "The service account does not match the service account in the provided key file." |
| Basic validation: verify service account not being used for data source connection credentials | Verifies that credentials that have been used to create Google BigQuery data sources are not the same credentials used to configure the Google BigQuery integration. | "Native BigQuery doesn't support the reuse of service accounts for integrations that are currently being used for data sources." |
| Validate manual: [dataset - create] | Verifies that the custom role assigned to the service account has the permissions to create the dataset. | Message includes a permission warning. |
| Validate manual: [dataset - delete] | Verifies that the custom role assigned to the service account has the permissions to delete the Immuta-managed dataset. | Message includes a permission warning. |
| Initialize validation: [dataset - exists] | Verifies that this dataset does not already exist. | "An existing Immuta instance exists. Delete this dataset to continue." |
| Validate manual: [table - create] | Verifies that the custom role assigned to the service account has the permissions to create Immuta-managed tables. | Message includes a permission warning. |
| Validate manual: [table - delete] | Verifies that the custom role assigned to the service account has the permissions to delete Immuta-managed tables. | Message includes a permission warning. |
| Validate manual: [table - get] | Verifies that the custom role assigned to the service account has the permissions to get Immuta-managed tables. | Message includes a permission warning. |
| Validate manual: [table - insert] | Verifies that the custom role assigned to the service account has the permissions to insert rows in Immuta-managed tables. | Message includes a permission warning. |
| Validate manual: [table - update] | Verifies that the custom role assigned to the service account has the permissions to update Immuta-managed tables. | Message includes a permission warning. |
Redshift validation tests
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
| Test name | Description | Message |
|---|---|---|
| Initial validation: basic connection test | Verifies that Immuta can connect to Redshift. | "Unable to connect to host." |
| Validate automatic: database does not exist | Verifies that the database specified in the request payload does not already exist. | "The database already exists. If this database can be safely dropped, please do so and try again. Alternatively, specify a different database name." |
| Validate automatic: impersonation role does not exist | Verifies that the user impersonation role specified in the request payload does not already exist. | "Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name." |
Snowflake validation tests
The table below provides the errors and messages for validation tests that fail when configuring or updating the integration.
| Test name | Description | Message |
|---|---|---|
| Initial validation: basic connection test | Verifies that Immuta can connect to the Snowflake database. | "Unable to connect to host." |
| Initial validation: default warehouse access test | Verifies that the default warehouse exists and that the Immuta system account user has permissions to act on the default warehouse specified. | "Unable to access default warehouse. If this was a manual installation, ensure that the user has been granted usage on the specified warehouse." |
| Initial validation: table grants role prefix is unique | Verifies that the prefix for Snowflake table grants does not already exist. If this prefix already exists, navigate to the Integration Settings section on the Immuta app settings page to disable Snowflake table grants, re-enable it, and then update the role prefix. | "The Snowflake table grants role prefix 'IMMUTA' is used by another Immuta instance connected to the same Snowflake host. Please update the table grants role prefix for this Immuta instance and try again." |
| Initial validation: validate access to privileged role | Verifies that the privileged role exists and that it has been assigned to the Immuta system account user. | "User does not have access to the privileged role." |
| Validate automatic bootstrap user grants | Verifies the credentials of the user executing the Immuta bootstrap script in Snowflake. | - |
| Validate automatic: database does not exist | Verifies that the database specified in the request payload does not already exist. | "The database already exists. If this database can be safely dropped, please do so and try again. Alternatively, specify a different database name." |
| Validate automatic: impersonation role does not exist | Verifies that the user impersonation role specified in the request payload does not already exist. | "Impersonation role already exists. If this role can be safely dropped please do so and try again. Alternatively, specify a different role name." |