Account Upgrade Service

galleyarcherySoftware and s/w Development

Oct 29, 2013 (3 years and 11 months ago)

86 views


AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

1

©

2006

Yahoo!

I
nc.

All

Rights

Reserved.

Confidential

and

Proprietary.


Account Upgrade Service

This document describes the Advertiser Web Services (AWS) DTC
-
XML operations that upgrade current
advertiser accounts to the new ad serving model.

Use the Account Upgrade service to upgrade an existing DTC/DTC
-
XML account to work wi
th the new ad
serving model.



Use DTC
-
XML to upgrade accounts one at a time. These upgrades may be performed one at a time.



Use the DTC Dashboard to upgrade multiple advertiser accounts at once.

There are two steps for the account upgrade

Preview and Upg
rade:



An account that is in Preview mode can be:



accessed via DTC
-
XML



changed via DTC
-
XML



viewed in read
-
only mode via the new Enterprise Web Services Marketing API. The Marketing API will
show the account as it will be after the upgrade is complete.



When
in Preview mode, any changes made in DTC
-
XML will not be reflected in the Marketing API for the
account until after account is upgraded.



An account that has been upgraded actually is a "new" account, for the new ad serving and delivery platform.
Once an a
ccount has been upgraded the advertiser or account manager:



may access the original account's listings as read
-
only objects via DTC
-
XML



may access the original account's performance reports as read
-
only objects via DTC
-
XML



may make changes to the live, u
pgraded account via the Marketing API only.

An advertiser with multiple accounts in preview mode can selectively upgrade accounts.

The operations described in this chapter are listed in
Upgra
de Operations


.



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

2

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.



Table

1

Upgra
de Operations



Operation

Description

GetAccountUpgradeStatus

Use this to get the status of upgrade for a specified account

ActivateAccountUpgrade

Use this to commit account to the new model. After you
execute this operation on your accou
nt, you will be restricted
to read
-
only commands in DTCXML.

GetMasterAccountIdForUpgradedAccount

Use this to retrieve the MasterAccountID of an account in
preview or upgrade status. The MasterAccountID is needed to
access the new upgraded account via the
Enterprise Web
Services Marketing API.

GetReport (MapListingIdToUpgradedId)

Use this report to retrieve a list of all campaign, ad group,
and keyword objects created when your account was
upgraded to the new Sponsored Search application. (Note
that each a
d group created during the upgrade process will
contain only one ad.)





AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

3

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


1

GetAccountUpgradeStatus

Use GetAccountUpgradeStatus to check the upgrade status for a specified account.

GetAccountUpgradeStatus behavior

Success

Response

When the GetAccountUpgradeS
tatus operation succeeds, Advertisers will see a upgrade status message on the
specified account.

The possible status messages are:

Not Upgraded

The account has not been upgraded. The account is
still in the DTC/DTCXML only.

Preview In Progress

The accoun
t and corresponding account information
is being moved to new model for preview purposes.

Preview

The account is now available for preview on the
new system

Upgrade In Progress

The account is in the process of being upgraded to
the new system permanentl
y.

Upgraded and Activated

The account is live in new model and users cannot
make modifications to their account on DTCXML

Status Pending

The account will rolled back to old system.


Failure

Response

When GetAccountUpgradeStatus operation is NOT successf
ul, the user does not see the status message for their
specified account. The response
success
attribute gets set to
false
, and the
reason
attribute contains an error
message as to why the operation failed.



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

4

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


GetAccountUpgradeStatus examples

The following is
an example
GetAccountUpgradeStatus
request:

<?xml version="1.0" encoding="UTF
-
8"?>


<DTCRequest xmlns:xs="http://www.w3.org/2001/XMLSchema
-
instance"


xs:schemaLocation="urn:/ows/aws/1.2 https://x
-
secure.overture.com/schema/dtc


/1.2/dtc_request.xsd" xml
ns="urn:/ows/aws/1.2" username=""


