Working with Guided Assistance

3 Working with Guided Assistance

This chapter provides information about guided assistance, how to create guided assistance in Oracle Communications Service Catalog and Design - Design Studio, and how to distribute guided assistance.

Working with Guided Assistance

Design Studio guided assistance is a range of context-sensitive learning aides mapped to specific editors and views in the user interface. For example, when working in editors, you can open the Guided Assistance dialog box for Help topics, cheat sheets, and recorded presentations that are applicable to that editor.

When working with guided assistance, you can review the learning aids delivered with Design Studio, and you can create your own and map them to projects and entities by using design patterns or by defining values for attributes directly in the guided assistance extension point.

About the Guided Assistance Dialog Box

You can access learning aids delivered in Design Studio by opening the Guided Assistance dialog box, which is available from the Studio menu, the main tool bar, and from the Studio Projects view context menu.

The learning aids included in the Guided Assistance dialog box are organized into categories that reflect a specific domain. For example, the Order and Service Management Project directory includes a category called Order, which includes learning aids that help you define and configure orders.

The Guided Assistance dialog box is organized in the following hierarchy:

The root level contains global guided assistance that is not specific to any cartridge project.
The second level is organized by project type and contains guided assistance for specific cartridge projects.
The third level contains entity-specific guided assistance for each project type.
The fourth level contains folders that include learning aids that are specific to functionality within an entity.

Folders appear only when there is guided assistance available at the corresponding folder level. When you first open the Guided Assistance dialog box, the hierarchy expands to the folder relevant to the context in focus. If no guided assistance is mapped to the active context, the hierarchy will appear fully collapsed. You can navigate to any folder level in the hierarchy, regardless of the context in focus.

Working with Guided Assistance Design Patterns

You can create and implement new guided assistance by using design patterns delivered with Design Studio.

These design patterns are preconfigured for guided assistance development and can help you create a directory structure where Design Studio users can save guided assistance learning aids. After applying a guided assistance design pattern, this directory structure appears in the plugin.xml file.

Creating Guided Assistance Using Design Patterns

The following procedure describes how to create your own guided assistance using design patterns.

To create new guided assistance using design patterns:

In Design Studio, verify that the Oracle Communications Design Studio Design Pattern Feature is installed.

Contact your system administrator if this feature is not available.
From the Studio menu, select Design Pattern.

The Design Pattern dialog box appears.
Expand the Others folder.

A list of guided assistance folders appears, one for each Design Studio project type.
Expand the folder for the project type for which you want to add guided assistance.

For example, if you are adding guided assistance for model projects, expand the Guided Assistance Design Pattern for Model folder.
Select the design pattern and click Next.

The Design Pattern wizard Introduction page appears.
Read the information on the Information page, and then click Next.

The Select Project page appears.
Do one of the following:
- To use an existing project for guided assistance development, select a plug-in project in the Guided Assistance Plug-in Project field.
- To create a new project for guided assistance development, click New.
Click Next.

The Plug-in Information page appears.
Enter all required information, and then click Next.

The Summary page appears.
Review the summary information, and then click Finish.

Design Studio populates the project with information necessary to build the guided assistance for the designated project type. The information includes a manifest and a guidedAssistance directory, which contains the folder structure for the project type and all plug-in related configuration for the packaging of the guided assistance. When you finish the wizard, Design Studio opens the Guided Assistance cheat sheet in the Help view.
(Optional) Modify the cheat sheets in the oracle.communications.sce.guided.assistance.feature.

The cheat sheets should provide help to users who apply the guided assistance design pattern. The information should describe how to copy guided assistance learning aids to the folder structure created by applying the design pattern.

Working with the Guided Assistance Extension Point

You use the guided assistance extension point (com.mslv.studio.core.ui.studioGuidedAssistance) to register the learning aid content locations.

In the plugin.xml file (located at the root of the plug-in project), you define attributes for the extension point to register guided assistance (for example, cheat sheets, HTML files, and Help documents) content locations that are applicable to:

All project types (globalGuidedAssistance)
A specific project type (cartridgeGuidedAssistance)
A specific entity type (entityGuidedAssistance)
A specific functionality in an entity type (guidedAssistanceContent, which is a child element of entityGuidedAssistance)

Table 3-1 Guided Assistance Extension Point Attributes

Attribute	Element Used In	Use
guideName	globalGuidedAssistance cartridgeGuidedAssistance guidedAssistanceContent	Enter the display name that appears in the Guided Assistance dialog box for the learning aid. If you define no value for helpContextId, the name you define here is displayed for the contentLocation, but only when the location refers to a single file; otherwise this value is ignored.
contentLocation	globalGuidedAssistance cartridgeGuidedAssistance guidedAssistanceContent	Enter the folder location for the learning aid.
helpContextId	globalGuidedAssistance cartridgeGuidedAssistance guidedAssistanceContent	Enter a unique ID that represents the learning aid. Design Studio uses this value to display the appropriate Help page. Optionally, you can specify the Help URL. Use the following format to define a Help context ID: pluginId.contextId For example: com.company.product.help.myContextId
projectTypeId	cartridgeGuidedAssistance (optional) entityGuidedAssistance	Enter a fully qualified ID of the project type to which the learning aid is related. The projectType extension can be defined in any plug-in (that is, it does not need to be defined in the same plug-in as cartridgeGuidedAssistance).
entityId	entityGuidedAssistance	Enter the fully qualified name of a modelType extension. The extension can be defined in any plug-in (that is, it does not need to be defined in the same plug-in as entityGuidedAssistance). The Package Explorer view model folder includes an entityId for each entity in a project.
folderId	guidedAssistanceContent	Enter the name of the folder in which the learning aid should appear in the Guided Assistance dialog box.

