A free-form dictionary means that service designers are free to specify the fields in the dictionary, the order in which they occur, and the data types assigned to each. To configure the fields in the free-form dictionary, see Fields to Configure Internal Dictionary.

Cisco Prime Service Catalog maintains a repository of all persons in the user organization who may need to access Prime Service Catalog applications. Personnel information in Service Catalog is viewable via Organization Designer. The personnel information in this repository is generally populated via directory integration. Any time a user logs in to Service Catalog, or has a service ordered on his/her behalf, his/her personnel information in the repository can be refreshed with their information from an enterprise-wide directory. Service forms typically need to refer to personnel information. For example, a service request always has a customer—the recipient of the service; and an initiator or requestor—the person who sits at the keyboard and requests the service. In most cases, the customer and the initiator are the same person—an employee requests a service for him/herself. Alternatively, an administrator or other authorized employee may initiate a service request on behalf of another person, who then becomes the customer for the service. To configure the fields in this type of dictionary, see Fields to Configure Internal Dictionary table.

About Person Search Option

When a person-based dictionary is used on a service form, you can choose a single person specifying the search criteria in the “Person Search” dialog box. Once a person is chosen, fields used in the dictionary are automatically filled in with the current values of the corresponding fields in the chosen person’s profile. The name appears in FirstName LastName format.

The “Select_Person” attribute provides the capability to search for people, either within the repository or, if directory integration has been enabled for service forms, in an external directory. This attribute has a data type of “Person,” not text. This data type governs the appearance of the attribute when it is used in a form. For example, the “Name” field on the service form below is defined as the “Select_Person” attribute. In any new person-based dictionary, you will see “Show in Grid” is checked by default for the “Select_Person” since it also checked for use Use by default. “Show in Grid” cannot be unchecked for the Select-Person, just as you cannot uncheck Use. Select the other dictionary attributes to be displayed on the service form by clicking the Use checkbox.

Figure 1. Select Person Attribute

A Service Item-Based Dictionary is a dictionary whose structure (fields) are based on a service item defined in the Service Item Manager module. This dictionary also holds data about that service item collected during a service request. To see type of data that can be configured for a service item, see section on Defining Service Items for a Service.

Fields in that dictionary provide the data stored on the service item and can optionally serve to update the history of the service item and its subscriptions. For more information, see Service Item Subscription and History Fields.

External dictionaries are added and maintained in Service Designer > Dictionaries. Using an external dictionary in read/write mode can result in corruption to the database that you are accessing from the system if you have not set up safe data transfer methods. Read the following tips:

• The Requisition Entry ID generated by the system needs a column and primary key of its own in the external database table. Otherwise, the system can overwrite other data in the table.
• We recommend that your site create an intermediate table with a key column to which the system writes new entries. This table can then work with your existing table.
• Before adding an external dictionary, consult with the external table’s DBA or owner to ensure that the system uses the correct columns for the Requisition Entry ID and the primary key.
• The system does not automatically synchronize changes that you make to external database tables with its own external dictionaries that reference those tables. Changes to column names or sizes, for example, will not flow through to external dictionaries, and services ordered that depend on those dictionaries will fail. Once you have created an external dictionary in the system, each time you change the structure of the external database table, you must save the definition page of the external dictionary in the Dictionaries component of Service Designer. When you click Add This Dictionary on this page, the system will synchronize the table structure, and display the new information in the section that describes the external database columns.

Every Service Catalog instance automatically includes two dictionaries, provided as seed data for customer and initiator information. These dictionaries can be found in the “Reserved” dictionary group in the Dictionaries component of Service Designer.

There is also a “Reserved” form group in Active Form Components, which contains the Customer-Initiator form. This form includes the Customer_Information and Initiator_Information dictionaries.

Features of Customer_ and Initiator_Information dictionaries:

• Supplement the standard behavior of automatically recording the customer and initiator for all requests.
• All information on the customer and initiator is available throughout the requisition life cycle via Business Engine namespaces, and is displayed as part of the Requisition Summary page for the request in My Services.
• These dictionaries are included in active form components and reusable for all services for the following reasons:
  • These fields reflect the values that were retrieved from the person's profile.
  • The person ordering the service has no opportunity to correct information that may be out of date or to supply additional information needed to fulfill the current request.
  • In addition, for reporting and governance reasons, it may be required to track customer and initiator information as they were when the request was submitted, not reflecting any subsequent changes.
