Skip to content

Commit 284a87c

Browse files
forstisabellaforstisabella
authored
Merge pull request #5371 from attio/develop
Initial catalog information for Attio Actions Destination
2 parents 5174e69 + 78dff11 commit 284a87c

File tree

1 file changed

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

1 file changed

+184
-0
lines changed

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

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

0 commit comments

Comments
 (0)