Sitecore Serialization Guide

Transcription

1 Sitecre CMS Sitecre Serializatin Guide Rev: 4 February 2011 Sitecre CMS Sitecre Serializatin Guide An administratr's guide t serializing cntent in Sitecre

2 Sitecre CMS Table f Cntents Chapter 1 Intrductin... 3 Chapter 2 Serializatin Serializatin Overview Serializatin Access Pints Serializatin Flder Enabling the Develper Tab Serializing an Item r a Tree f Items String Text Files Serializing Items Serializing Security Entities Updating an Item, a Tree f Items r a Database Updating Rules Updating Items r Database Reverting an Item, a Tree f Items, r a Database Reverting Rules Reverting Items Serializing Items Using Event Handlers Using the Service Page t Serialize, Update, and Revert a Database Managing a Database Serializing a Precnfigured Set f Items Cnfiguring a Set f Items Serializing a Set f Items Updating a Tree f Items Custmizing Serializatin Using Sitecre Serializatin with a Surce Cntrl System Cnvenience f SVN Usage Integratin with SVN Page 2 f 15

3 Sitecre Serializatin Guide Chapter 1 Intrductin The Sitecre serializatin functinality is designed t help teams f develpers that wrk n the same Sitecre slutin t synchrnize database changes between their individual develpment envirnments, but is als valuable when a single develper wrks n a slutin. Serializatin allws yu t serialize an entire Sitecre database r a series f items in a database t text files. Yu can then use these text files t transfer this database r series f items t anther database r Sitecre slutin. Sitecre serializatin is typically used in cmbinatin with a surce cntrl system t make it easy fr develpers t synchrnize database changes between their lcal databases that they use fr develpment with the added benefit that the surce cntrl system will keep track f database changes and allw yu t cmpare database changes. This dcument describes all the actins that yu can perfrm with Sitecre serializatin. This dcument cntains the fllwing chapters: Chapter 1 Intrductin This intrductin t the dcument. Chapter 2 Serializatin This chapter describes hw t use Sitecre serializatin. Page 3 f 15

4 Sitecre CMS Chapter 2 Serializatin This chapter describes hw t use the Sitecre serializatin functinality t administer and develp a Sitecre CMS slutin. This chapter cntains the fllwing sectins: Serializatin Overview Serializing an Item r a Tree Updating an Item, a Tree f Items r a Database Reverting an Item, a Tree f Items, r a Database Serializing Items Using Event Handlers Using the Service Page t Serialize, Update, and Revert a Database Using Sitecre Serializatin with a Surce Cntrl System Page 4 f 15

5 Sitecre Serializatin Guide 2.1 Serializatin Overview Serializatin allws yu t cnvert a whle database r a series f items in a database t text files. Yu can then use these text files t transfer this database r series f items t anther database r Sitecre slutin. Sitecre prvides three serializatin access pints and all f them use the same general setting in the web.cnfig file Serializatin Access Pints Yu can perfrm serializatin actins in three ways: In the Cntent Editr, yu can manually serialize, update, and revert items. Fr mre infrmatin abut using the Cntent Editr, see the Serializing an Item r a Tree f Items, Updating an Item, a Tree f Items r a Database and Reverting an Item, a Tree f Items, r a Database sectins. Yu can use the Sitecre event handlers t autmatically serialize items. Fr mre infrmatin abut using event handlers, see the Serializing Items Using Event Handlers sectin. Yu can use the Sitecre service page t serialize, update, and revert a whle database. Fr mre infrmatin abut using the service page, see the Using the Service Page t Serialize, Update, and Revert a Database sectin Serializatin Flder When yu serialize, update, r revert items, Sitecre uses nly ne general setting the serializatin flder. This setting cntains the path t the flder in the file system where the text files f the items are stred. By default, Sitecre stres serialized items in the website_rt/data/serializatin flder. T set anther path t the serializatin flder: 1. Open t the website_rt/website/web.cnfig file. 2. In the SerializatinFlder parameter, specify the path t the serializatin flder Enabling the Develper Tab Yu can perfrm all the serializatin actins in the Cntent Editr n the Develper tab. The Develper tab is disabled by default. T enable the Develper tab: 1. Open the Cntent Editr. Page 5 f 15

6 Sitecre CMS Right click n the Cntent Editr ribbn and select Develper. Page 6 f 15

