4.2 Service Example

The DOC_INFO service provides a good example of how services, queries, and templates work together. This section covers the following topics:

"DOC_INFO Service Definition"
"DOC_INFO Attributes"
"DOC_INFO Actions"
"DOC_INFO Template"

4.2.1 DOC_INFO Service Definition

The following figures show the DOC_INFO service definition from the IdcHomeDir/resources/core/templates/std_services.htm file:

The following is an example of the DOC_INFO service definition, displayed in a text editor and Web browser.

<@table StandardServices@>
<table border=1><caption><strong>Scripts For Standard Services</strong></caption>
<tr>
    <td>Name</td><td>Attributes</td><td>Actions</td>
</tr>
<tr>
    <td>DOC_INFO</td>
    <td>DocService
        33
        DOC_INFO
        null
        null<br>
        !csUnableToGetRevInfo</td>
    <td>5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2
         3:mapNamedResultSetValues:DOCINFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null
        3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)
        3:getDocFormats:QdocFormats:0:null
        3:getURLAbsolute::0:null
        3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null
        3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null
        3:getWorkflowInfo:WF_INFO:0:null
        3:getDocSubscriptionInfo:QisSubscribed:0:null
        5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)</td>
</tr>
</table>
<@end@>

Surrounding text describes services_example.gif.

4.2.2 DOC_INFO Attributes

The following table describes the attributes of the DOC_INFO service:

Attribute	Value	Description
Service class	DocService	This service is providing information about a content item.
Access level	33	1 = The user requesting the service must have Read permission on the content item. 32 = This service can be executed with the executeService Idoc Script function.
Template page	DOC_INFO	This service uses the DOC_INFO template (doc_info.htm file). The results from the actions will be merged with this template and presented to the user.
Service type	null	This service is not a subservice.
Subjects notified	null	No subjects are affected by this service.
Error Message	!csUnableToGetRevInfo	If this service fails on an English Content Server system, it returns the error message string: Unable to retrieve information about the revision

4.2.3 DOC_INFO Actions

The DOC_INFO service executes the following ten actions:

4.2.3.1 Action 1 Definition and Description

Action 1 takes the following form:

Action 1 - 5:QdocInfo:DOC_INFO:2:!csItemNoLongerExists2
5 : Select cache query action that retrieves information from the database using a query.
QDocInfo : This action retrieves content item information using the QDocInfo query in the query.htm file.
DOC_INFO : The result of the query is assigned to a ResultSet called DOC_INFO and stored for later use.
2 : The Check result non-empty control mask specifies that the query must return a record, or the action fails.
!csItemNoLongerExists2 : If this action fails on an English Content Server system, it returns the error message string:

This content item no longer exists

4.2.3.2 Action 2 Definition and Description

Action 2 takes the following form:

Action 2 : 3:mapNamedResultSetValues:DOCINFO,dStatus,dStatus,dDocTitle,dDocTitle:0:null
3: Java method action specifying a module that is a part of the Java class implementing the service.
mapNamedResultSetValues : This action retrieves the values of dStatus and dDocTitle from the first row of the DOC_INFO ResultSet and stores them in the local data. (This increases speed and ensures that the correct values are used.)
DOC_INFO,dStatus,dStatus,dDocTitle,dDocTitle : Parameters required for the mapNamedResultSetValues action.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.3 Action 3 Definition and Description

Action 3 takes the following form:

Action 3 : 3:checkSecurity:DOC_INFO:0:!csUnableToGetRevInfo2(dDocName)
3 : Java method action specifying a module that is a part of the Java class implementing the service.
checkSecurity : This action retrieves the data assigned to the DOC_INFO ResultSet and evaluates the assigned security level to verify that the user is authorized to perform this action.
DOC_INFO : ResultSet that contains the security information to be evaluated by the checkSecurity action.
0 : No control mask is specified.
!csUnableToGetRevInfo2(dDocName) : If this action fails on an English Content Server system, it returns the error message string:

Unable to retrieve information for '{dDocName}.'

4.2.3.4 Action 4 Definition and Description

Action 4 takes the following form:

Action 4 : 3:getDocFormats:QdocFormats:0:null
3 : Java method action specifying a module that is a part of the Java class implementing the service.
getDocFormats : This action retrieves the file formats for the content item using the QdocFormats query in the query.htm file. A comma-delimited list of the file formats is stored in the local data as dDocFormats.
QdocFormats : Specifies the query used to retrieve the file formats.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.5 Action 5 Definition and Description

