HP Service Manager Software

For the Windows and Unix Operating Systems Software version 9.20

Document Engine Guide

Document Release Date: June 2010 Software Release Date: June 2010

Legal Notices
Warranty
The only warranties for HP products and services are set forth in the express warranty statements accompanying such products and services. Nothing herein should be construed as constituting an additional warranty. HP shall not be liable for technical or editorial errors or omissions contained herein. The information contained herein is subject to change without notice.

Restricted Rights Legend

Confidential computer software. Valid license from HP required for possession, use or copying. Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, and Technical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Copyright Notices
Copyright 1994 2010 Hewlett-Packard Development Company, L.P

Trademark Notices
Adobe is a trademark of Adobe Systems Incorporated. Microsoft and Windows are U.S. registered trademarks of Microsoft Corporation. UNIX is a registered trademark of The Open Group.

Support
Visit the HP Software Support Online web site at: http://www.hp.com/go/hpsoftwaresupport This web site provides contact information and details about the products, services, and support that HP Software offers. HP Software online support provides customer self-solve capabilities. It provides a fast and efficient way to access interactive technical support tools needed to manage your business. As a valued support customer, you can benefit by using the support web site to:

Search for knowledge documents of interest Submit and track support cases and enhancement requests Download software patches Manage support contracts Look up HP support contacts Review information about available services Enter into discussions with other software customers Research and register for software training

Most of the support areas require that you register as an HP Passport user and sign in. Many also require a support contract. To register for an HP Passport ID, go to: http://h20229.www2.hp.com/passport-registration.html To find more information about access levels, go to: http://h20230.www2.hp.com/new_access_levels.jsp

Documentation Updates
The title page of this document contains the following identifying information:

Software Version number, which indicates the software version. Document Release Date, which changes each time the document is updated. Software Release Date, which indicates the release date of this version of the software.

To check for recent updates or to verify that you are using the most recent edition of a document, go to: http://h20230.www2.hp.com/selfsolve/manuals This site requires that you register for an HP Passport and sign in. To register for an HP Passport ID, go to: http://h20229.www2.hp.com/passport-registration.html Or click the New users - please register link on the HP Passport login page. You will also receive updated or new editions if you subscribe to the appropriate product support service. Contact your HP sales representative for details.

Contents
Contents 1 Document Engine overview
What is the Document Engine? Benefits of the Modular Approach Consistency Reduced Development Times Flexibility Accessing the Document Engine

5 9
9 9 9 10 10 10

2 Objects
Create and update Objects Object Definition form and fields Object Info tab field descriptions Locking tab field descriptions Revisions tab field descriptions Variable and Global Lists tab field descriptions Activities tab field descriptions Alerts tab field descriptions Approvals tab field descriptions Manage Queues tab field descriptions Views and Templates tab field descriptions Notifications tab field descriptions Search Configuration tab field descriptions Defined Queries tab Ranges tab

11
11 12 13 15 15 15 16 17 18 19 21 21 21 22 22

3 States
Searching Record Lists Viewing a single record Browsing a record Integration tips for display application Create and update States State Definition field descriptions

25
25 25 25 26 26 26 26

4 Processes

29

Create and modify a Process Process Definition form and field descriptions Initial Expressions tab Initial Javascript tab RAD tab Final Expressions tab Final Javascript tab Next Process tab

29 29 30 30 31 31 31 31

5 Document Engine resources

DEFAULT Object RAD applications se.search.engine se.list.engine se.view.engine RAD applications flow Integration tips for display application Base functions in se.search.engine Base functions in se.view.engine Base functions in se.list.engine Local variables

33
33 33 34 34 34 34 35 36 37 39 40

6 Troubleshooting overview
Research application path through the Document Engine Find dbdict or Object used Find State for the records Find the name of the Process Research application errors Print values of variables or results of expressions

41
41 41 41 42 42 43

7 Work order example overview

Create a table Add key fields to a table Create a form Create a copy of a form Create a link for the work order form Create a sequential number file Create an Object definition Create a State definition

45
46 47 48 49 50 51 51 53

Create an Initialization Process definition Create display application screen definition Create display application option definitions Add a close work order button Create a wizard for the work order Add a Process definition record Create an input form for the wizard Modify the close and update incident forms Create an alias in probsummary table for link Modify im.set.close Process definition Test the work order example

54 55 57 62 64 67 68 70 73 74 76

1 Document Engine overview

The Document Engine is a tailoring tool that includes the possibility to customize the system without the need of RAD changes. It provides a centralized method for setting privileges and behavior for standard actions, such as list, view, and search. It increases consistency across modules. The three main components of the Document Engine are Objects, States, and Processes. Processes can be reused for more modular programming and the integration is seamless, which can reduce development time.

What is the Document Engine?

The Document Engine comprises a set of tools and methodologies for developing and modifying Service Manager workflows. The Document Engine was originally tasked to develop an underlying set of base functionality that would support multiple modules inside Service Manager, improve consistency of the user interface between modules and reduce the amount of code needed for any new module. The Document Engine extends the display application capabilities with simplified and more extensive actions especially those involving multiple application calls. In addition, the Document Engine supports the use of joined tables and master format control calls. The Document Engine comprises Objects, States, and Processes to centralize tasks. It is designed to meet the needs of most customers out of the box, yet retain flexibility. The relationship between Objects, States, and Processes is hierarchical. The Document Engine controls behavior with Objects. An Object is referenced whenever a form opens, and the Object determines the behavior for the state of the form (open, list, search, etc.). Objects define overall table behavior. Within the Object, a State describes where a record is in its lifecycle (open, list, search, etc.). Within the State, different Processes are executed depending on the actions initiated by a user on the record. States also define how the system displays a record and what options are available at specific times or circumstances. For instance, States can determine an action, such as Save, given a users access privileges. Processes are called from States based on the user's action. The Process uses RAD expressions, JavaScript, and calls to existing RAD applications to perform actions against the current record..

Benefits of the Modular Approach

The advantages of the modular design include consistency in development, reduced development time, and flexibility.

Consistency
The fact that the engine allows all applications to run using the same base RAD applications brings consistency to the Service Manager application suite. Core functionality, such as locking, alerts, approvals, and use of record list functionality, will work the same for any module, as they are all using the same code base.

1 Document Engine overview

Reduced Development Times

The modularity of the Document Engine allows for reuse of existing code and Processes.

Flexibility
The Document Engine uses Process records as a mechanism to modify the behavior of modules inside of Service Manager applications. You can create a new Process that has a different behavior than the base system, without the need to change or remove the original Process from the system. Additionally, the systems base Processes can be overridden with your own Processes to give greater flexibility to the system developer when tailoring Service Manager to meet an organization's specific requirements.

Accessing the Document Engine

To access the Document Engine: 1. Start a Service Manager Client and log in as an administrator. 2. In the Service Manager System Navigator, click Tailoring. 3. Click Document Engine. From here, you can access the main three areas to define Objects, Processes or States. You can also set up Alerts and Approvals to be called from Objects or create Search Configuration Records, which are used by Objects.

10

Chapter 1

2 Objects
Objects are a base set of definitions that determine behavior of records and set the definitions and governing rules. Objects correspond one-to-one with database dictionary (dbdict) records in Service Manager. If a table does not have a dedicated Object record, the Document Engine applies the settings in the DEFAULT Object. All Objects should have list and default States defined. If not otherwise supplied, the default States are db.browse, db.list, db.search, and db.view. NOTE: Do not modify or delete the DEFAULT Object Record as doing so will cause unpredictable results. The Object record sets up the definitions and governing rules for the behavior of the table within the Document Engine. For example these may include:

The application used to create the users profile within this Object that determines what actions this user may take against any record of the table. The State records used in specific circumstances (see the States section for more details). The category, phase, and paging file names for the Object. The name of the number record to be used for this Object. How locking is to be used by this Object. Setup of revisions for records in the table. Which variables should be available to processes that run against this Object. Which global lists should always be available when using this Object. Use of activity records. How alerts are processed against this Object. How approvals are processed for this Object. Settings for the work queues. Ability to set up personal or global views and default templates. Notifications on add / update / delete of a record in this Object. Ability to configure additional search choices against this Object.

To view a list of the out-of-box Objects, click Search from the Object Definition form. To view a list of the fields and field descriptions for the Object definitions see Object definition form and fields.

Create and update Objects

To create an Object:

2 Objects

11

1. Navigate to the Document Engine. See Accessing the Document Engine for the steps. 2. Double click Objects. The Objects form opens. 3. Use the tabs on the Objects form, to fill in the fields required to create an Object that will perform the functions you desire. See the field descriptions for additional information. To update a Object definition: 1. Access the Document Engine. See Accessing the Document Engine for the steps. 2. Enter the name of the Object you want to update in the Object field or click Search to search for the Object.