• The dictionaries and group names for reserved dictionaries cannot be modified.
• The reserved dictionaries are included on a reserved form, the Customer-Initiator form. Form contents and appearance can be defined and its behavior manipulated by any form rules or ISF available.

Figure 2. Requisition Summary Page in My Services

The dictionary and group names of the Initiator and Customer Information dictionaries cannot be changed. Other general properties of the dictionaries are editable. The reserved dictionaries are included on a reserved form, the Customer-Initiator form. Form contents and appearance can be defined and its behavior manipulated by any form rules or Interactive Service Forms (ISF) available.

The reserved dictionaries list all available personnel information, and allows to designate which attributes should be part of each dictionary. Choose the attributes to be included in the dictionary by checking the corresponding attribute name. For example, include Supervisor information, since some service requests may require the customer’s supervisor’s approval. Attribute names and data types cannot be changed. Ensure that you include any attributes that need to be manipulated in a service, even if the field will always be hidden. Choosing the attribute ensures that it is populated with the corresponding value from the person’s profile. Designers can then configure the form containing the dictionary to hide the field as appropriate.

The personnel profile includes 10 custom fields (named Custom1 through Custom10) that are not used by Service Catalog. Any of these fields can be included in the Customer or Initiator dictionary. Some of these fields may be mapped to person attributes imported via directory (LDAP) integration. Others may be reserved for assignment or manipulation via the Display Properties or Conditional Rules available when configuring the Customer-Initiator Active Form Component which includes this dictionary.

For a Person Based dictionary and reserved dictionaries (Customer and Initiator dictionaries), you use the Dictionaries component of Service Designer to choose which dictionary fields (attributes) will appear on a service form. Simply navigate to the dictionary, and check or un-check the check boxes in the “Use” column to determine which fields are used, or included, on a form that uses the Person Based dictionary, or on the Customer-Initiator form—the active form component which automatically includes both Customer and Initiator dictionaries.

In addition to a customer or initiator's first and last name, and login ID, it is common to add fields for the person's email address, and home OU. The Person_ID is the unique identifier assigned to the person. Basic form processing does not require use of this field; however, it may be useful in writing data retrieval rules, for example, to dynamically retrieve additional information about the person or his/her supervisor that does not have a corresponding attribute in the dictionary. Similarly, the Supervisor_ID is also selectable for inclusion in the reserved dictionaries. This would allow the service designer to dynamically construct a “chain of command” for approval of chosen requests.

Similarly, you may want to include location information, especially in the Customer dictionary. This information may be required, for example, to determine which queue a task should be routed to, or simply to indicate the person’s address, in case contact via an actual physical visit is required.

The Integration dictionary group is automatically created in all Service Catalog instances. Any dictionary that is created through the Integration Wizard (Service Designer’s wizard for creating web services integrations between Service Catalog and external systems) is automatically placed in this group. Once created, integration dictionaries can be moved to any dictionary group. Designers cannot manually place dictionaries in this group.

Access control that must be granted to a form component used in multiple services may need to vary on a service-by-service basis, depending on the service teams involved in the fulfillment of each request. Additional participants for viewing/editing dictionaries can be added to the service definition. To do so, choose Service Designer > Services > Form, select the dictionary, then add the appropriate Participants. No other changes can be made to Access Control settings at the service level.

Standards can also be imported using options similar to those available for service items—either the standard definition, the standard entries, or both can be imported. Service Item Manager includes the following methods for importing service items and standards:

• The Import Data option in Service Item Manager allows administrators to import service items or standards on demand from file. See Importing Standards from File.
• A request can include a Service Link task to import service items or standards. See Importing Service Items and Standards using Service Link.

To edit an existing rule, review or modify the events to which the rule has been attached on the Active Form Behavior tab.

Examples of a Conditional Rule

Here are some conditions that might be useful in a service form, with the actions they might entail:

Note	Grid dictionaries and their fields cannot be chosen as the “Triggering Condition” for conditional rules.

