Skip to content

Commit 6ce2f03

Browse files
author
Nick Campbell
committed
Initial catalog information for Attio Action
1 parent ca83be5 commit 6ce2f03

File tree

1 file changed

+175
-0
lines changed
  • src/connections/destinations/catalog/actions-attio

1 file changed

+175
-0
lines changed

‎src/connections/destinations/catalog/actions-attio/index.md

Lines changed: 175 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,175 @@
1+
---
2+
title: Attio (Actions) Destination
3+
hide-boilerplate: true
4+
---
5+
6+
{% include content/plan-grid.md name="actions" %}
7+
8+
Powerful, flexible and data-driven, [Attio](https://attio.com) makes it easy to build the exact CRM that your business needs.
9+
10+
This destination allows you to use your existing Segment events to create or update records in Attio, for example creating User objects from identify events.
11+
12+
## Getting started
13+
14+
1. From the Segment web app, click **Catalog**, then click **Destinations**.
15+
2. Search for **Attio (Actions)** and select it.
16+
3. Click **Add destination**, then follow the setup instructions.
17+
4. Click **Connect to (destination name)** to select the Attio Workspace you'd like to connect to.
18+
19+
<!-- The following sections should be populated with config from destination, once published, and can be refined later -->
20+
21+
## Identify User
22+
23+
Create or update a **Person** using the provided email address, then create or update a
24+
related **User** using the same address. By default, this mapping runs for `identify`
25+
events.
26+
27+
*This mapping is a special form of [Assert Record](#assert-record), because it asserts
28+
both a Person and User and links them together. If you only need to assert either a Person
29+
or User, you should configure [Assert Record](#assert-record) instead.*
30+
31+
In Attio, a **Person** is an object which represents a human. People have names, email
32+
addresses, Twitter profiles, email and calendar interactions, etc.
33+
34+
Meanwhile, a **User** is an object which represents how they exist in your product.
35+
Users might have feature flags, permission levels, etc.
36+
37+
> info ""
38+
> To use the User standard object, you'll need to make sure it's activated first. Visit
39+
> your [Workspace Settings > Objects](https://app.attio.com/_/settings/data/objects) page
40+
> and click the "Activate" button next to the Users object.
41+
42+
This mapping only makes one assumption about your data, which is that it includes an email
43+
address property. You can specify additional attributes to be mapped on the **Edit
44+
Mapping** page.
45+
46+
For example, we could set some additional properties on the Person using these Mapping
47+
Fields under "Additional Person attributes". The column on the left should contain
48+
properties from your event, or custom text, and the column on the right should reference
49+
attributes on that object type in Attio, represented by their slug.
50+
51+
> info ""
52+
> Every Attio attribute has both an ID and a slug, and you can use either to reference
53+
> those attributes in this action. To find this value, on the object settings page, select
54+
> the "Attributes" tab, locate your attribute, then click on the **︙** button and select
55+
> "Copy slug".
56+
57+
Here's an example configuration that sets the `description`, `name` and `company`
58+
attributes on the Person object:
59+
60+
| Select event variable | Enter key name | Notes |
61+
|-----------------------------------------|----------------|--------------------------------------------------------------------|
62+
| `traits.description` | description | |
63+
| `traits.last_name`, `traits.first_name` | name | Person names must be formatted as `Last name(s), First name(s)` |
64+
| `traits.domain` | company | A Company relationship can be populated using the Company's domain |
65+
66+
You can also use the same approach to specify additional properties on the User object.
67+
Please note that by default, the User object doesn't specify many attributes; the
68+
expectation is that you'll add your own that make the most sense for your product. All
69+
custom attributes can be specified here, please see [attribute types](#attribute-types)
70+
below for more information.
71+
72+
## Group Workspace
73+
74+
Create or update a **Company** using the provided domain, then create or update a
75+
**Workspace** using the provided name. By default, this mapping runs for `group` events.
76+
77+
*This mapping is a special form of [Assert Record](#assert-record), because it asserts
78+
both a Company and Workspace and links them together. If you only need to assert either a
79+
Company or Workspace, you should configure [Assert Record](#assert-record) instead.*
80+
81+
In Attio, a **Company** is an object which can represent any of your customers, suppliers,
82+
partners or competitors. Companies have names and domains, as well as enriched properties
83+
like ARR or category.
84+
85+
Meanwhile, a **Workspace** is an object which represents how they might exist in your
86+
product. Workspaces might have feature flags, billing configurations, customer support
87+
representatives, etc.
88+
89+
> info ""
90+
> To use the Workspace standard object, you'll need to make sure it's activated first. Visit
91+
> your [Workspace Settings > Objects](https://app.attio.com/_/settings/data/objects) page
92+
> and click the "Activate" button next to the Workspaces object.
93+
94+
This mapping makes the assumption that your data includes two properties:
95+
96+
1. A `domain` property to create or update a Company
97+
2. A `name` property, to create or update an associated Workspace
98+
99+
You can specify additional attributes to be mapped on the **Edit Mapping** page.
100+
101+
For example, we could set some additional properties on the Company using these Mapping
102+
Fields under "Additional Company attributes". The column on the left should contain
103+
properties from your event, or custom text, and the column on the right should reference
104+
attributes on that object type in Attio, represented by their slug. For example:
105+
106+
| Select event variable | Enter key name |
107+
|-----------------------------------------|----------------|
108+
| `traits.twitter_handle` | twitter |
109+
110+
Similarly, you can also set some additional properties on the Workspace. All
111+
custom attributes can be specified here, please see [attribute types](#attribute-types)
112+
below for more information.
113+
114+
## Assert Record
115+
116+
Create or update a single type of Object, given a matching attribute name and value. For
117+
example, you could assert that a Company exists using a given `domain` property.
118+
119+
This mapping makes the assumption that your data includes the matching property. For the
120+
following example, we'll assume you have domain and twitter properties, like so:
121+
122+
```json
123+
{
124+
"type": "identify",
125+
"traits": {
126+
"domain": "app.attio.com",
127+
"twitter_handle": "@attio"
128+
}
129+
}
130+
```
131+
132+
First, we'll need to set the "Attio Object" property - it should pre-populate with all of
133+
the activated objects in your Attio instance. Then, we'll need to set the "Matching
134+
Attribute" property. This is the slug for the attribute in Attio, and must also be present
135+
in your "Attributes" mapping in the next form. In this example, we'll select "Company" as
136+
the Attio Object, and "domains" as the Matching Attribute.
137+
138+
We would then need to ensure the Attributes mapping is populated like so:
139+
140+
| Select event variable | Enter key name |
141+
|-----------------------------------------|----------------|
142+
| `traits.domain` | domains |
143+
| `traits.twitter_handle` | twitter |
144+
145+
When this mapping runs, Attio will try to find an existing Company where one of the
146+
domains matches the one you've provided here. If it finds it, it will update the `twitter`
147+
attribute with the value `"@attio"`. If it doesn't find it, a new Company will be created
148+
with both the domain and twitter handles above.
149+
150+
151+
## Attribute types
152+
153+
With the exception of location data, the Attio Action can write all other types of
154+
attribute to Attio. Below is an example of the format that each attribute must be; please
155+
note that you'll get validation failures if any of these are incorrect. To unset an
156+
attribute, you can also pass `null` as the value.
157+
158+
| `type` | Format | Example values |
159+
|----------------------|-----------------------------------------------------------------------------------------|-------------------------------------------------------------|
160+
| `actor-reference` | An email address of a workspace member | `"[email protected]"` |
161+
| `checkbox` | Boolean | `true`, `false` |
162+
| `currency` | Number with up to 4 decimal places | `99`, `29.9999` |
163+
| `date` | YYYY-MM-DD | `"2023-09-28"` |
164+
| `domain` | `{domain}.{tld}` | `"app.attio.com"`, `"www.example.com"` |
165+
| `email` | A valid email address | `"[email protected]"` |
166+
| `location` | *unsupported* | |
167+
| `number` | Number, stored as a 64 bit float | `42.192`, `17` |
168+
| `personal-name` | Last name(s), First name(s) *(note the comma in the middle)* | `"Bloggs, Joe"` |
169+
| `phone-number` | [E.164 format](https://en.wikipedia.org/wiki/E.164), starting with `+...` | `"+15558675309"` |
170+
| `pipeline` | A UUID or title representing the status | `"open"`, `"closed"` |
171+
| `rating` | Integer from 0 to 5 | `0`, `5` |
172+
| `record-reference` | To a person, an email. To a company, a domain. UUID of other entity always supported. | `"[email protected]"`, `"app.attio.com"`, `"0677efa..."` |
173+
| `select` | A UUID or title representing the option | `"open"` |
174+
| `text` | String | `"A piece of text"` |
175+
| `timestamp` | ISO8601, e.g. YYYY-MM-DDTHH:MM:SS | `"2023-09-28 04:39:17.000"` |

0 commit comments

Comments
 (0)