Object Definition form and fields

The field descriptions for the Object Definition form are:
Field Name File name file.name Common name message Unique key unique.field Description Enter the dbdict name for the Object, that is, use the dbdict name that corresponds to this Object's name. (required) The system fills in this information from Data Policy. It is a common name for the Object. The common name can be a simple name, such as Work Order. The system fills in this information from the dbdict. This is the unique key for the Object.

This form also includes the following tabs. The fields on these tabs are described in the field descriptions tables for the respective tab.

Object Info tab - specifies the general properties and behavior of the Object. Locking tab - determines the locking behavior for the Object. Revisions tab - tracks revisions for the Object. Variables / Global Lists - describes local variables and global variables used by the Object. Activities - defines logging (activities). Alerts - defines where to set alerts and the conditions for generating alerts. Approvals - sets approval options for the Object. Manage Queues - controls how queues display as well as threading, and who can create views (inboxes). Views/Templates - defines whether or not a user can create global and personal views and templates on the Object.

12

Chapter 2

Notifications - identifies notifications sent automatically for add, delete, or update activity for any record in the Object. Search Configuration - controls the available options on the More Choices tab of the search screen.

Object Info tab field descriptions

This tab specifies the general properties and behavior of the Object. The field descriptions for the Object Info tab are:
Field Name Description field desc.field Profile application profile.appl Profile variable profile.variable Number record name number.record Specifies the RAD application that creates the profile that determines if a user can perform certain functions, such as add and delete. For example, db.environment. (rquired) Specifies a variable that can be accessed any time this Object is called without accessing the environment record.For example, $L.env. (required) Defines a number class for the Object, which can be accessed from a call to the getnumb application either via a Process or FormatControl or RAD call. It can be used to retrieve a sequential number as a unique key for the record. For example, EXWorkOrder. Specifies the table name that links with the category table associated with this Object's category value. When displaying a record of this type, if a field called category exists, then the Object will search the category table name and for the record with the corresponding name. If found, the system stores the Category File Name as a variable: $L.category. Specifies the table name that links with the phase table associated with this Object, if applicable. When the system displays a record of this type, if a field called phase exists, then the Object goes to the phase table name and selects a record with a corresponding name. If found, the system will store the phase table name as a variable: $L.phase. Specifies the name of the table used for storing pages. Pages are created as full copies of the current record prior to the latest updates being applied. This is done every time a record is updated, which creates a detailed audit trail. Description Specifies a short description of the Object.

Category table name category.file.name

Phase table name phase.file.name

Paging table name paging.file

Object Info tab field descriptions

13

Field Name Master format control master.fc

Description Specifies the name of the Master Format Control record, if one exists for the record Object. Master Format Control allows you to define in one record the Format Control statements that apply to all phases in an area, for example Change Management Request Phases. Typically, the name of the master format control is the name of the dbdict or all categories in Incident Management, Problem Management, or Service Desk. Specifies the name of the joindef record used to join multiple tables, for example joincomputer, or an expression that evaluates to a valid joindef name, such as joindef in $L.category Specifies the field name that contains the record's status information.

Joindef joindef Status field statusField Assigned to fields assignedToFields Workgroup fields workgroupFields

Specifies the field name that contains the assignee name field for this Object. This field will be referred to when Folder Entitlement verifies that the record is assigned to the logged in operator. Specifies the field name that contains the assignment group field for this Object. This field will be referred to when Folder Entitlement verifies that the record is assigned to any of the logged in operator's work groups. Specifies the State definition record to use upon opening a new record.

Open state open.state Close state close.state List state list.state Default state default.state Search state search.state Browse state browse.state Manual states manual.states

Specifies the State definition record to use for close processing of an existing record. Specifies the State definition record used to display a list of records.

Specifies the name of the State used as default for the Object. To edit a record in this Object, the default State is used. Specifies the State definition record to use for searching.

Defines the State definition record to use when records use locking. Essentially, this field defines a read-only State when a record is currently locked by another user. Specifies the array of States that may be used with this Object other than the life-cycle states of open, close, list, view, search or browse.

14

Chapter 2

Locking tab field descriptions

The Locking tab determines the locking behavior for the Object. This means that when someone is actively updating a record the system does not allow another user to update the same record. The field descriptions for the Locking tab are:
Field Use locking use.locking Lock on display lock.on.display Lock parent record lock.parent Parent Id Field parent.id Parent Filename/Object parent.object Watch Variables watch.variables Watch Variables are used when the Document Engine checks to see if a record has been changed or not. Watch Variables must be NULL when the record first displays. If true or a condition that evaluates to true, Service Manager attempts to lock the record as soon as it displays. Use locking must be enabled for this field to work. Locks the current record and the records parent. For example, when this field is checked and someone is updating a change task, the change request for the task is also locked. Enter a field name in the current record that contains the ID of the parent to lock. The name of the table that contains the parent record. Description Select this check box to enable locking.

Revisions tab field descriptions

The Revisions tab determines the revisioning behavior for the Object The field descriptions for the tab are:
Field Name Revision table name revision.file Max # of revisions max.revisions Description Specifies the name of the table you want to store revisions to this Object's records in. Specifies the total number of revisions allowed for this Object. If left blank, then there is no upper limit.

Variable and Global Lists tab field descriptions

The Variables/Global List tab describes local variables and global variables used by the Object.

Locking tab field descriptions

15

Note: Global variables are built and stored in memory. The field descriptions for the Variable/Global List tab are:
Field Name Local variables local.variables Description Enter a list of local variables that can be used in Processes. Local variables are defined in the application. Local variables are assigned to the Object you are creating and are available to all Processes and States associated with the Object. Local variables are not available to other Objects. Global lists, once created, are available to all Processes. Global lists can be built on login, if they are listed in the Startup list. Global lists are available every time you access the Object.

Global lists global.lists

Activities tab field descriptions

The Activities tab defines update (Activity) logging for the Object. The field descriptions for the Activities tab are:
Field Name Activity log table activitylog.file.name Selection list variable activity.selection.var Posting link activity.post.link Require update if an activ- A check box to indicate that an activity update is required when the ity record is NOT genselected. erated? activity.mandatory Update field update.field.var Display message activity.mandatory.msg The field or variable that contains the activity update on the form. This field appears only when Require update if an activity record is NOT generated? is present. The message indicating that an activity update is required. This field appears only when Require update if an activity record is NOT generated? is present. The variable to use on an update form to display the types of activities the operator can select when performing an update on a record for a specific Object. The name of the link used to post information. Description The name of the table to hold the activity log entries for the Object.

16

Chapter 2

Alerts tab field descriptions

The Alerts tab defines where to set alerts and the conditions for generating alerts. Any Object that has a unique key can use these alerts. The field descriptions for the Alerts tab are:
Field Name Alert location alert.location Description The Alert location defines where the name of the Alert Definition to execute is found or stored. Specify where the Alert Definition is stored: Record: Store alerts in the record itself. Category: Store alerts in the category file defined on the Object Info tab. Phase: Store alerts in the Phase record defined on the Object Info tab. Object: Store alerts in the Object record. When selected an Alerts array table will be displayed to enable you to fill in alert(s) to be used. Note: The Object's table needs to have a unique key for the Alerts to relate to. A table that contains a no nulls key rather than a unique key cannot use Alerts. Alert condition alert.condition Alert field name alert.field.name Alert status field alert.status.field Alert update process alert.update.process Log alerts? log.alerts Process alerts on parent? alerts.against.parent Recalculate alerts if alert.recalc Reset alerts if alert.reset Specify a condition to determine whether or not to process the alert. For example, open in $L.file~=false. Specify the field name that contains the actual alert name, as defined by Alert location. Specifies the field in the current record in which to put the alert status, after the alert is processed. Specifies the name of the Process record for additional functions that the system performs after the alert runs. If selected, the alerts are moved after processing to the Alertlog file to keep an Alert history. If you have selected the Locking Parent Record field on the Locking/Revisions tab and you select this check box, then the alert will register against the parent record as well, when it is activated. Specifies conditions that determine whether to recalculate conditions on existing alerts. Determines when to delete existing alerts and recalculate all conditions.

Alerts tab field descriptions

17

Approvals tab field descriptions

