• Article

ConvertId Operation

Last modified: September 06, 2011

Applies to: Exchange Server 2007 | Exchange Server 2010

In this article
SOAP Headers
ConvertId Request Example
ConvertId Response Example
ConvertId Error Response Example

The ConvertId operation converts item and folder identifiers between formats that are accepted by Microsoft Exchange Server 2010.

Important

The Exchange Web Services identifier format changed between the initial release version of Microsoft Exchange Server 2007 and Exchange Server 2007 Service Pack 1 (SP1). Exchange 2010 uses the same identifier format that Exchange 2007 SP1 uses.

Note

The ConvertId operation supports impersonation starting with Exchange 2010 SP2.

You can convert the following identifiers by using this operation:

  • The identifier format for Exchange Web Services in the initial release version of Exchange 2007. This is represented by the EwsLegacyId enumeration value in the IdFormatType enumeration.

  • The identifier format for Exchange Web Services 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 Microsoft Office 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.

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.

SOAP Headers

The ConvertId operation can use the SOAP headers that are listed and described in the following table.

Header

Element

Description

Impersonation

ExchangeImpersonation

Identifies the user whom the client application is impersonating.

RequestVersion

RequestServerVersion

Identifies the schema version for the operation request.

ServerVersion

ServerVersionInfo

Identifies the version of the server that responded to the request.

ConvertId Request Example

Description

The following example of a ConvertId request shows how to convert from an Exchange Web Services identifier to an Outlook Web App identifier.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://schemas.xmlsoap.org/soap/envelope/"
               xmlns:t="https://schemas.microsoft.com/exchange/services/2006/types">
  <soap:Header>
    <t:RequestServerVersion Version="Exchange2010"/>
  </soap:Header>
  <soap:Body>
    <ConvertId xmlns="https://schemas.microsoft.com/exchange/services/2006/messages"
               xmlns:t="https://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>

Comments

The RequestServerVersion element in the SOAP header must be set to Exchange2007_SP1 or later for this operation to work. The item identifier has been shortened to preserve readability.

ConvertId Response Example

Description

The following example of a ConvertId response shows a successful response to a ConvertId request. This response example contains an Outlook Web App identifier.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://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="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <ConvertIdResponse xmlns="https://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>

Comments

The Outlook Web App identifier has been shortened to preserve readability.

ConvertId Error Response Example

Description

The following example shows the response to a request that contains the wrong type of identifier format.

Code

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="https://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="https://schemas.microsoft.com/exchange/services/2006/types" />
  </soap:Header>
  <soap:Body>
    <ConvertIdResponse xmlns="https://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>