Action 5 takes the following form:

Action 5 : 3:getURLAbsolute::0:null
3 : Java method action specifying a module that is a part of the Java class implementing the service.
getURLAbsolute : This action resolves the URL of the content item and stores it in the local data as DocUrl.
blank : This action takes no parameters.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.6 Action 6 Definition and Description

Action 6 takes the following form:

Action 6 : 3:getUserMailAddress:dDocAuthor,AuthorAddress:0:null
3 : Java method action specifying a module that is a part of the Java class implementing the service.
getUserMailAddress : This action resolves the e-mail address of the content item author.
dDocAuthor,AuthorAddress : This action passes dDocAuthor and AuthorAddress as parameters.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.7 Action 7 Definition and Description

Action 7 takes the following form:

Action 7 : 3:getUserMailAddress:dCheckoutUser,CheckoutUserAddress:0:null
3 : Java method action specifying a module that is a part of the Java class implementing the service.
getUserMailAddress : This action resolves the e-mail address of the user who has the content item checked out.
dCheckoutUser,CheckoutUserAddress : This action passes dCheckoutUser and CheckoutUserAddress as parameters.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.8 Action 8 Definition and Description

Action 8 takes the following form:

Action 8 : 3:getWorkflowInfo:WF_INFO:0:null
3 : Java method action specifying a module that is a part of the Java class implementing the service.
getWorkflowInfo : This action evaluates whether the content item is part of a workflow. If the WF_INFO ResultSet exists, workflow information is merged into the DOC_INFO template.
WF_INFO : This action passes WF_INFO as a parameter.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.9 Action 9 Definition and Description

Action 9 takes the following form:

Action 9 : 3:getDocSubscriptionInfo:QisSubscribed:0:null
3 : Java method action specifying a module that is a part of the Java class implementing the service.
getDocSubscriptionInfo : This action evaluates if the current user has subscribed to the content item:
- If the user is subscribed, an Unsubscribe button is displayed.
- If the user is not subscribed, a Subscribe button is displayed.
QisSubscribed : Specifies the query used to retrieve the subscription information.
0 : No control mask is specified.
null : No error message is specified.

4.2.3.10 Action 10 Definition and Description

Action 10 takes the following form:

Action 10 :

5:QrevHistory:REVISION_HISTORY:0:!csUnableToGetRevHistory(dDocName)
5 : Select cache query action that retrieves information from the database using a query.
QrevHistory : This action retrieves revision history information using the QrevHistory query in the query.htm file.
REVISION_HISTORY : The result the query is assigned to a ResultSet called REVISION_HISTORY. The DOC_INFO template loops on this ResultSet to present information about each revision.
0 : No control mask is specified.
!csUnableToGetRevHistory(dDocName) : If this action fails on an English Content Server system, it returns the error message string:

Ubpnable to retrieve revision history for ''{dDocName}.''

4.2.4 DOC_INFO Template

The template page for the DOC_INFO service is the DOC_INFO template. It is important to know what is happening between the files so that you can understand the interactions between the template page and the actions performed in a service.

The definition for the content that the doc_info.htm template contains is located in the IdcHomeDir/components/Folders/resources/std_page.htm file. Code from both files appear in the following markup section:

Markup from the IdcHomeDir/resources/core/templates/doc_info.htm file:

<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<html>
<head>

<$include std_info_html_head_declarations$>

</head>
<$include info_body_def$>
<$include info_page_content$>
</body>
</html>

Markup from the IdcHomeDir/components/Folders/resources/std_page.htm file that defines what will appear in the doc_info.htm template:

<@dynamichtml info_page_content@>
<$include std_page_begin$>
<$include std_header$>
…
<!-- Do a loop on DOC_INFO so that all substitution tags will use DOC_INFO as their first place to find their values.  Otherwise their is confusion between this result set and the REVISION_HISTORY table that comes later.  For example 'dStatus' is a value in both tables-->
<$loop DOC_INFO$>
<$if AllowPrimaryMetaFile and isTrue(AllowPrimaryMetaFile) and
isTrue(dFormat like "*idcmeta*")$>
<$showPrimaryMetaFileFields = "1"$>
<$endif$>
<$include doc_info_notify_data$>

