# Custom Application Integration Data Upload
## Getting started
Click the link below to download the CSV template for manual upload.
{% file src="/files/LAuBTvizllPpbbLYiBeB" %}
{% hint style="info" %}
If you have a disconnected or desktop app which doesn't provide an API, and for which you do not have a CSV in our entitlements format, you can upload PDFs or screenshots instead and extract entitlements with AI. See [Media Extraction for Disconnected Apps](/getting-started/setting-up-your-tenant/application-integrations/media-extraction-for-disconnected-apps.md).
{% endhint %}
{% hint style="info" %}
For use cases where only identity-entitlement pairs need to be uploaded for review, **Express Mode** provides a quicker and simpler setup. Refer to [#h\_01hq2qjpvw92s23qrb4y8dey7f](#h_01hq2qjpvw92s23qrb4y8dey7f "mention")
{% endhint %}
#### **Key Concepts**
Before filling out the CSV, it's essential to understand the following key concepts.
#### What are Entities?
In BalkanID, **Entities** are fundamental representations of identities, resources, connections, and insights within your system. They are designed to be flexible and can be extended to cover new data types (like logs) in the future.
We categorize the data extracted from your application integrations into the following core entity types:
* **Identity:**
* Represents a **user or service account** in your system.
* **Extracted directly from your application integrations.**
* Examples include individual users (e.g., "Alice Smith"), customer profiles, or different types of service accounts, each with unique access rights.
* **Resource:**
* Represents the **assets or services that users can access**.
* **Extracted directly from your application integrations.**
* Can be anything from documents, databases, or reports to specific features within your applications.
* Examples: a premium feature, a cloud storage bucket, an API service, or a specific repository.
* **Connection:**
* Represents the **access provider** that grants an Identity access to a Resource.
* **Derived from entities granted through your application integrations.**
* Often represents roles, groups, or memberships.
* Example: If a user gains access to admin resources because they are part of an "Admin" role, then the "**Admin**" role serves as the Connection.
#### Understanding Entity Relations (**Entity Has Access To)**
**Entity relations** describe how two entities are connected and interact with each other. They provide the context for how identities gain access to resources within your environment.
To illustrate, let's consider a GitHub integration example:
Scenario:
A user, "alicegh" (Identity) within a GitHub integration, belongs to the "Engineering" group (Connection). Because of her membership in "Engineering", Alice has access to two repositories: "customer-application" (Resource) and "admin-application" (Resource).
**Entities Involved:**
* `alicegh` (Identity)
* `Engineering` (Connection)
* `customer-application` (Resource)
* `admin-application` (Resource)
**Entity Relations:**
1. `alicegh` → `Engineering`
* *Meaning:* Alice is a member of the Engineering group. This is a direct relationship.
2. `Engineering` → `customer-application`
* *Meaning:* The Engineering group has access to the `customer-application` repository.
3. `Engineering` → `admin-application`
* *Meaning:* The Engineering group has access to the `admin-application` repository.
4. `alicegh` → `customer-application` (Connection Provider: `Engineering`)
* *Meaning:* Alice has access to `customer-application` *because* she is part of the `Engineering` group.
5. `alicegh` → `admin-application` (Connection Provider: `Engineering`)
* *Meaning:* Alice has access to `admin-application` *because* she is part of the `Engineering` group.
#### **CSV Format Overview**
Here’s the format that must be followed for **Manual Upload CSV**. Each column is described below, along with the required information.
| **Column Name** | **Description** | **Example** |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| **Project** | The project or app where the entity relations belong. Can be a **Jira project**, **Azure directory**, **GCP project**, etc. Optional. | \`BalkanID - Org |
| **Entity Name\*** | The name of the entity, such as a **user,group or application** . **Required**. | `Aabbott Reese` |
| **Entity Type\*** | The category of the entity: **identity**, **connection**, or **resource**. **Required**. | `identity` |
| **Entity Source Type\*** | The term used for the entity in the source system (e.g., **user**, **group**, **service account**). **Required**. | `user` |
| **Entity Source ID\*** | The unique ID of the entity from the source system. **Required**. | `63c16f61-d355-420b-87c6-615785ad8053` |
| **Entity Username** | The username associated with the entity. **Optional**. | `aabbott.reese@balkanit.onmicrosoft.com` |
| **Entity Email** | The email associated with the entity. **Optional**. | `aabbott.reese@balkanit.onmicrosoft.com` |
| **Entity - Has Access To Name\*** | The name of the entity being accessed. **Required**. | `Admin` |
| **Entity - Has Access To Source ID\*** | The source ID of the entity or resource that the entity has access to. **Required**. | `x1234567890abcdef` |
| **Entity - Has Access To Entity Type\*** | The type of the entity or resource the entity has access to (e.g., resource, connection, identity). **Required.** | `connection` |
| **Entity - Has Access To Source Type\*** | The type of source system or entity that the Entity Has Access To belongs to (e.g., application, group, role, policy). **Required.** | `group` |
| **Entity - Has Access To Permission Name** | The permission granted (e.g., **member**, **admin**). **Optional**. Defaults to **member, access** if not filled. | `member` |
| **Entity - Has Access To Permission Value** | Whether the entity has access (boolean: **true** or **false**). **Optional**. Defaults to **true**. | `true` |
| **Entity Status** | The current status of the entity in the source system (e.g., **inactive**, **active**, **suspended**). **Optional**. | `active` |
| **Entity First Name** | The first name of the entity (required for users). Optional | `Aabbott` |
| **Entity Last Name** | The last name of the entity. **Optional**. | `Reese` |
| **Entity LastLoginTime** | The last time the entity logged into the system. **Optional**. | `2023-12-14 04:42:12 +0000 UTC` |
| **Entity LastPasswordChangedTime** | The time when the entity last changed the password. **Optional**. | `2023-12-14 04:42:12 +0000 UTC` |
| **Entity MfaEnabled** | Whether multi-factor authentication is enabled (boolean: **true** or **false**). **Optional**. | `true` |
***
#### **Key Field Explanations**
1. **Project**
* The **Project** represents the specific project or organizational unit where the entity relations belong. This could be an internal system (like a **Jira project**) or a cloud environment (like a **GCP** or **Azure** project). This field helps categorize the data based on projects or systems.
**Example:**
* Refers to an Azure project or directory.
2. **Entity Has Access To**
* This indicates the **entity** or **resource** the entity has access to. It could be another **entity** (like a **group**, **role**, **channel**) or a **resource** (like an **application** or **app role**). This relationship can be direct or mediated via a **connection**.
**Example:**
* A **user** might have access to an **application** (`BalkanID`), or a **group** might have access to a **policy**.
***
## **Example Data Entries**
| Project | Entity Name | Entity Type | Entity Source Type | Entity Source ID | Entity Username | Entity Email | Entity - Has Access To Name | Entity - Has Access To Source ID | Entity - Has Access To Permission Name | Entity - Has Access To Permission Value | Entity Status | Entity First Name | Entity Last Name | Entity LastLoginTime | LastPasswordChangedTime | Entity MfaEnabled | Entity - Has Access To Entity Type | Entity - Has Access To Source Type |
| ---------- | --------------------------- | ----------- | ------------------ | ------------------------------------------------------- | --------------------------- | ---------------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------- | -------------------------------------- | --------------------------------------- | ------------- | ----------------- | ---------------- | ----------------------------- | ----------------------------- | ----------------- | ---------------------------------- | ---------------------------------- |
| CloudOps | john.developer | identity | user | AIDACKCEVSQ6C2EXAMPLE | john.developer | | S3-Development-Bucket | arn:aws:s3:::dev-bucket-12345 | s3:GetObject | True | active | John | Developer | 2024-01-15 09:30:00 +0000 UTC | 2024-01-10 14:22:00 +0000 UTC | true | resource | storage |
| CloudOps | DevOps-Team | connection | group | arn:aws:iam::123456789012:group/DevOps-Team | DevOps-Team | | Admin-Console-Access | arn:aws:iam::123456789012:role/AdminConsoleRole | AssumeRole | True | active | | | | | false | connection | role |
| CloudOps | Database-Admins | connection | group | arn:aws:iam::123456789012:group/Database-Admins | Database-Admins | | RDS-Full-Access-Policy | arn:aws:iam::123456789012:policy/RDS-Full-Access-Policy | PolicyAttachment | True | active | | | | | false | connection | policy |
| CloudOps | Lambda-Execution-Role | connection | role | arn:aws:iam::123456789012:role/Lambda-Execution-Role | Lambda-Execution-Role | | Lambda-Basic-Execution-Policy | arn:aws:iam::aws:policy/service-role/AWSLambdaBasicExecutionRole | PolicyAttachment | True | active | | | | | false | connection | policy |
| CloudOps | EC2-CloudWatch-Role | connection | service\_role | arn:aws:iam::123456789012:role/EC2-CloudWatch-Role | EC2-CloudWatch-Role | | CloudWatch-Logs-Group | arn:aws:logs:us-east-1:123456789012:log-group\:/aws/ec2/application | logs:CreateLogStream | True | active | | | 2024-01-15 12:45:00 +0000 UTC | | false | resource | logging |
| CloudOps | Network-Operations-Team | connection | group | arn:aws:iam::123456789012:group/Network-Operations-Team | Network-Operations-Team | | AWS-Management-Console | res\_aws\_console\_001 | console\_access | True | active | | | | | false | resource | application |
| AzureOps | mary.analyst | identity | user | 63c16f61-d355-420b-87c6-615785ad8053 | mary.analyst | | Power-BI-Dashboard | res\_powerbi\_dashboard\_001 | view\_reports | True | active | Mary | Analyst | 2024-01-14 08:15:00 +0000 UTC | 2024-01-10 09:30:00 +0000 UTC | true | resource | application |
| AzureOps | Security-Team | connection | group | 87654321-4321-4321-4321-210987654321 | Security-Team | | Security-Reader-Role | /subscriptions/sub-123/providers/Microsoft.Authorization/roleDefinitions/39bc4728-0917-49c1-b181-199c9e0c9e7e | RoleAssignment | True | active | | | | | false | connection | role |
| AzureOps | app-registration-service | connection | service\_principal | 12345678-1234-1234-1234-123456789012 | app-registration-service | | Key-Vault-Access | /subscriptions/sub-123/resourceGroups/rg-prod/providers/Microsoft.KeyVault/vaults/prod-vault | Key Vault Secrets User | True | active | | | 2024-01-15 11:20:00 +0000 UTC | 2024-01-05 16:30:00 +0000 UTC | false | resource | security |
| AzureOps | Compliance-Team | connection | group | grp\_compliance\_001 | Compliance-Team | | Audit-Management-System | res\_audit\_system\_001 | read\_audit\_logs | True | active | | | | | false | resource | application |
| AzureOps | Backup-Service-Role | connection | role | role\_backup\_001 | Backup-Service-Role | | Storage-Access-Policy | pol\_storage\_backup\_001 | PolicyAttachment | True | active | | | | | false | connection | policy |
| CoreSystem | sarah.admin | identity | user | usr\_sarah\_001 | sarah.admin | | Admin-Dashboard | res\_admin\_dashboard\_001 | full\_access | True | active | Sarah | Admin | 2024-01-15 07:45:00 +0000 UTC | 2024-01-08 10:15:00 +0000 UTC | true | resource | application |
| CoreSystem | System-Administrators | connection | group | grp\_sysadmin\_001 | System-Administrators | | Admin-Dashboard | res\_admin\_dashboard\_001 | full\_access | True | active | | | | | false | resource | application |
| CoreSystem | HR-Access-Group | connection | group | grp\_hr\_001 | HR-Access-Group | | Employee-Data-Access-Role | role\_employee\_data\_001 | RoleAssignment | True | active | | | | | false | connection | role |
| CoreSystem | metrics-collector-service | connection | service\_account | svc\_metrics\_001 | metrics-collector-service | | Monitoring-Data-Policy | pol\_monitoring\_001 | collect\_metrics | True | active | | | 2024-01-15 13:15:00 +0000 UTC | | false | connection | policy |
| CoreSystem | Integration-Service-Role | connection | role | role\_integration\_001 | Integration-Service-Role | | External-API-Access | res\_external\_api\_001 | api\_invoke | True | active | | | | | false | resource | api |
| CoreSystem | Network-Operations-Team | connection | group | grp\_netops\_001 | Network-Operations-Team | | Network-Configuration-Policy | pol\_network\_config\_001 | configure\_network | True | active | | | | | false | connection | policy |
| CoreSystem | Analytics-Team | connection | group | grp\_analytics\_001 | Analytics-Team | | Data-Warehouse-Access | res\_data\_warehouse\_001 | read\_write | True | active | | | | | false | resource | application |
| CoreSystem | Backup-Operator-Role | connection | role | role\_backup\_operator\_001 | Backup-Operator-Role | | Backup-Management-Console | res\_backup\_console\_001 | manage\_backups | True | active | | | | | false | resource | application |
| CoreSystem | email-service-account | connection | service\_account | svc\_email\_001 | email-service-account | | Email-Template-Policy | pol\_email\_template\_001 | send\_email | True | active | | | 2024-01-15 14:30:00 +0000 UTC | | false | connection | policy |
| CoreSystem | Document-Managers | connection | group | grp\_docmgr\_001 | Document-Managers | | Document-Management-System | res\_doc\_system\_001 | manage\_documents | True | active | | | | | false | resource | application |
| CoreSystem | Report-Generation-Role | connection | role | role\_report\_gen\_001 | Report-Generation-Role | | Report-Access-Policy | pol\_report\_access\_001 | generate\_reports | True | active | | | | | false | connection | policy |
| CoreSystem | Security-Audit-Team | connection | group | grp\_security\_audit\_001 | Security-Audit-Team | | Security-Monitoring-Console | res\_security\_console\_001 | view\_security\_logs | True | active | | | | | false | resource | application |
| CoreSystem | Workflow-Automation-Service | connection | service\_account | svc\_workflow\_001 | Workflow-Automation-Service | | Workflow-Execution-Policy | pol\_workflow\_exec\_001 | execute\_workflows | True | active | | | 2024-01-15 15:45:00 +0000 UTC | | false | connection | policy |
| CoreSystem | Identity-Management-Team | connection | group | grp\_identity\_001 | Identity-Management-Team | | User-Provisioning-System | res\_user\_provisioning\_001 | manage\_users | True | active | | | | | false | resource | application |
#### **Important Notes**
* **Required Fields:** Ensure the following fields are filled for each entity:
* **Entity Name**, **Entity Type**, **Entity Source Type**, **Entity Source ID**, **Entity Has Access To Name**, **Entity Has Access To Source ID, Entity Has Access To Entity Type, Entity Has Access To Source Type**.
* **Optional Fields:** Fields such as **Entity LastLoginTime**, **Entity Status**, **LastPasswordChangedTime**, **Entity First Name**, **Entity Last Name**, **Entity MfaEnabled**, and **Entity Has Access To Permission Name/Value** can be left empty if not applicable.
* **Consistency:** Double-check all **IDs** (especially **Source ID** and **Source IDs**), as they are crucial for linking entities and their access relationships accurately.
* **Entity Username** and **Entity Email** are optional fields. If these values are not provided, the mapping will **not** be done automatically. The user will need to handle the mapping of these fields separately using BalkanID Web App.
## Manually updating on BalkanID tenant
1. Login to your BalkanID tenant.
2. Go to the *Configure* > *Integrations > Add Integrtion*.
3. Choose the **Custom App** integration from the list.
4. Click on the **Custom App**.
5. After clicking on the **Custom App**, you will be directed to the next screen. Simply fill in the required details and select the `File Upload` option and drag and drop the File.
6. **Choose an upload mode** based on the structure of the data:
* Select **Express Mode** if the file contains only identity–entitlement pairs.
* Select **Power Mode** if the file contains additional fields or requires more flexible mapping.
The following steps can be followed to upload your data for either of the modes chosen above:
1. If you're only uploading entities (i.e., only uploading *users*, *identities*, etc. without any *entitlement* pairs), toggle on the `Entities Only Mode`.
2. The column mapping UI as shown below will appear. In case our intelligent auto-map did not map any columns satisfactorily, you map it manually based on your requirement.\
**Note:**
1. In Express Mode, you only need to provide *name* and *ID* column for the user (or identity), and the corresponding *entitlement*.
2. In Power Mode, you can map your fields as per the definitions given above: [#csv-format-overview](#csv-format-overview "mention")
3. Feel free to preview the mapped CSV before confirming.
7. Click on Confirm Mapping, and Next.
8. Click on the **Save** Button**.** Your integration is now configured and you will see the status of the integration displayed alongside other integrations on the *Integrations* page. Integrations are synced daily (or as configured for your tenant).
9. When data is available, the integration Status column will read **Connected** and the integration Message will read **Data available**.
{% hint style="info" %}
We will save your configured mapping for a particular Custom App — you won't have to remap your columns the next time.
{% endhint %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://docs.balkan.id/getting-started/setting-up-your-tenant/application-integrations/custom-application-integration-data-upload.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.