The Approvals tab sets approval options and their associated notifications for the Object. Approvals are defined in the ApprovalDef file. The field descriptions for the Approvals tab are:
Field Name Approval condition approval.condition Approval location approval.location Approval field name approval.field.name Approval status field approval.status.field Approval groups approval.groups Approval type appr.cond.type Stores a variable to contain the groups the current user must belong to in order to issue approvals for this Object. There are four pre-defined approval types: All must approve: All groups/operators defined in the Approval Definition must issue an approval before the system sets the status of the record to approved. If only one or some but not all of the groups/operators issue an approval, then the status is set to pending. One must approve: The record is approved with one approval from any member of the approving group/operator. Quorum: The record is approved as soon as a majority of the approving group indicate approval. All must approve immediate denial: All groups/operators must approve the record. The first denial causes the status to change to deny. All other approvers do not need to take any action. Select the notification to run if the request is approved. Description If the approval condition evaluates to true, approvals are used on the Object's records. Indicates where the approval information is stored: record, phase, object, or category. The field name that contains the actual Approval name within the table that is defined in the Approval location. The field in the current record in which to store the approval status.

Approval notification single.notify.approval Denial notification single.notify.denial Retraction notification single.notify.retraction Final approval notification final.notify.approval

Select the notification to run if one approver denies the request.

Select the notification to run when retracting a previous action.

Select the notification to send once the final approval is granted.

18

Chapter 2

Field Name Final denial notification final.notify.denial Approval FC appr.fc Approval process approval.process Denial process denial.process Preapprove on open preapprove.cond

Description Select the notification to send when the request is denied.

Specifies the name of the Format Control record to run upon approval. Select the Process to run when the record is approved.

Select the Process that runs when the record is denied.

Determines whether the record should be automatically approved. If the condition is true and the user belongs to one of the pending approval groups, the approval is processed automatically. If the user does not belong to one of the pending approval groups, the approval does not occur automatically and must then go through the regular approval process. Defaults to true. Select this check box to log the history of approvals in the ApprovalLog table. If checked, approval comments are requested from the approver.

Log approvals? log.approvals Require appr. comments approval.comments Aggregate approvals? aggregate.approvals Recalculate approvals if approval.recalc Reset approvals if approval.reset

If checked, approvals are cumulative.

Specifies the conditions that determine whether or not to recalculate the conditions on the existing approvals. Determines when to delete existing approvals and recalculate all conditions.

Manage Queues tab field descriptions

The Manage Queues tab controls how queues and views display as well as threading. These same fields are available in Data Policy for files that do not have an associated Object record, or they are virtual joined into the datadict record from the Object record if it exists. The field descriptions for the Manage Queues tab are:

Manage Queues tab field descriptions

19

Field Name Manage condition scm.condition Manage display format scm.manage.screen

Description Specifies a condition that allows only certain users to view the queues that display records of this Object. For example, browse in $G.pm.environment. Select the format to use to display the view. The out-of-box Service Manager has a default display format: sc.manage.generic that is used if no other form is chosen. HP recommends that you do not change the sc.manage.generic format. Select the default view for this queue. By specifying a user view for a particular user, a specific list of views can be set up for the HP Service Manager Manage Queues. If a user does not have a specific view defined , the default user view is used. Specifies a default query to run if no default view is selected.

Manage default view scm.inbox

Manage default query scm.query Default query description scm.query.name Thread view -> search? scm.thread.list.edit Search format (if necessary) scm.search.format Thread search -> list? scm.thread.search.list Thread list -> edit? scm.thread.list.edit Thread view -> edit? scm.thread.inbox.edit Allow add condition scm.add.condition Add/open application scm.add.appl Parameter Names scm.add.names Parameter Values scm.add.values

Specifies a name for the above field. You can associate a message with this field. For example, scmsg(491, "us"). Specifies true or an expression that evaluates to true to open a new thread when conducting a search. Select a default search format.

Specifies true or an expression that evaluates to true for a new thread when a user finds a list of records to view. Specifies true or an expression that evaluates to true for a new thread when a user selects a record to view out of a list of records. Specifies true or an expression that evaluates to true to open a new thread when the user views an existing record out of the queue. Specifies an expression that evaluates an operators ability to add a record. Specifies the name of the application to call when a record is added or opened. Specifies the parameter names to pass to the application specified in the Add/open application field. Specifies the parameter values to pass to the application specified in the Add/open application field

20

Chapter 2

Views and Templates tab field descriptions

The Views/Templates tab defines whether or not a user can create global and personal views as well as template support. The field descriptions for the tab are:
Field Name Can create personal views personal.inbox Can create system views global.inbox Default Template default.template Supports Templates? supportTemplates Specifies a condition that evaluates to true or false to determine if the user can create global views. Specifies the name of the default template to use for records in this table. Select this check box to enable support for templates for the Object. Description Specifies a condition that evaluates to true or false. True allows the user to create personal views.

Notifications tab field descriptions

The Notification tab identifies notifications sent automatically for add, update, or delete activity for the Object. The field descriptions for the Notifications tab are:
Field Name Add notification.add Update notification.update Delete notification.delete Description Select the notification that is sent automatically when a record is added to the table. Select the notification that is sent automatically when a record is updated in the table. Select the notification that is sent automatically when a record is deleted from the table.

Search Configuration tab field descriptions

The Search Configuration tab controls the available choices on the More Choices tab of the search screen. The field descriptions for the Search Configuration tab are:

Views and Templates tab field descriptions

21

Field Name Table Name tablename Search Format searchFormat Initialization Process init.process Allow Advanced Find allowAdvAccess

Description The name of the table that will be queried.

The name of the sub-format used for the More Choices tab.

The name of a Process that will be run before displaying the search form. Defines the conditions that determine whether or not to allow Advanced Find.

Defined Queries tab

The Defined Queries tab defines the query statements and labels to use on the More Choices tab of the search screens (for example, More Choices on the Search Incidents form). The fields are defined in the SearchConfig table. The field descriptions for the Defined Queries tab are:
Field Name Id id Query query Description description Description Provides the unique ID for the query and cannot include special characters including spaces. A query expression using system language syntax. For example,
assignee.name=operator().

Provides the label for the check box on the More Choices tab.

Ranges tab
The Ranges tab allows you to easily set up a search for begin and end date ranges. To do so click the Modify Configuration link, to define a variable each for begin and end to use as input in the form. Enter this variable in the Variable 1 column and use the Field and Operator 1 columns to define the query that will be executed. Modify Configuration is also how modifications are made on the Defined Queries tab as well. The field descriptions for the Ranges tab are:

22

Chapter 2

Field Name Field fieldName Operator 1 operator1 Variable 1 variable1 Special Type specialType

Description Specifies the field in the table to use in the query.

The comparison operator in the query. (for example: >=)

Specifies the variable used as input on the form.

Not used at this time.

Ranges tab

23

3 States
States are called by Objects and are defined by Processes. The State record contains information about how a record looks and acts at a specific period in time. A State record definition can include the following:

The State name. The display screen to use in order to display the record or records. The initialization process used when a list is first displayed. The format to use to display the data. The input condition to indicate whether or not a user can modify the record. The Process to run when a user triggers a specific display option (Display Action).

The State record used depends on how many records the user views. There are out-of-box State records for searching for records, viewing a list, viewing a single record, and browsing a record.

Searching
When there are no records in the current file variable, it is assumed that the user is in search mode. The State that is used is the Search State defined in the tables Object record. The default search state is db.search.

Record Lists
When viewing a list of records, the List State defined in the tables Object record is used. The default list state is db.list. Note: In some earlier versions of Service Manager, record lists are referred to as QBE lists.

Viewing a single record

When viewing a single record, the record is first checked to see if it includes a State field in the dbdict. If the field exists and is populated, the contents of that field will be used as the current State of the record. If this field does not exist or is NULL, the Default State defined in the tables Object record is used. The default value for the default state is db.view.

3 States

25

Browsing a record
When browsing a record in read-only mode, the Browse State defined in the tables Object record is used. Note that only files that use locking need a browse State. Although viewing a record without having update rights looks similar to the browse screen, it is using the default State, not the browse State. There is no default browse state.

Integration tips for display application

If a display screen does not have any display events associated with it, the system automatically uses the se.default display event that performs se.lock.object in case of OnFormModified. If a display option record has the Modifies Record check box activated, the record is locked when the button is pressed.

Create and update States

To create a new State: 1. Access the Document Engine. See Accessing the Document Engine for steps. 2. On the State Definition form, fill in the fields required to create a State that will perform the functions you desire. See the field descriptions in State definition field descriptions. To modify an existing State: 1. Access the Document Engine. See Accessing the Document Engine for steps. 2. Enter the name of the State you want to modify in the State field or click Search to search for the State.

State Definition field descriptions