The Context Condition: In some cases, the Context may seem redundant—for example, a request is only visible in the Ordering moment in My Services. However, a service form may be viewed in the Service Delivery moment within Service Manager by task performers and within My Services by the user who originally submitted the request. Similarly, a form may be viewable by multiple participants in the Service Delivery moment. You may want to vary the form's behavior or appearance depending on who is doing the viewing, and where.

The Does Unsubmitted Requisition Exist Condition: When a requisition is initiated, it is in the Ordering Moment. At this time any rules or ISF functions that “prefill” form fields with default values are typically executed. The end user may complete data entry and immediately click Submit. In that case, assuming all data in the form is valid, the requisition goes from the Ordering Moment to next moment defined for that service.

In certain circumstances the user may save the requisition without submitting it by clicking “Add and Review”. For example, a user may save a requisition if not all data for the requisition is available; if additional services must be added to the same requisition; or if an attachment must be added. The user may edit an unsubmitted requisition by choosing it in My Services.

When an existing requisition entry is opened for edit before the requisition is submitted, the “Does Unsubmitted Requisition Exist” condition is true; it is false at all other times. Use this condition, for example, to ensure that a rule that prefills default values, is executed only for new requests, not for any requests that have not been saved. This ensures the data the user has previously supplied is not overwritten.

The Moment = Service Delivery Condition: The Service Delivery Moment may encompass many tasks. If a rule is to be conditionally executed for a particular task, use the Task Name condition.

The Task Name Condition: Be careful when referring to a Task Name, since this is a descriptive field that can freely be changed in Service Designer. This problem is minimized if service design guidelines are developed and strictly enforced for naming tasks.

Service designers sometimes include namespaces in task names. For example, the namespace #Name#, referring to the service name, is used to differentiate the same task when it occurs within multiple services. The Task Name used by a conditional rule has all Namespace references properly evaluated. String operations (only checking the beginning or end of the task name, or checking for a phrase contained within the task name) can be used to compare against the portion of the task name that is not derived from the namespace.

Operators in Conditions: The available operators are context sensitive, displayed in a drop-down list that depends on the condition you have chosen. For example, since a field may contain numeric, alphanumeric, or date data, both arithmetic and string operations are allowed, as well as operators to determine the usage of the field. Task and service names are text, so only string operations are appropriate. For conditions that are either true or false, or for which only a limited number of options are possible (such as the current context), radio buttons are available.

Dictionary Field	Task and Service Name	Is Order on Behalf/Does Unsubmitted Req. Exist

Most of the operators that can be applied to dictionary fields check the value of that field, comparing it to the value of the specified or literal field. Of these operators, only “is equal to ignore case” is case-insensitive. All other operators are case-sensitive; be sure to take this into account when writing rules such as “starts with” and “contains”, which operate on alphanumeric data.

Other operators, such as “exists on the service form” and “is read only” refer not to the value of the field but to its usage. You do not need to use these rules under most circumstances, since the runtime rule framework automatically checks for the presence of a field on the form and its usage before attempting to execute a rule.

Variables in Conditions: The value of any field in any dictionary may be used in a condition. Since the dictionary may not be included in the current form, the service designer must ensure that forms containing all dictionaries referred to in the rule are included in the service.

Combining Conditions within One Rule: Multiple conditions can be combined and evaluated to determine if the rule’s actions should be executed. In this case, the rule must include Boolean operators (AND, OR) and may include parentheses to alter the normal precedence of these operators.

The conditions essentially build an “if” clause. The Rule Builder does not currently support an “else” clause. If you need to apply if/then/else logic, define two rules with conditions that are mutually exclusive:

Actions are summarized in the table below:

Grid dictionaries are different from nongrid dictionaries in the way they are rendered in the browser and stored in the WDDX generated in the database. Therefore you will need a mixture of conditional rules and ISF functions to manipulate individual cells. This section covers the conditional rule actions and ISF functions that can be used on grids.

In order to modify an existing data retrieval or conditional rule, you must edit the rule, apply the desired changes, and navigate through all pages of the Rule Wizard. The Save button is available only on the last page of each wizard. This process ensures that all aspects of the rule are internally consistent.

Changes to the dictionaries and fields may not automatically be propagated to a rule that uses the corresponding dictionary, field or lightweight namespace. If you change the name of a dictionary or field, you must edit the rule, navigating through all pages. For conditional rules and table-based data retrieval rules, references to the dictionaries or fields are updated automatically as you proceed through each page. For SQL entry data retrieval rules, you must re-enter the SQL code, using correct lightweight namespaces.