password="" key="123456789">


<Actions accountId="123456789" >


<GetAccountUpgradeStatus/>


</Actions>

</DTCRequest>

The following is an example GetAccountUpgradeStatus response:

<?xml version="1.0" encoding="UTF
-
8
"?>


<DTCResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
instance"

xsi:schemaLocation="urn:/ows/aws/1.2 https://x
-
secure.overture.com/schema/dtc

/1.2/dtc_response.xsd" xmlns="urn:/ows/aws/1.2" success="true">


<ActionsResponse accountId="123456789">


<GetAccountUpgradeStatusResponse success="true"


upgradeStatus="Not Upgraded" />


</ActionsResponse>

</DTCResponse>



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

5

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


2

ActivateAccountUpgrade

Use ActivateAccountUpgrade to complete the upgrade process and have the account upgraded permanently to the
new model. Once account has finished upgrading and has been activated, users will no longer be able to make
modifications to their accounts on DTC
-
XML.

ActivateAccountUpgrade behavior

Success

Response

When ActivateAccountUpgrade operation succeeds, the acc
ount gets moved to the new system permanently. The
response returns a message acknowledging this request.

Failure

Response

When the ActivateAccountUpgrade operation is NOT successful, the account does not get upgraded, the response
success attribute is fal
se, and the reason attribute contains an error message as to why the operation failed.



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

6

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


ActivateAccountUpgrade examples

The following is an example ActivateAccountUpgrade request:


<?xml version="1.0" encoding="UTF
-
8"?>


<DTCRequest xmlns:xs="
http://www.w3.org/2001/XMLSchema
-
instance
" xs:schemaLocation="urn:/ows/aws/1.2
https://x
-
secure.overture.com/schema/dtc/1.2/dtc_request.xsd
" xmlns="urn:/ows/aws/1.2" username=""
password="" key="123456789">


<A
ctions accountId="123456789" >


<ActivateAccountUpgrade/>


</Actions>

</DTCRequest>


The following is an example ActivateAccountUpgrade success response:

<?xml version="1.0" encoding="UTF
-
8"?>


<DTCResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
i
nstance"


xsi:schemaLocation="urn:/ows/aws/1.2 https://x
-
secure.overture.com/schema/dtc


/1.2/dtc_response.xsd" xmlns="urn:/ows/aws/1.2" success="true">


<ActionsResponse accountId="123456789">


<ActivateAccountUpgradeResponse success="true"


mes
sage=”Account 123456789

Upgrade in Progress” >


</ActivateAccountUpgradeResponse>


</ActionsResponse>

</DTCResponse>

The following are example ActivateAccountUpgrade error responses:


<?xml version="1.0" encoding="UTF
-
8
" ?>

-
<
http://app19oc2qa4.ysm.oc2.yahoo.com:6450/index.jhtml?_DARGS=/index.jhtml#
#>

<DTCResponse
xmlns:xsi="
http://www.w3.org/2001/XMLSchema
-
instance
" xsi:schemaLocation="urn:/ows/aws/1.2
https://x
-
secure.overture.com/schema/dtc/1.2/dtc_response.xsd
" xmlns="urn:/ows/aws/1.2" success="true">

-
<
http://app19oc2qa4.ysm.oc2.yahoo.com:6450/index.jhtml?_DARGS=/index.jhtml#
#>

<ActionsResponse
accountId="123456789">

<ActivateAccountUpgradeResponse success="false" reason="This account is not ready for upgrade at this
time" />

</ActionsResponse>

</DTCResponse>




<?xml version="1.0" encoding="UTF
-
8" ?>

-
<
http://app19oc2qa4.ysm.oc2.yahoo.com:6450/index.jhtml?_DARGS=/index.jhtml#
#>