The State definition record defines the behavior and display specifications for a record at a specific period in time. In the State record non-base methods can be defined or the behavior of base methods can be modified. Base methods are described in the sections Base functions in se.search.engine, Base functions in se.view.engine, and Base functions in se.list.engine. They include functions such as save, find, fill, OK, Cancel, and Search. The field descriptions for the State Definition form are:
Field Name State state Description Specifies the name of the State. (required)

26

Chapter 3

Field Name Display Screen display.screen Initialization Process init.process Format format.name

Description The display screen to associate with the State.

The name of a Process to run prior to entering the State.

Specifies the format in which the State record opens. This form is stored in a record, and it can be a variable or hard-coded. The name of the format can be hard-coded or be contained in a variable or retrieved from a record via a system language expression. The input condition is evaluated for view States and determines whether or not the record is read-only. Specify false for read-only or true for editable. You may also enter an expression that evaluates to true or false.otherwise, enter true or enter an expression that evaluates to true or false.

Input Condition input.condition

Non-base methods Display Action process.label Process Name valid.process Condition process.condition Save First run.save.before Specifies an expression that evaluates to true for the Process specified in the Process Name to be called. Choose to run the save Process before you run this Process. Type true to save first; otherwise, enter false. The default is false. Specifies the action parameter that comes from a display action after input from a user. The display action comes from the action field in the display option of a button or menu item clicked by a user. Specifies the name of the Process run as a result of the action.

State Definition field descriptions

27

4 Processes
Processes are the smallest discrete units of work available to the Document Engine and are the level where the data is manipulated. Users can create their own Process or use one of the over 700 Processes that ship with Service Manager. The Process definition consists of initial expressions, RAD, and final expressions, entered on the Initial Expressions, Initial Javascript, RAD, Final Expressions, Final Javascript, and Next Process tabs, as well as an optional call to a next Process. Expressions are written using standard RAD expressions and/or JavaScript.

Create and modify a Process

To create a Process: 1. Access the Document Engine. See Accessing the Document Engine. 2. Using the tabs on the Process panel, fill in the fields required to create a Process that will perform the functions you desire. See Process form and field definitions for more information. To modify a Process: 1. Access the Document Engine. See Accessing the Document Engine. 2. Enter the name of the Process you want to modify in the Process Name field or click Search to search for the Process.

Process Definition form and field descriptions

On the Process Definition form, you define new Processes or edit existing Processes. Processes run code or expressions to perform the user selected actions The field descriptions for the Process Definition form are:
Field Name Process Name process Save Cursor Position save.cursor.position Select this box if you want to return to the same cursor position after the action (for example on a fill). Description Specifies the name of the process. (required)

4 Processes

29

Field Name Run Standard Process when complete? run.standard

Description When selected, then the system runs a standard process after completing the current action or Process. A standard Process such as save, for example. If you have created a save Process and want to run the save Process that comes with the Document Engine after completing the save process you defined, check this box. A standard process is defined in the base functions sections of this document. When selected, the process runs in a separate window.

Run in Window run.in.window Window Title window.name

If the Run in Window? check box is selected, specify a title for the window. An scmsg expression can be used for localized window titles, such as scmsg(1980, "us").

In addition to the fields described above, there are also tabs on this form that allow you to further define the Process. These tabs are:

Initial Expressions Initial Javascript RAD Final Expressions Final Javascript Next Process

Initial Expressions tab

The Initial Expressions tab defines the initial expressions that run prior to the initial Javascript and prior to the RAD calls defined on the RAD tab. The initial expressions are written using standard Service Manager expressions.

Initial Javascript tab

The Initial Javascript tab defines the initial javaScript expressions that run before the RAD defined on the RAD tab.

30

Chapter 4

RAD tab
The RAD tab defines the pre-RAD expressions, RAD calls, and post-RAD expressions that run as part of the Process. The field descriptions for the RAD tab are: Note: These fields are repeated for each RAD application defined on this tab.
Field Name Expressions evaluated before RAD call pre.rad.expressions Description Specify the expression to run prior to the RAD application defined in the RAD Application field. All parameter values passed to the RAD application must be in the form of variables or expressions. The variables must be assigned their values in the pre-RAD expressions; for example, $L.value.name="Test". Specifies the name of the RAD application to run.

RAD Application application Condition rad.condition Parameter Names names Parameter Values values Post RAD Expressions post.rad.expressions

Specify under which circumstances the RAD application should be executed (condition evaluates to true) or skipped (condition evaluates to false). Specifies the parameter names passed to the RADapplication

Specifies the parameter values passed to the RAD application. These values must be in the form of variables or expressions. String values can be passed when enclosed in double quotes ( "Wizard Name"). Specifies any RAD expression that will run after the RAD application completes.

Final Expressions tab

The Final Expressions tab defines the final expressions that run after the RAD tab processing completes. The final expressions are written using standard Service Manager expressions.

Final Javascript tab

The Javascript defined on this tab runs after the final expressions and after the RAD applications on the RAD tab.

Next Process tab

This tab specifies the next Process or Processes to run when the current Process completes. The field descriptions for the Next Process tab are:

RAD tab

31

Field Name Next Process next.process Condition process.condition

Description Specifies the name of the next Process to run.

Specifies a condition associated with the Process in the Next Process field that evaluates to true or false. For example, true for the sm.close Process.

32

Chapter 4

5 Document Engine resources

The Document Engine includes local variables and base functions that can be used by any Object. The base functions are defined out-of-box to execute standard actions that are available to the user. For example, when a user clicks the save button after updating a record, the Document Engine processes this request and writes the changes to the database. A base function can be overwritten in the State record to run a different Process.

DEFAULT Object
Any file accessed by the Database Manager automatically uses the rules and processes defined for the corresponding Object. If no Object has been defined for the file, it uses the DEFAULT Object. The DEFAULT Object duplicates the functionality of the earlier versions of the Database Manager. A System Administrator may also access a file that has a corresponding Object via the DEFAULT Object by accessing the file through Database Manager with the Administration Mode check box marked. This check box is available for System Administrators only. A user with the capability word of "AlwaysAdmin" will always use the DEFAULT Object when accessing information within Service Manager. Assigning the capability word to a user is not recommended. The Document Engine uses environment profiles. In previous versions of the system, a System Administrator was granted all rights (add, update, delete.), regardless of the format control settings. With the Document Engine, the rights granted match those defined in the format control record. Administrators that prefer the old method of granting rights can simply modify the Profile Application setting in the DEFAULT Object record from db.environment to db.environment.sysadmin.

RAD applications
With a database driven application, a user may be working with any of the following three basic record sets:

Zero records when searching for information. Many records when looking at a list of information. One record when making changes to a single record.

From a user perspective when working with data:

you either view a blank form, where you can enter search information (or create a new record), or you are working on updating / viewing a single record, or you did a search and now have a set of multiple records displayed as a list.

The Document Engine uses three main RAD applications to mirror this idea. The RAD routine used is determined by the number of records displayed at any time.

5 Document Engine resources

33

se.search.engine
The search engine is used when there are no records being viewed. The main purpose of this routine is to formulate a query and select records from the correct table. This routine may also be used for the initial entry of information into a blank record for the purpose of adding a new record to the database. The Default State is db.search.

se.list.engine
The list engine displays multiple records. Using the list engine a user may select a specific record from the list, or perform actions on the entire list of records. Default State is db.list.

se.view.engine
The view engine displays a single record. This application is used to perform actions against a specific record, such as updates or deletes. Default State is db.view. Note: When using Service Managers record list functionality, the view engine is used for both the list and single record information.

RAD applications flow

The following figure provides an overview of how the other tailoring tools interact with the Document Engine.

34

Chapter 5

Note: All RAD applications related to the Document Engine start with "se", such as se.view.engine. The document engine treats every record as a document made available to the user. When a file is displayed using the Document Engine it will always be using one of the three applications specified earlier in this document. The display screen, display options, and format are determined by the current State of the record. When a display option is triggered, after the standard display functionality is performed, the engine checks the action of that option against the available processes defined in the current State record. If there is a process defined that has a condition that evaluates to true, the engine then performs that process against the current record (or record set). If the action is not defined in the State record, the engine will then check to see if that action is defined as a Base Process in the current application. If it is, then the system will perform that base process against the record. If not, no action is taken.
Integration tips for display application

If a display screen does not have any display events associated to it, the system automatically uses the se.default display event that performs se.lock.object in case of OnFormModified. If a display option record has the Modifies Record check box activated, the record is locked when the button is pressed.

Integration tips for display application

35

Base functions in se.search.engine

