### Read, Write, and Subscribe Installation Example Source: https://docs.withampersand.com/reference/installation/create-a-new-installation Example of an installation configuration that supports reading, writing, and subscribing to events. ```yaml groupRef: group-456 connectionId: b2d5f8a3-9e4c-4b7f-8d1a-6c9e2f5b8d4a config: content: provider: salesforce read: objects: contacts: objectName: contacts schedule: '*/15 * * * *' selectedFields: phone: true email: true selectedFieldMappings: phoneNumber: phone emailAddress: email write: objects: contacts: objectName: contacts subscribe: objects: contacts: objectName: contacts destination: contactWebhook inheritFieldsAndMappings: true ``` -------------------------------- ### Example Installation Object Source: https://docs.withampersand.com/reference/installation/list-installations-for-an-integration This example shows a detailed installation object for an integration, including project ID, integration ID, group, health status, connection details, and configuration. ```json { "id": "3f8b2a1e-7c4d-4e9a-b5f6-1d2e3a4b5c6d", "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "integrationId": "550e8400-e29b-41d4-a716-446655440000", "group": { "groupRef": "org_12345", "groupName": "Acme Corp", "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "createTime": "2024-01-15T10:30:00.000000Z" }, "healthStatus": "healthy", "connection": { "id": "9d8c7b6a-5e4f-3a2b-1c0d-ef9876543210", "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "provider": "salesforce", "group": { "groupRef": "org_12345", "groupName": "Acme Corp", "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "createTime": "2024-01-15T10:30:00.000000Z" }, "consumer": { "consumerRef": "user_67890", "consumerName": "Jane Smith", "projectId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "createTime": "2024-01-15T10:30:00.000000Z" }, "createTime": "2024-01-15T10:30:00.000000Z", "authScheme": "oauth2/authorizationCode", "status": "working" }, "createTime": "2024-01-15T10:30:00.000000Z", "createdBy": "consumer:user_67890", "config": { "id": "e4d3c2b1-a098-7654-3210-fedcba987654", "revisionId": "f0e1d2c3-b4a5-6789-0abc-def123456789", "createTime": "2024-01-15T10:30:00.000000Z", "createdBy": "consumer:user_67890", "content": { "provider": "salesforce", "read": { "objects": { "account": { "objectName": "account", "schedule": "*/15 * * * *", "destination": "accountWebhook", "selectedFields": { "name": true } } } } } } } ``` -------------------------------- ### Minimal Write-Only Installation Example Source: https://docs.withampersand.com/reference/installation/create-a-new-installation Example of a minimal installation configuration for write-only operations. ```yaml groupRef: group-123 connectionId: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c config: content: provider: salesforce write: objects: contacts: objectName: contacts ``` -------------------------------- ### Ampersand CLI Help Example Source: https://docs.withampersand.com/cli/reference Example of using the help command to get specific information about the 'deploy' command. ```bash amp help deploy ``` -------------------------------- ### Example Selected Field Mappings Source: https://docs.withampersand.com/reference/installation/create-a-new-installation Illustrates how to specify which fields should be read for an installation. ```json { "phone": true, "fax": true } ``` -------------------------------- ### React Example: Creating an Installation Source: https://docs.withampersand.com/headless This React component demonstrates how to use the `useCreateInstallation` hook to create a new installation. It includes form submission handling, disabling the button during pending state, and displaying error messages. ```tsx import { useCreateInstallation } from '@amp-labs/react'; function InstallationForm() { const { createInstallation, isPending, error, errorMsg, } = useCreateInstallation(); const handleSubmit = async (e) => { e.preventDefault(); createInstallation({ // Add your installation config here config: { read: { objects: { companies: { objectName: 'companies', selectedFieldsAuto: 'all', // Read all fields }, }, }, }, onSuccess: (data) => { console.log("Installation created", { installation: data }); }, onError: (error) => { console.error("Installation creation failed", { error }); }, }); }; return (
{error &&
{errorMsg}
}
); } ``` -------------------------------- ### Get Installation Details Source: https://docs.withampersand.com/reference/installation/get-an-installation Retrieves the details of an existing installation for a specific project and provider. ```APIDOC ## GET /websites/withampersand/{projectId} ### Description Retrieves the details of an existing installation for a specific project and provider. ### Method GET ### Endpoint /websites/withampersand/{projectId} ### Parameters #### Path Parameters - **projectId** (string) - Required - The Ampersand project ID. ### Response #### Success Response (200) - **projectId** (string) - The Ampersand project ID. - **provider** (string) - The SaaS provider that this Connection is for. - **providerApp** (object) - Details about the provider application. - **id** (string) - The provider app ID. - **projectId** (string) - The Ampersand project ID. - **externalRef** (string) - The ID used by the provider to identify the app (optional). - **provider** (string) - The SaaS provider that this app connects to. - **clientId** (string) - The OAuth client ID for this app. - **scopes** (array) - The OAuth scopes for this app. - **metadata** (object) - Provider-specific configuration that extends the standard OAuth flow. - **createTime** (string) - The time the provider app was created. - **updateTime** (string) - The time the provider app was updated. - **group** (object) - Details about the group associated with the installation. - **groupRef** (string) - Reference to the group. ``` -------------------------------- ### Example Installation Updated Payload with Config Source: https://docs.withampersand.com/notifications/notification-payloads Illustrates the payload for an 'installation.updated' event, including nested 'config' and 'lastConfig' fields. It also shows how 'configURL' and 'lastConfigURL' are used when configuration data is too large to include directly. ```json { "notificationType": "installation.updated", "data": { "...", "config": { "read": { "objects": { "account": { "objectName": "account", "destination": "my-webhook", "requiredFields": [...], "optionalFields": [...] } } } }, "lastConfig": { "read": { "objects": { "account": { "objectName": "account", "destination": "my-old-webhook", "requiredFields": [...], "optionalFields": [...] } } } } } } ``` -------------------------------- ### Error Response Example Source: https://docs.withampersand.com/reference/installation/create-a-new-installation This snippet shows an example of an error response that might be returned during the installation process. It includes details about the problem, its cause, and how to resolve it. ```APIDOC ## Error Response Example ### Description This is an example of a standardized error response format that can be returned by the API. It provides details about the problem, including status, detail, instance, and optional fields like subsystem, time, requestId, causes, remedy, and support information. ### Response Example ```json { "type": "urn:problem-type:exampleOrganization:exampleProblem", "href": "https://www.belgif.be/specification/rest/api-guide/#standardized-problem-types", "title": "Description of the type of problem that occurred", "status": 400, "detail": "Description of specific occurrence of the problem", "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000", "subsystem": "api", "time": "2024-04-22T18:55:28.456076Z", "requestId": "89eb1ffb-2a54-4105-aaae-7bf990f1aa69#87715", "causes": [ "database connection failed", "database query failed", "unable to fetch user" ], "remedy": "Shorten your input to be under 100 characters", "supportEmail": "support@withampersand.com", "supportPhone": "+1-555-555-5555", "supportUrl": "https://example.com/support" } ``` ``` -------------------------------- ### Create Installation API Source: https://docs.withampersand.com/write-actions Use the Create Installation API to include `deletionSettings` in the write object when creating a new installation. ```APIDOC ## POST /reference/installation/create-a-new-installation ### Description Creates a new installation and allows for the configuration of deletion settings. ### Method POST ### Endpoint /reference/installation/create-a-new-installation ### Parameters #### Request Body - **groupRef** (string) - Required - The reference to the customer group. - **connectionId** (string) - Required - The ID of the connection. - **config** (object) - Required - The configuration object for the installation. - **revisionId** (string) - Required - The revision ID of the configuration. - **content** (object) - Required - The content of the configuration. - **provider** (string) - Required - The name of the provider (e.g., "salesforce"). - **write** (object) - Required - Write configuration for objects. - **objects** (object) - Required - Object-specific write configurations. - **contact** (object) - Required - Configuration for the contact object. - **objectName** (string) - Required - The name of the object (e.g., "contact"). - **deletionSettings** (object) - Optional - Settings for deletion behavior. - **enabled** (boolean) - Required - Whether deletion is enabled. ``` -------------------------------- ### Create Installation Source: https://docs.withampersand.com/reference/installation/create-a-new-installation Creates a new installation with specified configurations for read, write, and subscribe operations. It returns the details of the created installation. ```APIDOC ## POST /installations ### Description Creates a new installation with specified configurations for read, write, and subscribe operations. It returns the details of the created installation. ### Method POST ### Endpoint /installations ### Parameters #### Request Body - **groupRef** (string) - Required - Reference to the group the installation belongs to. - **connectionId** (string) - Required - The ID of the connection to use for the installation. - **config** (object) - Required - The configuration for the installation. - **content** (object) - Required - The content configuration, specifying provider and operations. - **provider** (string) - Required - The integration provider (e.g., salesforce). - **read** (object) - Optional - Configuration for read operations. - **objects** (object) - Required - Defines objects to read. - **[objectName]** (object) - Required - Configuration for a specific object. - **objectName** (string) - Required - The name of the object. - **schedule** (string) - Optional - The schedule for reading the object (cron format). - **selectedFields** (object) - Optional - Fields to select for reading. - **selectedFieldMappings** (object) - Optional - Mappings for selected fields. - **write** (object) - Optional - Configuration for write operations. - **objects** (object) - Required - Defines objects to write. - **[objectName]** (object) - Required - Configuration for a specific object. - **objectName** (string) - Required - The name of the object. - **subscribe** (object) - Optional - Configuration for subscribe operations. - **objects** (object) - Required - Defines objects to subscribe to. - **[objectName]** (object) - Required - Configuration for a specific object. - **objectName** (string) - Required - The name of the object. - **destination** (string) - Required - The destination for subscription events. - **inheritFieldsAndMappings** (boolean) - Required - Whether to inherit fields and mappings from read configuration. ### Response #### Success Response (201) - **id** (string) - The installation ID. - **config** (object) - The configuration of the installation. - **connection** (object) - Details about the connection. - **createTime** (string) - The creation timestamp of the installation. - **created_by** (string) - The user who created the installation. - **healthStatus** (string) - The health status of the installation. - **integrationId** (string) - The ID of the integration. - **projectId** (string) - The ID of the project. #### Response Example { "id": "inst-12345", "config": { "content": { "provider": "salesforce", "read": { "objects": { "contacts": { "objectName": "contacts", "schedule": "*/15 * * * *", "selectedFields": { "phone": true, "email": true }, "selectedFieldMappings": { "phoneNumber": "phone", "emailAddress": "email" } } } }, "write": { "objects": { "contacts": { "objectName": "contacts" } } }, "subscribe": { "objects": { "contacts": { "objectName": "contacts", "destination": "contactWebhook", "inheritFieldsAndMappings": true } } } } }, "connection": { "id": "a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c" }, "createTime": "2023-10-27T10:00:00Z", "created_by": "user@example.com", "healthStatus": "HEALTHY", "integrationId": "int-abcde", "projectId": "proj-fghij" } ``` -------------------------------- ### Setup Ampersand and Installation Providers Source: https://docs.withampersand.com/headless Wrap your application with AmpersandProvider and InstallationProvider to provide context for headless hooks and functions. Ensure correct configuration for authentication and installation details. ```tsx import { AmpersandProvider, // Needed for all hooks and components in @amp-labs/react. InstallationProvider, // Needed for headless hooks and functions. } from "@amp-labs/react" const options = { project: 'PROJECT', // Your Ampersand project name or ID // Pick one of the following authentication methods. apiKey: 'API_KEY', // Ampersand API key (simple) // OR getToken: async ({consumerRef, groupRef}) => { // JWT Authentication (advanced) // Custom logic to fetch JWT token from your backend, e.g. return await getTokenFromMyBackend(consumerRef, groupRef); // See https://docs.withampersand.com/api/jwt-auth }, }; // Define variables that will be used for this code snippet and // other code snippets on this page. const integration = "my-salesforce-integration"; // Must match name in `amp.yaml`. const provider = "salesforce"; const groupRef = "group-test-1"; const groupName = "Test Group"; const consumerRef = "consumer-test-1"; const consumerName = "Test Consumer"; function App() { return ( {/* Your custom component */} ); } ``` -------------------------------- ### List Installations Source: https://docs.withampersand.com/reference/installation/list-installations-for-a-project Fetches a list of all installations configured for a given project. Each installation object contains details about the data to subscribe to, event configurations, and destination settings. ```APIDOC ## GET /websites/withampersand ### Description Retrieves a list of all installations configured for a given project. Each installation object contains details about the data to subscribe to, event configurations, and destination settings. ### Method GET ### Endpoint /websites/withampersand ### Parameters #### Query Parameters - **objects** (object) - Optional - Allows specifying which objects to subscribe to. Each object can have configurations for create and update events, including which fields to watch. - **additionalProperties** (object) - Represents a subscription configuration for a specific object. - **objectName** (string) - Required - The name of the object to subscribe to. - **destination** (string) - Required - The name of the destination that the result should be sent to. - **inheritFieldsAndMappings** (boolean) - Required - Whether to inherit fields and mappings from the read config. - **createEvent** (object) - Configuration for create events. - **enabled** (string) - Required - Conditions to enable create events. Enum: `always`, `never`. - **updateEvent** (object) - Configuration for update events. - **enabled** (string) - Required - Conditions to enable update events. Enum: `always`, `never`. - **watchFieldsAuto** (string) - Optional - Whether to watch all fields automatically. Enum: `all`. - **requiredWatchFields** (array) - Optional - A list of fields that are required to be watched. - **items** (string) ### Response #### Success Response (200) - **objects** (object) - A map where keys are object names and values are their respective configurations. - **additionalProperties** (object) - Represents a subscription configuration for a specific object. - **objectName** (string) - The name of the object to subscribe to. - **destination** (string) - The name of the destination that the result should be sent to. - **inheritFieldsAndMappings** (boolean) - Whether to inherit fields and mappings from the read config. - **createEvent** (object) - Configuration for create events. - **enabled** (string) - Conditions to enable create events. Enum: `always`, `never`. - **updateEvent** (object) - Configuration for update events. - **enabled** (string) - Conditions to enable update events. Enum: `always`, `never`. - **watchFieldsAuto** (string) - Whether to watch all fields automatically. Enum: `all`. - **requiredWatchFields** (array) - A list of fields that are required to be watched. - **items** (string) ``` -------------------------------- ### List Installations Source: https://docs.withampersand.com/reference/installation/list-installations-for-a-project Fetches a list of all installations for a specified project. Each installation object contains details about the connection, project, provider, and provider app. ```APIDOC ## GET /websites/withampersand ### Description Retrieves a list of all installations for a given project. ### Method GET ### Endpoint /websites/withampersand ### Parameters #### Query Parameters - **projectId** (string) - Required - The Ampersand project ID. ### Response #### Success Response (200) - **connections** (array) - List of connection objects. - **id** (string) - The connection ID. - **projectId** (string) - The Ampersand project ID. - **provider** (string) - The SaaS provider that this Connection is for. - **providerApp** (object) - Details about the provider app. - **id** (string) - The provider app ID. - **projectId** (string) - The Ampersand project ID. - **externalRef** (string) - Optional - The ID used by the provider to identify the app. - **provider** (string) - The SaaS provider that this app connects to. - **clientId** (string) - The OAuth client ID for this app. - **scopes** (array) - The OAuth scopes for this app. - **items** (string) - **metadata** (object) - Provider-specific configuration. - **authQueryParams** (object) - Additional query parameters for the OAuth authorization URL. - **providerParams** (object) - Provider-specific string values. - **createTime** (string) - The time the provider app was created. - **updateTime** (string) - The time the provider app was updated. - **group** (object) - Group details. - **createTime** (string) - The time the group was created. ### Response Example { "connections": [ { "id": "connection-123", "projectId": "project-456", "provider": "salesforce", "providerApp": { "id": "provider-app-123", "projectId": "project-456", "externalRef": "external-id-123", "provider": "salesforce", "clientId": "client-id-123", "scopes": [ "oauth", "offline", "crm.read" ], "metadata": { "authQueryParams": { "optional_scope": [ "automation.sequences.read" ] }, "providerParams": { "packageInstallURL": "https://login.salesforce.com/packaging/installPackage.apexp?p0=04t123456789", "gcpProjectId": "my-gcp-project", "gcpPubSubTopicName": "my-topic" } }, "createTime": "2023-10-27T10:00:00Z", "updateTime": "2023-10-27T10:00:00Z" }, "group": { "createTime": "2023-10-27T10:00:00Z" } } ] } ``` -------------------------------- ### API: Configure Write Behavior for Lead Object Source: https://docs.withampersand.com/write-actions Use the Create Installation API to specify when fields should be written for a 'lead' object. This example shows how to prevent writing to the 'source' field on update while allowing it on create. ```javascript { "groupRef": "customer-group-ref", "connectionId": "connection-id", "config": { "revisionId": "revision-id", "content": { "provider": "hubspot", "write": { "objects": { "lead": { "objectName": "lead", "selectedFieldSettings": { "source": { // Do not write to source field when updating a record. "writeOnUpdate": "never", // Write to source field when creating a record, // This is the default behavior. "writeOnCreate": "always" }, }, } } }, } } } ``` -------------------------------- ### List Setups Source: https://docs.withampersand.com/provider-guides/sageIntacct Retrieves a list of fixed asset setups. ```APIDOC ## GET /fixed-assets/setup ### Description Retrieves a list of fixed asset setups. ### Method GET ### Endpoint /fixed-assets/setup ``` -------------------------------- ### Get an installation Source: https://docs.withampersand.com/llms.txt Retrieves a single installation by ID, including its connection details, config, and health status. ```APIDOC ## GET /installations/{id} ### Description Retrieves a single installation by ID, including its connection details, config, and health status. ### Method GET ### Endpoint /installations/{id} ``` -------------------------------- ### Create Installation Source: https://docs.withampersand.com/reference/installation/create-a-new-installation This section outlines the structure for creating a new installation, detailing the project ID, creation and update times, provider references, authentication schemes, and connection status. ```APIDOC ## POST /websites/withampersand ### Description Creates a new installation for a website with an ampersand. ### Method POST ### Endpoint /websites/withampersand ### Parameters #### Request Body - **project**: object - Required - Details about the project. - **id** (string) - Required - The Ampersand project ID. - example: project-456 - **createTime** (string) - Optional - The time the consumer was created. - format: date-time - example: '2023-07-13T21:34:44.816Z' - **updateTime** (string) - Optional - The time the consumer was last updated. - format: date-time - example: '2023-07-13T21:34:44.816Z' - **providerWorkspaceRef** (string) - Optional - If available, the identifier for the provider workspace (e.g. the Salesforce subdomain). - example: provider-workspace-123 - **providerConsumerRef** (string) - Optional - If available, the ID that Salesforce/Hubspot uses to identify this user (e.g. Salesforce has IDs in the form of https://login.salesforce.com/id/00D4x0000019CQTEA2/0054x000000orJ4AA). - example: provider-consumer-123 - **authScheme** (string) - Optional - The authentication scheme used for this connection. - example: oauth2/authorizationCode - enum: [none, apiKey, basic, oauth2/authorizationCode, oauth2/authorizationCodePKCE, oauth2/clientCredentials, oauth2/password] - **status** (string) - Optional - The status of the connection. - example: working - enum: [created, working, bad_credentials] - **oauth2AuthorizationCode** (object) - Optional - Details for OAuth2 Authorization Code flow. - **accessToken** (object) - Required - The access token for the connection. - **token** (string) - Required - **issuedAt** (string) - Optional - format: date-time, example: '2024-04-22T18:55:28.456076Z' - **expiresAt** (string) - Optional - format: date-time, example: '2024-10-22T18:55:28.456076Z' - **refreshToken** (object) - Optional - The refresh token to use for the connection. - **token** (string) - Required - **issuedAt** (string) - Optional - format: date-time, example: '2024-04-22T18:55:28.456076Z' - **expiresAt** (string) - Optional - format: date-time ### Response #### Success Response (200) - **createTime** (string) - The time the connection was created. - format: date-time - example: '2023-07-13T21:34:44.816Z' - **updateTime** (string) - The time the connection was last updated. - format: date-time - example: '2023-07-13T21:34:44.816Z' - **authScheme** (string) - The authentication scheme used for this connection. - example: oauth2/authorizationCode - **status** (string) - The status of the connection. - example: working #### Response Example { "createTime": "2023-07-13T21:34:44.816Z", "updateTime": "2023-07-13T21:34:44.816Z", "authScheme": "oauth2/authorizationCode", "status": "working" } ``` -------------------------------- ### OpenAPI Specification for Updating an Installation Source: https://docs.withampersand.com/reference/installation/update-an-installation This OpenAPI 3.0.1 specification defines the PATCH endpoint for updating an installation. It outlines the required parameters, the structure of the request body including the `updateMask` and `installation` objects, and provides examples for field paths. ```yaml platform patch /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId} openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /projects/{projectIdOrName}/integrations/{integrationId}/installations/{installationId}: patch: tags: - Installation summary: Update an installation description: > Update an installation using field masks. Note: subscribe config changes trigger a subscription change in the provider's system, which typically takes 1-2 minutes but may take up to 10 minutes. operationId: updateInstallation parameters: - name: projectIdOrName in: path required: true description: The Ampersand project ID or project name. schema: type: string example: my-project - name: integrationId in: path required: true description: The ID of the integration that this installation belongs to. schema: type: string example: e3a7f9c1-4b2d-4e8a-9f6b-2d5c8a1e3b7f - name: installationId in: path required: true description: The Ampersand installation ID. schema: type: string example: 7b3c9d2e-5a1f-4e8b-b6d4-9c8a2f1e5d3b requestBody: content: application/json: schema: required: - installation - updateMask type: object properties: updateMask: type: array items: type: string description: > Array of field paths specifying which fields to update. Each path must have a corresponding value in the `installation` object. A field included in `installation` but not listed here will be ignored. Allowed values: - `connectionId` - switch the SaaS connection tied to this installation. - `config.createdBy` - change the attribution for who created this config. - `config.content.read.objects.` - replace the read config for a single object (e.g. `config.content.read.objects.contacts`). - `config.content.write.objects.` - replace the write config for a single object. - `config.content.write.objects` - replace the entire write objects map. - `config.content.subscribe.objects.` - replace the subscribe config for a single object. - `config.content.subscribe.objects` - replace the entire subscribe objects map. - `config.content.proxy.enabled` - enable or disable the proxy. Replace `` with the provider object name (e.g. `contacts`, `leads`, `accounts`). example: - config.content.read.objects.contacts - config.content.write.objects.leads installation: type: object properties: connectionId: type: string description: The ID of the SaaS connection tied to this installation. example: a1c4e7b2-8f3d-4a6e-9c2b-5d8f1e4a7b3c config: type: object properties: revisionId: type: string deprecated: true description: >- Deprecated: This field will be automatically set to the latest revision ID. createdBy: type: string description: >- The person who created the config, in the format of "consumer:{consumer-id}" or "builder:{builder-id}". content: description: The content of the config. title: Update Installation Config Content allOf: - title: Base Config Content type: object properties: provider: description: The SaaS API that we are integrating with. example: hubspot ``` -------------------------------- ### Installation Creation Parameters Source: https://docs.withampersand.com/reference/installation/create-a-new-installation This section outlines the parameters available when creating a new installation, specifically focusing on field filters for backfill and incremental reads, as well as object configurations. ```APIDOC ## Installation Creation ### Description This section details the parameters for creating a new installation, including advanced filtering options for data reads and object configurations. ### Parameters #### Request Body - **fieldFilters** (array) - Optional - Filters to apply only during backfill. Multiple conditions are joined by AND. Use this when you want different filter behavior for backfill vs. incremental reads. - **fieldName** (string) - Required - The name of the field to filter on. Example: `status` - **operator** (string) - Required - The comparison operator. Enum: `eq`. Example: `eq` - **value** (string, boolean, number) - Optional - The value to filter on. - **fieldFilters** (array) - Optional - Filters to apply when reading records during incremental reads and backfill. Multiple conditions are joined by AND. Each field can only have one condition. - **fieldName** (string) - Required - The name of the field to filter on. Example: `status` - **operator** (string) - Required - The comparison operator. Enum: `eq`. Example: `eq` - **value** (string, boolean, number) - Optional - The value to filter on. - **objects** (object) - Optional - Configuration for read objects. This property allows for additional properties defining read configurations. - **additionalProperties** (object) - Required - Defines the structure for read config objects. - **Base Read Config Object** (object) - Base properties for read configuration objects. ``` -------------------------------- ### List Installations for a Project Source: https://docs.withampersand.com/reference/installation/list-installations-for-a-project Use this OpenAPI definition to understand the parameters and responses for listing all installations within a project. This is useful for getting a complete view of active customer integrations. ```yaml openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /projects/{projectIdOrName}/installations: get: tags: - Installation summary: List installations for a project description: > Lists all installations across every integration in a project, giving you a complete view of all active customer integrations. To narrow results to a single integration, use listInstallations instead. operationId: listInstallationsForProject parameters: - name: projectIdOrName in: path required: true description: The Ampersand project ID or project name. schema: type: string example: my-project - name: groupRef in: query description: >- The ID that your app uses to identify a group of users (e.g. an org ID, workspace ID, or team ID). When provided, only returns installations belonging to this group. example: group-123 schema: type: string responses: '200': description: List of installations content: application/json: schema: type: array items: title: Installation required: - config - connection - createTime - createdBy - healthStatus - id - integrationId - projectId type: object properties: id: type: string description: The installation ID. projectId: type: string description: The Ampersand project ID. example: project-456 integrationId: type: string description: The integration ID. group: title: Group required: - createTime - groupName - groupRef - projectId type: object properties: groupRef: type: string description: >- The ID of the user group that has access to this installation. example: group-123 groupName: type: string description: >- The name of the user group that has access to this installation. example: Super Customer projectId: type: string description: The Ampersand project ID. example: project-456 createTime: type: string description: The time the group was created. format: date-time example: '2023-07-13T21:34:44.816Z' updateTime: type: string description: The time the group was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' healthStatus: type: string enum: - healthy - unhealthy description: The health status of the installation. example: healthy lastOperationStatus: type: string enum: - success - failure - in_progress description: > The status of the latest operation for this installation. example: success connection: title: Connection required: - id - createTime - group - consumer - projectId - provider - authScheme - status type: object properties: id: type: string ``` -------------------------------- ### Create Installation Configuration Source: https://docs.withampersand.com/reference/installation/create-a-new-installation This snippet outlines the configuration parameters for creating a new installation, focusing on default value application and update behaviors. ```APIDOC ## Create Installation Configuration ### Description Configuration for creating a new installation, specifying how default values are applied and how fields are written on update. ### Parameters #### Request Body - **writeOnUpdate** (string) - Optional - Whether the default value should be applied when updating a record. Possible values: `always`, `never`, `ifEmpty`. - **default** (string) - Optional - Whether the default value should be applied when creating a record. Possible values: `always`, `never`. ### Subscribe Configuration #### Request Body - **objects** (object) - Required - Configuration for subscribing to objects. - **objectName** (string) - Required - The name of the object to subscribe to. - **destination** (string) - Required - The name of the destination for the result. - **inheritFieldsAndMappings** (boolean) - Required - Whether to inherit fields and mappings from the read config. - **createEvent** (object) - Required - Conditions to enable create events. - **enabled** (string) - Required - Conditions to enable create events. Possible values: `always`, `never`. ``` -------------------------------- ### OpenAPI Specification for Listing Installations Source: https://docs.withampersand.com/reference/installation/list-installations-for-an-integration This OpenAPI 3.0.1 specification defines the GET endpoint for listing installations of an integration. It includes details on parameters, request structure, and the expected JSON response. ```yaml openapi: 3.0.1 info: title: Ampersand public API version: 1.0.0 servers: - url: https://api.withampersand.com/v1 security: - APIKeyHeader: [] - Bearer: [] paths: /projects/{projectIdOrName}/integrations/{integrationId}/installations: get: tags: - Installation summary: List installations for an integration description: > Lists all installations for a specific integration within a project. To list installations across all integrations, use listInstallationsForProject instead. operationId: listInstallations parameters: - name: projectIdOrName in: path required: true description: The Ampersand project ID or project name. schema: type: string example: my-project - name: integrationId in: path required: true description: The unique identifier (UUID) of the integration. schema: type: string example: 550e8400-e29b-41d4-a716-446655440000 - name: groupRef in: query description: >- The ID that your app uses to identify a group of users (e.g. an org ID, workspace ID, or team ID). When provided, only returns installations belonging to this group. example: group-123 schema: type: string responses: '200': description: List of installations content: application/json: schema: type: array items: title: Installation required: - config - connection - createTime - createdBy - healthStatus - id - integrationId - projectId type: object properties: id: type: string description: The installation ID. projectId: type: string description: The Ampersand project ID. example: project-456 integrationId: type: string description: The integration ID. group: title: Group required: - createTime - groupName - groupRef - projectId type: object properties: groupRef: type: string description: >- The ID of the user group that has access to this installation. example: group-123 groupName: type: string description: >- The name of the user group that has access to this installation. example: Super Customer projectId: type: string description: The Ampersand project ID. example: project-456 createTime: type: string description: The time the group was created. format: date-time example: '2023-07-13T21:34:44.816Z' updateTime: type: string description: The time the group was last updated. format: date-time example: '2023-07-13T21:34:44.816Z' healthStatus: type: string enum: - healthy - unhealthy description: The health status of the installation. example: healthy lastOperationStatus: type: string enum: - success - failure - in_progress description: > The status of the latest operation for this installation. example: success connection: title: Connection required: - id - createTime - group - consumer ``` -------------------------------- ### Install @amp-labs/react Source: https://docs.withampersand.com/headless Install the Headless UI library and prebuilt UI components using npm or yarn. ```bash npm install @amp-labs/react # or yarn add @amp-labs/react ``` -------------------------------- ### Shopify App Store Listing URL Example Source: https://docs.withampersand.com/provider-guides/shopify This is an example of the App Store listing URL that merchants will use to install your app. Replace YOUR_APP_HANDLE with your actual app's handle. ```text https://apps.shopify.com/YOUR_APP_HANDLE ```