DocumentReaderGetProperties Method (ConnectionId, SessionId, DocumentId, String, Int32) Content Studio 5.7 SDK
Content Studio Web Content Management System

[This is preliminary documentation and is subject to change.]

Returns selected properties of a Content Studio document depending on the document version.

Namespace: ContentStudio.Document
Assembly: CSServer5 (in CSServer5.dll) Version: 5.7.5016.0 (5.7.5016.0)
Syntax

public string GetProperties(
	ConnectionId connectionId,
	SessionId sessionId,
	DocumentId documentId,
	string[] properties,
	int versionNumber
)

Parameters

connectionId
Type: ContentStudioConnectionId
A value that identifies the web site
sessionId
Type: ContentStudio.SecuritySessionId
A value that identifies the user's session. This value usually originates from a call to OpenSession(ConnectionId).
documentId
Type: ContentStudio.DocumentDocumentId
The document to read properties for
properties
Type: SystemString

An array of names of the properties to be read. These names are not case-sensitive.

Currently (CS 5.4) only a limited number of document properties are versioned. When asking for a valid property that is not listed below, the value in the dbo.tbl_elements table is returned. This might not be the proper value that a specific version of the document have. However the returned property values are correct when the draft or the currently approved version is requested.

A list of versioned property names in CS 5.4
PropertyComment
Marking -
VirtualPath -
DocumentName -
BodyProperties -
PublishDate -
ArchiveDate -
StatusIntonly the flag value 0x1 (Published) is versioned
versionNumber
Type: SystemInt32
The version of the document whose properties should be returned.
ValueMeaning
-2Returns the draft. If no draft exists the currently approved content is returned.
-1Returns the draft. If no draft exists a ContentStudio.CSException is thrown.
0Returns the currently approved content. If no approved content exists a ContentStudio.CSException is thrown
Any existing version number Returns the content of the specified version.

Return Value

Type: String
XML with the returned properties as attributes.
<root>
  <status>0</status>
  <statustext>Success</statustext>
  <document PROPERTY1="VALUE1" PROPERTY2="VALUE2" />
</root>

The PROPERTY is the name of the property to read and the VALUE is the found value. You will find one attribute for each property you requested. The casing of these attribute names are identical to the casing of the passed in names and the attributes will be ordered in the same order as the order in the passed in list.

Exceptions

ExceptionCondition
CSExceptionA business rule was violated in the underlying Content Studio database
CSPermissionDeniedExceptionThe caller has no permission to perform the requested action
CSInvalidSessionExceptionThe session is invalid
CSInvalidParameterExceptionA parameter has an invalid value
CSDocumentNotFoundExceptionThe document could not be found
SqlExceptionAn error occurred when executing the command against the Content Studio database
ArgumentNullExceptionproperties parameter is null - or - one of the property names is null
ArgumentOutOfRangeExceptionThe properties parameter is an empty array
CSException
  • 1821 - No writable content exists. This exception can be thrown when versionNumber is -1.
  • 1830 - There is currently no approved content. This exception can be thrown when versionNumber is 0.
  • 1829 - The requested version could not be found. This exception can be thrown only if a specific version is requested (versionNumber is > 0).
Content Studio permissions

READ permission on the document is required.
Remarks

This method was introduced in Content Studio version 5.4.

You can get the value of any columns in the [dbo].[tbl_elements] table in a Content Studio database.

This method was introduced in Content Studio 5.4 and adds the versionNumber parameter to be able to read property values from the [dbo].[tbl_elements] table that are subject to extended versioning.

Note Note
Internally, the properties are fetched by the use of a dynamically, paramentarized sql query where all passed in property names are checked individually against the database. For this reason asking for a large number of properties can be time consuming and will result in may small database calls. For this reason you should try to limit the number of properties as much as possible. If you need to read a lot of properties consider using the CSDocumentInformation class instead which provides an object oriented way of reading document properties. However, for a very limited number of properties this method can be very efficient.

Caution note Caution
A few columns in the [dbo].[tbl_elements] table have property names that differ from the underlying column names.
To read columnUse property name
ElementNameDocumentName
ElementIDDocumentID
ParentElementIDParentDocumentID
If you attempt to use the original column names above an exception is thrown.


Common document properties
Property nameMeaning
DocumentIDThe identifier of the document
ParentDocumentIDThe identifier of the document that acts as the parent document.
UserIDIdentifies the id of the user that created the document.
CategoryIDIdentifies the category of the document
FileNameThe full pathname of the document
DocumentNameThe document's name
CreatedDateThe document's creation date
PublishDateThe document's publish date
ArchiveDateThe document's archive date
MarkingA short list of words that can be used to classify the document
RevisionThe version number of the approved version of the document. Zero indicates that the document has never been approved.
ContentTypeThe content type string. e.g. 'text/html'
ModuleName This property is retrieved from the document's category and determines (together with the StatusInt property the type of document.

The following module names are available:

ModuleNameDescription.
ActiveScriptingThe category contains Active Scripting components.
DokumentThe category contains regular documents or text documents, with or without meta data.
EditTemplateThe category contains Editing templates.
FilThe category contains uploaded files
FormatmallThe category contains templates (for fragments of a page).
HelsidesmallThe category contains document templates.
PresentationTemplateThe category contains presentation templates.
XMLDocumentThe category contains EPT documents.

Use GetDocumentType method to determine the type of document.

StatusInt / InheritedStatusIntThe InheritedStatusInt virtual property is new in CS 5.4

A bitmasked value that indicates the status of the document.

When requesting the property InheritedStatusInt, these flags are combination of values from the document, its category and the category module.