<DTCR
esponse
xmlns:xsi="
http://www.w3.org/2001/XMLSchema
-
instance
" xsi:schemaLocation="urn:/ows/aws/1.2
https://x
-
secure.overture.com/schema/dtc/1.2/dtc_response.xsd
" xmlns="urn:/ows/aws/1.2" success="t
rue">

-
<
http://app19oc2qa4.ysm.oc2.yahoo.com:6450/index.jhtml?_DARGS=/index.jhtml#
#>

<ActionsResponse
accountId="123456789">

<ActivateAccountUpgradeResponse succes
s="false" reason="Error4444: Account cannot be upgraded at this
time; Update status is pending" />

</ActionsResponse>

</DTCResponse>




<?xml version="1.0" encoding="UTF
-
8" ?>

-
<
http://appmud27.ysm.mud.yahoo.com:6450/index.jhtml?_DARGS=/index.jhtml#
#>

<DTCResponse


AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

7

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


xmlns:xsi="
http://www.w3.org/2001/XMLSchema
-
instance
" xsi:schemaLocation="urn:/ows/aws/1.2
https
://x
-
secure.overture.com/schema/dtc/1.2/dtc_response.xsd
" xmlns="urn:/ows/aws/1.2" success="true">

-
<
http://appmud27.ysm.mud.yahoo.com:6450/index.jhtml?_DARGS=/index.jh
tml#
#>

<ActionsResponse
accountId="123456789">

<ActivateAccountUpgradeResponse success="false" reason="error502 : This account has been upgraded and is
accessible only as read
-
only via DTCXML" />

</ActionsResponse>

</DTCResponse>



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

8

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


3

GetMasterAccountIdFor
UpgradedAccount

Use GetMasterAccountIdForUpgradedAccount to retrieve the MasterAccountId which contains your upgraded
account in the new Sponsored Search. For more information on Master Accounts, please see the Enterprise Web
Services Marketing API docume
ntation.

GetMasterAccountIdForUpgradedAccount behavior

Success

Response

When GetMasterAccountIdForUpgradedAccount operation succeeds, the Master Account ID is returned.

Failure

Response

The operation will fail if the account is not yet in one of the follo
wing modes:



Preview In Progress



Preview



Upgrade In Progress



Upgraded and Activated

In this case, the response success attribute is false, and the reason attribute contains an error message as to why the
operation failed.



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

9

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


GetMasterAccountIdForUpgradedAccou
nt examples

The following is an example GetMasterAccountIdForUpgradedAccount request:


<?xml version="1.0" encoding="UTF
-
8"?>


<DTCRequest xmlns:xs="http://www.w3.org/2001/XMLSchema
-
instance"


xs:schemaLocation="urn:/ows/aws/1.2

https://x
-
secure.overtur
e.com/schema/dtc/1.2/dtc_request.xsd"

xmlns="urn:/ows/aws/1.2" username="" password="" key="">

<Actions accountId="123456789">

<GetMasterAccountIdForUpgradedAccount />

</Actions>

</DTCRequest>


The followin
g is an example GetMasterAccountIdForUpgradedAccount success response:


<?xml version="1.0" encoding="UTF
-
8"?>

<DTCResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
instance"

xsi:schemaLocation="urn:/ows/aws/1.2

https://x
-
secure.overture.com/schema/
dtc/1.2/dtc_response.xsd"

xmlns="urn:/ows/aws/1.2" success="true">

<ActionsResponse accountId="123456789">

<GetMasterAccountIdForUpgradedAccountResponse success="true"

masterAccountId=”12345”>

<GetMasterAccountIdForUpgradedAccount
Response>

</ActionsResponse>

</DTCResponse>


The following is an example GetMasterAccountIdForUpgradedAccount failure response:


<?xml version="1.0" encoding="UTF
-
8"?>


<DTCResponse xmlns:xsi="http://www.w3.org/2001/XMLSchema
-
instance"

xsi:schemaLoca
tion="urn:/ows/aws/1.2

https://x
-
secure.overture.com/schema/dtc/1.2/dtc_response.xsd"