Display Action back find fill advanced Description Exits the record. Displays detailed information from the record linked to the field. Fills information from a linked record into a target record. Puts data from a source record field into a target field. Starts the Advanced Search process that gives the user more search options. Typically, this is only available for system administrators, but this option can be made available to other users. Clears the current screen. Prompts the user to open a view associated with the current file. This is a predefined query that displays results as a view. Performs a standard search by creating a search query using the information provided and then displays the results in a record list. Performs add format control and attempts to add a record to the database. Restores the contents of the screen (after a clear is performed). Runs an IR Query text search. Performs Service Manager validity lookup. Validity lookup verifies via an entry in the validity table that a specific value is valid for the defined field. Using validity lookup, the system verifies that a userentered value complies with the validation rules. Expand array provides additional functionality for editing arrays, such as insert line and delete line. Resets the current file. This action deletes ALL records in the database for the table. Regens the indexes of the current file. This action applies only to tables that have an IR Key, and it will perform only an IR regen. Starts the no records export/unload process. Used for unloading empty DBDICT definitions without data only. When selected, the system presents to the user a list of alternate forms in which to display the current record. Displays revisions for records in this object.

clear openinbox / inbox search add restore irquery validitylookup

expandarray reset regen export/unload views findrevision

36

Chapter 5

Display Action initrevision newsite newview newTable addFilter editFilter addCompound removeSelection

Description Creates a revision of a record in this object.

Triggered by customer performing an Advanced Filter search in the standard search screen. Triggered by customer performing an Advanced Filter search in the standard search screen. Triggered by customer performing an Advanced Filter search in the standard search screen. Triggered by customer performing an Advanced Filter search in the standard search screen.

Base functions in se.view.engine

Display Action save add ok reselect fill find next previous back Description Performs update in Format Control and updates the record in the database if the update is valid. Performs add in Format Control and adds a new record to the database if the new record is valid. If the record has changed, perform a save, otherwise exit. Re-selects the current record from the database (in case it was changed). Fills information from a linked record into a target record. Puts information from a source field into a target field. Displays detailed information from the record linked to the field. Move to next record in the list (after checking for changes). Move to previous record in the list (after checking for changes). Exit to list or search form.

Base functions in se.view.engine

37

Display Action menu delete views print printlist* validitylookup

Description Exits to the calling menu. Performs delete Format Control and attempts to delete record from the database after validating the request. When selected, the system presents to the user a list of alternate forms in which to display the current record. Prints the current record. Prints the current list of records. Performs Service Manager validity lookup. Validity lookup verifies via an entry in the validity table that a specific value is valid for the defined field. Using validity lookup, the system verifies that a user entered value complies with the validation rules. Standard Service Manager export/unload functionality (multiple record). Provides unload functionality for a list of records. Adds a new set of records that exactly duplicates an existing set of records except that new set of records will have a unique key value updated with new data. At the end of the processing there will be twice as many records in the table. Provides the same updates to a set of specified fields in a list of records. Deletes a specified set of records from a table. Runs an IR Query text search. Expand array provides additional functionality for editing arrays, such as insert line and delete line. Counts records in the record list and displays the total count. Calls the standard audit history routine. The audit history is determined by the fields to audit as defined in the auditdef table. Saves the current query as a view. Views the approval history for the current record. Views the alert history for the current record. Views the current and scheduled alerts for the current record.

export/unload massunload* massadd*

massupdate* massdelete* irquery expandarray count* audithistory inbox.save / inbox* approval.log alert.log alerts

38

Chapter 5

Display Action pagelist / listpages

Description The page list shows a complete history of a record. When paging is enabled, every time an update is performed, a copy of the record is written to the page file. The page list shows the complete history of a record based on the paging file. Displays clock records associated with this record. Handles XML fields, such as the user options in Service Catalog. Creates a Template record out of the current record. Applies an existing Template to the current record.

clocks xmlfill createTemplate applyTemplate

Note: * These commands only apply if the record list functionality is being used.

Base functions in se.list.engine

Display Action exit (or back) inbox.save / inbox count refresh big.green print views export/unload massadd Description Returns to the search (or calling) form. Prompts the user to save the current query as a new view. Performs standard count functionality and displays the total record count. Refreshes the list using the current query. Completely exits the current module. Big Green Arrow Prints the list of records displayed. When selected, the system presents to the user a list of alternate forms in which to display the current record. Standard Service Manager export/unload functionality (multiple records). Adds a new set of records that exactly duplicates an existing set of records except that new set of records will have a unique key value updated with new data. At the end of the processing there will be twice as many records in the table. Provides the same updates to a set of specified fields in a list of records. Deletes a specified set of records from a table.

massupdate massdelete

Base functions in se.list.engine

39

Local variables
Local variables begin with $L. and persist only within the currently executing RAD application. The server cleans up local variables automatically when it exits a RAD application. The following is a list of Standard Variables used with the Document Engine: $L.action - the display action value from the display option $L.bg - Background flag $L.category - The category record (if available) $L.env - The current environment record $L.exit - internal exit parameter $L.file - The current file variable $L.file.save - A copy of the record in its original state $L.format name of the format used to display the record $irspread determines the IR discovery options: 0=shallow search, 2=deep search, 4=complete match $L.mode the mode the viewed record is in, typically add to create a new record, update to modify an existing record or close to finish processing of an existing record $L.mult - Flag that is true if there are multiple records in the $L.file variable $L.object - The object record $L.phase - The phase record (if available) $L.sql or $L.query- the current query $L.sort - the current sort order $L.state The state record the system is using (=the state the record is in). Variables that are available in View mode (when viewing a single record) $L.fc copy of the detail FormatControl record $L.fc.master copy of the master FormatControl record

40

Chapter 5

6 Troubleshooting overview
To successfully troubleshoot the Document Engine you will need to gather the following information:

What dbdict and Object is being used What State is the record in What is the Process being called Steps followed to reproduce (STR) the problem

Research application path through the Document Engine

In troubleshooting the Document Engine, as with troubleshooting any Service Manager application, enter RTM:3 and debugdbquery:999 in the Service Manager sm.ini file and then start a new client connection. Unless this user process is the very first to invoke the Document Engine processes to debug, it may not show the selection of the State or Process records in the sm.log file when doing this trace, but it will give helpful hints as to which Process was being invoked.
Find dbdict or Object used

To determine which dbdicts or Object is being used, search the log file. Log sample:
1320 07/18/2006 11:00:36 RADTRACE 20 [ 1] se.get.object get.object select CPU( 0 1411 ) 1320 07/18/2006 11:00:36 (0x0129AC08) DBACCESS - Cache Find against file Object found 1 record, query: file.name="pcsoftware" 1320 07/18/2006 11:00:36 RADTRACE 20 [ 1] se.get.object set.access process CPU( 0 1411 )

Find State for the records

The next question to look at is which State the record is in. To find that information, search for the following in the trace sm.log: Log sample:

6 Troubleshooting overview

41

1320 07/18/2006 11:00:48 RADTRACE 10 [ 1] se.get.state select.state select CPU( 0 1491 ) 1320 07/18/2006 11:00:48 (0x01292FB0) DBACCESS - Cache Find against file States found 1 record, query: state="pcs.list" 1320 07/18/2006 11:00:48 RADTRACE 10 [ 1] se.get.state exit.normal process CPU( 0 1491 )

Find the name of the Process

The name of the Process can be found as well, by searching in the sm.log containing the trace shown in the following example. Log sample:
1320 07/18/2006 11:00:50 RADTRACE 20 [ 1] se.call.process select.process select CPU( 0 1542 ) 1320 07/18/2006 11:00:50 (0x00B56810) DBACCESS - Cache Find against file Process found 1 record, query: process="upgrade.pcs" 1320 07/18/2006 11:00:50 RADTRACE 20 [ 1] se.call.process run.pre.exp process CPU( 0 1542 )

Research application errors

Processes call a number of RAD applications and execute a number of expressions, with a possibility of invoking more Processes afterwards. If any of the applications or expressions caused an error exit due to wrong syntax or wrong logic, this information can be found in the sm.log file. Log sample:

42

Chapter 6