If you delete a field or dictionary, you must edit rules to remove references to the deleted object. If a rule that previously worked suddenly stops working, a renamed or deleted object still referenced in the rule is a probable cause.

An SIBD has one unique property—the ability to automatically retrieve and prefill data about an existing service item instance. For a chosen form, this option is found on the Display Properties tab for the service-item-based dictionary.

“Enable automatic retrieval of service item instance data” should typically be checked if the service is to be used to update or delete an existing service item. To take advantage of this prefill capability, you may need two form components based on the same service item dictionary—one to be included in services where the item is created and the second to be included in services that update or delete the item.

The drop-down list for Table Name is populated to include:

• Any service items defined in Service Item Manager supplied with all Service Catalog installations
• ServiceItemHistory, a table automatically maintained to track the history of a service items
• ServiceItemSubscription, a table automatically maintained to track subscriptions (the current status) of service items

You can then proceed to complete the rule definition as you would for any table-based data retrieval rule. For details on defining rules, see Configuring Dynamic Form Behaviors Using Form Rules.

Figure 3. New Rule

You can use a service item in a SQL-entry data retrieval rule by referencing the database table name which the system assigns to the service item. The table name is the prefix “Si” followed by the item name, with spaces removed. An easy way to find out the database table name (without returning to the Manage Service Items page to look up the item’s name) is to define and save a table-based rule using the service item. The generated SQL on the Summary page includes the table name.

Any dictionary field may have an associated button, as specified in the “Add a Button” section of the Display Properties for the field:

Figure 9. HTML Representation

Figure 10. Remedy Ticket Numbers

You can specify a caption (text to appear on the button) and a URL. The URL can point to a JavaScript function or to an external page accessible elsewhere on the network.

When referring to an external web page, use the fully qualified URL.

• The URL may point to a JavaScript function, available in a library, or embed JavaScript code. Form data cannot be included in the parameters, if any, included in a function call. However, the function can include ISF.
• The Send Data option is applicable only to an external web page. This will POST a response to that page including all of the data on the current form.

The disadvantage of using an associated button, rather than placing code in an event handler, is that the user must use an extra keystroke (clicking on the button) to invoke the code. Consequently, buttons are best reserved for events that need to occur on demand, not in the course of regular form processing, or for extended dialog boxes or browsing of external sites.

Simply specifying a URL brings up the specified web page in a separate window. However, the window is not resizable and does not include scroll bars. Therefore, for some applications, it might be preferable to use JavaScript to display the web page in a window that you explicitly specify. Sample code is shown below.

javascript:window.open ("http://www.coder.com", "mywindow","status=1,toolbar=1, scrollbars=1, width=500, resizable=1"); 

The JavaScript all has to be on one line (no carriage returns). See sample output (primitive, but you get the idea) below. The above line is copied and pasted from the URL entry for the button with the “URL with JavaScript” label.

Storing JavaScript in an external JavaScript (library) file has the following benefits:

• Code for many functions is maintained in one place rather than requiring the user to navigate to different screens, as would be the case if each event had a function attached in Script Manager.
• Maintaining the code in a file makes it easier to version control the source code.
• Maintaining the code in a text file makes it easier to do global search-replace and execute searches on the file.
• A JavaScript library is simply an ASCII file which resides on the application server. As such, you can use a powerful editor to maintain file contents.
• Since the same piece of code is referenced from one or more functions, changes only need to be made at one location and tested only once.

In principle, all client code could be included in one library. However, under some circumstances it might be advisable or required to divide the code into multiple libraries.

• One or more JavaScript libraries can be used, grouping the ISF functions so that those that are likely to be used in the same service or group of services are in one library, and those used by another set of services are grouped in another. This allows multiple sets of developers, potentially working on independent projects, to keep their work separate.
• If using multiple, independent libraries, the libraries should never be attached globally to the service forms (using the “Include this library in all functions” check box on the “Library” page of the Scripts option). Instead, the relevant library (libraries) should be included in a function attached to the “onLoad event” of a form (using the “Libraries” tab of the “Scripts” page).
• Similarly, the onLoad event to which the relevant library is attached should not be included in all forms (using the “Add this script...when the form is loaded (browser-side)” option on the Scripts page). Instead, it must be associated with the event using the Active Form Behavior tab for the form in the Active Form Components.
• There is a theoretical advantage in placing ISF functions likely to be used in the same service in one library and those functions that are rarely used, or used under well-defined circumstances, in another. The advantage would be a reduction of memory used (functions not required for a particular service are not loaded). However, since memory is relatively cheap and plentiful these days, and the amount used by ISF functions is minor compared to that used by other components, so no practical advantage have been observed.