7 Sitecre Serializatin Guide 2.2 Serializing an Item r a Tree f Items When yu serialize an item r a tree f items, Sitecre stres the item hierarchy in text files String Text Files When yu are serializing items, Sitecre creates a separate text file fr each item it prcesses. Sitecre generates the full path t the files: Serializatin Flder \ Database Name \ Path t the item in the Database \ Item Name \ *.item Fr example: D:\CMS640update1\Data\serializatin\master\sitecre\cntent\Hme\Services\Architectual- Services.item Each text file cntains the fllwing infrmatin: Item definitin: versin, ID, path, and s n. Shared fields. Item versins: Versin definitin, including language versin, numbered versin, and revisin number. Nn-shared fields. A serialized item might lk like this: ----item---- versin: 1 id: {7F0A4C0A-083D-4D21-BA63-C3F1051BA6D6} database: master path: /sitecre/cntent/hme/services/architectual-services parent: {58EE5060-FC0B-45D2-883F-7C9C7C6C59C9} name: Architectual-Services master: { } template: {373CAA7B E20-AA C4CE81EA} templatekey: Services Categry ----field---- field: {F7D48A F F73} name: Standard values key: standard values cntent-length: 0 <r /> Each ----field---- sectin in the text file cntains the cntent-length parameter, which cntains the length f the crrespnding item field value Serializing Items In Sitecre, yu can serialize a single item r a series f items. T serialize an item: 1. In the Cntent Editr, select an item that yu want t stre in a text file n the disk. 2. On the Develper tab, in the Serialize grup, click Serialize Item. T serialize an item with all its subitems: 1. In the Cntent Editr, select a parent item that yu want t stre with all its subitems in text frmat n the disk. 2. On the Develper tab, in the Serialize grup, click Serialize Tree. Page 7 f 15

