This chapter provides an overview of Microsoft Word document generation and discusses:
Generate Microsoft Word documents.
Refresh Microsoft Word documents.
View document generation logs.
PeopleSoft Supplier Contract Management generates Microsoft Word 2003 documents in an .xml file format when you preview a clause, section, or document configurator or when you generate the first-draft document using the Document Management component. This chapter focuses primarily on draft document generation and refresh capabilities of document generation.
Note. Make sure you are using the latest service pack of Microsoft Office Word 2003, at least SP1, and that the application is a part of Microsoft Office Professional Edition 2003. The Standard version is not sufficient for editing and maintaining PeopleSoft custom XML tags.
Microsoft Word document generation is the process the system uses to assemble elements from the document library into Microsoft Word documents. The process of creating a document is the beginning phase for enabling integration between PeopleSoft Internet Architecture pages and Microsoft Word documents.
PeopleSoft Supplier Contract Management uses the Microsoft Word generation program when creating initial draft versions of an authored document and initial draft versions of amendment documents when you are creating separate amendment files. You create the initial Microsoft Word document using the Document Management component.
To create an initial document, use the Add a Document page to select a value for the Source Transactionfield, assign either a contract ID or ad hoc ID, and click the Add a Document button. Use the next page to define the document configurator that structures the document and click the Create Document button, starting the generation process.
If a wizard is associated with the configurator, the system captures the responses, then invokes a process to create an instance of the initial draft of the Microsoft Word document. During the generation, the system processes all elements from the library that are directly or indirectly linked to the document configurator to expand and create the initial draft Microsoft Word document in an .xml file format. After you create the initial draft, you can view, modify, and perform document life-cycle actions against the document.
Depending on how the document configurator has been defined, the system includes any required content such as sections and clauses, resolves related bind values, evaluate rules linked to the configurator and takes appropriate action depending on the result of the rule. For example, a rule might require that an additional clause be added to the content.
After the system generates the document, it stores the document as a draft version of the document on a file transfer protocol (FTP) server outside of the database. The system also stores detailed information about the document on the Document Management page so that it can be managed from the PeopleSoft document authoring system. These details include the document identifier, its name, location, and version used in the document.
Note. For the best results in auditing the details and testing the generation process for wizards and configurators, select the Details option in the Log at Document Generation field on the Document Configurator Definition page or when defining installation option default values. This option enables you to log and review details for warnings, bind variable resolutions, configurator expansion processing, and wizard details.
See Defining Installation Options.
This flowchart describes a high-level view of how the system generates Microsoft Word documents:
Document generation flow
The next sections provide a more detailed explanation of Microsoft Word document generation.
See Also
Microsoft Word Integration with Supplier Contract Management
See Also
Source Transactions for Authoring Purposes
This section describes the steps you use and system actions for generating documents. The steps also apply to amendment document generation. Generally, this information applies to both creating documents and creating separate amendment files where you specify an amendment configurator ID.
To generate a Microsoft Word document:
You invoke the document generation process.
To begin the generation process, you can create the Microsoft Word document through the Document Management page. For purchasing contracts, the transaction contract must already exist.
Use the following links for more information about invoking the document generation process for ad hoc and purchasing contract documents.
See Adding Purchasing Contract Documents, Adding Ad Hoc Documents.
You specify document attributes to incorporate into the Microsoft Word document.
As you define a document, you can define additional attributes related to the authored document. You can optionally, define a document administrator, sponsor and sponsor's department for the document, along with begin and expiration dates for ad hoc documents, and a document description. You can also define any external contact information for the document at this point.
Attributes can serve as additional information for the document which, in turn, the system can use to evaluate and include in the generation process when using bind variables. For example, you can specify sponsor for the contract and reference the sponsor in the contract by using a transactional bind that represents the sponsor. After the system generates the document, you can update several of the attributes.
Note. The system has several predefined bind variables. Many of the binds related to document attributes have a DOC_ prefix. You set up bind definitions and then map them to source transactions.
You specify a configurator ID and click the Create Document button.
The system evaluates the document configurator ID and invokes the document creation process. Then, if a wizard is specified in the configurator definition, the system initiates the wizard and presents the questions to document authors.
The contract wizard is a tool that enables you to prompt and store values related to groups of questions you define specific for each document configurator. These questions can result in wizard bind values that the system can use during the document generation process to place values in the contract, or as values referenced in rules to determine contract content.
The system uses the document configurator to expand the content of the document.
During the expansion process, the system finds all elements linked to the document configurator and expands the content into a draft version of the Microsoft Word document. The system evaluates wizard bind values, rules, alternate rules, and repeating elements to expand the document.
In addition to wizard bind values the system, can reference additional transactional bind values from purchasing contract or ad hoc source transaction defined in the setup. The expansion process applies to both the initial document and the separate amendment files.
During the expansion process, the system:
Expands the content within the document configurator.
Using the begin date of the purchasing contract or the ad hoc document to select active and approved content, the system incorporates all directly referenced sections and clauses, section child structures, and clause dependents included on the configurator. The expansion includes the children of those elements, such as dependent clauses or clauses attached to sections and children of those elements.
Note. The system automatically excludes content from the document that is not approved, is inactive, or is approved, but future-dated beyond the contract begin date.
See Defining Basic Configurator Information.
Note. If the contract begin date changes after the system generates the document and then you regenerate the document, the system uses the new contract begin date to expand the content during the regeneration process. Changing the begin date alone does not affect the document.
Applies rules attached directly to the configurator or to a section element.
During document generation, the system evaluates each rule that has been included directly to the configurator or section element for a simple true or false result. If the rule is true, the system attaches all elements and their children to that rule and includes them in the Microsoft Word document.
If the rule is false, the system does not include the related elements, but saves the rule with the document in case a future refresh of the document causes the system to invoke the rule again.
You nest rules in the configurator. For example, you can attach a rule to a section that itself was included by a rule on the configurator. The system evaluates rules for each instance of repeating data that it includes as children of a repeating structure. For example, suppose that the repeating information is a section that includes procurement contract items. The system can attach a rule to include additional contract clauses specific to the item category of that particular item. When generating the document, the system reevaluates the rule for each contract item to determine if the additional clauses should be included for that particular item.
Resolves binds.
During document expansion, the system determines which binds to resolve for use in document clauses, sections, or rules. The system resolves transactional binds by using the source transaction definition and bind mappings of these variables to transactional sources, such as the transactional purchasing contract. All wizard binds and many transactional binds are typically nonrepeating, level zero binds, where there is only one occurrence of the bind value during document generation. A contract number is an example of a nonrepeating bind.
For binds that repeat, such as transactional purchasing contract items, the system resolves them based on how many occurrences exist in the contract transaction. An example of a repeating bind might be the items that exist on the purchasing contract. The system logs resolved bind values as part of the generation process.
Expands repeating sections or clauses that may exist.
If the document configurator contains repeating sections or clauses, the system expands these during the generation process. For example, suppose a configurator contains a nonrepeating section defined as S_PRODUCTS01 (products and services) and within that section there is a repeating child section S_CONTRACT_LINES (contract lines) with a title or body that references transactional purchasing contract item bind variables. During document generation, the system repeats the child section S_CONTRACT_LINES in the document for each instance of the item information contained on the transactional contract. The system evaluates each instance based on the bind mappings for bind variables defined within the section S_CONTRACT_LINES.
A section, such as S_PRODUCTS_01, might also contain additional clauses or sections within it, depending on how you define the section. The system expands the section according to it contents. Furthermore, if the system finds nested repeating structures, it expands them in each child section. For example, if the S_CONTRACT_LINES child section contains a repeating child with line-level milestone information, the system repeats the appropriate line-level milestone information directly beneath the corresponding contract line.
Applies rules attached to alternate clauses.
The system uses rules attached to alternate clauses to determine which alternate clauses to use in the Microsoft Word document. Each alternate clause can have a rule attached to it. The system checks the alternates in sequenced priority order to find the first alternate for which the rule is true starting with the highest priority.
During document generation, the system substitutes an alternate clause and its dependent clauses for the primary clause and its dependents in the document when one of the alternate clause rules renders true. Thus, when using multiple alternate clauses, you should typically list the most restrictive rules first followed by the least restrictive.
For example, suppose that the contract specifies that a clause be substituted if the supplier is located in a specific state, and substituted with a different, more restrictive clause, if the supplier is located within a specific county of that state. The highest priority rule and alternate clause should evaluate the combination of the county and state first, then followed by the second rule that evaluates just the state so that the system evaluates alternate clauses in the correct sequence.
If the system doesn't find any alternate rule that is true, it does not substitute an alternate. The system evaluates alternates during contract generation once for a clause. For example, if an alternate clause is selected during contract generation, and it, in turn, has alternate rules and clauses defined (alternates for the alternate), the system does not evaluate the rules or alternates for the alternate clause.
Alternates can exist for nested elements within the configurator. The system evaluates those nested alternate clauses. For example, if an alternate clause has dependent clauses which, in turn, have alternates, the system evaluates the alternate clauses as the document is expanded.
The system creates an XML-based document using Microsoft WordML schema.
After the system creates the draft Microsoft Word document, it stores it on the FTP server and links it back to the Document Management page as version 0.0.
The filename the system uses to generate the document uses this format: <setid>_<contract/ah-hoc ID>_<version number>. So, for example, the first time you check out a newly generated document for procurement contract 0000000000000000000000023 the file name might be SHARE_0000000000000000000000023_0.00. You can change this default filename by renaming the file on the local system during check out.
The system does not change the name of the document during check in, check out, or refresh since it displays document names during dispatch and can be referenced within the document itself as Microsoft Word headers or footers.
Note. You specify the file transfer protocol location using the Administer File Attachments page. To access the page, select Set Up Financials/Supply Chain, Common Definitions, File Attachments.
See Setting Up Supplier Contract Attachment FTP Servers and Directories.
To create an XML-based document during document generation, the system:
Creates a memory resident XML structure to contain the new document.
Expands and resolves the .xml versions of sections and clauses.
The system checks for section and clauses on the document configurator and assembles these elements in the memory resident XML structure. It applies Microsoft Word paragraphs styles and content from the Microsoft Word template that are associated with the document configurator.
Stores and moves the XML-based document to the FTP server and folder defined in the File Attachments component.
This action takes place after the system fully expands the XML document.
Associates the XML file to the Document Management page by version number.
The system displays the current version on the Document Management page. Previous versions of documents that have been generated are accessible using the Document Version History link on the Document Management page. The system displays the Document Management page upon completion of the generation process along with any logging messages.
The system generates a log.
The system generates a log for the initial document generation and displays a message if there are any serious logging warnings such as bind values that it could not resolve in the document. After you initially generate the document, the system does not use the document configurator for document editing, unless you select to regenerate the document. Changes you make to the document at this point are to the draft document, either through application pages or Microsoft Word. For each generation the system performs against the document, it provides a logging history. You access the history using the Document Version History link on the Document Management page.
You select to regenerate the document.
After the system generates the document, you can click the Regenerate Document button to regenerate the document. This action indicates that you want to create the document again. The system completely erases the original document and generates a new document using the same processing as it did for the original document generation. Document regeneration does not include any edits that you have made to the existing current document. If you regenerate the document and use a new version number, you can use the Document Version History link to view prior versions of the originally generated document.
Warning! When you regenerate a document, the system creates a new document using the latest transactions and document elements in effect as of the begin date of the source transaction. This is either the purchasing contract begin date or ad hoc begin date. You lose all changes to the original document.
Note. The Regenerate feature can also apply to amendments when maintaining separate amendment files for the contract.
This section describes how the system refreshes bind variables and related content in a document. You refresh documents after you make changes to a contract transaction or wizard binds. To refresh documents:
You select to refresh an existing document.
You use the Refresh Document button on the Document Management component to initiate the refresh. The system invokes the wizard to enable refresh of wizard binds and use the previous values as default values.
Note. The system use the wizard that is defined for the configurator used to generate the document the last time. So, if you change the wizard on the contract after initial generation, and the new wizard does not access all the binds used by the old wizard, then you may not be able to modify a wizard bind used by the contract.
The system evaluates the bind values in the document and compares them to current values in the transaction or wizard.
If the system finds any differences, it replaces the old values in the document with their new values. In this case, the system does not alter other text elements that originate from the document generation or from manual changes to the document. However, there are exceptions.
If the system detects any value changes within a document structure, described in the Common Element Used in This Chapter section, then it completely rebuilds the related content in the document using the current definition of the elements it includes. In this situation, it is possible to refresh the document and lose manual changes that were made to the document.
For example, assume you generated a document that includes a repeating document structure that list transactional contract line items. Later, you make manual changes to the document text related to those line items, and then add a new item to the transactional contract. Refreshing the document replaces the entire repeating document structure of the document, this is the parent repeating element and all its descendents. The new transactional line now appears, but the system removes the manual changes
Note. The system does not use the document configurator to rebuild document structures. Instead, it rebuilds the document starting with the parent element for the document structure and its descendent elements.
When rebuilding document structures in the document, the system uses the current effective-date definition for the content based on the begin date of the source transaction. So, if an element in the hierarchy changes, it is possible for the system to include element changes when it rebuilds the structure.
Before you use the Refresh Document button on the Document Management page, remember that the Refresh process starts with the bind values already on the document and compares those to the current values on the transaction or wizard to determine where it needs to update the document. If a rule is true, then the document binds includes those used on the rule, and those used on any elements included by the rule. If a rule is false, the system saves the rule in the document, hidden from view. In this case, the document binds include only those used on the rule, but not those used on objects attached to the false rule.
You should consider these points about how the system processes content when it refreshes a document:
Refresh of a rule document structure when a bind changes within the rule structure:
Whether the rule was originally true or false, when the system detects a bind value in the rule document structure, it reevaluates the rule.
If the rule was true and is still true, during the refresh, the system replaces the content related to the rule. The system adds the new content from the library as specified by the rule using the source transaction begin date. This situation occurs even if the rule binds did not change, but binds within the rule structure did change.
If the rule was true and is now false, the system removes the content related to the rule from the document. However, the system keeps the rule as part of the document, but hidden from view, for consideration with future document refreshes.
If the rule was false and is now true, the system inserts the content related to the rule into the document at the location where it originally placed the rule.
If the rule was false, and is still false, and even if binds have changed on descendent elements, the system does not change the document.
Refresh of repeating document structure when a bind changes within the repeating structure.
The system rebuilds the entire document structure using the current version of the parent element and all descendents. Any manual changes you make are lost.
Refresh of alternate document structure when a bind changes within the alternate structure.
The system checks alternate clauses with attached rules in their priority sequence order similar to the Generate process. Because of the change in bind values, the system can select an alternate clause that is different than the original clause used in the document. If a different clause is used, then the system includes corresponding descendents of that clause instead of the descendents on the original clause. The system bases alternate rules and clauses that it uses on the current version. Any manual changes made within the alternate document structure is lost
Refresh of elements not residing within a document structure.
The system does not modify any content. It replaces only old bind values with the new bind value and retains any manual changes.
Manual insertion of nonrepeating clauses in Microsoft Word:
If you manually include a nonrepeating clause in the Microsoft Word document using the Research task pane in Microsoft Word, and the clause contains a nonrepeating bind variable, the system resolves the variable after you check in the document and click the Refresh Document button.
If you insert a repeating bind variable in a Microsoft Word document, the system cannot automatically resolve the bind. It expands and resolves the repeating binds during the initial generation of the document.
Note. The Refresh feature can also apply to Amendments when you are maintaining separate amendment files for the contract.
This section provides an overview of log generation and discusses how to view generation logs.
During document generation, the system generates a log that you use to review the processing results that indicate how the system interpreted and built the document from the configurator. You can also use the log to resolve unexpected results. After it completes the generation process, the system displays a message that it has logged document generation issues.
The generation log provides you a view of how the system processed the document. The log is essential when building documents from complex configurators that contain wizards, binds, rules, alternates, and repeating sections.
The generation log is the primary validation tool for use with wizards and configurators. For example, you can define a wizard that enables document authors to branch through multiple paths that result in a variety of bind responses, rules, and related content. You can validate the wizard combined with the configurator when you generate test documents that exercise the various paths. The log validates that the proper content and bind variable resolution is taking place for each wizard path you define.
Two options are available for logging warnings and generation details. Logging options determine the content of the log. You can define the default value setting by using PeopleSoft Supplier Contract Management installation options. You can override the default value using the Log at Document Generation field on the Document Configurator Definition page.
Generation logging options are:
Details
This option logs more extensive information for document generation including grids that contain:
General warnings.
Bind variables used in the document and their resolved values.
Configuration expansion that shows how elements were included in the document.
Rules that were evaluated.
Extended wizard log showing navigation choices and responses to wizard questions.
Log Warnings and Wizard
This option includes warnings and wizard summary information only. You should use this for configurators that are in production, especially complex configurators that require more complex processing. This logging option provides better overall performance for complex processing.
See Defining Basic Configurator Information.
Logging Errors and Messages
The next table describes detail messages and warnings that are associated with document generation logging:
Grid Message Type |
Messages |
Cause and Resolution |
Generation Warnings grid |
Document contains no content. Content is possibly Empty, Inactive, Not Approved, or Future Dated. |
This can indicate a problem with the configurator, elements in the library, or with the begin date on the contract. |
Alternate not resolved. |
An error occurred when creating the alternate clause. You can proceed with the document, but you should review the alternates for the specified clause. |
|
Rule not resolved. |
An error occurred when resolving a rule. You can proceed with the document, but you should review the specified rule. |
|
Variable not resolved. |
The system found a bind variable (wizard or transactional) in the generated document, but could not resolve the variable. This might happen if a wizard bind exists in a clause or section, but was not answered as part of the wizard. |
|
Effective-dated content inactive. |
The specified element is effective-dated, but there is no active effective row. The content might have prior- or future-dated entries; however, the closest date prior to the current date is inactive. |
|
Effective-dated content not approved. |
The specified element is effective-dated, but the content has not been approved. The content might have prior- or future-dated entries; however, the closest date prior to the current date is active and unapproved. |
|
Effective-dated content not found. |
The specified element is effective-dated, but the date was not found. The content has effective-dated entries for only future dates. |
|
Configurator Expansion grid action messages |
Alternate considered. |
Alternate Used: The system evaluated the alternate clause listed in the Content ID column and used it instead of the primary clause. Alternate Not Used: The system evaluated the alternate clause listed in the Content ID column and did not use it to replace the primary clause. For example, the alternate rule did not resolve to true. |
Include. |
Inserted by Clause: The content ID was included in the document because it was listed as a dependent to the clause object listed in the Source Content ID column. Inserted by Section: The content ID was included in the document because it was listed as a child to the section object identified in the Source Content ID column. Inserted by Rule: The content ID was included in the document because it was tied to a rule identified in the Source Content ID column that was evaluated to true. Blank: If the message column is blank, the content ID was included in the document because it was listed directly on the document configurator. |
|
Include repeating. |
Inserted by Clause: The repeating content ID was included in the document because it was listed as a dependent to the clause object listed in the Source Content ID column. Inserted by Section: The repeating content ID was included in the document because it was listed as a child to the section object identified in the Source Content ID column. Inserted by Rule: The repeating content ID was included in the document because it was tied to a rule identified in the Source Content ID column that was evaluated to true. Blank: If the message column is blank, then the repeating content ID was included in the document because it was listed directly on the document configurator. |
Page Name |
Object Name |
Navigation |
Usage |
CS_DOC_WGEN_LOG |
Supplier Contracts, Create Contracts and Documents, Document Management Click the Generation Log on the Document Management page. |
View generation logs. |
Access the Generation Log page.
Depending on the logging option specified on the Document Configurator Definition page, different grids appear for the Generation Log page.
Use this page to view document processing information. This information indicates system processing conditions and any warnings that were produced during the document's generation.
Logging occurs during processing for rules, alternate clauses, and resolution of binds. The system provides messages on this page that indicate what it is logging. The messages are:
No Warnings Logged |
This message indicates that there were no warnings logged during the generation of the document. |
Logging Warnings and Wizard Only |
This message indicates that the system is logging only warnings for transactions and wizards based on the logging setting defined on the document configurator. When the configurator is set to only log warnings, the Bind Variables and Configurator Expansion grids are not available. |
Generation Warnings
This grid describes warnings that the system generates when it processes a document.
Message |
Displays the subject of the warning. |
Content Type |
Displays the type of document content from which the system generated the warning. Examples of content types are rules, clauses, and sections. |
Content ID |
Displays the content's object name. This is the name that was assigned to the content during its creation. |
Source Content Type |
Displays the parent content type (section, rule, clause) for the source content ID. |
Source Content ID |
Displays the parent content object ID in which the specified content ID is a child or is dependent. |
Bind Type |
Displays the type of bind for which the system logged the message. Values are Transactional, which retrieves data values from source transactions, and Wizard. |
Bind Variable |
Displays the system identifier for the bind variable for which the system generated the warning. When the system generates a document, it replaces bind variables with either transactional values or values supplied by the wizard. |
Document Type |
Displays whether the log is for an actual document or for an attachment file. When you regenerate documents, you can regenerate only the document, only the attachment, or both. The process logs both types. Main indicates the log is for the core document and Attachment indicates the log is for an attachment file. |
Wizard Log
Use this grid to view logging entries for contract wizards the system processed. The system always logs all wizard details, regardless of the value in the Log at Document Generation field on the Document Configurator Definition page. When the value is Details, all the wizard question appear in the log. When the value is set to Log Warnings and Wizard only the questions the document author saw when running the wizard appear in the log.
Question Group |
Displays the contract wizard question group to which the listed question belongs. |
Display Sequence |
Displays the display order in which the question appears to the author. |
Question |
Displays the question as it appeared to the author. |
Answer |
Displays the answer the author provided for the question. |
Bind Variable |
Displays the bind variable associated with the question. |
Group Sequence |
Displays the group sequence number specified on the question group definition for the question. If any of the questions were navigational questions and jumped to a specific sequence number, this is the sequence number that is referenced in that setup. |
Navigate |
Describes the system navigation after a question was answered by the author. When the field is blank, it indicates that there was no navigation defined for that question. Other values are: Next Group: Indicates that the system went to the next question group after the question was answered by the author. Next Question: Indicates that the system went to the next question in the question sequence after the question was answered by the author. Specific Sequence Number: Indicates that the system went to a specific question in the question group after the question was answered. This might happen based on the response to a question when the next question in the set is not required. |
Jump to Group Sequence |
Displays the sequence number the system accessed after this question was answered. It is based on the navigation option of Specific Sequence Number. |
See Setting Up Question Groups for the Contract Wizard.
Log
Select the Log tab.
Use this grid to view information on the resolution of bind variables.
Occurrence |
Displays the occurrence sequence. An occurrence is similar to a line number. Occurrences that are equal to zero are header-level variables. The system uses them anywhere in the document, but the data comes from the header record or the contract wizard. Occurrences greater than zeros relate to each occurrence of a repeating structure, such as lines for purchasing contracts, in the document. For example, if the contract contains 10 lines and all 10 lines are included in the document, the occurrences are one to 10. However, if only five of the 10 lines are in the document, then the occurrences are 1 to 5. |
Bind Type |
Displays whether the bind is a wizard or transactional bind. Wizard type binds are those used with the contract wizard. Transactional type binds originate from a source transaction. These are nonwizard binds, such as those related to the purchasing transactional contract or ad hoc binds. |
Bind Variable |
Displays the bind variable identifier. |
Variable Value |
Indicates the value that the system inserted in the document to replace the bind variable. |
Bind Change Type |
Displays the type of change the system made to a bind when the bind was refreshed. |
Document Type |
Displays whether the log is for an actual document or for an attachment. |
Wizard Details
Select the Wizard Details tab.
Use this grid to view information about bind variables used in the contract wizard. Fields in this grid are the same as those in the Wizard Log grid.
Display Sequence |
Displays the display order in which the bind appeared to the author. This number is the same as the number shown in the Wizard Log Grid and can be used to link the two together. |
Question Group |
Displays the contract wizard question group from which this bind came. |
Configurator Expansion
Use this grid to review log warnings and details about how the system processed the document configurator during document generation.
Action |
Displays the action taken by the system when it generated the document. |
Generate Position |
Displays the outline position to which this document content belongs in the document. This number is an internally generated number the system uses to sequence the content as it is expanded for use in the document. This number may not match exactly to the Microsoft Word Outline number that appears in the actual document because it does not use paragraph numbering in the document. The field also includes expansion information for items that may ultimately not be used in the final document. These might be, for example, rules that the system evaluate to false. The system uses outline numbering in logging only to assist you in understanding the order of the elements and their relationships to each other. |
Content Type |
Indicates if the corresponding type for the content ID (clause, section, or rule). |
Message |
Displays more information associated with the action. |
Source Content ID |
Displays the parent content ID that resulted in the action. This is only applicable for certain actions and messages. |
Document Type |
Displays the document type that this row belongs too. Document types include Main and Amendment. |