The ISF you write will be in JavaScript functions. If the functions apply to a specific dictionary or field within that dictionary, the function names should reflect this hierarchy. This makes it much easier to track function usage. Function names follow the convention:

• dictionaryName_event
• dictionaryName_fieldName_event

For example,

• RC_REQUESTEDBY_onLoad
• ST_HighProfile_onSubmit
• ST_UserLocation_FieldOffice_onChange
• SVC_Phone_PhoneType_onClick

In addition to dictionary- and field-specific functions, Cisco Advanced Services may create the following site-wide functions, which may be modified as required:

• rc_CommonService_onLoad
• rc_CommonService_onSubmit
• siteRC_REQUESTEDBY_onLoad
• siteRC_REQUESTEDFOR_onLoad

This naming convention makes it easier to understand how each script is used, and to find the appropriate place to create any new functionality. It also allows site-specific code to interface correctly with ISF code that may have been installed in conjunction with a standard service library.

We recommend that ISF JavaScript functions be placed in an external JavaScript library. It is important to order the functions within that file, to facilitate finding a particular function.

All code should be stored in ANSI text files without tabs, using 2-space indentation for clarity of reading and understanding. Lines should not be longer than 76 characters each.

Be very careful changing the names of fields in a dictionary. If a field is referred to in a function, that function will stop working.

Every standard property and method in JavaScript starts with a lower case character, and the next word starts with an upper case character. For instance the property “readOnly” or the method “onSubmit” follow this convention. Although it is not enforced in ISF, following similar conventions is recommended.

Using the Libraries option under Service Designer > Scripts, you can place custom ISF code in one or more JavaScript libraries. Since the library is a text file, external to the application, you need a text editor to maintain the library contents. A JavaScript-aware editor or development environment is highly recommended. Third-party JavaScript libraries may also be used in conjunction with ISF.

To be accessible by the service form, the library must reside within the directory structure on the application server, mapped to the URL/RequestCenter. By convention, the library is placed on a directory named, isfcode located directly under the root. The physical location of the /RequestCenter site may vary according to how Service Catalog is installed on your server and the application server in use. Please consult your system administrator to determine the physical location on which the ISF libraries need to reside. You also need to ensure that ISF developers have read/write access to this directory and a tool for transferring files to the directory.

A reference to the library (implemented as an HTML script tag) must be included in the generated service form in order for functions in the library to be used in the service form. This reference may be generated in one of two ways.

• Use the Libraries tab of the JavaScripts node of the Scripts option to associate the library with a particular function. The library is then available in all forms that use the function.
• Use the “Include this library in all functions” check box on the Library option of Scripts to include the library in all service forms.

This is the recommended approach to including a library reference in a service form. There should be a function that is invoked as an onLoad event. Libraries are then included in that function. One or more onLoad functions may be coded. Each may have a different set of libraries attached. In this way different teams of developers have control over which libraries are available to their service forms.

Note	The loading sequence of the JavaScript libraries is not controlled by the application and can be influenced by known and unknown environmental variables such as Application Server, OS version, and Database Type.

The “Include this library in all function” check box on the Library page is a misnomer; it should be “Include this library in all forms” since the library is only loaded once per form. Using this check box puts the <script> tag for the library at the beginning of the generated HTML page, ensuring that the library and its functions are present when the page-level ISF calls it.

This methodology is not recommended for complex projects.

Note	The loading sequence of the JavaScript libraries is not controlled by the application and can be influenced by known and unknown environmental variables such as Application Server, OS version, and Database Type.

