Defining writes
To define a write action, addwrite
as a key in your integration defined in amp.yaml
, and add a list of standard and custom objects you want to write to.
Share mappings with read actions
If you are using Read Actions and have already defined field mappings, your Write Actions can automatically use the same mappings if you addinheritMapping
to your manifest file. When you call our Write API, we will ensure that we are writing back to the appropriate field that the customer has mapped.
On the roadmapThe ability to programmatically create custom objects when a user installs your integration.
Writing records
Once your users install an integration with a write action, your app can write data to their SaaS by making a POST call to Ampersand, the URL is in the format of:https://write.withampersand.com/v1/projects/:projectIdOrName/integrations/:integrationId/objects/:objectName
You can find your project ID and integration ID in the Ampersand Dashboard (look in the address bar) or you can run the following in the terminal to get projectId
& integrationId
:
objectName
refers to the objectName
key within the amp.yaml
file that defines your integration. This must match the name of an object that exists within the SaaS instance.
Create a new record
To create a new record, make a request to the Write endpoint withtype
being create
. For example:
Create associations when creating a record
If you’d like to create records that are associated with other records, you can make a similar request with theassociations
parameter.
This is currently only supported for HubSpot.
Update an existing record
To update an existing record, you need to know the ID of the record, which is the ID that the SaaS provider uses to uniquely identify this record. If you created the record using Ampersand, this ID is available in the API response. If you are reading the record first using Ampersand’s Read Actions, make sure you add the ID as a required field in the read action. Here is an example request:Advanced use cases
These advanced use cases are currently only supported when creating or updating installations via the API or Headless UI.
Prevent overwriting of customer data
There are certain fields that you may only want to write to when you are creating a record, not when you are updating a record. This helps prevent the scenario where you may accidentally overwrite a field that the customer has manually modified in their SaaS product. You may also have a need for the opposite behavior, where you want to leave a field blank when creating records, but write to that field when updating records.Using headless UI
You can set overwrite behavior on a customer-by-customer basis when using the functionsetFieldSettings
. Learn more about pre-requisites for headless UI here.
Using API
As an alternative to headless UI, you can set overwrite behavior on a customer-by-customer when you make a call to the Create Installation API. Here is a sample request body:Default values
Default values are applied to a field whenever that value is missing from the write request. We current support string, boolean and number values.Using headless UI
You can set default values on a customer-by-customer basis using thesetFieldSettings
function. Learn more about pre-requisites for headless UI here.
Using API
As an alternative to headless UI, you can set this behavior on a customer-by-customer basis when you make a call to the Create Installation API. Here is a sample request body:Remove unmapped fields
If your write action is sharing mapping with read actions, we can drop unmapped fields from the write request before sending the request to the provider API. Please contact support@withampersand.com if you want to use this preview feature.Write modes
Write actions support two modes:synchronous
and asynchronous
. The mode determines how the API handles your write request and when you receive a response.
Synchronous mode
In synchronous mode, the write operation is processed immediately and the API waits for the operation to complete before returning a response.Asynchronous mode
In asynchronous mode, Ampersand validates the request & immediately returns an operation ID. The write is then processed in the background. If the write fails due to API quota issues or other retryable errors, Ampersand will automatically keep retrying for up to 1 hour. If needed, the retry policy can be configured to retry for up to 48 hours. To use async mode, setmode: "asynchronous"
in your request:
Checking status of an async write operation
To check the status of an async write operation, use the Get Operation endpoint with the operation ID in the response body of the write API endpoint.success
, failure
or in_progress
state.
Retry policy for async writes
Ampersand will automatically retry failed operations with exponential backoff until the default deadline of 1 hour. If this is not enough, you can specify a longer deadline of up to 48 hours.Combine use cases
Here is a full example for a request body to the Create Installation API that combines multiple use cases:- sharing mapping with read actions
- applying default values
- configuring when the field should be written to
Using headless UI
You can see an example here of combining multiple use cases.Using API
customSource
has been mapped to the myCustomSource
field in this customer’s Hubspot instance, the default value for this field is “myApp” and the field will only be written to when it is a create record request, and not an update request.