These flags can be combination of the following hexadecimal values and meaning:

ValueDescription
0x00000001Can be published
0x00000004Can have version history
0x00000008Source code preservation
0x00000010Is an Html template type
0x00000020Is in the recycling bin
0x00000040Is protected by the system
0x00000080Workflow: for authoring
0x00000100Workflow: authored
0x00000200Linkable (no impact)
0x00000800Is on workflow / versioning
0x00001000Is a plain text document
0x00002000Does not have meta data
0x00004000Has been rejected
0x00008000Is a binary, uploaded file
0x00040000Is an edit template
0x00080000Is a presentation template
0x00200000Recently approved (for subscription services only)
0x00400000Workflow: is for review
0x00800000Workflow: has been reviewed
0x01000000Workflow: for approval
0x02000000Workflow: rejected by workflow server

Note When requesting the property StatusInt and in Content Studio version earlier than 5.3 only the status directly applied to the document is returned. These status values are:

ValueDescription
0x00000001Can be published
0x00000020Is in the recycling bin
0x00000080Workflow: for authoring
0x00000100Workflow: authored
0x00000200Draft exists
0x00000800Is on workflow / versioning
0x00004000Has been rejected
0x00040000Is an edit template
0x00080000Is a presentation template
0x00200000Recently approved (for subscription services only)
0x00400000Workflow: is for review
0x00800000Workflow: has been reviewed
0x01000000Workflow: for approval
0x02000000Workflow: rejected by workflow server
FilesizeThe size of the document on disk.
BodyPropertiesA string containing attibute data that appears in the BODY section of the document
DeletedByIDThe id of the user that threw the document in the recycling bin.
SentForApprovalByIDThe id of the user that has sent the document for versioning
ModifiedDateThe document's last modified date
RejectedByIDThe id of the user that rejected the document.
RejectedDateIndicates when the document was rejected
DeletedDateIndicates when the document was thrown into the recycling bin
SentForApprovalDateIndicates when the document was sent for approval
ChkOutByIDThe id of the user that currently has the document checked out
AppCIDA GUID that identifies the currently approved content of the document.
ETForPTIDIf the document is a presentation template, this property is the identifier of the edit template in use
EncodingThe endoding of the document
WFStatusTextThe workflow status text
ImagesAvailableFor image files only. This boolean parameter indicates if adjusted images has been created
TreeIDIndicates the top root document in a document hierarchy.
ElementLevelIndicates the order of the document within a document hierarchy. This value can be zero to let Content Studio decide the order.
UsePublishDate(0 or 1) Indicates whether this document uses the publish date functionality.
PublishStatusAn integer value that specifies the publish status value for this document.
This property is new in CS 5.1
Possible values and meaning:
0Exists only as a draft
1Waiting to be published.
2Is published.
3Deleted in the recycling bin.
4Reserved - not used
5The document has expired.
6Not published (not approved yet) but a former approved content exists.
LastPublishState Gets a value that indicates the calculated publish status of a document. This property can have one of the following values:
ValueMeaning
PThe document is published and "live"
UThe document is not published.
AThe document has been archived.
-Unknown status.
This value is maintained in the background by the DEPRO (Dynamic Event Processor) in Content Studio Service Manager and cannot be 100% trusted. How accurate this value is depends on how soon DEPRO detects a change and how often it queries a site but it is likely that the precision is no better than a few minutes.
This property was introduced in Content Studio version 5.2.
VirtualPath A site-unique path to the document. e.g. the document http://www.company.com/default.aspx?id=12345 could be identified as http://www.company.com/news. In this example the VirtualPath will be news.
This property was introduced in Content Studio version 5.2.
SubStat A document's subscription status. Can be one of the following values and meaning
ValueMeaning
C Indicates that this document can be sent to subscribers the next time it is published or re-published.
N Normal status (default). The document is not subject to subscription.
P Indicates that the document is waiting to be picked up for sending or currently is being sent.
S Indicates that the document will be sent to subscribers at the next possible occation.
F Indicates that the document has been sent out to its subscribers and will not be sent again.
This property corresponds to the DocumentSubscriptionStatus enumeration. Use the SubscriptionStatus property of the DocumentSubscriptionProperties class to read this value.
This property was introduced in Content Studio version 5.2.
Examples

The following code snippet shows how to get some document properties for the approved version of a document with id=4500
int DocumentID = 4500;
DocumentReader DocReader = new DocumentReader();
string xml = DocReader.GetProperties(CS_ConnectionId, 
                                     CS_UserSessionId, 
                                     DocumentID, 
                                     new string[3] {"DocumentName",
                                                    "ParentDocumentID",
                                                    "CreatedDate" }),
                                     0;
//The following Xml is returned
//<root>
// <status>0</status>
// <statustext>Success</statustext>
// <document DocumentName="Content Studio AS Xml Converter" 
//           ParentDocumentID="3644"
//           CreatedDate="2007-01-08T15:59:39.070" />
//</root>
int ParentID = 0;
string Name = "";
DateTime Created = DateTime.MinValue;
//use an XmlReader to the the individual properties returned
using (StringReader sr = new StringReader(xml))
{
  XmlReader XReader = XmlReader.Create(sr);
  if (XReader.ReadToFollowing("document"))
  {
     ParentID = Int32.Parse(XReader.GetAttribute("ParentDocumentID"));
     Name = XReader.GetAttribute("DocumentName");
     Created = DateTime.Parse(XReader.GetAttribute("CreatedDate"));
  }
}
//Write out the data to the web page
Response.Write(String.Format("The document {0} has a parent with id {1} and was created {2}", Name, ParentID, Created));
See Also

Reference