/
office.entities.yml
223 lines (176 loc) · 7.92 KB
/
office.entities.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
### YamlMime:TSType
name: Office.Entities
uid: 'outlook!Office.Entities:interface'
package: outlook!
fullName: Office.Entities
summary: >-
Represents a collection of entities found in an email message or appointment. Read mode only.
The `Entities` object is a container for the entity arrays returned by the `getEntities` and `getEntitiesByType`
methods when the item (either an email message or an appointment) contains one or more entities that have been found
by the server. You can use these entities in your code to provide additional context information to the viewer, such
as a map to an address found in the item, or to open a dialer for a phone number found in the item.
If no entities of the type specified in the property are present in the item, the property associated with that entity
is null. For example, if a message contains a street address and a phone number, the addresses property and
phoneNumbers property would contain information, and the other properties would be null.
To be recognized as an address, the string must contain a United States postal address that has at least a subset of
the elements of a street number, street name, city, state, and zip code.
To be recognized as a phone number, the string must contain a North American phone number format.
Entity recognition relies on natural language recognition that is based on machine learning of large amounts of data.
The recognition of an entity is non-deterministic and success sometimes relies on the particular context in the item.
When the property arrays are returned by the `getEntitiesByType` method, only the property for the specified entity
contains data; all other properties are null.
remarks: >-
**[Minimum permission
level](https://learn.microsoft.com/office/dev/add-ins/outlook/understanding-outlook-add-in-permissions)<!-- -->**:
**read item**
**[Applicable Outlook
mode](https://learn.microsoft.com/office/dev/add-ins/outlook/outlook-add-ins-overview#extension-points)<!-- -->**:
Read
**Important**: Entity-based contextual Outlook add-ins will be retired in Q2 of 2024. The work to retire this
feature will start in May and continue until the end of June. After June, contextual add-ins will no longer be able to
detect entities in mail items to perform tasks on them. The following APIs will also be retired.
- `Office.context.mailbox.item.getEntities` - `Office.context.mailbox.item.getEntitiesByType` -
`Office.context.mailbox.item.getFilteredEntitiesByName` - `Office.context.mailbox.item.getSelectedEntities`
To help minimize potential disruptions, the following will still be supported after entity-based contextual add-ins
are retired.
- An alternative implementation of the **Join Meeting** button, which is activated by online meeting add-ins, is
being developed. Once support for entity-based contextual add-ins ends, online meeting add-ins will automatically
transition to the alternative implementation to activate the **Join Meeting** button.
- Regular expression rules will continue to be supported after entity-based contextual add-ins are retired. We
recommend updating your contextual add-in to use regular expression rules as an alternative solution. For guidance on
how to implement these rules, see [Use regular expression activation rules to show an Outlook
add-in](https://learn.microsoft.com/office/dev/add-ins/outlook/use-regular-expressions-to-show-an-outlook-add-in)<!--
-->.
For more information, see [Retirement of entity-based contextual Outlook
add-ins](https://devblogs.microsoft.com/microsoft365dev/retirement-of-entity-based-contextual-outlook-add-ins)<!--
-->.
isPreview: false
isDeprecated: false
type: interface
properties:
- name: addresses
uid: 'outlook!Office.Entities#addresses:member'
package: outlook!
fullName: addresses
summary: Gets the physical addresses (street or mailing addresses) found in an email message or appointment.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'addresses: string[];'
return:
type: 'string[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const addresses = item.getEntitiesByType(Office.MailboxEnums.EntityType.Address);
```
- name: contacts
uid: 'outlook!Office.Entities#contacts:member'
package: outlook!
fullName: contacts
summary: Gets the contacts found in an email address or appointment.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'contacts: Contact[];'
return:
type: '<xref uid="outlook!Office.Contact:interface" />[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const contacts = item.getEntitiesByType(Office.MailboxEnums.EntityType.Contact);
```
- name: emailAddresses
uid: 'outlook!Office.Entities#emailAddresses:member'
package: outlook!
fullName: emailAddresses
summary: Gets the email addresses found in an email message or appointment.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'emailAddresses: string[];'
return:
type: 'string[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const emailAddresses = item.getEntitiesByType(Office.MailboxEnums.EntityType.EmailAddress);
```
- name: meetingSuggestions
uid: 'outlook!Office.Entities#meetingSuggestions:member'
package: outlook!
fullName: meetingSuggestions
summary: Gets the meeting suggestions found in an email message.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'meetingSuggestions: MeetingSuggestion[];'
return:
type: '<xref uid="outlook!Office.MeetingSuggestion:interface" />[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const meetingSuggestions = item.getEntitiesByType(Office.MailboxEnums.EntityType.MeetingSuggestion);
```
- name: phoneNumbers
uid: 'outlook!Office.Entities#phoneNumbers:member'
package: outlook!
fullName: phoneNumbers
summary: Gets the phone numbers found in an email message or appointment.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'phoneNumbers: PhoneNumber[];'
return:
type: '<xref uid="outlook!Office.PhoneNumber:interface" />[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const phoneNumbers = item.getEntitiesByType(Office.MailboxEnums.EntityType.PhoneNumber);
```
- name: taskSuggestions
uid: 'outlook!Office.Entities#taskSuggestions:member'
package: outlook!
fullName: taskSuggestions
summary: Gets the task suggestions found in an email message or appointment.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'taskSuggestions: string[];'
return:
type: 'string[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const taskSuggestions = item.getEntitiesByType(Office.MailboxEnums.EntityType.TaskSuggestion);
```
- name: urls
uid: 'outlook!Office.Entities#urls:member'
package: outlook!
fullName: urls
summary: Gets the Internet URLs present in an email message or appointment.
remarks: ''
isPreview: false
isDeprecated: false
syntax:
content: 'urls: string[];'
return:
type: 'string[]'
description: |-
#### Examples
```TypeScript
const item = Office.context.mailbox.item;
const urls = item.getEntitiesByType(Office.MailboxEnums.EntityType.Url);
```