ConvertId operation
Updated: April 16, 2013
Find information about the ConvertId EWS operation.
Applies to: Exchange 2013 | Exchange Online | Exchange Server 2007 Service Pack 1 (SP1) | Exchange Server 2010
The ConvertId Exchange Web Services (EWS) operation converts item and folder identifiers between formats that are accepted by versions of Exchange starting with Exchange Server 2007 Service Pack 1 (SP1), including Exchange Online.
Important
|
|---|
|
The EWS identifier format changed between the initial release version of Exchange 2007 and Exchange 2007 Service Pack 1 (SP1). Exchange 2010 uses the same identifier format that Exchange 2007 SP1 uses. |
Note
|
|---|
|
The ConvertId operation supports impersonation in versions of Exchange starting with Exchange Server 2010 SP2, including Exchange Online. |
You can convert the following identifiers by using the ConvertId operation:
-
The identifier format for EWS in the initial release version of Exchange 2007. This is represented by the EwsLegacyId enumeration value in the IdFormatType enumeration.
-
The identifier format for EWS in Exchange 2007 SP1 or Exchange 2010. This is represented by the EwsId enumeration value in IdFormatType.
-
The MAPI identifier, as in the PR_ENTRYID property. This is represented by the EntryId enumeration value in the IdFormatType enumeration.
-
The availability calendar event identifier. This is a hexadecimal-encoded representation of the PR_ENTRYID property. This is represented by the HexEntryId enumeration value in IdFormatType.
-
The Exchange store identifier. This is represented by the StoreId enumeration value in IdFormatType.
-
The Outlook Web App identifier. This is represented by the OwaId enumeration value in IdFormatType. The passing of URLs that are created from this identifier to Outlook Web App is not supported. The Outlook Web App identifier is applicable to Exchange 2007 and Exchange 2010. Outlook Web App for Exchange Online and versions of Exchange starting with Exchange Server 2013 uses EWS identifiers.
|
Note
|
|---|
|
The ConvertId operation validates that a given SMTP address has a valid format. The operation does not determine whether an SMTP address represents a valid mailbox. |
The ConvertId operation can use the SOAP headers that are listed in the following table.
|
Header |
Element |
Description |
|---|---|---|
|
Impersonation |
Identifies the user whom the client application is impersonating. This is applicable to a request. |
|
|
RequestVersion |
Identifies the schema version for the operation request This is applicable to a request. |
|
|
ServerVersion |
Identifies the version of the server that responded to the request. This is applicable to a response. |
The following example of a ConvertId request shows how to convert from an EWS identifier to an Outlook Web App identifier.
The RequestServerVersion element in the SOAP header must be set to Exchange2007_SP1 or later for this operation to work.
|
Note
|
|---|
|
The item identifier has been shortened to preserve readability. |
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types">
<soap:Header>
<t:RequestServerVersion Version="Exchange2010"/>
</soap:Header>
<soap:Body>
<ConvertId xmlns="http://schemas.microsoft.com/exchange/services/2006/messages"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types"
DestinationFormat="OwaId">
<SourceIds>
<t:AlternateId Format="EwsId" Id="AAMkAGZhN2IxYTA0LWNiNzItN="
Mailbox="user1@example.com"/>
</SourceIds>
</ConvertId>
</soap:Body>
</soap:Envelope>
The following example shows a successful response to a ConvertId request. This response example contains an Outlook Web App identifier.
|
Note
|
|---|
|
The Outlook Web App identifier has been shortened to preserve readability. |
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<t:ServerVersionInfo MajorVersion="8" MinorVersion="1"
MajorBuildNumber="191" MinorBuildNumber="0"
Version="Exchange2010"
xmlns:t="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<ConvertIdResponse xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<ResponseMessages>
<ConvertIdResponseMessage ResponseClass="Success">
<ResponseCode>NoError</ResponseCode>
<AlternateId xsi:type="t:AlternateIdType" Format="OwaId" Id="RgAAAAAS2%2"
Mailbox="user@example.com" />
</ConvertIdResponseMessage>
</ResponseMessages>
</ConvertIdResponse>
</soap:Body>
</soap:Envelope>
The following example shows the response to a request that contains the wrong type of identifier format.
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Header>
<ServerVersionInfo MajorVersion="8" MinorVersion="1"
MajorBuildNumber="206" MinorBuildNumber="0"
Version="Exchange2010"
xmlns="http://schemas.microsoft.com/exchange/services/2006/types" />
</soap:Header>
<soap:Body>
<ConvertIdResponse xmlns="http://schemas.microsoft.com/exchange/services/2006/messages">
<ResponseMessages>
<ConvertIdResponseMessage ResponseClass="Error">
<MessageText>Id is malformed.</MessageText>
<ResponseCode>ErrorInvalidIdMalformed</ResponseCode>
<DescriptiveLinkKey>0</DescriptiveLinkKey>
</ConvertIdResponseMessage>
</ResponseMessages>
</ConvertIdResponse>
</soap:Body>
</soap:Envelope>
|
Date |
Description |
|---|---|
|
April 16, 2013 |
Added information about Outlook Web App identifier applicability for Exchange 2013 and Exchange Online. |
|
July 16, 2012 |
Initial publication |