Process panel run.pre.exp in RAD se.call.process encountered error in line 1 (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Bad arg(2) oper = (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Bad arg(2) oper = (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Bad arg(2) oper nullsub (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Bad arg(2) oper in (se.call.process,run.pre.exp) Cannot evaluate expression (se.call.process,run.pre.exp) Unrecoverable error in application: se.search.objects on panel call.list.engine Unrecoverable error in application: se.list.engine on panel call.process.1 Unrecoverable error in application: se.call.process on panel run.pre.exp

In this example (not out-of-box), the error occurred in se.call.process, run.pre.exp, or in other words, while evaluating the initial expressions of the Process. To find out which Process was causing the issue, go through the steps outlined above and note the process from the line:
DBACCESS - Cache Find against file Process found 1 record, query: process="upgrade.pcs"

Go to the Process record by the name of upgrade.pcs and check for any statements on the initial expressions tab. In this specific case, the expression will include the word nullsub. For example, the expression in question for this test may be
$L.icount=nullsub($L.icount, anynumberIwant)

The variable, anynumberIwant, is not a valid field, literal or variable, so it will have to be changed to prevent this issue.

Print values of variables or results of expressions

In the Document Engine, the path through a work flow is often determined by the value assign to a field or variable. To determine the value assigned to a field or variable that influences the work flow, use the JavaScript print() function or use the log rtecall ($L.void=rtecall(log, $L.rc, message) in the RAD expressions. The message can be a concatenated string such as
$L.message="The value of $L.test is " + $L.test

where $L.test is a variable that was assigned a character value.

Print values of variables or results of expressions

43

7 Work order example overview

What is a work order? A work order is a specific task assigned to a single engineer that identifies some activity necessary to resolve an incident or possibly any other module if the work order system were extended to include changes, problems, or known errors. The following example is based on Service Managerversion 7.11 and was written to enable users to create, update, and close work orders for Incident Management. It can be modified easily for another Service Manager application. This example creates a work order system to demonstrate how to use the Document Engine. This work order system will enable users to create work orders for an incident and view the status of these work orders. The work order system also enables users to view and update a work order from Incident Management. All work orders are associated with a particular incident in the system, and the incident cannot be closed until all work orders for the incident are closed. This example is intended for users who tailor or customize the system. You should have a good understanding of the following tailoring functions:

Database Dictionary to create a new table Forms Designer to modify out-of-box forms and create new forms. Wizard creation tool

The work order example walks you through the following steps:.

Create a new database dictionary (dbdict) using the dbdict utility. Specify the key fields for the table. Create a EXWorkOrder form for the EXWorkOrder table using Forms Designer. Create a Sequential Number File. Modify the form to include drop-down lists. Create a link for the EXWorkOrder form. Create a form for the wizard to use to collect information for the work order. Modify the close and update incident forms Create aliases to link work orders to incidents Create State definitions. Create Display Application Screen Definitions for open, close, and view. Create Display Application Option Definition of Add, Cancel, Fill and Find for open, close and view. Modify the Process definition record im.set.close Test the work order example

7 Work order example overview

45

Create a table
Use the dbdict utility to create a new table. In this example you will create a table named EXWorkOrder. Before you can create this table, you need to know what fields are needed and the attributes of the fields.In this example, the table stores the data for work orders associated with incidents. To create a table: 1. From the System Navigator, click Tailoring > Database Dictionary. The Database Dictionary form opens. 2. Type EXWorkOrder in File Name. 3. Click New. 4. On the Fields tab, enter the following information after clicking NewField/Key.
Field ID RelatedID Description Will be filled from the number file. Type: character Will be filled by the unique ID of the related record, example: incident number) Type: character Used to store the status of the work order. Type: character initiator assignee.name description category RelatedCIs The operator who opened the work order. Type: character The operator assigned to the work order. Type: character Used to hold the description of the work to do for the work order. Type:array of character Filled from the category of the related record. Type: character Used for the list of Configuration Items (CIs) associated with the work order. Type: array of character Type: character Type: character

status

impact urgency

46

Chapter 7

priority closure.code deadline est.finish update.action closure.comments

Type: character Type: character Date by which the work order must be completed and filled on open. Type: date/time The assignee's estimate for completion. Type: date/time . Type: array of character . Type: array of character

5. After you have added the fields to the table you need to add keys to the table. You should not exit Database Dictionary utility until you have done this for the EXWorkOrder table. See Add key fields to table for the detailed information.

Add key fields to a table

Use the dbdict utility to add keys to a new table. After you create a table named EXWorkOrder, you need to add keys to the table. Keys are used to enable indexed searches as well as ensure data consistency. To add keys to a table: 1. From the The Database Dictionary click the Keys tab. 2. Select the first available entry for a new key field. 3. Click the New Field/Key. 4. Enter the following information for each key you create or edit.
Field ID RelatedID RelatedCIs assignee.name Description Type: unique Type: no nulls Type: nulls & duplicates Type: nulls & duplicates

5. Click OK.

Add key fields to a table

47

Create a form
Go to Forms Designer to create a form for the EXWorkOrder table. Utilizing the wizard to create the form select Detail of a single record and proceed. A basic form with all of the fields will be created which can be modified as needed. Below is an example for the EXWorkOrder form:. To create a form: 1. From the System Navigator, click Tailoring > Forms Designer. The Forms Designer form opens. 2. Type EXWorkOrder in Form Name. 3. Click New. 4. Click Yes to use the Form Wizard. 5. Type EXWorkOrder for the name of the table for which to create a form. 6. Select Detail of a Single Record for the type of form you want to create. 7. Click OK. 8. Click Proceed to accept the defaults for the fields to include on the form. 9. Use the Forms Designer tool to modify the form layout. Below is an example of the EXWorkOrder form. 10. The values for Status are: New (default status)

Open Ready Closed

11. The Values for the Closure Code are: Implemented

Canceled Rollback

The following is a sample EXWorkOrder form.

48

Chapter 7

Create a copy of a form

In Forms Designer create the sc.manage.WorkOrder form by making a copy of sc.manage.problem. Modify the table column inputs to use the fields from the EXWorkOrder table. To create a new form from a copy of a form: 1. From the System Navigator, click Tailoring > Forms Designer. The Forms Designer form opens. 2. Type sc.manage.problem in Form. 3. Click Search. 4. Select sc.manage.problem.g. 5. Click Copy/Rename in the detail Options menu. 6. Type sc.manage.WorkOrder in New Name 7. Click OK. 8. In Forms Designer, update the input fields for the columns using the EXWorkOrder table. 9.

Incident ID - ID

Create a copy of a form

49

Category - category Related Id - RelatedID Status - status Assignee - assignee.name Description - description,1 Priority - priority Impact - impact Urgency - urgency

10. Click OK.

Create a link for the work order form

Discuss what links do and what they are need for in this example. To create a link for the work order form: 1. From the System Navigator, click Tailoring > Tailoring Tools > Links. The Link File form opens. 2. Type EXWorkOrder in Name. 3. Add a description in Description. 4. Click New. 5. Enter the following information.
Source Field Name initiator assignee.name RelatedCIs Target File Name operator operator device Target Field Name name name logical.name

6. Select the initiator row (highlight) then right click initiator and choose Select Line. 7. In the link.structure.g form enter the following information for initiator. Then repeat Step 6 for assignee.name and RelatedCIs and use the following information for those fields, respectively.
Source Field (Fill To/Post From) initiator Target Field Name (Fill To/Post From) name

50

Chapter 7

assignee.name RelatedCIs

name logical.name

8. Click Save. 9. Click OK.

Create a sequential number file

Create sequential number file to generate sequence numbers for the records in the EXWorkOrder table. To create a sequential number file: 1. From the System Navigator, click Tailoring > Tailoring Tools > Sequential Numbers The Sequential Number File form opens. 2. Type EXWorkOrder in Class. 3. Type 1 in Last Number. 4. Type Number for WorkOrder in Description. 5. Type 5 in Length. 6. Type WO in Prefix. 7. Click Add.

Create an Object definition

The purpose of this Object is to define the characteristics and behavior of the EXWorkOrder Object that determines what data needs to be included in a work order record and how the system will process work orders. Note: See Object definition field descriptions for the Object definition field descriptions. To create an Object definition: 1. From the System Navigator, click Tailoring > Document Engine > Objects. The Object Definition form opens. 2. Type EXWorkOrder in File Name. 3. Click Add to create the Object record.

Create a sequential number file

51

4. On the Object Info tab, enter the following information.

Field Unique Key Common name Description field Profile application Profile variable Number record name Category table name Master format control Status field Assigned to fields Open state Close state Default state Search state Value Automatically filled (ID) Automatically filled (EXWorkOrder) Table to hold work orders that can relate to any of the modules db.environment $L.env EXWorkOrder category EXWorkOrder status assignee.name EXWorkOrder.open EXWorkOrder.close EXWorkOrder.view EXWorkOrder.search

5. Click Save. 6. Select the Manage Queues tab. 7. On the Manage Queues tab, enter the following information.
Field Manage condition Manage display format Manage default query Allow add condition Default query description Value true sc.manage.WorkOrder assignee.name=operator() false My WorkOrders

8. Click Save. 9. Click OK.

52

Chapter 7

Create a State definition

These State definitions for the work order example specifies what process to use and what actions are allowed when a user opens, closes, or views a work order record. Note: See State definition field descriptions for the State definition field descriptions. To create a State definition for open: 1. From the System Navigator, click Tailoring > Document Engine > States. The State Definition form opens. 2. Enter the following information.
Field State Display Screen Initialization Process Format Input Condition Value EXWorkOrder.open EXWorkOrder.open EXWorkOrder.open.initial $L.format true

3. Click ADD.

To create a State definition for close: 1. From the System Navigator, click Tailoring > Document Engine > States. The State Definition form opens. 2. Enter the following information.
Field State Display Screen Initialization Process Format Input Condition Value EXWorkOrder.close EXWorkOrder.close EXWorkOrder.close.initial $L.format true

3. Click ADD.

Create a State definition

53

To create a State definition for view: 1. From the System Navigator, click Tailoring > Document Engine > States. The State Definition form opens. 2. Enter the following information.
Field State Display Screen Initialization Process Format Input Condition Value EXWorkOrder.view EXWorkOrder.view EXWorkOrder.view.initial $L.format true

3. Click ADD. To create a State definition for search: 1. From the System Navigator, click Tailoring > Document Engine > States. The State Definition form opens. 2. Enter the following information.
Field State Display Screen Initialization Process Format Input Condition Value EXWorkOrder.search db.search EXWorkOrder.view.search $L.format true

3. Click OK.

Create an Initialization Process definition

These Process definitions for the work order example specifies what initial expressions and RAD applications to use when a user opens a work order record.

54

Chapter 7

To create a Process definition for initialization: 1. From the System Navigator, click Tailoring > Document Engine > Processes. The Process Definition form opens. 2. Type EXWorkOrder.open.initial in Process Name. 3. Click Add. 4. Type $L.format="EXWorkOrder" the Initial Expressions tab. 5. Click Save. 6. Enter the following information in the RAD tab.
Field Expressions evaluated before RAD call RAD Application Parameter Names name index text Value $L.number.record="EXWorkOrder";$L.number.type="string" getnumb Parameter Values $L.number.record ID in $L.file $L.number.type

7. Click Save.

Create display application screen definition

You create the display application screen definitions for open, close, and view screens for the work order forms that allow users to open, close, and view work order records. To create a screen application definition for open, close, and view: 1. From the System Navigator, click Tailoring > Tailoring Tools > Display Screens. The Display Application Screen Definition form opens. 2. Type EXWorkOrder.open in Screen ID. 3. Enter the following information.
Field ScreenID Title Value EXWorkOrder.open Open New Work Order

Create display application screen definition

55

Format I/O (If RIO) On option 0: Language

$L.format true redraw screen ENG

4. Click Add and then click OK. 5. For this example you need to create display application screen definitions for close screen also. Use the following information:
Field Screen ID Title Format I/O (If RIO) On option 0: Language Value EXWorkOrder.close Close Work Order $L.format true redraw screen ENG

6. Click ADD and then click OK. 7. For this example you need to create display application screen definitions for view screen also. Use the following information:
Field Screen ID Title Format I/O (If RIO) On option 0: Language Value EXWorkOrder.view View New Work Order $L.format true redraw screen ENG

8. Click Add and then clickOK.

56

Chapter 7

Create display application option definitions

This procedure provides step-by-step instructions for creating add, cancel, fill, and find display application option definitions for the following WorkOrder definitions :

open close view

In doing this, you will repeat the same steps four times for each of the WorkOrder screen definitions (open, close, view). However, each time you enter different values in the fields on the Display Application Option Definition form. The tables below the steps provide the values you need to configure the display application options. For additional information about the display application options, see the online help topics for the display application on the HP Service Manager online help server. After you create the display application screen definitions for open, close, and view, you need to create display application options for the open, close, and view screens. To create a display application option definition: 1. From the System Navigator, click Tailoring > Tailoring Tools > Display Options. The Display Application Screen Definition form opens. 2. Type EXWorkOrder.open in Screen ID. 3. Enter the following information.
Field Unique ID Action GUI option Text Option Bank Condition Default Label Value Automatically generated (EXWorkOrder.open_add) add 4 4 1 true Add

4. Click Add. 5. Click OK. 6. Repeat steps 1 - 6 for each of the following display option definitions using the values provide in the table.

Create display application option definitions

57

Note: In some cases the value required for the Action field is not available in the drop-down list, but you can type the applicable value in the field. Open - Cancel
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.open Generated by the system. (EXWorkOrder.open_cancel) back 3 3 1 true Cancel

Open - Fill
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.open Generated by the system. (EXWorkOrder.open_fill) fill 9 9 1 true Fill

Open - Find
Field Value

58

Chapter 7

Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label

EXWorkOrder.open Generated by the system. (EXWorkOrder.open_find) find 8 8 1 true Find

Close - Cancel
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.close Generated by the system. (EXWorkOrder.close_cancel) back 3 3 1 true Cancel

Close - Close
Field Screen ID Unique ID Action GUI option Value EXWorkOrder.close Generated by the system. (EXWorkOrder.close_close) close 5

Create display application option definitions

59

Text Option Bank Condition Default Label

5 1 true Close

Close - Fill
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.close Generated by the system. (EXWorkOrder.close_fill) fill 9 9 1 true Fill

Close - Find
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.close Generated by the system. (EXWorkOrder.close_find) find 8 8 1 true Find

60

Chapter 7

View - Cancel
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.view Generated by the system. (EXWorkOrder.view_cancel) back 3 3 1 true Cancel

View - Fill
Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label Value EXWorkOrder.view Generated by the system. (EXWorkOrder.view_fill) fill 9 9 1 true Fill

View - Find
Field Screen ID Unique ID Value EXWorkOrder.view Generated by the system. (EXWorkOrder.view_find)

Create display application option definitions

61

Action GUI option Text Option Bank Condition Default Label

find 8 8 1 true Find

View - Save

Field Screen ID Unique ID Action GUI option Text Option Bank Condition Default Label

Value EXWorkOrder.view Generated by the system. (EXWorkOrder.view_save) save 4 4 1 true Save

Add a close work order button

When a user completes the task or tasks, the work order should be closed. This procedure describes how to put a close button on the EXWorkOrder form and update the status of the work order to close. This procedure adds a display application option definition, adds a State definition for EXWorkOrder.view, and adds a Process definition for EXWorkOrder.close. Note: This procedure does not explain how to include validation for this activity. You would use Format Control to add validation. To create a display application option definition for EXWorkOrder.view:

62

Chapter 7

1. From the System Navigator, click Tailoring > Tailoring Tools > Display Options. The Display Application Screen Definition form opens. 2. Type EXWorkOrder.view in Screen ID. 3. Enter the following information.
Field Unique ID Action GUI option Text Option Bank Condition Default Label Value Automatically generated (EXWorkOrder.view_close) close 5 5 1 true Close

4. Click Add. 5. Click OK. To update the EXWorkOrder.view state definition: 1. From the System Navigator, click Tailoring > Document Engine > States. The State Definition form opens. 2. In the State field, type EXWorkOrder.view and then click Search. The EXWorkOrder.view state definition form opens. 3. Add the following to update the state definition form.
Field Display Action Process Name Condition Value close EXWorkOrder.close true

4. Click Save and then click OK. To add a process definition record for EXWorkOrder.close: 1. From the System Navigator, click Tailoring > Document Engine > Processes. The Process Definition form opens. 2. Type EXWorkOrder.close in Process Name.

Add a close work order button

63

3. Click Add. 4. On the Initial Expressions tab, type the following expression: status in $L.file="Closed"

$L.mode="closed"

5. Click Save. 6. On the RAD tab, enter the following information:

Field Expressions evaluated before RAD call RAD Application Condition Parameter Names file prompt second file record second.record boolean1 Value $L.EXaction="update" se.base.method true Parameter Values $L.file $L.EXaction $L.file.save $L.fc $L.object false

7. Click Save and then OK.

Create a wizard for the work order

This examples uses a wizard to create a work order because it simplifies the task for the user and the functionality is already available in the system, so it is more efficient to use this functionality rather than to recreate it. Use the wizard creation tool to create a wizard to allow users to create a work order from the Incident module. When a user creates a work order from an incident, the wizard will prompt the user for information and autofill some of the fields in the work order. To create a wizard for the work order form: 1. From the System Navigator, click Tailoring > Wizards. The Wizard Information form opens. 2. Type Create Workorder - 1 in Wizard Name. 3. Click Add to create the Wizard record.

64

Chapter 7

4. On the Wizard Info tab, enter the following information:

Field Brief Description Window Title Title Start Node Value Create a new work order. Create Workorder Create Workorder Select (set to true) to indicate that this is the first wizard in a series of wizards in cases where you have a series of wizard records.

5. Click Save. 6. In the File Selection tab of the Wizard Information form, select the Select $L.file by tab. 7. On the Select $L.file by tab, enter the following information:
Field Create a record of type Value true EXWorkOrder

8. Click Save. 9. On the Usage tab, enter the following information:

Field Wizard Usage Sub Format to Display Main Format Display Screen Activate "Finish" option Value Click Request user input in the Wizard Usage section. Type createWO.assigneeAndCIs Select Buttons on Top Type wizard.display Select (set to true) to have a Finish button on the wizard form.

10. Click Save. 11. On the Actions tab, enter the following information:
Field Perform Actions On Value Select Current File ($L.file).

Create a wizard for the work order

65

Actions to Perform > Expressions

initiator in $L.file=operator() status in $L.file="New" RelatedID in $L.file=number in $relatedRec category in $L.file=category in $relatedRec impact in $L.file=initial.impact in $relatedRec urgency in $Lfile=severity in $relatedRec priority in $L.file=priority.code in $relatedRec

Display Record(s) when com- Click Display Record(s) when complete? plete? Mode Select Add.

12. Click Save. 13. On the Cancel Expressions tab, enter the following information:
Field Expressions Executed on Cancel Value cleanup($relatedRec)

14. Click Save and then OK.

66

Chapter 7

Add a Process definition record

Explain why we need to add a process definition record. What is this record going to do for the work order example. To add a process definition record: 1. From the System Navigator, click Tailoring > Document Engine > Processes The Process Definition form opens. 2. Type create.WorkOrder in Process Name. 3. Click Add. 4. On the Initial Expressions tab, type the following expression: $L.void=fduplicate($relatedRec, $L.file)

$relatedCIs={}

5. Click Save. 6. On the Initial Javascript tab, type the following expression:
system.vars.$relatedCIs=system.library.BSGFunctions.getMembers(system.vars.$L_ file.affected_item, false, 3)

Note: This expression must be entered on one line. 7. Click Save.

Add a Process definition record

67

8. On the RAD tab, enter the following information:

Field Expressions evaluated before RAD call Value Type the following two expressions: $L.wiz.name="Create Workorder-1" if (not null(logical.name in $L.file)) then ($relatedCIs=insert ($RelatedCIs, 1, 1, logical.name in $L.file)) Note: Be sure to enter this expression on one line. Also note that when entering this expression, there is no space after the word insert. For example, the expression above continues at the word 'insert' as follows: insert($RelatedCIs, 1, 1, logical.name in $L.file))

RAD Application Parameter Names Parameter Values Parameter Names Parameter Values Condition

wizard.run name $L.wiz.name text $L.exit true

9. Click Save. 10. On the Final Expressions tab, type cleanup($relatedRec). 11. Click Save and then OK.

Create an input form for the wizard

This form is the first form to display in the work order wizard. The user enters the information the user needs to provide for the wizard to create the work order record. Use Forms Designer to create this form. For this example, the form name is createWO.assigneeAndCIs. To create an input form for the wizard: 1. From the System Navigator, click Tailoring > Forms Designer. The Process Definition form opens. 2. Type createWO.assigneeAndCIs in the Form for the form name. 3. Click New. You do not need to use the Forms Designer wizard for this form.

68

Chapter 7

4. Create the following input fields on the form: Description (Please enter a description of the work to be done)

Due date (Please enter the due date for this work order) Assignee (Please enter the assignee for this work order) CIs (Please enter the CIs this work order is for)

5. The Properties for this form should include: Input: RelatedCIs

Value List: $relatedCIs Sortable: checked

6. Click Save. The following figure shows a sample createWO.assigneeAndCIs form for the EXWorkorder wizard input form.

Create an input form for the wizard

69

Modify the close and update incident forms

For this example, you need to modify the close incident and update incident form so that you can view the work orders assigned to the incident and then double click and read or edit the work order from the incident.. Use Forms Designer to update the IM.update.incident and IM.close.incident form. To do this you must add a tab and then a form on the tab on both the IM.update.incident and IM.close.incident forms. To modify update incident form: Note: Use these same general procedures to update the close incident form. 1. From the System Navigator, click Tailoring > Forms Designer. The Process Definition form opens. 2. Type IM.update.incident in the Form for the form name. 3. Click Search. 4. Click Design. 5. Add a new tab to the existing notebook. 6. Set the caption of the tab to WorkOrder. 7. Add a subformat with the following properties: Visible: checked

Format: WorkOrder.vj Virtual Join: checked Display Blank: checked Display Using Table: checked Input: number.WO.vj

8. Click Save. 9. Use the Forms Designer tool to create the WorkOrder.vj form: WorkOrderID: ID

WorkOrder Deadline: deadline WorkOrder Status: status WorkOrder Assignee: assign.name WorkOrder Description: description

10. Repeat steps 1 - 8 for the IM.close.incident. Note: You can use the WorkOrder.vj form created in step 9 for the virtual join. The following figures show samples of the tabs to add.

70

Chapter 7

Modify the close and update incident forms

71

72

Chapter 7

Create an alias in probsummary table for link

In the work order example, users need to be able to access a work order from an incident record when the incident has a work order associated with it. In order to do this, you must create an alias in the probsummary table and then use that alias to create a link between the probsummary table and the EXWorkOrder table. To add an alias to the probsummary table: 1. From the System Navigator, click Tailoring > Database Dictionary. The Database Dictionary form opens. 2. Type probsummary in File Name. 3. Click Search. 4. On the Fields tab, select the number field and click Edit Field/Key. 5. Click Create Alias and type number.WO.vj for name and character for type. 6. Click OK. To link the EXWorkOrder table with the probsummary table:

Create an alias in probsummary table for link

73

1. From the System Navigator, click Tailoring > Tailoring Tools > Links. The Link File form opens. 2. Type probsummary in Name. 3. Click Search. 4. Click after the last entry to create a blank line for a new entry. 5. In the Source field, type number.WO.vj. 6. Select the entire new line and then click Select Line. 7. Enter the following information:
Field Field (From/Source) File (To/Target) Field (To/Target) Query Expressions Value number.WO.vj EXWorkOrder RelatedID $query $query="RelatedID=\""+number in $File+"\""

8. Click Save and then Back. 9. Repeat steps to create a link line for the ID field. 10. Enter the following information.
Field Field (From/Source) File (To/Target) Field (To/Target) Query Expression Value ID EXWorkOrder ID $query $query="ID=\""+nullsub(cursor.field.contents(), "xxx")+"\""

11. Click Save and then Back.

Modify im.set.close Process definition

This process needs to be modified so that a user cannot close an incident if there are work orders still open for the incident. To modify a process definition record:

74

Chapter 7

1. From the System Navigator, click Tailoring > Document Engine > Processes The Process Definition form opens. 2. Type im.set.close in Process Name. 3. Click Search. 4. On the Initial Javascript tab, type the following JavaScript: var WO=new SCFile ("EXWorkOrder") var FoundOpenWO=WO.doSelect ("RelatedID=\""+system.vars.$L_ file.number + "\""+" and status ~=\"" + "Closed" + "\"" if (FoundOpenWO == RC_SUCCESS) { system.vars.$openWO=true; } else { system .vars.$openWO=false; } 5. Click Save. 6. On the RAD tab, enter the following information:
Field Value

Note: Some of the fields on the RAD tab are pre-filled with values that you do not need to modify RAD Application - Select the empty section below the section calling the RAD Application us.consume.wrapper and then enter the following information: Expressions evaluated before RAD call RAD Application Condition Parameter Names Parameter Values $L.text="There are still open work orders. This incident cannot be closed yet." apm.mb.ok $openWO=true text $L.text

7. Click Save. 8. On the Final Expressions tab, enter the following information:

Modify im.set.close Process definition

75

if ($openWO=true) then ($L.exit="badval") $L.exit="closestate"

9. Click Save and then OK.

Test the work order example

After you complete the tasks to create a work order system, you need to verify that it works correctly. To verify the basic functionality of the work order example, do the following:

In Incident Manager, find an open incident or create one. Use the Options menu or button on the tool bar to create a work order. Create Workorder should display on the Options menu. In the Workorder wizard, enter the data to create a work order for the incident. Add the work order to the incident and save the changes to the incident. Open the incident for editing, and from the WorkOrder tab edit the work order. Save your changes. Open the incident again, and this time edit the work order and close it. You should now be able to close the incident. Repeat these steps, but this time create two work orders for an incident. Close only one work order and then attempt to close the incident. The system should generate an error message indicating that there are still open work orders for the incident, and therefore it cannot be closed. Close all work orders for the incident. You should now be able to close the incident.

76

Chapter 7