At this point you have a library (which possibly contains no code) and a specification to use the library for all service forms. You can verify your work by running a service form, looking at the source code, and searching for the name of your library. To view the source code of a service form, you cannot use the “View Source” option of your browser. Because the service form is displayed as a frame within an HTML page, its generated source is not displayed. Instead, move the mouse pointer to within the service form (not within a field) and use the right mouse button option to “View Source”. A search shows the name of the library.

Due to the difficulty of debugging in an HTML and JavaScript environment, it is recommended that your write, debug, and test one function at a time while writing the code.You may, of course, edit the library file containing your JavaScript locally; but to test it, it must be copied back to the designated directory on the application server. When initially developing code, or if your access to the application server is limited, it may be easier to write the code within a Script and refactor when you are done, moving the function to the library and leaving only a wrapper function, which calls the library function, under the Scripts. Make sure that you save often and keep backup copies in case you need to revert to a previous version of the code.

Once the code is written, it needs to be attached to an event in the form. Since the service form HTML page is generated dynamically, you must use Service Designer to do this. See the Adding Functions Arguments to JavaScript for more information. To attach a field-level event to a dictionary field:

• Write the function in the JavaScript library. Name it dictionaryName_fieldName_event , for example, RC_REQUESTORLOCATION_LocationName_OnChange.
• Name the function with a site-specific code prefixed to the name of the function you previously included in the JavaScript library. Service Catalog-provided functions (for example, those used in services included in the Service Catalog libraries) use an “rc” prefix, so the code would appear as shown here:

rcRC_REQUESTORLOCATION_LocationName_onChange () {
 RC_REQUESTORLOCATION_LocationName_onChange();
}

• Use the Active Form Behavior tab of the Active Form Components option to attach the function to the appropriate field-level event. Choose the field and triggering event, then add the function by clicking Add JavaScript. (If the dictionary is used in multiple forms, the function must be attached to the dictionary field in every form. This is not recommended.)

ISF code is attached to an active form which can be reused in many services. However, it is not sufficient to test just one service. For example, you may have code that assumes that a field in a dictionary in another form is also present in the service; if that is not the case, your ISF code will fail with a JavaScript error. Therefore, you need to set up a testing matrix based on the different combinations of forms that can be used. Especially in the initial phases of testing, it is useful to run multiple sessions of Service Catalog simultaneously.

• Start Service Designer in one browser, with the option set to Scripts (to make changes to function code) or Active Form Components: Active Form Behavior (to change JavaScript attachments) displayed.
• Run My Services or Service Manager in the other browser, to test the service form in the moments for which rules or ISF have been defined.
• If you are testing code that resides in a library you will, of course need another window: to edit the library file and upload your changes to the application server.

If a JavaScript error is encountered, the JavaScript debugger is displayed. After you have fixed the error (by editing the function or library code) and dismissed the debugger, there is no reason to exit the current service form and start a new request. Simply refresh the page to cause the current service form to be reloaded with the new ISF code.

If the Browser Cache setting is enabled in the Administration Settings, changes made to the JavaScript libraries will not take effect until the browser cache has been deleted. Therefore in a development environment, it is best to disable browser caching. When modifications to JavaScript libraries are deployed to the production environment where browser caching might be enabled, application users will need to delete their browser cache. To prompt the application users to do so, follow the instructions in the Cisco Prime Service Catalog Administration and Operations Guide to increment the browser cache version.

The Syntax for Specifying a Service Item or Standards Import File table summarizes the syntax for specifying a service item or standards import file. The same syntax applies to both service items and standards. Each XML file consists of one SI Import Specification.

The Import Specification (SIImportSpec), in turn, consists of a SIClassDefinition, followed by a list of one more SIInstances for the specified class (Service Item or standard). One or both of the class definition and instances may be included in the file. File content should match the import options specified.

Each SIClass specification consists of the service item/standard definition, embedded within appropriate XML tags, followed by the definition of each of the attributes.

Each attribute definition specifies the name, caption, and other configuration options specified for the attribute.

Each service item instance (SIInstance) specifies the name of the service item/standard to which the instance applies and a list of the values for each of the attributes of the item. If an attribute value is blank, appropriate tags must still be included in the import file, with no value specified for the attribute.

The datatypes do not exactly match the datatypes specified when you define a Service Item or Standard using Service Item Manager. Map the Service Item Manager datatypes to those used in the import file using the Import File Datatype fro Service Item Manager Datatype table.