Guided Assistance Extension Point Example

Example 3-1 shows how you can configure the attributes for the guided assistance extension point:

Example 3-1 Example: Guided Assistance Extension Point

<extension
  point="com.mslv.studio.core.ui.studioGuidedAssistance">
   <globalGuidedAssistance
         contentLocation="guidedassistances/"
         guideName="Global Guides Location">
   </globalGuidedAssistance>
   
     <cartridgeGuidedAssistance
         contentLocation="guidedassistances/ModelProject/"
         guideName="Data Dictionary Wizard Help"
         helpContextId="com.mslv.studio.core.help.DataDictionaryWizard"
         projectTypeId="com.mslv.studio.core.datadictionary.project">
     </cartridgeGuidedAssistance>
      <entityGuidedAssistance
            entityId="com.mslv.studio.core.dataDictionary">
            projectTypeId="com.mslv.studio.core.datadictionary.project">
        <guidedAssistanceContent
            contentLocation="guidedassistances/ModelProject/DataSchema/"
            guideName="Data Schema Guides"></guidedAssistanceContent>
      </entityGuidedAssistance>
     
      <cartridgeGuidedAssistance
           contentLocation="guidedassistances/OSM/"
           guideName="OSM Guides"
           projectTypeId="com.mslv.studio.provisioning.project">
      </cartridgeGuidedAssistance>
       
      <entityGuidedAssistance
           entityId="com.mslv.studio.provisioning.process">
        <guidedAssistanceContent
            contentLocation="guidedassistances/OSM/order/"
            folderId="com.mslv.studio.provisioning.order">
        </guidedAssistanceContent>
        <guidedAssistanceContent                     
            contentLocation="guidedassistances/OSM/process/creationTask/"
            folderId="orderCreationTask">
        </guidedAssistanceContent>
      </entityGuidedAssistance>
     
      <entityGuidedAssistance
            entityId="com.mslv.studio.provisioning.order">
        <guidedAssistanceContent
            contentLocation="guidedassistances/OSM/order/">
        </guidedAssistanceContent>
      <guidedAssistanceContent
        contentLocation="guidedassistance/OSM/video/722_whats_new.htm"
        guideName="Design Studio 7.2.2 What's New Video">
      </guidedAssistanceContent>
      </entityGuidedAssistance>
</extension>

Distributing Guided Assistance

You save guided assistance in Eclipse plug-in projects. Plug-in projects are grouped into features, and your system administrator can make these features available to other users by adding the feature to your Design Studio update site.

To distribute guided assistance:

From the File menu, select New and then select Project.

The New wizard appears.
Expand the Plug-in Development folder.
Select Feature Project, and then click Next.

The New Feature wizard appears.
Enter the information required by the wizard, and then click Finish.

The new feature appears in the Feature editor.
Click the Plug-ins tab.
Click Add.
Add the plug-in project in which you saved the guided assistance.

You can add any number of projects to the feature.
Contact your system administrator to request that the new feature be added to the Design Studio update site.

See Eclipse Plug-in Development Environment Guide for information about using feature projects. The samples included in the Design Studio software package demonstrate how your system administrator can configure feature projects.

About the Design Pattern and Guided Assistance SDK Folder

The design pattern and guided assistance SDK folder is a root-level folder included in the Design Studio software package available on the Oracle software delivery website:

https://edelivery.oracle.com

It includes the following:

A samples folder

This folder contains the Pattern folder and a Guided Assistance folder.

The Pattern folder contains the oracle.communications.sce.pattern.sample.zip archive file, which includes the following projects:
- oracle.communications.sce.pattern.sample contains the plug-in project (plug-in.xml) that includes a single design pattern.
- oracle.communications.sce.pattern.sample.feature contains the feature project (feature.xml) that you can use for building and distributing the plug-in project.
- oracle.communications.sce.pattern.update.site contains an update site project (site.xml) that illustrates how your system administrator can build an update site for delivering your feature to end users.
The Guided Assistance folder contains the oracle.communications.sce.guidedassistance.sample.zip archive file, which includes the following projects:
- oracle.communications.sce. guidedassistance.sample contains the plug-in project (plug-in.xml) that includes guided assistance mappings.
- oracle.communications.sce. guidedassistance.sample.feature contains the feature project (feature.xml) that you can use for building and distributing the plug-in project.
- oracle.communications.sce. guidedassistance.update.site contains an update site project (site.xml) that illustrates how your system administrator can build an update site for delivering your feature to end users.
See the Design Studio Help for information about importing projects into your workspace.
A schema folder

This folder contains the Design Pattern XML schema (DesignPattern.xsd), which is a standard XML Schema document. You can review the contents of this document using any schema or XML editor.