<table border=0 cellpadding=2 cellspacing=0 width=<$docInfoWidth-30$>>
<caption align=top><h4 class=pageTitle><$pageTitle$></caption>
<$include special_checkin_fields1$>
<$include std_revision_label_field$>
<$include std_document_type_field$>
<$include std_document_title_field$>
<$include author_checkin_field$>
<$include std_meta_fields$>
<$include security_checkin_fields$>
<$include checkout_author_info_field$>
<$if IsStagingDoc$>
<$include doc_date_fields$>
<$endif$>
<$fieldName = "dStatus", fieldCaption = "Status"$><$include std_displayonly_field$>
<$if HasOriginal$>
<$fieldName = "dDocFormats", fieldCaption = "Formats"$><$include std_display_field$>
<$endif$>
<$include workflow_list_for_doc$>
<$if HasUrl$>
<$include doc_url_field$>
<$endif$>
<$if HasOriginal and not ClientControlled and not showPrimaryMetaFileFields$>
<$fieldName = "dOriginalName", fieldCaption = "Get Native File"$>
<$if DownloadApplet$>
<$valueStyle="xxsmall", fieldValue = strTrimWs(inc("download_file_by_applet_form_content"))$>
<$else$>
<$fieldValue = strTrimWs(inc("doc_file_get_copy"))$>
<$endif$>
<$if DownloadApplet$><form name=downloadForm><$endif$>
<$include std_displayonly_field$>
<$if DownloadApplet$></form><$endif$>
<$endif$>
<$if IsFailedConversion or IsFailedIndex or IsDocRefinePassthru$>
<$if IsFailedConversion$><$include std_namevalue_separator$><$endif$>
<tr>
<td align=right><span class=errorHighlight>
<$if IsFailedIndex$>Index Error:
<$else$>Conversion Error:
<$endif$></span></td>
<td>
<table>
<tr>
<td><span class=tableEntry>
<$dMessage$>
<$if IsFailedIndex$>
<br>Content has been indexed with Info only.
Resubmit should only be performed if the problem has been resolved.
<$elseif IsDocRefinePassthru$>
<br>Content Refinery failed to convert the content item but released it to the
web by copying the native file.
<$endif$></span></td>
<td><form action="<$HttpCgiPath$>" method="POST">
<input type=hidden name=dID value="<$dID$>">
<input type=hidden name=dDocName value="<$dDocName$>">
<input type=hidden name=IdcService value="RESUBMIT_FOR_CONVERSION">
<input type=submit value= "Resubmit ">
<$if ClientControlled$>
<input type=hidden name=ClientControlled value="DocMan">
<$endif$>
</form></td>
</tr>
</table>
</td>
</tr>
<$if IsFailedConversion$><$include std_namevalue_separator$><$endif$>
<$endif$>
</table>
<$if IsNotSyncRev$>
<table width="100%">
<tr>
<td align=center><span class=errorHighlight>The local copy of this content item has
not been updated to the latest revision.  Use <i>Get Native File</i> or <i>Check out</i>
to update your local copy of <i><$dDocName$></i>.</span></td>
</tr>
</table>
<$endif$>

<$if IsStagingDoc$>
<br>
<table width="90%">
<tr>
<td width="20%" align=center><$include doc_problem_reports$></td>
<td width="20%" align=center><$include project_problem_reports$></td>
</tr>
</table>
<$include doc_provider_info$>
<$else$>
<table width="90%">
<tr>
<$if ClientControlled$>
<td width="20%" align=center><$include doc_select_actions$></td>
<$else$>
<td width="20%" align=center><$include doc_file_undo_checkout$></td>
<td width="20%" align=center><$include doc_file_checkout$></td>
<td width="20%" align=center><$if showPrimaryMetaFileFields$><$include meta_file_update$>
<$else$><$include doc_file_update$><$endif$></td>
<$endif$>
<td width="20%" align=left><$include doc_subscription_unsubscription$></td>
<$if ClientControlled$>
<td width="20%"></td>
<td width="20%"></td>
<$endif$>
</tr>
</table>
<$endif$>
<$if HasOriginal and DownloadApplet$>
<$include download_native_applet$>
<$endif$>

<!-- end loop on DOC_INFO-->
<$endloop$>
<$if IsStagingDoc$>
<!-- present a problem report form -->
<$include doc_add_problem_report$>
<$else$>
<!-- Table holding information about all revisions of this document-->
<$include doc_rev_table$>
<$endif$>
</td>
</tr>
</table>
<$include std_page_end$>
<@end@>