8 Sitecre CMS In ur example we have the fllwing structure f items: When we serialize a tree f items, starting frm the Services item, Sitecre creates the fllwing hierarchy f flders in the file system: Serializing Security Entities Sitecre rev and later versins let yu serialize security entities. The fllwing table describes the serializatin cmmands and the applicatins where yu can perfrm them: Sitecre Applicatin Cmmand Descriptin Strage Flder User Manager Serialize User Serializes the selected user. Serializatin flder Serialize All Users Serializes all the users. / security / dmain name / users / user Revert User Reverts the selected user. name /*.user Serializatin flder Revert All Users Reverts all the users. is set in the Warning: All the users wh are in web.cnfig file. the database but are nt in the file system will be remved. Rle Manager Serialize Rle Serializes the selected rle. Serializatin flder Serialize All Rles Serializes all the rles. / security / dmain name / rles / rle Revert Rle Reverts the selected rle. Page 8 f 15

9 Sitecre Serializatin Guide Sitecre Applicatin Dmain Manager Cmmand Descriptin Strage Flder Revert All Rles Serialize Dmain Users Serialize Dmain Rles Serialize Dmain Users and Rles Revert Dmain Users Revert Dmain Rles Revert Dmain Users and Rles Reverts all the rles. Warning: All the rles that are in the database but are nt in the file system will be remved. Serializes all the users in the selected dmain. Serializes all the rles in the selected dmain. Serializes all the users and rles in the selected dmain. Reverts all the users in the selected dmain. Warning: all users frm the selected dmain which are nt in the file system will be remved. Reverts all the rles frm the selected dmain. Warning: all rles frm the selected dmain which are nt in the file system will be remved. Reverts all the users and rles frm the selected dmain. Warning: all users and rles frm the selected dmain which are nt in the file system will be remved. name /*.rle Serializatin flder is set in the web.cnfig file. Page 9 f 15

10 Sitecre CMS Updating an Item, a Tree f Items r a Database Sitecre lets yu update items with the infrmatin that is stred in the text files in the file system. Fr mre infrmatin abut cnverting Sitecre items int text files, see the Serializing an Item r a Tree f Items sectin Updating Rules When yu are updating items, Sitecre merges the changes frm the text files with the current database items accrding t the fllwing rules: If an item r an item versin exists in the file system, but there is n such item r item versin in the database, Sitecre adds it t the database. If an item r an item versin exists in the database but there is n such item r item versin in the file system, Sitecre des nt remve it frm the database. Sitecre des nt verwrite the fllwing infrmatin abut the item: Item name Template ID Origin ID Parent ID If an item versin that is laded frm the file system cntains the same number and language versin, Sitecre nly verwrites the existing item versin if the date in the new item in the Updated field is later in the current ne Updating Items r Database In Sitecre, yu can update items r a whle database. T update an item frm the text file: 1. In the Cntent Editr, select the item that yu want t update. 2. On the Develper tab, in the Serialize grup, click Update Item. T update an item with all its subitems frm the file system: 1. In the Cntent Editr, select the parent item that yu want t update with all its subitems. 2. On the Develper tab, in the Serialize grup, click Update Tree. T update the whle database: 1. In the Cntent Editr, select any item. 2. On the Develper tab, in the Serialize grup, click Update Database. Page 10 f 15

11 Sitecre Serializatin Guide 2.4 Reverting an Item, a Tree f Items, r a Database Sitecre lets yu rll back changes and revert items. When yu are reverting items Sitecre lads the items frm the file system and verwrites any changes. This prcedure lets yu bring the database t the exactly same state as it is in the file system Reverting Rules When yu are reverting items Sitecre lads cntent frm the file system t the database accrding t the fllwing rules: If an item r an item versin exists in the database but there is n such item r item versin in the file system, Sitecre deletes it frm the database. If an item r an item versin exists in the file system but there is n such item r item versin in the database, Sitecre adds it t the database. If an item r an item versin differs frm the crrespnding ne in the file system, Sitecre verwrites it Reverting Items In Sitecre yu can revert items and a whle database. T revert an item: 1. In the Cntent Editr, select the item that yu want t revert. 2. On the Develper tab, in the Serialize grup, click Revert Item. T revert an item and all its subitems: 1. In the Cntent Editr, select the parent item that yu want t revert with all its subitems. 2. On the Develper tab, in the Serialize grup, click Revert Tree. T revert the whle database: 1. In the Cntent Editr, select any item. 2. On the Develper tab, in the Serialize grup, click Revert Database. Page 11 f 15

12 Sitecre CMS Serializing Items Using Event Handlers Yu can use Sitecre event handlers t autmatically save any database changes t the file system. By default, serializatin event handlers are disabled. T enable event handlers add the fllwing strings t the web.cnfig file: <cnfiguratin> <sitecre> <events> <event name="item:saved"> <handler type="sitecre.data.serializatin.itemhandler, Sitecre.Kernel" methd="onitemsaved"/> </event> <event name="item:deleted"> <handler type="sitecre.data.serializatin.itemhandler, Sitecre.Kernel" methd="onitemdeleted"/> </event> <event name="item:mved"> <handler type="sitecre.data.serializatin.itemhandler, Sitecre.Kernel" methd="onitemmved"/> </event> <event name="item:versinremved"> <handler type="sitecre.data.serializatin.itemhandler, Sitecre.Kernel" methd="onitemversinremved"/> </event> </events> </sitecre> </cnfiguratin> Nte Sitecre event handlers autmatically save any changes in Sitecre items t the file system and this is why we recmmend using event handlers with a revisin cntrl system. Page 12 f 15

13 Sitecre Serializatin Guide 2.6 Using the Service Page t Serialize, Update, and Revert a Database Yu can serialize, update, and revert a whle database withut using the Cntent Editr. The Sitecre service page lets yu perfrm any serializatin actins n the whle database Managing a Database Yu can use the Sitecre service page t manage a database. T use the service page t serialize, update, r revert a whle database: 1. In yur brwser s address bar type: 2. On the Lg int Sitecre page enter the username (dmain\user_name) and passwrd and then click Lgin. 3. On the Serialize and revert databases page, in the Select database sectin, select ne r mre databases that yu want t serialize, update, r revert. 4. Select Serialize selected databases, Update selected databases, r Revert selected databases depending n the actin that yu want t perfrm n the database Serializing a Precnfigured Set f Items Yu can serialize nt nly the whle database but a precnfigured set f items n the serializatin service page Cnfiguring a Set f Items Yu can specify the predefined set f items as XML ndes in the web.cnfig file r in any included cnfiguratin files using include and exclude entries. The Include entry defines the paths t the items that will be serialized including all their subitems. The Include entry can use the fllwing attributes: database the database name. path the path t the rt item. The Exclude entry defines the items that will nt be serialized. The Exclude entry can use the fllwing attributes: path the path t the item. id the item ID. templateid the template ID f the item. template the template name f the item. In this example, we serialize all the subitems f the Cntent item in the Master database except fr the items under the Hme item and thse items that are based n the Sample item template: <?xml versin="1.0" encding="utf-8"?> <sitecre> <serializatin> <default> <include database="master" path="/sitecre/cntent"> <exclude path="/sitecre/cntent/hme"/> <exclude template="sample item"/> </include> </default> </serializatin> Page 13 f 15

14 Sitecre CMS </sitecre> </cnfiguratin> Serializing a Set f Items When yu have cnfigured a set f items yu can serialize it. T serialize a precnfigured set f items: 1. In yur brwser s address bar type: 2. On the Sitecre Lg in page, enter the username (dmain\user_name) and passwrd and then click Lgin. 3. On the Serialize and revert databases page, in the Serialize databases sectin, click Serialize precnfigured Updating a Tree f Items The Sitecre serializatin service page lets yu update a tree f items withut using the Cntent Editr. T update a tree f items: 1. In yur brwser s address bar type: 2. On the Sitecre Lg in page, enter the username (dmain\user_name) and passwrd and then click Lgin. 3. On the Serialize and revert databases page, in the Update sectin, enter the path t the parent item in the file system. We recmmend cpying this path frm Windws Explrer. The path might lk like this: master\sitecre\cntent\hme\services 4. Click Update specific path Custmizing Serializatin Yu can custmize the serializatin service page t make it wrk as yu need. Use the fllwing classes and namespaces t custmize serializatin: Sitecre.Data.Serializatin.Manager this is the central class f Sitecre serializatin that prvides the API fr all the peratins. Sitecre.Data.Serializatin.PathUtils this class cntains methds fr mapping item paths t the serializatin tree and cnverting abslute paths int item paths. Sitecre.Data.Serializatin.ObjectMdel this namespace cntains classes that manipulate the data in serializatin files. Sitecre.Data.Serializatin.Presets this namespace cntains classes that are respnsible fr the serializatin presets. Page 14 f 15

15 Sitecre Serializatin Guide 2.7 Using Sitecre Serializatin with a Surce Cntrl System As Sitecre serializatin lets yu cnvert items int text files yu can use a surce cntrl system, fr example Subversin (SVN), t manage this data. This is very imprtant when a Sitecre slutin is develped by a team f develpers Cnvenience f SVN Usage Using Sitecre serializatin with SVN gives yu the fllwing advantages: Database state is stred in a central lcatin in the surce cde repsitry. Database files are n lnger a critical cmpnent because yu can restre any item versin frm SVN. SVN stres the cntent as plain text and yu can retrieve it withut any special tls. SVN tracks all the item mdificatins: SVN is respnsible fr slving any cnflicts that can ccur when tw peple mdify the same item simultaneusly. Yu can use the SVN Blame cmmand t shw the authr and revisin infrmatin in-line fr the specified files Integratin with SVN T integrate the Sitecre slutin with SVN, fllw this general scenari: 1. Back up the Sitecre items t the file system using serializatin. Fr mre infrmatin abut serializing items, see the Serializing Items sectin. 2. Cpy yur tree f serialized flders int a repsitry using SVN Imprt and SVN Checkut r SVN Add and SVN Cmmit cmmands. 3. Update yur SVN sandbx befre yu start t update Sitecre items with the SVN Update cmmand. Use the SVN Edit Cnflicts cmmand t reslve cnflicts where necessary. 4. Revert the Sitecre database t the latest state. Fr mre infrmatin abut reverting items, see the Reverting Items sectin. 5. Make any changes in the Sitecre items. 6. Serialize the items r use serializatin event handlers t save the mdificatins t the file system. 7. Use the SVN Add cmmand t register the mdificatins in the SVN sandbx r see if there are any unnecessary items. 8. Use the SVN Cmmit t review the changes and cmmit them t the SVN repsitry. If there are any missing items in the SVN cmmit list, it means that the items have been deleted frm the database but are still registered in SVN. Use the SVN Delete cmmand t delete them frm the sandbx r the SVN Revert and SVN Update cmmands t restre the deleted files and flders. Page 15 f 15