Tip 037: Creating a Microsoft Word document

PeopleCode | Creating a native Microsoft Word document

A. Is This Really a Good Idea?

If you’ve ever wondered whether it’s possible to create a native Microsoft Word document from within PeopleCode, the short answer is ‘yes’. A PeopleCode programme can take advantage of the ‘API’ (Application Programming Interface) that automatically comes installed with Microsoft Office. However, before you eagerly rush off to create your first Word document, consider carefully whether this is an option you really want to pursue. There are a number of important points to keep in mind.

B. Availability of Microsoft Office on Process Scheduler?

Microsoft Office is of course designed for Windows. While most people have Office on their own Windows PC – so as a developer creating and testing a programme on a local PC is never a problem – once a programme is completed and available for users within the PeopleSoft environment, it is the system App Server and Process Server that become more relevant. If the Word document is being created in an online programme, MS Office must be available on the App Server. If the document is being created as part of a batch process, then it’s the Process Scheduler that must have Office installed. In the real world, the App Server and Process Scheduler are often installed on the same machine, so assuming this is Windows based, one installation of Office will cover both requirements.

However, this could become a bit messy if you have a mix of UNIX and Windows servers available. In this situation, you will have to structure your environment to ensure the Word functionality always run on the Windows server. For instance, you would set up the processes to run only on ‘PSNT’ (or whatever your Windows server happens to be). Running an online process via the App Server will be trickier. This will require users to log into a specific machine, rather than going through a ‘load balancer’ and leaving the outcome to chance. A system administrator will need to set up a mechanism that allows a user to connect directly to an NT App Server.

C. Handling ‘stuck’ Word processes

For a variety of reasons (programme crashes, system down-time), you may end up with a server containing lots of Word processes that have failed to terminate. When the PeopleSoft process runs, it opens up Word like it would on any local PC. If a bug causes the App Engine to crash, the MS Word process remains open on the server. MS Word has not had the chance to properly close itself.

If processes are never closed, they will gradually accumulate over time, meaning you may end up with dozens (or possibly hundreds) of ‘hanging’ Word processes. If too many sessions are open at once, this will drain system resources and possibly cause machine limits to be reached.

Therefore, you will need to discuss the situation with your system administrators. They can set up a scheduled batch job to automatically ‘kill’ any Word processes that have been running for a certain amount of time. Depending on the sort of processes you intend to run, a process running for at least one hour is a prime candidate for deletion.

D. Upgrades?

Upgrades, of both MS Office and PeopleTools, can be particularly problematic for any PeopleSoft functionality that takes advantage of the Office API. To assist in the upgrade process, I’ve often set up a small test App Engine that can be run, just to test that the basic Word functionality is still there. I also make certain to perform a thorough test of any Office integration components following a system upgrade of any type.

E. Isn’t BI Publisher a better option anyway for ‘rich content’ documents?

In most cases, the short answer is an even more definitive ‘yes’. BI Publisher is built into the PeopleSoft system and given a choice, it is always better to choose an in-house solution as opposed to an external one. BI Publisher gives you the ability to produce RTF and PDF documents (among other types) based on a Word template. While RTF (Rich Text Format) is not as powerful as Word documents, it still contains a significant number of standard word processing functionality. This should be enough to cover most requirements.

F. Word Processing

If, after giving the MS Word question a sufficient amount of thought, you’re still convinced that MS Word is the way to go, here’s some code to create a Word document. This code isn’t doing anything super-special, but it’s an introduction to seeing how PeopleCode can take advantage of an API supplied by a third party.

Local object &currentApp;
Local object &currentDoc;
Local object &range;

/* Create Word application object */
&currentApp = CreateObject("COM", "Word.Application");

/* Set document to visible and turn off alerts */
&currentApp.Visible = True;
&currentApp.DisplayAlerts = False;

/* Create a new Word document */
&currentDoc = &currentApp.Documents.Add();

/* Set document margins */
&currentDoc.PageSetup.TopMargin = 75;
&currentDoc.PageSetup.BottomMargin = 75;
&currentDoc.PageSetup.LeftMargin = 100;
&currentDoc.PageSetup.RightMargin = 100;

/* Set document font */
&currentDoc.Content.Font.Name = "Arial";

/* Set document line spacing (12 represents single line spacing) */
&currentDoc.Content.ParagraphFormat.LineSpacing = 12;

/* Set up range to start entering text */
&range = &currentApp.Selection;

/* Enter first line */
&range.ParagraphFormat.Alignment = 1; /* centre text */
&range.Font.Bold = 1;
&range.Font.Size = 24;
&range.TypeText("Hello World!");

/* Enter two carriage returns */
&range.TypeParagraph();
&range.TypeParagraph();

/* Enter second line */
&range.Font.ColorIndex = 6;  /* sets font to red */
&range.Font.Size = 16;
&range.TypeText("Congratulations");

/* Enter two carriage returns */
&range.TypeParagraph();
&range.TypeParagraph();

/* Enter paragraph text (normal font) */
&range.ParagraphFormat.Alignment = 0;  /* alignment left-justified */
&range.Font.ColorIndex = 0; /* colour reset to Auto, ie black */
&range.Font.Size = 12;
&range.Font.Bold = 0;
&range.TypeText("This is your first Word document created in PeopleCode.");
&range.TypeParagraph();

/* Enter second paragraph */
&range.TypeText("Scroll down to see page 2.");
&range.TypeParagraph();

/* Insert page break */
&range.InsertBreak();

/* Enter text on second page using document styles */
&range.Style = "Heading 1";
&range.Font.Italic = 1;
&range.TypeText("Welcome to page 2.");
&range.TypeParagraph();
&range.TypeParagraph();
&range.Style = "Normal";
&range.Font.Italic = 0;
&range.TypeText("That's all folks.");

/* Save document */
&currentDoc.SaveAs("c:\temp\hello_world.doc");

/* Close Word */
&currentApp.Quit();

Always make certain to close MS Word after any document is created, otherwise you will end up with an endless number of Word processes running on the server. Refer to the ‘Handling ‘Stuck’ Word Processes’ point above for further details.