xmlns="urn:/ows/aws/1.2" success="true">

<ActionsResponse accountId="123456789">

<GetMasterAccountIdForUpgradedAccount Response success="false"

reas
on="Account has not been upgraded yet" >

<GetMasterAccountIdForUpgradedAccountResponse>

</ActionsResponse>

</DTCResponse>


AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

10

©

2006

Yahoo!

I
nc.

All

Rights

Reserved.

Confidential

and

Proprietary.


4

GetReport
-
MapListingIdToUpgradedId

Use the new report type MapListingIdToUpgradedId with GetReport to retrieve a list
ing
of the IDs of all
campaign, ad group, and keyword objects created when your account was upgraded to the new Sponsored Search
application.

Get Report behavior

This TechNote will not attempt to describe in detail the usage of GetReport. For general usage
of this operation,
please see the DTC
-
XML User Guide.

Success

Response

When the Get Report operation succeeds, the ID mapping information is returned.

Failure

Response

The operation will fail if the account is not yet in the “Upgraded and Activated” mode
.

In this case, the response success attribute is false, and the reason attribute contains an error message as to why the
operation failed.

The operation will also fail if the report data cannot be completely retrieved during the initial request. However,
in
this instance, the report will continue to run and the results will be cached. You may repeat the report request at a
later time (we recommend waiting at least 30 minutes), and your data will be immediately returned.



AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

11

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


GetReport
-
MapListingIdToUpgradedI
d examples

The following is an example GetReport request:


<?xml version="1.0" encoding="UTF
-
8"?>


<DTCRequest xmlns:xs="
http://www.w3.org/2001/XMLSchema
-
instance
"


xs:schemaLocation="urn:/ows/a
ws/1.2

https://x
-
secure.overture.com/schema/dtc/1.2/dtc_request.xsd"

xmlns="urn:/ows/aws/1.2"

username="" password="" key="">



<Actions accountId="123456789">




<GetReport>




<MapListingIdToUpgradedId />


</GetReport>



</Actions
>

</DTCRequest>



The following is an example GetReport failure response:


<?xml version="1.0" encoding="UTF
-
8"?>


<DTCResponse xmlns:xsi="
http://www.w3.org/2001/XMLSchema
-
instance
"

xsi
:schemaLocation="urn:/ows/aws/1.2
https://x
-
secure.overture.com/schema/dtc/1.2/dtc_response.xsd
"

xmlns="urn:/ows/aws/1.2" success="true">


<ActionsResponse accountId="123456789">


<GetReportResponse success="false"

reason="Your report contains a
large amount of data and is
being processed. Please wait 30 minutes and submit your request again."

>

</GetReportResponse>


</ActionsResponse>

</DTCResponse>





AWS

DTC
-
XML:

Technical

Note

Account

Upgrade

Service

12

©

2006

Yahoo!

Inc.

All

Rights

Reserved.

Confidential

and

Proprietary.


The following is an example GetReport success response:


<?xml version="1.0
" encoding="UTF
-
8"?>


<DTCResponse xmlns:xsi="
http://www.w3.org/2001/XMLSchema
-
instance
"

xsi:schemaLocation="urn:/ows/aws/1.2
https://x
-
secure.overture.com/schema/dtc/1.2/dtc_response.xsd
"

xm
lns="urn:/ows/aws/1.2"
success="true">


<ActionsResponse accountId="123456789">


<GetReportResponse success="true"

>


<MapListingIdToUpgradedIdResponse>


<MapListingIdToUpgradedIdRow listingId="987654321" keywordId="123456789
1"

adGroupId="5555555" campaignId="111111"/>


<MapListingIdToUpgradedIdRow listingId="987654322" keywordId="1234567892"

adGroupId="6666666" campaignId="111111"/>


</MapListingIdToUpgradedIdResponse>


</GetReportResponse>


</Action
sResponse>


</DTCResponse>