> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argalabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Salesforce

> Salesforce Scenario seeding parameters, nested fields, and examples

Use `salesforce` in `twins` and put this configuration under `seed_config.salesforce`.

Salesforce CRM/support workspace with Accounts, Contacts, Cases, EmailTemplates, EmailMessages, custom objects, custom fields, apps, tabs, layouts, and imported org metadata.

## Example seed

This is the complete Scenario request body for [creating a Scenario](https://docs.argalabs.com/api-reference/post-create-a-scenario.md). You can also import it with `arga test-runner scenarios import --file scenario.json`.

```json theme={null}
{
  "name": "Salesforce eval fixture",
  "twins": [
    "salesforce"
  ],
  "seed_config": {
    "salesforce": {
      "org_id": "00DACME00000001AAA",
      "user_id": "005ACME00000001AAA",
      "username": "agent@acme.example",
      "roles": [
        {
          "id": "support_manager",
          "name": "Support Manager"
        },
        {
          "id": "support_agent",
          "name": "Support Agent",
          "parent_id": "support_manager"
        }
      ],
      "profiles": [
        {
          "name": "Support Agent",
          "api_enabled": true,
          "view_all_data": false,
          "modify_all_data": false,
          "view_setup": false,
          "manage_users": false,
          "object_permissions": {
            "Case": {
              "read": true,
              "create": true,
              "edit": true,
              "delete": false
            }
          },
          "field_permissions": {
            "Case.Subject": {
              "read": true,
              "edit": true
            },
            "Case.Status": {
              "read": true,
              "edit": true
            },
            "Case.Priority": {
              "read": true
            }
          }
        },
        {
          "name": "System Administrator",
          "api_enabled": true,
          "modify_all_data": true,
          "view_setup": true,
          "manage_users": true,
          "object_permissions": {
            "*": {
              "read": true,
              "create": true,
              "edit": true,
              "delete": true
            }
          },
          "field_permissions": {
            "*.*": {
              "read": true,
              "edit": true
            }
          }
        }
      ],
      "permission_sets": [
        {
          "name": "Case Priority Editor",
          "field_permissions": {
            "Case.Priority": {
              "read": true,
              "edit": true
            }
          }
        }
      ],
      "sharing_defaults": {
        "Case": {
          "access": "Private",
          "grant_access_using_hierarchies": true
        }
      },
      "record_shares": [],
      "public_groups": [],
      "account_team_members": [],
      "opportunity_team_members": [],
      "permission_set_groups": [],
      "territories": [],
      "user_territory2_associations": [],
      "object_territory2_associations": [],
      "sharing_rules": {},
      "access_token_ttl_seconds": 900,
      "refresh_token_ttl_seconds": 7776000,
      "browser_session_ttl_seconds": 7200,
      "oauth_clients": [
        {
          "client_id": "customer-exporter",
          "client_secret": "twin-secret",
          "name": "Customer Data Exporter",
          "redirect_uris": [
            "https://consumer.example.test/oauth/callback"
          ],
          "allowed_scopes": [
            "api",
            "refresh_token",
            "openid"
          ],
          "grant_types": [
            "authorization_code",
            "refresh_token"
          ],
          "require_pkce": true
        }
      ],
      "oauth_accounts": [
        {
          "org_id": "00DACME00000001AAA",
          "user_id": "005ACME00000001AAA",
          "username": "agent@acme.example",
          "profile": "Support Agent",
          "role_id": "support_agent",
          "permission_sets": [],
          "password": "acme-password",
          "security_token": "ACME-TOKEN",
          "email": "agent@acme.example",
          "display_name": "Acme Agent",
          "instance_url": "https://acme.my.salesforce.com",
          "records": [
            {
              "object": "Account",
              "alias": "acme_customer",
              "values": {
                "Name": "Acme Customer"
              }
            }
          ]
        }
      ],
      "apps": [
        {
          "name": "Support_App",
          "label": "Support App",
          "tabs": [
            "Subscription__c"
          ]
        }
      ],
      "objects": [
        {
          "name": "Subscription__c",
          "label": "Subscription",
          "pluralLabel": "Subscriptions",
          "fields": [
            {
              "name": "Name",
              "type": "string",
              "nillable": false
            },
            {
              "name": "Status__c",
              "type": "picklist",
              "picklistValues": [
                "Trial",
                "Active",
                "Canceled"
              ]
            },
            {
              "name": "Account__c",
              "type": "reference",
              "referenceTo": [
                "Account"
              ],
              "relationshipName": "Account__r"
            }
          ],
          "layouts": [
            {
              "name": "Default",
              "sections": [
                {
                  "heading": "Details",
                  "fields": [
                    "Name",
                    "Status__c",
                    "Account__c"
                  ]
                }
              ]
            }
          ],
          "compactLayoutFields": [
            "Name",
            "Status__c"
          ],
          "searchColumns": [
            "Id",
            "Name",
            "Status__c"
          ]
        }
      ],
      "accounts": [
        {
          "alias": "customer_account",
          "Name": "Customer Account",
          "Website": "https://customer.example"
        }
      ],
      "contacts": [
        {
          "FirstName": "Customer",
          "LastName": "Contact",
          "Email": "customer@example.com",
          "alias": "customer_contact",
          "AccountId": "customer_account (the seed runner resolves this alias)"
        }
      ],
      "cases": [
        {
          "Subject": "Support case subject",
          "Description": "Support case description",
          "Origin": "Email",
          "Status": "New",
          "Priority": "Medium",
          "ContactId": "customer_contact (the seed runner resolves this alias)",
          "AccountId": "customer_account (the seed runner resolves this alias)"
        }
      ],
      "email_templates": [
        {
          "Name": "Support Reply",
          "DeveloperName": "Support_Reply",
          "Subject": "Re: {!Case.Subject}",
          "Body": "Hi {!Contact.FirstName}, we are working on case {!Case.CaseNumber}."
        }
      ],
      "records": [
        {
          "object": "Account",
          "alias": "acct_acme",
          "values": {
            "Name": "Acme"
          }
        },
        {
          "object": "Subscription__c",
          "alias": "sub_acme",
          "values": {
            "Name": "Enterprise",
            "Status__c": "Active",
            "Account__c": {
              "$ref": "acct_acme.Id"
            }
          }
        }
      ]
    }
  }
}
```

## Parameters

The following fields belong directly inside `seed_config.salesforce`. Required nested fields are marked in their tables. Provider-native objects can contain service-specific fields beyond the representative record shapes below.

| Parameter | Type | Description |
| - | - | - |
| `org_id` | `string` | Org id. |
| `user_id` | `string` | User id. |
| `username` | `string` | Username. |
| `roles` | `SalesforceRole[]` | Role definitions and their supported relationships. |
| `profiles` | `SalesforcePermissionSet[]` | Profiles fixtures in provider-native format. |
| `permission_sets` | `SalesforcePermissionSet[]` | Object and field permission grants. |
| `sharing_defaults` | `map<string, SalesforceSharingDefault>` | Default record visibility keyed by Salesforce object. |
| `record_shares` | `SalesforceRecordShare[]` | Record shares fixtures in provider-native format. |
| `public_groups` | `PublicGroupSeed[]` | Public groups fixtures in provider-native format. |
| `account_team_members` | `AccountTeamMemberSeed[]` | Account team members fixtures in provider-native format. |
| `opportunity_team_members` | `OpportunityTeamMemberSeed[]` | Opportunity team members fixtures in provider-native format. |
| `permission_set_groups` | `PermissionSetGroupSeed[]` | Permission set groups fixtures in provider-native format. |
| `territories` | `TerritorySeed[]` | Territories; model\_id defaults to the seeded territory2\_model. |
| `user_territory2_associations` | `UserTerritoryAssociationSeed[]` | User territory2 associations fixtures in provider-native format. |
| `object_territory2_associations` | `ObjectTerritoryAssociationSeed[]` | Object territory2 associations fixtures in provider-native format. |
| `sharing_rules` | `map<string, SalesforceSharingRules>` | Sharing-rule metadata keyed by object API name (for example Account, Contact, Lead, Opportunity), not a list. Each value contains optional sharingOwnerRules and sharingCriteriaRules arrays. Read with GET /services/data/v{version}/metadata/sharingRules/{object} and a Bearer token with view\_setup permission. Resolvable owner and criteria rules grant access and recalculate after record and membership changes. Incomplete or unresolved definitions remain inert. |
| `access_token_ttl_seconds` | `integer` | Access token ttl seconds, in seconds. Minimum: 1. |
| `refresh_token_ttl_seconds` | `integer` | Refresh token ttl seconds, in seconds. Minimum: 1. |
| `browser_session_ttl_seconds` | `integer` | Browser session ttl seconds, in seconds. Minimum: 1. |
| `oauth_clients` | `SalesforceOAuthClient[]` | Oauth clients fixtures in provider-native format. |
| `oauth_accounts` | `SalesforceOAuthAccount[]` | Oauth accounts fixtures in provider-native format. |
| `apps` | `SalesforceAppDefinition[]` | Apps fixtures in provider-native format. |
| `objects` | `SalesforceObjectDefinition[]` | Object and field metadata. Standard objects retain their built-in fields. Custom fields declared on Activity are shared by Task and Event; Activity itself is not queryable. |
| `accounts` | `object[]` | Accounts fixtures in provider-native format. |
| `contacts` | `object[]` | Contacts fixtures in provider-native format. |
| `cases` | `object[]` | Cases fixtures in provider-native format. |
| `email_templates` | `object[]` | Email templates fixtures in provider-native format. |
| `records` | `object[]` | Provider-native record fixtures, with optional aliases for references. |
| `access_token` | `string` | Synthetic access token used by the twin. |
| `seed_records` | `SeedRecord[]` | Salesforce object, alias, and values record fixtures. |
| `host` | `string` | Host. |
| `default_case_owner_id` | `string` | Default case owner id. |
| `client_id` | `string` | Test OAuth client identifier. |
| `api_version` | `string` | Api version. |
| `password` | `string` | Password. |
| `oauth_seed` | `string` | Oauth seed. |
| `rotate_refresh_tokens` | `boolean` | Enable or set rotate refresh tokens behavior. |
| `client_secret` | `string` | Test OAuth client secret. |
| `oauth_audiences` | `string[]` | Oauth audiences fixtures in provider-native format. |
| `email` | `string` | Main account email address. |
| `default_sender_email` | `string` | Default sender email. |
| `queue_grant_access_using_hierarchies` | `boolean` | Org setting used for omitted DoesIncludeBosses on Queue groups. Regular groups default to true. |
| `display_name` | `string` | Display name. |
| `territory2_types` | `TerritoryTypeSeed[]` | Territory types; territories without type\_id share a default type within their org. |
| `locale` | `string` | Locale. |
| `territory2_model` | `TerritoryModelSeed or null` | Territory model; nested territories and types are accepted. Default state is Active. |
| `jwt_assertion_max_lifetime_seconds` | `integer` | Jwt assertion max lifetime seconds, in seconds. Minimum: 1. |
| `security_token` | `string` | Security token. |
| `timezone` | `string` | Timezone. |
| `authorization_code_ttl_seconds` | `integer` | Authorization code ttl seconds, in seconds. Minimum: 1. |
| `opportunities` | `object[]` | Opportunities fixtures in provider-native format. |
| `leads` | `object[]` | Leads fixtures in provider-native format. |
| `email_messages` | `object[]` | Email messages fixtures in provider-native format. |

## Seeding behavior

Roles control record visibility through the hierarchy; profiles and permission sets grant object and field access. Preserve role names exactly and assign both the role and required permission grants to each user. Users in one org share record state while retaining their own permissions. Define referenced custom fields in `objects`; resolve record relationships with declared aliases.

## Resource fields

These tables describe the record shapes used by the example. Keep native field names and casing. Map keys such as property names, IDs, and metadata keys are supplied by your fixture.

### `roles[]`

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `name` | `string` | Human-readable name. |
| `parent_id` | `string` | Parent id. |

### `profiles[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `api_enabled` | `boolean` | Enable or set api enabled behavior. |
| `view_all_data` | `boolean` | Enable or set view all data behavior. |
| `modify_all_data` | `boolean` | Enable or set modify all data behavior. |
| `view_setup` | `boolean` | Enable or set view setup behavior. |
| `manage_users` | `boolean` | Enable or set manage users behavior. |
| `object_permissions` | `object` | Object permissions. |
| `field_permissions` | `object` | Field permissions. |

### `permission_sets[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `field_permissions` | `object` | Field permissions. |

### `oauth_clients[]`

| Parameter | Type | Description |
| - | - | - |
| `client_id` | `string` | Test OAuth client identifier. |
| `client_secret` | `string` | Test OAuth client secret. |
| `name` | `string` | Human-readable name. |
| `redirect_uris` | `string[]` | Redirect uris fixtures in provider-native format. |
| `allowed_scopes` | `string[]` | Allowed scopes fixtures in provider-native format. |
| `grant_types` | `string[]` | Grant types fixtures in provider-native format. |
| `require_pkce` | `boolean` | Enable or set require pkce behavior. |

### `oauth_accounts[]`

| Parameter | Type | Description |
| - | - | - |
| `org_id` | `string` | Org id. |
| `user_id` | `string` | User id. |
| `username` | `string` | Username. |
| `profile` | `string` | Owner identity and display profile. |
| `role_id` | `string` | Role id. |
| `permission_sets` | `array` | Object and field permission grants. |
| `password` | `string` | Password. |
| `security_token` | `string` | Security token. |
| `email` | `string` | Main account email address. |
| `display_name` | `string` | Display name. |
| `instance_url` | `string` | Instance url. |
| `records` | `object[]` | Provider-native record fixtures, with optional aliases for references. |

### `oauth_accounts[].records[]`

| Parameter | Type | Description |
| - | - | - |
| `object` | `string` | Object. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `values` | `object` | Values. |

### `apps[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `label` | `string` | Label. |
| `tabs` | `string[]` | Tabs fixtures in provider-native format. |

### `objects[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `label` | `string` | Label. |
| `pluralLabel` | `string` | PluralLabel. |
| `fields` | `object[]` | Fields fixtures in provider-native format. |
| `layouts` | `object[]` | Layouts fixtures in provider-native format. |
| `compactLayoutFields` | `string[]` | CompactLayoutFields fixtures in provider-native format. |
| `searchColumns` | `string[]` | SearchColumns fixtures in provider-native format. |

### `objects[].fields[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `type` | `string` | Type. |
| `nillable` | `boolean` | Enable or set nillable behavior. |
| `picklistValues` | `string[]` | PicklistValues fixtures in provider-native format. |
| `referenceTo` | `string[]` | ReferenceTo fixtures in provider-native format. |
| `relationshipName` | `string` | RelationshipName. |

### `objects[].layouts[]`

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `sections` | `object[]` | Sections fixtures in provider-native format. |

### `objects[].layouts[].sections[]`

| Parameter | Type | Description |
| - | - | - |
| `heading` | `string` | Heading. |
| `fields` | `string[]` | Fields fixtures in provider-native format. |

### `accounts[]`

| Parameter | Type | Description |
| - | - | - |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `Name` | `string` | Name. |
| `Website` | `string` | Website. |

### `contacts[]`

| Parameter | Type | Description |
| - | - | - |
| `FirstName` | `string` | FirstName. |
| `LastName` | `string` | LastName. |
| `Email` | `string` | Email. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `AccountId` | `string` | AccountId. |

### `cases[]`

| Parameter | Type | Description |
| - | - | - |
| `Subject` | `string` | Subject. |
| `Description` | `string` | Description. |
| `Origin` | `string` | Origin. |
| `Status` | `string` | Status. |
| `Priority` | `string` | Priority. |
| `ContactId` | `string` | ContactId. |
| `AccountId` | `string` | AccountId. |

### `email_templates[]`

| Parameter | Type | Description |
| - | - | - |
| `Name` | `string` | Name. |
| `DeveloperName` | `string` | DeveloperName. |
| `Subject` | `string` | Subject. |
| `Body` | `string` | Body. |

### `records[]`

| Parameter | Type | Description |
| - | - | - |
| `object` | `string` | Object. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `values` | `object` | Values. |

## Typed configuration objects

Named object types in the parameter table use these fields.

### AccountTeamMemberSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `account_alias` | `string` | Account alias. |
| `account_id` | `string or map<string, string>` | Account id keyed by identifier or resource name. |
| `user_id` | `string or map<string, string>` | User id keyed by identifier or resource name. |
| `team_member_role` | `string` | Team member role. |
| `access_level` | `string` | Access level. |
| `account_access_level` | `string` | Account access level. |
| `opportunity_access_level` | `string` | Opportunity access level. |
| `contact_access_level` | `string` | Contact access level. |
| `case_access_level` | `string` | Case access level. |

### ObjectTerritoryAssociationSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `record_alias` | `string` | Record alias. |
| `record_id` | `string or map<string, string>` | Record id keyed by identifier or resource name. |
| `territory_id` | `string or map<string, string>` | Territory id keyed by identifier or resource name. |
| `association_cause` | `string` | Association cause. |

### OpportunityTeamMemberSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `opportunity_alias` | `string` | Opportunity alias. |
| `opportunity_id` | `string or map<string, string>` | Opportunity id keyed by identifier or resource name. |
| `user_id` | `string or map<string, string>` | User id keyed by identifier or resource name. |
| `team_member_role` | `string` | Team member role. |
| `access_level` | `string` | Access level. |
| `opportunity_access_level` | `string` | Opportunity access level. |

### PermissionSetGroupSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `name` | `string` | Human-readable name. |
| `developer_name` | `string` | Developer name. |
| `permission_sets` | `string[]` | Object and field permission grants. |

### PublicGroupSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `name` | `string` | Human-readable name. |
| `developer_name` | `string` | Developer name. |
| `type` | `string` | Type. |
| `does_include_bosses` | `boolean` | Enable or set does include bosses behavior. |
| `does_send_email_to_members` | `boolean` | Enable or set does send email to members behavior. |
| `members` | `string or map<string, string>[]` | Members fixtures in provider-native format. |

### SalesforceAppDefinition

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | **Required.** Human-readable name. |
| `label` | `string or null` | Label. |
| `description` | `string or null` | Description. |
| `tabs` | `string[]` | Tabs fixtures in provider-native format. |

### SalesforceOAuthAccount

| Parameter | Type | Description |
| - | - | - |
| `org_id` | `string` | **Required.** Org id. Minimum length: 1. |
| `user_id` | `string` | **Required.** User id. Minimum length: 1. |
| `username` | `string` | **Required.** Username. Minimum length: 1. |
| `password` | `string` | Password. |
| `security_token` | `string` | Security token. |
| `email` | `string or null` | Main account email address. |
| `display_name` | `string or null` | Display name. |
| `first_name` | `string or null` | First name. |
| `last_name` | `string or null` | Last name. |
| `alias` | `string or null` | Fixture-local name used by supported relationship references. |
| `instance_url` | `string or null` | Instance url. |
| `locale` | `string` | Locale. |
| `timezone` | `string` | Timezone. |
| `active` | `boolean` | Enable or set active behavior. |
| `profile` | `string or null` | Owner identity and display profile. |
| `permission_sets` | `string[]` | Object and field permission grants. |
| `role_id` | `string or null` | Role id. |
| `permission_set_groups` | `string[]` | Permission set groups fixtures in provider-native format. |
| `records` | `SeedRecord[]` | Provider-native record fixtures, with optional aliases for references. |

### SalesforceOAuthClient

| Parameter | Type | Description |
| - | - | - |
| `client_id` | `string` | **Required.** Test OAuth client identifier. Minimum length: 1. |
| `client_secret` | `string or null` | Test OAuth client secret. |
| `name` | `string` | Human-readable name. |
| `redirect_uris` | `string[]` | Redirect uris fixtures in provider-native format. |
| `allowed_scopes` | `string[]` | Allowed scopes fixtures in provider-native format. |
| `grant_types` | `string[]` | Grant types fixtures in provider-native format. |
| `token_endpoint_auth_method` | `"client_secret_post" / "client_secret_basic" / "none" or null` | Omit or use null to accept a client secret through either HTTP Basic or request parameters. An explicit client\_secret\_post or client\_secret\_basic restricts the transport; none configures a public client. |
| `require_pkce` | `boolean` | Enable or set require pkce behavior. |
| `run_as_username` | `string or null` | Run as username. |
| `jwt_public_key_pem` | `string or null` | Jwt public key pem. |
| `active` | `boolean` | Enable or set active behavior. |

### SalesforceObjectDefinition

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | **Required.** Human-readable name. |
| `label` | `string or null` | Label. |
| `pluralLabel` | `string or null` | PluralLabel. |
| `keyPrefix` | `string or null` | KeyPrefix. |
| `custom` | `boolean or null` | Custom. |
| `createable` | `boolean` | Enable or set createable behavior. |
| `updateable` | `boolean` | Enable or set updateable behavior. |
| `deletable` | `boolean` | Enable or set deletable behavior. |
| `queryable` | `boolean` | Enable or set queryable behavior. |
| `retrieveable` | `boolean` | Enable or set retrieveable behavior. |
| `searchable` | `boolean` | Enable or set searchable behavior. |
| `layoutable` | `boolean` | Enable or set layoutable behavior. |
| `fields` | `SalesforceFieldDefinition[]` | Fields fixtures in provider-native format. |
| `recordTypes` | `SalesforceRecordTypeDefinition[]` | RecordTypes fixtures in provider-native format. |
| `layouts` | `SalesforceLayoutDefinition[]` | Layouts fixtures in provider-native format. |
| `compactLayoutFields` | `string[]` | CompactLayoutFields fixtures in provider-native format. |
| `searchColumns` | `string[]` | SearchColumns fixtures in provider-native format. |
| `childRelationships` | `SalesforceChildRelationshipDefinition[]` | ChildRelationships fixtures in provider-native format. |

### SalesforceChildRelationshipDefinition

| Parameter | Type | Description |
| - | - | - |
| `childSObject` | `string` | **Required.** ChildSObject. |
| `field` | `string` | **Required.** Field. |
| `relationshipName` | `string` | **Required.** RelationshipName. |

### SalesforceFieldDefinition

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | **Required.** Human-readable name. |
| `type` | `string` | Type. |
| `label` | `string or null` | Label. |
| `nillable` | `boolean` | Enable or set nillable behavior. |
| `createable` | `boolean` | Enable or set createable behavior. |
| `updateable` | `boolean` | Enable or set updateable behavior. |
| `custom` | `boolean or null` | Custom. |
| `picklistValues` | `any[]` | PicklistValues fixtures in provider-native format. |
| `referenceTo` | `string[]` | ReferenceTo fixtures in provider-native format. |
| `relationshipName` | `string or null` | RelationshipName. |
| `childRelationshipName` | `string or null` | ChildRelationshipName. |
| `externalId` | `boolean` | Enable or set externalId behavior. |
| `idLookup` | `boolean` | Enable or set idLookup behavior. |
| `unique` | `boolean` | Enable or set unique behavior. |
| `calculated` | `boolean` | Enable or set calculated behavior. |
| `defaultedOnCreate` | `boolean` | Enable or set defaultedOnCreate behavior. |
| `defaultValue` | `any` | DefaultValue. |
| `length` | `integer or null` | Length. |
| `precision` | `integer or null` | Precision. |
| `scale` | `integer or null` | Scale. |

### SalesforceLayoutDefinition

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `label` | `string or null` | Label. |
| `recordTypeId` | `string or null` | RecordTypeId. |
| `sections` | `SalesforceLayoutSection[]` | Sections fixtures in provider-native format. |

### SalesforceLayoutSection

| Parameter | Type | Description |
| - | - | - |
| `heading` | `string` | Heading. |
| `fields` | `string[]` | Fields fixtures in provider-native format. |

### SalesforcePermissionSet

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | **Required.** Human-readable name. |
| `api_enabled` | `boolean` | Enable or set api enabled behavior. |
| `view_all_data` | `boolean` | Enable or set view all data behavior. |
| `modify_all_data` | `boolean` | Enable or set modify all data behavior. |
| `view_setup` | `boolean` | Enable or set view setup behavior. |
| `manage_users` | `boolean` | Enable or set manage users behavior. |
| `allow_view_edit_converted_leads` | `boolean` | Enable or set allow view edit converted leads behavior. |
| `object_permissions` | `map<string, SalesforceObjectPermission>` | Object permissions keyed by identifier or resource name. |
| `field_permissions` | `map<string, SalesforceFieldPermission>` | Field permissions keyed by identifier or resource name. |

### SalesforceFieldPermission

| Parameter | Type | Description |
| - | - | - |
| `read` | `boolean` | Enable or set read behavior. |
| `edit` | `boolean` | Enable or set edit behavior. |

### SalesforceObjectPermission

| Parameter | Type | Description |
| - | - | - |
| `read` | `boolean` | Enable or set read behavior. |
| `create` | `boolean` | Enable or set create behavior. |
| `edit` | `boolean` | Enable or set edit behavior. |
| `delete` | `boolean` | Enable or set delete behavior. |
| `view_all` | `boolean` | Enable or set view all behavior. |
| `modify_all` | `boolean` | Enable or set modify all behavior. |

### SalesforceRecordShare

| Parameter | Type | Description |
| - | - | - |
| `object` | `string` | **Required.** Object. |
| `record_id` | `string` | **Required.** Record id. |
| `org_id` | `string or null` | Org id. |
| `user_id` | `string or null` | User id. |
| `role_id` | `string or null` | Role id. |
| `group_id` | `string or null` | Group id. |
| `include_subordinates` | `boolean` | Enable or set include subordinates behavior. |
| `access` | `"Read" / "Edit"` | Stripe API-key and Dashboard-user permissions. |
| `row_cause` | `"Manual" / "Rule"` | Row cause. |
| `case_access_level` | `"None" / "Read" / "Edit" or null` | Case access level. |
| `opportunity_access_level` | `"None" / "Read" / "Edit" or null` | Opportunity access level. |
| `contact_access_level` | `"None" / "Read" / "Edit" or null` | Contact access level. |

### SalesforceRecordTypeDefinition

| Parameter | Type | Description |
| - | - | - |
| `name` | `string` | Human-readable name. |
| `developerName` | `string` | DeveloperName. |
| `recordTypeId` | `string` | RecordTypeId. |
| `active` | `boolean` | Enable or set active behavior. |
| `available` | `boolean` | Enable or set available behavior. |
| `defaultRecordTypeMapping` | `boolean` | Enable or set defaultRecordTypeMapping behavior. |
| `master` | `boolean` | Enable or set master behavior. |
| `urls` | `map<string, string>` | Urls keyed by identifier or resource name. |

### SalesforceRole

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | **Required.** Explicit resource identifier, when supported. |
| `name` | `string` | **Required.** Human-readable name. |
| `parent_id` | `string or null` | Parent id. |
| `may_forecast_manager_share` | `boolean` | Enable or set may forecast manager share behavior. |
| `contact_access_for_account_owner` | `"None" / "Read" / "Edit"` | Contact access for account owner. |
| `case_access_for_account_owner` | `"None" / "Read" / "Edit"` | Case access for account owner. |
| `opportunity_access_for_account_owner` | `"None" / "Read" / "Edit"` | Opportunity access for account owner. |

### SalesforceSharingDefault

| Parameter | Type | Description |
| - | - | - |
| `access` | `"Private" / "Read" / "ReadWrite" / "ControlledByParent"` | Stripe API-key and Dashboard-user permissions. |
| `grant_access_using_hierarchies` | `boolean` | Enable or set grant access using hierarchies behavior. |
| `parent_field` | `string or null` | Parent field. |

### SalesforceSharingRules

| Parameter | Type | Description |
| - | - | - |
| `sharingOwnerRules` | `object[]` | Owner-rule metadata objects returned unchanged. Typical fields are fullName, label, accessLevel, sharedFrom, and sharedTo. Omitted means no owner rules. |
| `sharingCriteriaRules` | `object[]` | Criteria-rule metadata objects returned unchanged. Typical fields are fullName, label, accessLevel, sharedTo, criteriaItems, and booleanFilter. Omitted means no criteria rules. |

### SeedRecord

| Parameter | Type | Description |
| - | - | - |
| `object` | `string` | **Required.** Object. |
| `alias` | `string or null` | Fixture-local name used by supported relationship references. |
| `org_id` | `string or null` | Org id. |
| `account_username` | `string or null` | Account username. |
| `values` | `object` | Values. |

### TerritoryModelSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `name` | `string` | Human-readable name. |
| `developer_name` | `string` | Developer name. |
| `state` | `string` | State. |
| `is_clone_source` | `boolean` | Enable or set is clone source behavior. |
| `is_opp_unassignment_done` | `boolean` | Enable or set is opp unassignment done behavior. |
| `is_sharing_group_delete_done` | `boolean` | Enable or set is sharing group delete done behavior. |
| `types` | `TerritoryTypeSeed[]` | Types fixtures in provider-native format. |
| `territories` | `TerritorySeed[]` | Territories fixtures in provider-native format. |

### TerritorySeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `name` | `string` | Human-readable name. |
| `developer_name` | `string` | Developer name. |
| `model_id` | `string or map<string, string>` | Model id keyed by identifier or resource name. |
| `type_id` | `string or map<string, string>` | Type id keyed by identifier or resource name. |
| `parent_id` | `string or map<string, string>` | Parent id keyed by identifier or resource name. |
| `account_access_level` | `string` | Account access level. |
| `opportunity_access_level` | `string` | Opportunity access level. |
| `contact_access_level` | `string` | Contact access level. |
| `case_access_level` | `string` | Case access level. |

### TerritoryTypeSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `name` | `string` | Human-readable name. |
| `master_label` | `string` | Master label. |
| `developer_name` | `string` | Developer name. |
| `priority` | `integer` | Priority. |
| `description` | `string` | Description. |
| `language` | `string` | Language. |

### UserTerritoryAssociationSeed

| Parameter | Type | Description |
| - | - | - |
| `id` | `string` | Explicit resource identifier, when supported. |
| `alias` | `string` | Fixture-local name used by supported relationship references. |
| `org_id` | `string` | Org id. |
| `user_id` | `string or map<string, string>` | User id keyed by identifier or resource name. |
| `territory_id` | `string or map<string, string>` | Territory id keyed by identifier or resource name. |
| `is_active` | `boolean` | Enable or set is active behavior. |
| `role_in_territory` | `string` | Role in territory. |

## API coverage and limitations

**Twin name:** `salesforce`

**Supports**

* Salesforce REST discovery, sObject CRUD, describe metadata, relationship reads, and updated/deleted feeds under `/services/data/v{version}`.
* Accounts, Contacts, Cases, Leads, Opportunities, Tasks, Events, templates, messages, custom objects, and the standard fields needed for CRM ingestion.
* Governance objects: Organization, User, Profile, UserRole, PermissionSet, PermissionSetAssignment, ObjectPermissions, FieldPermissions, Group, GroupMember, AccountShare, OpportunityShare, LeadShare, ContactShare, AccountTeamMember, OpportunityTeamMember, Territory2Model, Territory2, UserTerritory2Association, ObjectTerritory2Association, PermissionSetGroup, PermissionSetGroupComponent, UserRecordAccess, EntityDefinition, and RecordType.
* Relationship objects: OpportunityContactRole, AccountContactRelation, and EventRelation.
* SOQL child subqueries and multiple-level parent paths, comparison and IN filters, ordering, LIMIT, and pagination. Use `Sforce-Query-Options: batchSize=200` to exercise `nextRecordsUrl`. Positive values below 200 are raised to 200; the maximum is 2,000. Repeat the header on each page request, or the page size defaults to 2,000. LIMIT caps the complete result rather than setting a page size.
* Stateful Bulk v1 JSON jobs and batches with `X-SFDC-Session`, including the insert/update/upsert/delete flow used by `simple-salesforce`. Bulk v2 CSV ingest applies uploaded rows when you set `state` to `UploadComplete` and exposes successful, failed, and unprocessed row results. When upserting by `Id`, a blank Id inserts a new record.
* Bulk v2 query CSV results with `Accept: text/csv`, `maxRecords`, and `locator`. Follow `Sforce-Locator` until its value is `null`; `Sforce-NumberOfRecords` reports the page count. Existing JSON result clients remain supported.
* Composite batch version-relative URLs, references in Composite/graph bodies and URLs, graph rollback, and collection external-ID upsert at `PATCH /composite/sobjects/{object}/{externalField}`.
* External-ID upserts return 201 when creating and 200 when updating, with `id`, `success`, `errors`, and `created` in the response. Later graph requests can reference the returned ID for either outcome.
* OAuth authorization-code login/consent, PKCE, client credentials, username/password, refresh and signed JWT bearer grants. OAuth clients and accounts share the twin's record and permission state. Users in one org share records while separate orgs remain isolated.
* SOSL search, invocable case/email actions, Tooling API discovery, and scenario-defined custom objects, fields, record types, layouts, tabs, and apps.

Use `SystemModstamp` for incremental setup-object sync. `PermissionSetAssignment` and `FieldPermissions` have neither `CreatedDate` nor `LastModifiedDate`; `UserRole` has no `CreatedDate`. Use `Profile.Name` rather than `Profile.Label`.

### Default OAuth credentials

Use these local test credentials when you have not supplied `oauth_clients` or `oauth_accounts`:

| Setting | Default |
| - | - |
| Client ID | `salesforce-twin-client-id` |
| Client secret | `salesforce-twin-client-secret` |
| Username | `agent@example.test` |
| Password | `salesforce-twin-password` |
| Bootstrap access token | `00D000000000001!salesforce-twin-token` |
| Allowed callback URIs | `https://client.example.test/oauth/callback`, `http://localhost:3000/oauth/callback`, `http://127.0.0.1:3000/oauth/callback` |

Open `/services/oauth2/authorize` with the client ID, a registered `redirect_uri`, and `response_type=code`. Use `prompt=login`, `prompt=consent`, or `prompt=login consent` when needed. Exchange the code at `/services/oauth2/token`; token parameters can be form encoded or supplied in the query string. Body values take precedence. The `/oauth2/*` aliases also work.

Issued tokens enforce expiry, revocation, scopes, object permissions, field permissions, and record access. The bootstrap token follows the default user's permissions when you configure security.

### Scenario configuration

Put these keys inside `seed_config.salesforce` when you [create a Scenario](https://docs.argalabs.com/features/custom-scenarios.md). Custom and package objects and fields must be declared in `objects`. Adding fields to a standard object extends its existing schema.

| Key | Purpose and default |
| - | - |
| `objects`, `apps` | Custom/package object definitions, field metadata, layouts, record types, and app tabs; empty by default. |
| `seed_records` | Records in `{object, alias?, org_id?, account_username?, values}` form. The scenario runner also accepts `records`. Use `{"$ref": "alias.Id"}` for record references. |
| `oauth_clients` | Connected apps: `client_id`, `client_secret`, `redirect_uris`, `allowed_scopes`, `grant_types`, `require_pkce`, optional `run_as_username`, and `jwt_public_key_pem`. Defaults to the test client above. |
| `oauth_accounts` | Users: `org_id`, `user_id`, `username`, `password`, optional `security_token`, `profile`, `role_id`, `permission_sets`, `permission_set_groups`, and owned `records`. Defaults to the test user above. |
| `profiles`, `permission_sets` | Named additive system, object, and field grants; empty by default. Grant `api_enabled` for API users. |
| `roles` | `{id, name, parent_id?}` definitions. Roles open access through their hierarchy; profiles and permission sets grant object/field access. |
| `sharing_defaults` | Per-object `Private`, `Read`, `ReadWrite`, or `ControlledByParent` with `parent_field`; optional `grant_access_using_hierarchies`. |
| `record_shares` | A record's `object`, `record_id` or `record_alias`, one of `user_id`/`role_id`/`group_id`, and `access` or `access_level` (`Read`/`Edit`). An alias can supply the object when it appears in the declared seed. |
| `public_groups` | `{id, name, members: [user_id or group_id]}`. Add `org_id` to scope a group to one org. |
| `account_team_members`, `opportunity_team_members` | Record alias, `user_id`, optional `team_member_role`, and access level. Account members use `account_alias` / `account_access_level`; opportunity members use `opportunity_alias` / `access_level`. |
| `permission_set_groups` | `{id, name, permission_sets: [name]}`. Assign through `oauth_accounts[].permission_set_groups`. |
| `territory2_model` | `{name, developer_name, state}`; use `Active` for territory grants. |
| `territories` | `{alias, name, model_id?, parent_id?, account_access_level}`. |
| `user_territory2_associations` | `{user_id, territory_id}`. |
| `object_territory2_associations` | `{record_alias or record_id, territory_id}` for Account assignments. |
| `sharing_rules` | Read-only sharing-rule metadata keyed by object, with `sharingOwnerRules` and/or `sharingCriteriaRules`. Definitions do not execute criteria-based rules. |
| `oauth_seed` | Deterministic OAuth seed; default `salesforce-twin`. |
| `authorization_code_ttl_seconds` | Authorization-code and pending-authorization lifetime; default `900`. |
| `access_token_ttl_seconds` | Access-token lifetime; default `7200`. |
| `refresh_token_ttl_seconds` | Refresh-token lifetime; default `7776000`. |
| `browser_session_ttl_seconds` | Browser login-session lifetime; default `7200`. |
| `rotate_refresh_tokens` | Default `true`. Replaying a rotated token revokes its grant. |
| `jwt_assertion_max_lifetime_seconds` | Maximum JWT assertion lifetime; default `300`. |
| `oauth_audiences` | Default `https://login.salesforce.com` and `https://test.salesforce.com`. |

For example, this seed creates a named role, an API user, and an owned Account:

```json theme={null}
{
  "salesforce": {
    "org_id": "00DACME00000001AAA",
    "user_id": "005ACME00000001AAA",
    "username": "reader@acme.example",
    "roles": [{"id": "reader", "name": "CRM Reader"}],
    "profiles": [{
      "name": "CRM Reader",
      "api_enabled": true,
      "object_permissions": {"Account": {"read": true}},
      "field_permissions": {"Account.Name": {"read": true}}
    }],
    "sharing_defaults": {"Account": {"access": "Private"}},
    "oauth_accounts": [{
      "org_id": "00DACME00000001AAA",
      "user_id": "005ACME00000001AAA",
      "username": "reader@acme.example",
      "profile": "CRM Reader",
      "role_id": "reader",
      "records": [{"object": "Account", "alias": "customer", "values": {"Name": "Acme Customer"}}]
    }]
  }
}
```

With security configured, unspecified permissions are denied. API changes to permission assignments, memberships, shares, and teams affect existing tokens. Record grants do not bypass object or field permissions. Scope governance shortcuts with `org_id` when you seed several orgs.

### Sharing-rule metadata

Use the twin-specific REST alternative to SOAP `readMetadata(SharingRules)`:

```http theme={null}
GET /services/data/v67.0/metadata/sharingRules/Account
Authorization: Bearer <access_token>
```

It requires setup read access and returns `fullName`, `sharingOwnerRules`, and `sharingCriteriaRules` from `sharing_rules`. This route is an Arga twin extension, not a Salesforce REST endpoint.

### Known limitations

* The catalog covers the fields described above and scenario-defined extensions, not every standard field in every Salesforce edition. Unknown objects and undeclared fields return Salesforce-shaped errors; custom unique and length constraints are enforced.
* Business records start empty. The default org, authenticated User, and schema catalog are available for governance queries. Seed CRM records through Scenarios or create them through the API.
* Permission-set muting, criteria-based sharing-rule execution, restriction rules, full implicit sharing, and advanced territory inheritance are not modeled.
* SOAP Metadata, Bulk v1 XML, hard-delete, Apex REST, Streaming, and Einstein APIs remain outside this surface. Unsupported SOQL expressions fail explicitly.
* Salesforce APIs are the twin surface; there is no Lightning CRM UI. The OAuth login and consent pages support authentication tests.
* API responses include a simulated `Sforce-Limit-Info` header. The configured API version does not imply complete coverage of that Salesforce release.
* Twin Run TTL is an Arga plan entitlement: Free runs are limited to 10 minutes; eligible paid plans can request up to 480 minutes. OAuth token lifetimes do not extend the Twin Run.

**MCP tools:** `get_twin_catalog`, `provision_twins`, `start_url_validation`, `get_validation_results`.

See [Scenario seeding](https://docs.argalabs.com/twins/seeding.md) for saving, provisioning, and resetting fixtures.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.