Working with Design Patterns

2 Working with Design Patterns

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

About Design Patterns

Design Studio design patterns are wizards that automate complex, repeatable tasks, and that enable team members with varying levels of skill to complete those tasks. When extending solutions, you may be required to repeat design activities multiple times and in a specific order. Design patterns enable you to define a generic pattern that, when run, automates the creation of model objects and their relationships in a user's workspace. Your teams can use design patterns to reduce errors, simplify modeling, and increase productivity.

Typically, designers create design patterns using information identified from existing reference implementations and sample solutions. For example, a designer can identify common modeling tasks and the key resources included in those tasks, then create a design pattern to formalize those tasks into a reusable modeling pattern (one that is not specific to any domain). The designer then distributes the design pattern to solution design teams.

Solution design teams install design patterns as Design Studio features and, using wizards, apply the patterns to their workspace. These wizards ensure compliance with the best practices and reduce the need for coding and complex configuration.

When a user runs a design pattern, a domain-specific implementation of the design pattern is run in the user workspace. For example, you might create a design pattern that creates customer edges or provider edges in a VPN. Or, a user might run a design pattern to set up a Technical Order Management layer or a Service Order Management layer for a solution.

About the Design Pattern Framework

The design pattern framework includes:

A Data Model

The data model includes all of the entities and data elements that realize the pattern, how that data is organized in the workspace, the expected user input and how the input is applied to the workspace, and the embedded Help available when the user runs the design pattern.
A User Interface

Users interact with design patterns using the Design Pattern wizard. The wizard collects information from the user. The information that the design pattern requires can be organized onto different wizard pages, can be augmented with hints or embedded help, and can be validated when entered by the user.
An Implementation Processor

When a user completes the Design Pattern wizard and clicks the Finish button, the design pattern applies the user input against the entities and data elements defined in the design pattern data. The design pattern generates and organizes the entities and data elements in the user workspace.

About the Design Pattern Development Life Cycle

The life cycle of a design pattern begins with the identification and isolation of the pattern itself. Working from a reference implementation, designers identify the repeatable pattern, which comprises the resources and the relationships of the resources to the workspace.

The tasks in the life cycle of a design pattern are completed by two different actors, a designer who creates and distributes design patterns, and a user (solution designer) who installs the design patterns and then runs the patterns to facilitate solution development.

Designers do the following:

Evaluate common modeling tasks and key resources in reference implementations, sample solutions, and best practices. then identify which repeatable tasks can be automated in a design pattern.
Develop design patterns using the identified resources as key components of the design patterns.
Test design patterns by running them in the Design Studio environment.
Include design patterns in plug-in projects, associate the plug-in project to a feature project, and associate the feature project to an update site.
Distribute update sites to Design Studio users.

Design pattern users do the following:

Install features based on their role and objectives.
Run design patterns to assist with solution design.

About the Design Pattern Development Environment

Design patterns are built into Eclipse plug-in projects, and plug-in projects are associated with feature projects. See "About Plug-in Projects" for more information.

Figure 2-1 Design Pattern Development Environment

Description of "Figure 2-1 Design Pattern Development Environment"

The number of plug-in projects that you use depends on the number of design pattern designers and whether the team members prefer to own their own plug-in projects. For example, team members may prefer to manage their own plug-in projects during the development cycle to avoid difficult source code merges.

To facilitate ease of distribution and maintenance, partition the design patterns across plug-ins so that common design patterns can be distributed to distinct audiences.

About Design Pattern Folder Structure

In a design pattern plug-in project, each pattern is assigned a folder:

plug-inID/pattern/patternID

where plug-inID is the name of the plug-in project and patternID is the name of a design pattern in the pattern folder.

Designers develop all of the design pattern resources in a folder structure. Figure 2-2 illustrates an example of the folder structure as viewed in the Package Explorer view when you create a plug-in project using the Design Pattern Development design pattern.

Figure 2-2 Design Pattern Folder Structure Example

Description of "Figure 2-2 Design Pattern Folder Structure Example"

In your plug-in project pattern folder, there exists a folder for each design pattern. For example, in Figure 2-2, the pattern folder contains a single design pattern called SamplePattern.

Each design pattern folder contains subfolders and a pattern.xml file:

cheatSheet: include one or multiple cheat sheets. For example, you might include a cheat sheet that the design pattern initiates to provide additional information to the user who runs the design pattern.
dataDictionary: include all data schemas and all data dictionary companion files relevant to the entities generated by the design pattern.
model: include the definitions of the entities generated by the design pattern. For example, you include all of the resources (suffixed with .pat extension) generated by the design pattern.
resource: include the design pattern resources that are not Design Studio model entities. For example, this folder can contain Java or XML files.
pattern.xml: define the contents of the design pattern model.

About the pattern.xml File

Each design pattern has a pattern.xml file that defines the contents of the design pattern model. In addition to the high-level attributes defined for the pattern.xml file (for example, the namespace, pattern ID, and name attributes), the file also includes the sections in Table 2-1.

For detailed descriptions of the elements and attributes in the pattern.xml file, see the Design Pattern XML Schema, which is named DesignPattern.xsd in the schema folder, available in the Design Studio software package, which is available from the Oracle software delivery website:

https://edelivery.oracle.com

Table 2-1 pattern.xml Sections

Element	Description
version	The version number of the design pattern. For example, you can specify whether the design pattern is a major or minor release, or part of a service pack release.
description	The information that describes how the design pattern can be used. This information is displayed to users on the Design Pattern wizard Introduction page. See "Defining a Description for a Design Pattern" for more information.
includes	The list of existing design patterns in a workspace from which a design pattern leverages logic. See "Leveraging Logic from Existing Design Patterns" for more information.
contexts	The places in the Design Studio user interface where the design pattern is accessible. You can define multiple contexts for a design pattern to enable users to access the design pattern from multiple places in the application. See "Defining Context for Design Patterns" for more information.
projects	The valid target projects into which resources are saved when the design pattern is applied. See "Defining Target Projects for Design Patterns" for more information.
tokens	Placeholders that represent information to be entered by the user applying the design pattern. The information entered by the user customizes the resources in the manifest when the design pattern is applied. Tokens can be embedded in the target locations of resources in the manifest, in text documents that will be copied to a user's workspace, and in other tokens. See "Working with Tokens" for more information.
tokenGroups	The pages that appear in the Design Pattern wizard. Design pattern tokens are organized as pages in the Design Pattern wizard, where each page is a token group. You can define any number of token groups in a design pattern, and each token is associated with a single token group. See "Defining Token Groups for Design Patterns" for more information.
manifest	The list of resources included in the design pattern. The design pattern copies these resources to a user's workspace when the design pattern is applied. You can include in a manifest any type of resource that is valid in an Eclipse workspace. See "Defining the Manifest for Design Patterns" for more information.
actions	The actions that a user can perform on resources or inputs, such as creating relationships between or adding data elements to inputs or resources. See "Working with Design Pattern Actions" for more information.
inputs	The default information provided to the Design Pattern wizard to automatically populate token names. For example, if a design pattern creates actions for services, when a user runs the design pattern they can specify an existing service entity as input, and the design pattern uses that entity to generate the action. See "Defining Inputs for Design Patterns" for more information.
customActions	The custom actions that you define to call custom Java code from a design pattern. See "Defining Custom Actions" for more information.

Figure 2-3 displays part of an example pattern.xml file in the Design Studio default XML editor:

Figure 2-3 pattern.xml File

Description of "Figure 2-3 pattern.xml File"

Developing Custom Design Patterns

You create custom design patterns using groups of resources identified from an existing reference implementation or from a sample solution. After you create a design pattern, you package and distribute it to solution design teams. Solution design teams can install a design pattern as a Design Studio feature and, using a wizard, apply the pattern to their workspace.

To develop a custom design pattern:

Create and switch to a clean workspace.

See the Design Studio Help for information about switching workspaces.
Create a design pattern plug-in project.

See "Creating Design Pattern Plug-in Projects" for more information.
Model the design pattern.

You model design patterns in the pattern.xml file. See "Modeling Design Patterns" for more information.
Create custom Java code.

See "Invoking Custom Java Code from Design Patterns" for more information.
Build the design pattern plug-in project.

A successful project build indicates that the design pattern is built and ready for testing. See the Design Studio Help for more information about building projects.
Test the design pattern.

See "Testing Design Patterns" for more information.
Package the design pattern project.

See "Packaging Plug-in Projects" for more information.
Distribute the design pattern project.

See "Distributing Plug-in Projects" for more information.
Instruct team members to apply the design pattern.

See "Applying Design Patterns" for more information.

Creating Design Pattern Plug-in Projects

You can create design pattern plug-in projects using the Design Pattern Development design pattern. This design pattern creates the basic structure for design pattern model files.

To create new design pattern plug-in projects:

Verify that the Oracle Communications Design Studio Design Pattern Feature is installed.

Contact your system administrator if this feature is not available from your organization's update site.
In Design Studio, from the Studio menu, select Design Pattern.

The Design Pattern dialog box appears.
Expand the Others folder and then expand the Design Pattern Development folder.
Select Design Pattern Development and then 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.
Select an existing plug-in project to be used for the design pattern development or create a new design pattern plug-in project.

To create a new project:
1. Click New.
  
  The New Project page appears.
2. Expand the Plug-in Development folder and select Plug-in Project.
3. Click Next.
  
  The Plug-in Project page appears.
4. In the Project Name, enter a name for the design pattern plug-in project.
5. Accept the default values for the remaining fields or replace the default values with information specific to your installation.
6. Click Next.
  
  The Content page appears.
7. Accept the default values for the remaining fields or replace the default values with information specific to your installation.
8. Click Finish.
  
  Design Studio prompts you to open the Plug-in Development perspective. Oracle recommends that you develop design patterns using this perspective. Click Yes to switch to the Plug-in Development perspective.
  
  Design Studio populates the Design Pattern Plug-in Project field with the project you created.
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 a design pattern. The information includes a manifest, a resource directory, and all plug-in-related configuration for the packaging of the design pattern. Design Studio opens the Design Pattern Development cheat sheet in the Help view.
In the Design Pattern Development cheat sheet, click the Click to Begin link and complete the steps in the cheat sheet.

For example, the cheat sheet steps help you with tasks such as copying resources to the project, populating the design pattern manifest, building the design pattern, testing, and distributing the design pattern.

Modeling Design Patterns

Before you can begin to model the design pattern content, identify required resources from a reference implementation or a sample solution and copy the required resources to the location of your design pattern in your plug-in project.

To model design patterns:

Review the design pattern configuration data.

See "Reviewing Design Pattern Configuration Data" for more information.
Open the design pattern pattern.xml file.

Note:

Use the Design Studio default XML editor to edit the pattern.xml file. This default editor includes a Design tab with right-click context menu options and a Source tab to view the XML. Additionally, the default XML editor includes content assistance to help with tag completion and tag documentation.

For detailed information about the elements and attributes in the pattern.xml file, see the Design Pattern XML schema, which is named DesignPattern.xsd and is located in the Design Studio software package.

To open the pattern.xml file:
1. Open the Plug-in Development perspective. See the Design Studio Help for information about opening perspectives.
2. Click the Package Explorer tab.
3. Navigate to the location of your design pattern.
4. In the design pattern root directory, double-click the pattern.xml file.
  
  The pattern.xml file opens in an XML editor.
Add a description of the design pattern that displays on the design pattern Introduction page.

See "Defining a Description for a Design Pattern" for more information.
(Optional) Enable designs patterns to leverage the logic defined in other design patterns.

See "Leveraging Logic from Existing Design Patterns" for more information.
Define the context for the design pattern.

See "Defining Context for Design Patterns" for more information.
Define the types of projects into which the design pattern resources can be saved.

See "Defining Target Projects for Design Patterns" for more information.
Define the tokens for the design pattern.

See "Defining Tokens for Design Patterns" for more information.
Define the token groups for the design pattern.

See "Defining Token Groups for Design Patterns" for more information.
Define the manifest for the design pattern.

See "Defining the Manifest for Design Patterns" for more information.
Define actions for the design pattern.

See "Defining Actions for Design Patterns" for more information.
Define custom actions for the design pattern.

See "Defining Custom Actions" for more information.
Define the inputs for the design pattern.

See "Defining Inputs for Design Patterns" for more information.
Define a description for the design pattern.

See "Defining a Description for a Design Pattern" for more information.
(Optional) Write a new cheat sheet for the design pattern.

See "Working with Cheat Sheets" for more information.

Reviewing Design Pattern Configuration Data

Before configuring design patterns, review the MANIFEST.MF, build.properties, and plugin.xml files. The MANIFEST.MF file is in the META-INF directory. The build.properties and plugin.xml files can be found at the root of the project. These files contain dependencies to the required packages needed for design pattern development. They also include the registration and specific build properties required to build and package your design pattern.

Note:

When you are working on design patterns, many of the artifacts are not visible in standard Design Studio views. Use the Plug-in Development perspective and the Package Explorer view when working with design patterns. See the Design Studio Help for information.

If you are configuring the plug-in project manually (and not creating the design pattern plug-in project using the Design Pattern Development design pattern), ensure that you configure the data noted in the following files:

MANIFEST.MF

The name and version of the project and the required plug-ins. The oracle.communications.sce.pattern.core plug-in must be named as a dependency or your design patterns will not be visible when your plug-in is installed.
build.properties

The content that will be visible to other plug-ins after you have packaged your project. If you intend to locate design patterns in other folders, you must manually configure the location in the bin.includes section of the document.
plugin.xml

The design patterns contained by this plug-in. The plugin.xml includes an extension point named oracle.communications.sce.pattern.core.designPattern. This extension point has one entry in the section that points to the location of the pattern. You can add additional entries to package multiple design patterns within a single plug-in project. The Name and ID fields of the registration of a design pattern are not visible to Design Studio users. Rather, they are used only to add clarity to the registration. The ID field must be unique.

You can edit the content of these files using the Plug-in Manifest editor. See the Eclipse Plug-in Development Environment Guide for more information about using the Plug-in Manifest editor.

Defining a Description for a Design Pattern

You can provide a description of a design pattern to describe what the design pattern does when users apply the pattern, information that users require before running a design pattern, and what is required from users after applying the pattern. The description appears on the first page of the Design Pattern wizard.

To add a description to a design pattern:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
In the description element, provide a description of the design pattern.

Escape special characters if you use HTML tags.
(Optional) Insert images into the description.

The following is an example of the description element:

<description>
   &lt;b&gt;dp1title&lt;/b&gt;&lt;br&gt;&lt;br&gt;Enter explanation of the 
     design pattern here.&lt;br&gt;&lt;br&gt;Escape special characters if 
     using HTML tags.
   &lt;img 
      src="images\sampleImage.jpg" 
      alt="This is a sample image" 
      style="width:128px;height:128px;display: block;margin-left: 
             auto; margin-right: auto;" 
      align="middle"&gt;&lt;
   /img&gt;
</description>

Inserting Images into Description Elements

You can include images on a design pattern Introduction page by inserting the image in the description element of the pattern.xml file.

To insert images into the Introduction page, you define an img attribute with the following child attributes:

Use the src attribute to specify the location of the image.
Use the alt attribute to specify alternate text for an image. For example, you can use this attribute to insert text if the original image cannot be displayed because of slow connections or errors in the src attribute. This attribute is optional.
Use the style attribute to specify the size of the image. Also, you use this attribute in conjunction with the align attribute if you want more control over the image alignment. This attribute is optional.
Use the align to specify the alignment of an image on the page. You can align the image with the left, middle or right of the page. If you don't define an alignment, the image is left-aligned. This attribute is optional.

Note:

Inserting a high-resolution image may produce a horizontal scroll in a browser. An HTML limitation prevents the appearance of the horizontal scroll if the image is right-aligned.

You can also add images on the design pattern Introduction page by inserting a CDATA section:

<description>
   &lt;b&gt;dp1title&lt;/b&gt;&lt;br&gt;&lt;br&gt;Enter explanation of the 
   design pattern here.&lt;br&gt;&lt;br&gt;Escape special characters if using 
   HTML tags.

   <![CDATA[
        <img src="images\HomePhoneService.jpg" alt="Home Phone Service 
            image is not available" style="width:128px;height:128px;display:
            block;margin-left: auto; margin-right: auto;" align="middle"></img>
   ]]>
</description>

Leveraging Logic from Existing Design Patterns

You can create a design pattern, called a composite design pattern, that leverages the logic of existing design patterns and combines that logic with its own configuration. The ability to share logic among design patterns enables you to define common logic in a single design pattern and leverage that logic, as required. When users run a composite design pattern, the design pattern presents all of the fields, pages, and custom logic defined in all of the leveraged design patterns.

About Composite Design Patterns

When creating and running composite design patterns, consider the following:

You can leverage logic from any valid design pattern installed in the workspace.
You can leverage logic only from the following design pattern elements: manifest, projects, tokenGroups, tokens, actions, inputs, and customActions.
When an element (such as a project element, token element, and so forth) defined in a composite design pattern is defined with an id attribute that is identical to that defined for an element in a leveraged design pattern, the element defined in the composite design pattern is used.
If identical element id attribute values exist in multiple leveraged design patterns, the value defined in the design pattern that appears first in composite design pattern includes element list is used.
When a user runs a composite design pattern, pages (tokenGroup elements) defined in the composite design pattern appear before all pages defined in the leveraged design patterns. When the composite design pattern leverages logic from multiple existing design patterns, the pages defined in the leveraged design patterns appear in the order defined by includes element list in the composite design pattern.
When a user runs a composite design pattern, the tokens defined in the composite design pattern appear before all tokens defined in a leveraged design pattern. When the composite design pattern leverages logic from multiple existing design patterns, the tokens from the leveraged design patterns appear in the order defined by includes element list in the composite design pattern.

Defining the <includes> Element List:

When creating a composite design pattern, you define an includes element in the pattern.xml file to which you add the list of design patterns that contribute logic.

To define an includes element in the pattern.xml file:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add an includes element, and then add one or more child include elements.
Define the following attributes for each include element:
- For the id attribute, enter a value that uniquely identifies the leveraged design pattern.
- For the pattern attribute, enter the unique identifier of the design pattern from which this design pattern leverages logic.

The following is an example of the includes element:

<includes>
   <include id="Add_New_RFS_to_Tech_Domain" pattern="addRfstoExistingRfs" />
   <include id="Add_New_Resource_to_Tech_Domain" pattern="addResourceToRfs" />
</includes>

Defining Context for Design Patterns

You define the context for a design pattern to specify where in the user interface the design pattern will be accessible and to group design patterns in the Design Pattern Selection dialog box.

Because there are a large number of design patterns delivered with Design Studio, and because individual users can add to their environments additional custom design patterns developed post-market, defining context for your design patterns provides guidance to users by narrowing the scope of the design patterns that are available for a task.

To define context for design patterns:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add a contexts element and then add a context child element.
In the context child element, add a scope element.

The scope identifies where in Design Studio the design pattern will be accessible.

Enter one of the following values:
- project: use this value to make the design pattern accessible when a project is selected in the Studio Projects view.
- entity: use this value to make the design pattern accessible when an entity is selected in the Studio Projects view or Solution view.
- folder: use this value to make a design pattern accessible when a folder is selected.
- category: use this value to create an arbitrary grouping of design patterns that appear in the Design Pattern wizard (in the other folder).

Add an id element and enter a value to filter the scope of the context.

For example, if you defined the scope as entity, then you specify the types of entities in the id element.

Use the following values in the id element:

If you defined scope as:	Use the following values:
project	OSM, to filter for Order and Service Management projects. OSM_COMP, to filter for Order and Service Management Composite projects. UIM, to filter for Inventory projects. ACT, to filter for Activation projects. ACT_IPSA, to filter for Activation IPSA projects. ACT_SRT, to filter for Activation SRT projects. NI, to filter for Network Integrity projects. MODEL, to filter for Model projects.
entity	Use the file extension defined for the type of Design Studio entity for which you want to filter. For example, to filter for an OSM manual task, define the id element as manualTask.
folder	Define the id element with the file extension of the entity and the folder name, separated by a period. For example: productClass.fulfillmentPlan
category	Define the id element with the text to be used as a category heading in the Design Pattern wizard.

(Optional) Add a cheatSheet element and define the resource ID to identify the cheat sheet in the manifest.

The cheat sheet must be defined as a resource in the manifest element and the resource id element must be defined. The cheatSheet element must reference the resource id element. Also, you can define the cheat sheet element with a token.

After the design pattern completes, design studio launches the cheat sheet in the Cheat Sheets view. You can use cheat sheets to assist users with manual configuration required after the design pattern completes, or to display the user-specific resources that were created by the design pattern.

See "Working with Cheat Sheets" for more information.

The following is an example of the contexts element:

<contexts>
   <context>
      <scope>project</scope>
      <id>OSM</id>
      <id>UIM</id>
   </context>
   <cheatSheet>cheatSheet</cheatSheet>
</contexts>

Defining Target Projects for Design Patterns

When a design pattern is applied, each resource in the design pattern is copied to a single target project in a workspace. The projects element enables you to specify the number and type of target projects required by your design pattern. The user applying the design pattern can select an existing target project or create a new one. The type of project the user can select or create is limited to the types that you specify in the design pattern.

To define target projects for design patterns:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add a projects element, and then add a child project element.
Define the following attributes for the project element:
- For the id attribute, enter a value that uniquely identifies the project in a design pattern. You use this value if you need to make a reference to the project.
- For the name attribute, enter the value that appears in the Design Pattern wizard for the project field.
(Optional) Add a tokenGroup attribute and enter the name of the token group to which this project belongs.

A token group represents a page in the design pattern. You can group project elements in a group so that a project field appears on a specified page in the wizard.

If you do not define a token group, project tokens appear on the default project token page, which appears to the user following the Introduction page.
(Optional) Add the Sealed attribute.

Add the Sealed attribute to determine whether the design pattern creates a sealed or unsealed project, or whether to enable the user to determine the status after applying the design pattern. Define the Seal attribute with one of the following values:
- ALWAYS, to indicate that the design pattern creates a sealed project.
- NEVER, to indicate that the design pattern creates an unsealed project. This is the default value.
- OPTIONAL, to add a check box to the Design Pattern wizard that enables the user to seal the project after the design pattern completes.
(Optional) Add a defaultValue element and enter the information that appears initially for the project field in the Design Pattern wizard.

Users applying the design pattern can override default values. You can embed tokens in the defaultValue element, except for conditional tokens. See "Example: Defining Tokens as Default Values" for more information.

If the user running the design pattern does not have a Project entity with the default name defined in the workspace, then the user can click the Next button to create a project with the default value name.

If you are defining a default value for an Activation Service cartridge, you must also add the domain child element and the service child element. If you are defining a default value for an Activation Network cartridge, you must also add the vendor, the technology, and the softwareLoad child elements.
(Optional) Add a regularExpression element.

You can use regular expressions to enforce naming conventions. The value that you define in the message element is displayed to the user if the condition that you define in the expression element is not satisfied. See "About Regular Expressions" for more information.
Add a typeID element and enter a value.

The typeID element defines a project type to which this project belongs. Define typeID with one of the following values:
- OSM, to associate the design pattern with Order and Service Management projects.
- OSM_COMP, to associate the design pattern with Order and Service Management Composite projects.
- UIM, to associate the design pattern with Inventory projects.
- ACT, to associate the design pattern with Activation projects.
- ACT_IPSA, to associate the design pattern with Activation IPSA projects.
- ACT_SRT, to associate the design pattern with Activation SRT projects.
- NI, to associate the design pattern with Network Integrity projects.
- MODEL, to associate the design pattern with Model projects.
- OTHER, to associate the design pattern with a project type not listed above (for example, with a Java or plug-in project).
Add a description element and enter a description of the project.

The description appears in the Design Pattern wizard as embedded Help.
(Optional) Add a condition element and define a condition to dynamically control the visibility of the project field in the Design Pattern wizard.

See "About Token Conditions" for more information.
(Optional) Add a modelVersion element.

Defining a model version assures compatibility with the solution loaded in the user workspace by limiting the projects to only those with a specific set of target version values. A project target version specifies the version of the server to which a cartridge project is deployed. For example, if you define the modelVersion as 7.3.0, then a user running the design pattern can select only projects with target versions defined as 7.3.0.
(Optional) Add a projectVersion element.

Defining a project version assures compatibility of the design pattern with a user development environment, ensuring that users cannot run the design pattern in an incompatible version of Design Studio. The version number of a project is defined in the .studio file, located at the root of a project.

See "Example: Adding Project Dependencies" for an example of a design pattern that creates a dependency between a new project and an existing base project. The following is an example of the projects element:

    <projects>
        <project name="Activation Network Cartridge" 
                 id="DesignPatternProject"
                 tokenGroup="ProjectPage"     
                 seal="ALWAYS">
            <description>Create a first project</description>
            <condition>
               <equals v2="@@SelectProject@@" v1="true" />
            </condition>
            <typeId>ACT</typeId>
            <defaultValue>COMVERSE_MMS</defaultValue> 
            <vendor>CMVT</vendor>
            <technology>@@technology@@</technology>
            <softwareLoad>3-5-X</softwareLoad>
        </project>

Working with Tokens

The outcome of a design pattern is affected by the data that a user enters into the Design Pattern wizard. When creating design patterns, you use a token to represent each piece of data that you expect a user to add to the wizard. Tokens are placeholders that represent information to be collected by the Design Pattern wizard from a user applying a design pattern. You use tokens to ensure that the resources a design pattern copies to a workspace are based on information supplied by the user who applies the design pattern. You define tokens for resources in pattern.xml files.

You can use tokens to:

Append the value of a token to the name of a Design Studio entity.
Influence where in a target project an entity will be created by including the value of a token in the location path.
Influence the actions that create relationships, populate data elements, or otherwise modify existing Design Studio entities.
Automate design pattern decisions with the use of conditions.
Provide default values to other tokens. You can use tokens in the defaultValue element of other tokens to provide intelligent defaults based on previously collected information.
Customize the content of files.

About Tokens

Token elements include an id attribute that uniquely identifies the token in a design pattern. To reference a token id in another element in a design pattern, you use the following syntax:

@@id@@

where id is the value that you defined for the token id attribute.

Token elements also include a name attribute, which appears in the Design Pattern wizard as the field name, and a description attribute, which appears in the Design Pattern wizard as embedded Help under the field.

The following example includes a token called service in a resource targetLocation element:

targetLocation="/src/oracle/communications/services/@@service@@/@@service@@Interface.java"

If the user applying the design pattern enters the value VOIP for the service token, the targetLocation element would appear as:

targetLocation="/src/oracle/communications/services/VOIP/VOIPInterface.java"

Note:

Design Studio cannot detect embedded token name spelling errors. Check for consistent token usage to ensure tokens are replaced properly. Design Studio detects invalid tokens when a user attempts to run design pattern.

For a more detailed description of token types and their configuration, see the Design Pattern XML schema (schema/DesignPattern.xsd).

About Token Types

Token types represent the type of data that you expect a design pattern user to supply in the Design Pattern wizard. For example, a user may be expected to select from a list of valid projects, to select or deselect a check box, or to specify an entity name with a valid string of characters. When you create design patterns, the type of token that you specify determines what child elements are available to define for the token element.

Define tokens with one of the following token types:

StringToken, if you want the user to enter a string of text. The text accepted by the token can be constrained by configuring regular expressions and by defining a maxLength value to limit the string to a maximum number of characters. The Design Pattern wizard displays each StringToken as a single-line text input field.
NumericToken, if you want the user to enter numeric input. The number accepted by the token can be constrained by configuring regular expressions and by defining a minValue and a maxValue. The Design Pattern wizard displays each NumericToken as an input field with up and down arrows that can be used to increase or decrease the value.

Note:

When defining numeric tokens, Oracle recommends that you define the minimum and maximum values for the token.
BooleanToken, if you want the user to select a true or false value. Boolean tokens are displayed in the Design Pattern wizard as check boxes. When a token type is defined as a Boolean, the design pattern ignores any values defined in the regularExpression element. You can define the initial state of the check box by defining the defaultValue element as true or false.
EnumerationToken, if you want the user to select from a set of preconfigured choices that you define using the values tag. Enumeration tokens appear in the Design Pattern wizard as lists, from which the user must select a value. You can define a default value from the list of values.
EntityRefToken, if you want the user to select a Design Studio entity in a workspace. The Design Pattern wizard displays a Select button next to entity reference token fields, which enables a user to select an existing entity of a specific type from the workspace. See "About Entity Reference Tokens" for more information.
ElementRefToken, if you want the user to select an element, such as a Data Dictionary element, in a workspace. Design patterns can use element reference tokens to associate entities created by a design pattern with elements that exist in the workspace. The Design Pattern wizard displays a Select button next to element reference token fields, which enables the user to select an existing element from the workspace. See "About Element Reference Tokens" for more information.

About Entity Reference Tokens

You can use entity reference tokens to represent the name of a Design Studio entity in a workspace. An entity reference token enables a user to select an existing entity of a specific type from the workspace. EntityRefToken types include the following child elements:

entityType: Use to restrict the type of entity that a user can select. You specify the type by defining this element with the file extension for an entity type.
projectFilter: Use to restrict the type of entities that a user can select. This element includes two mandatory child elements, filterType and id. For the filterType element, select the value project or entityRef. For the id child element, enter the unique identifier of the project element or of the EntityRefToken as defined in the pattern.xml file. Depending on the mandatory element values, the project is derived at run time and the user is restricted to select entities from this derived project.
entityFilter: Use to further restrict the entities available for selection. This element includes one mandatory attribute, filterType, for which you can define one of the following properties: entityName, entityReference, or referencedByEntity. Depending on the property that you specified, you can define additional child element criteria. See "About EntityRefToken Filtering" for more information.
relationship: Use to construct the reference to the entity. You can determine the relationship type by viewing the XML file of an entity where the reference is embedded.
allowMultiple: Use to enable design pattern users to select multiple entities from a list. When you define this child element with the value true, design pattern users can select multiple existing entities of the specified entityType from the workspace. This element is optional. The default value of this element is false, which limits a selection to one existing entity of the specified entity type from the workspace. See "Example: Supporting Multiple Selections for Entity Reference Tokens" for more information.

Restrictions that you define using regular expressions apply to the entity name.

You can use entity properties to enable a design pattern access to information about the entity that is bound to an EntityRefToken. See "About Entity Properties" for more information.

You can define a default value for an EntityRefToken. When a design pattern is run, the pattern validates the default value to ensure that the value exists in the workspace. If an entity with the default value name does not exist in the workspace, the Design Pattern wizard displays a validation error and disables the Next button. In this scenario, the user must select a different value.

Example 2-1 illustrates a token defined with a type of EntityRefToken.

Example 2-1 EntityRefToken

<token name="Service Order" tokenGroup="HelloWorldInfo"
   id="Order" xsi:type="EntityRefToken">
   <description>Select the service order defined for
                your solution.</description>
   <allowMultiple>true</allowMultiple>
   <entityType>order</entityType>
   <relationship>com.mslv.studio.provisioning.task.manual.orderType</relationship>
   <defaultValue>VoiceMailService</defaultValue>
</token>

About EntityRefToken Filtering

When defining entity reference tokens, you can specify an entity type to limit the available selections to the user running a design pattern. You can define additional filtering criteria by using the entityFilter child element.

The entityFilter element includes the property filterType, which you can define using the following values:

Use entityName to limit the selection based on an entity name. This filter option supports additional child elements, such as equals, notEquals, beginsWith, endsWith, and contains.
Use entityReference to limit the selection to entities with a reference to the entity type defined in the entityType child element and to those entities that meet the entityName criteria.
Use referencedByEntity to limit the selection to entities that are referenced by the entity specified in the entityType element and to those that meet the entityName criteria.

Example 2-2 demonstrates how to limit the selection to all Domain entities with name Line.

Example 2-2 Filtering Entity Reference Tokens Using the entityName Property

<token id="domain1" name="Domain Entity Name Line" 
           tokenGroup="PSRModelInfo"   
           xsi:type="EntityRefToken">
      <description>Choose a Domain entity of Name Line</description>
      <entityType>cmnDomain</entityType>
      <entityFilter filterType="entityName">
           <entityName>
                <equals>Line</equals>
           </entityName>
      </entityFilter>
</token>

Example 2-3 demonstrates how to limit the selection to all Domain entities that contain references to Functional Area entities that are named Service.

Example 2-3 Filtering Entity Reference Tokens Using the entityReference Property

<token id="domain1" name="Service Domain" 
           tokenGroup="PSRModelInfo"   
           xsi:type="EntityRefToken">
     <entityType>cmnDomain</entityType>
     <entityFilter filterType="entityReference">
          <entityType>funcArea</entityType>
          <entityName>
               <equals>Service</equals>
          </entityName>
     </entityFilter>
</token>

Example 2-4 demonstrates how to limit a selection to all the Customer Facing Service entities that are referenced by Domain entities with a name that begins with Line.

Example 2-4 Filtering Entity Reference Tokens Using the referencedByEntity Property

<token id="domain1" name="Service Domain" 
           tokenGroup="PSRModelInfo"   
           xsi:type="EntityRefToken">
     <entityType>custSrvc</entityType>
     <entityFilter filterType="referencedByEntity">
          <entityType>cmnDomain</entityType>
          <entityName>
               <beginsWith>Line</beginsWith>
          </entityName>
     </entityFilter>
</token>

About Entity Properties

You use entity properties to enable the design pattern to acquire information from conceptual model entities that are bound to an entity token. Using a token substitution string, you can instruct the design pattern to acquire the value entered for the entity token.

Use the following format:

@@tokenid.propertyName@@

where tokenid is the id attribute defined for the token, and propertyName is the supported property.

Design Studio supports the use of entity properties for project and resourceType properties for all entity types, and for implementationMethod and implementationSystem properties for conceptual model entities that support realization.

In Example 2-5, the design pattern queries the Implementation Method and the Implementation System properties of the entities that are selected for the tokens with IDs defined as resourceEntity. The design pattern compares the properties to the value DEVICE. If both properties evaluate to true, the design pattern adds the resource to the workspace.

Example 2-5 Entity Properties

<resource id="resImpl" overwritePolicy="NEVER">
   <condition>
      <All>
         <equals v1="@@resourceEntity.implementationMethod@@" v2="DEVICE"/>
         <equals v1="@@resourceEntity.implementationSystem@@" v2="UIM"/>
      </All>
   </condition>

About Element Reference Tokens

You can use element reference tokens to represent the name of a data element defined in a workspace. An element reference token enables a user to select an existing data element from the workspace.

You can use element reference tokens to embed a reference to the select element in the other Design Studio entities.

ElementRefToken types include the following child elements:

entityType: Use to restrict the type of entity for data element selection. You specify the type by defining this element with the file extension for an entity type.
elementType: Use to restrict the type of elements for selection. An elementType is defined with an ID, for example com.mslv.studio.provisioning.order.node or com.mslv.studio.core.data.dictionary.node. You can determine the element type by viewing the XML file of an entity where the reference is embedded.
projectFilter: Use to restrict the type of entities that a user can select. This element includes two mandatory child elements, filterType and id. For the filterType element, select the value project or entityRef. For the id child element, enter the unique identifier of the project element or of the ElementRefToken as defined in the pattern.xml file. Depending on the mandatory element values, the project is derived at run time and the user is restricted to select elements from this derived project.
relationship: Use to construct the reference to the entity. You can determine the relationship type by viewing the XML file of an entity where the reference is embedded.

Example 2-6 illustrates a token defined with a type of ElementRefToken.

Example 2-6 ElementRefToken

<token name="Data Element for Order Template" tokenGroup="HelloWorldInfo"
   id="OTDataRef" xsi:type="ElementRefToken">
   <description>Select a data element for the order template.</description>
   <entityType>order</entityType>
   <elementType>com.mslv.studio.provisioning.order.node</elementType>
   <relationship>ora.task.orderTemplateRef</relationship>
</token>

Element reference tokens return XML instead of a simple value (and therefore, you cannot embed element references in default values or in target locations). Design Studio returns XML to ensure that the token can be embedded in a Design Studio entity document, where it replaces a reference to an element.

The format of the return XML is:

<com:entity>--from selection--</com:entity>
<com:entityType>--from selection--</com:entityType>
<com:relationship>--from token configuration--</com:relationship>
<com:element>--from selection--</com:element>
<com:elementType>--from token configuration--</com:elementType>

Use the token to replace a section of XML in a Design Studio entity document with the corresponding structure.

About Regular Expressions

When configuring design patterns, you can use regular expressions to ensure that the information a user enters for a token is valid. When using String tokens, Oracle recommends that you restrict the valid input using regular expressions, because some character-based input is not valid for use in a token definition. For example, if you use a token as a file name, then it must contain only characters that are valid for a file name. If you use a token as a Design Studio entity name or in an XML document, you must restrict the use of XML special characters. Embedded tokens are the most common place where errors are introduced into a design pattern. If a design pattern is not working properly, first ensure that all tokens are properly replaced when the pattern was applied.

Example 2-7 illustrates how a regular expression can be used to ensure that a user enters a valid entity name. The example also includes a message that will appear to the user if they enter invalid values.

Example 2-7 Regular Expression

<regularExpression>
     <expression>^[a-zA-Z_][a-zA-Z0-9_-[.]]{0,255}$</expression>
     <message>Invalid value for Name. The first character should be 
              an alphabetic character or underscore. The second and 
              following characters can be alphanumeric characters, 
              underscores, hyphens, and periods. The length should not 
              exceed 255 characters.
     </message>
</regularExpression>

About Token Functions

You can use the following functions with any token (except for element reference tokens) in a design pattern:

toUpper
toLower

These functions enable design patterns to force token values to upper case or to lower case when required by naming conventions. Use the following format:

@@tokenId.toUpper@@

@@tokenId.toLower@@

where tokenid is the id attribute defined for the token.

Note:

You can not use entity properties and entity functions in the same token expression. See "About Entity Properties" for more information.

About Token Conditions

Conditions enable you to dynamically control the visibility of a token that appears in the Design Pattern wizard. You use conditions with tokens to optimize the user experience by displaying only the tokens relevant to the specific task and context from which the pattern is initiated.

When a design pattern is run, the Design Pattern wizard evaluates the conditions defined for the tokens. Additionally, the Design Pattern wizard evaluates conditions before each page in the wizard is displayed. This behavior enables you to control whether a token appears on a page based on user input values and entity selections made on previous pages.

Example 2-8 is a small piece of XML from a design pattern that creates a new Service specification entity in an Inventory project. The design pattern also optionally creates a reference to an existing Resource Facing Service (RFS) entity in a model project.

When initiated, the design pattern displays a check box (in this example, represented by the Boolean token isRFS) that a user selects if they want to add the optional RFS reference. If the user selects the check box (and the Boolean token evaluates to true), the design pattern displays a list of available RFS entities (in this example, represented by the entityRef token rfsToken). If the user does not select the check box, the design pattern does not display the list of RFS entities.

Example 2-8 Conditional Token

<token id="isRFS" name="Create RFS" tokenGroup="rfsDetails"
   xsi:type="BooleanToken">
        <description>Add a reference to an existing 
                     Resource Facing Service entity.
        </description>                       
      <defaultValue>false</defaultValue>
</token>
           
<token id="rfsToken" name="Resource Facing Service" tokenGroup="taDetails"   
   xsi:type="EntityRefToken">
       <description>The Resource Facing Service</description>
       <condition>
          <equals v1="@@isRFS@@" v2="true"/>
       </condition>
       <entityType>rsrcSrvc</entityType>
</token

Tokens referenced by conditions that evaluate to false do not appear in the Design Pattern wizard (and a user, therefore, has no opportunity to enter or select a value). A design pattern will display an error if a condition that references an EntityRefToken or ElementRefToken type evaluates to false and if the same EntityRefToken or ElementRefToken type is included in a subsequent condition definition of another token. Therefore, conditional tokens that support default values must specify a default value.

Conditions are optional for tokens, and condition statements can be arbitrarily complex.

Defining Tokens for Design Patterns

You define tokens to ensure that the resources a design pattern copies to a workspace are based on information supplied by the user who applies the design pattern. See "Working with Tokens" for more information.

To define tokens in a design pattern:

With the pattern.xml file open in the Design Studio default XML editor, click the Design tab.
Add a tokens element, and then add a child token element for each piece of information that the design pattern must obtain from a user.
Add and define values for the following token attributes:
1. For the name attribute, enter the name of the field to appear in the Design Pattern wizard.
2. For the tokenGroup attribute, enter the name of the token group to which this token belongs.
  
  A token group represents a page in the design pattern. You can group tokens in a group so that the tokens all appear on the same page in the wizard.
3. For the id attribute, enter a unique value to represent the token. You use the value in this attribute to reference the token in the design pattern. See "About Tokens" for more information.
In the token element, add a type attribute.

See "About Token Types" for more information.
Add child elements to all token elements.

Some elements are common to all tokens, and some are available only to specific token types.
- For the description element, enter a description of the information being requested from the user.
  
  The description appears in the Design Pattern wizard and provides information or instructions to the user about the values that they must provide.
- For the defaultValue element, enter the information that appears initially for the token in the Design Pattern wizard.
  
  You can embed other tokens in the defaultValue element, except for conditional tokens. Default values are optional. Users applying the design pattern can override default values. See "Example: Defining Tokens as Default Values" for more information.
  
  When applying design patterns, users can click the Reset Page button to reset all of a page's token values to their initial default values. When a user clicks the Reset Page button, all token values on the current page are reset to the default value. All token values on previous pages remain as defined by the user.
- For the regularExpression element, define an expression to validate or restrict the token values entered by users in the Design Pattern wizard. Regular expressions are optional and may not apply to all token types. You can also define the message that appears to the user if the input text fails to conform to the regular expression. See "About Regular Expressions" for more information.
- For the value element, define one of the enumerated values that appears in a list of enumeration tokens. This element appears for EnumerationToken types only.
- For the entityType element, specify the type of Design Studio entity that a user must select. The value that you define here is determined by the file extension of the Design Studio entity. For example, to indicate that a user must select an OSM manual task, you define this element as manualTask. The entityType element appears for entity reference tokens only. See "About Entity Reference Tokens" for more information.
- For the elementType element, specify the element ID for the type of element that the user must select. The elementType element appears for element reference tokens only. See "About Element Reference Tokens" for more information.
- For the relationship element, specify the relationship type used in a reference.
- For the condition element, define a condition to dynamically control the visibility of a token that appears in the Design Pattern wizard. See "About Token Conditions" for more information.
Add token functions to ensure that all characters in a token value are forced to upper case or to lower case.

See "About Token Functions" for more information.
Click Save.

The following is an example of the tokens element:

<tokens>
   <token id="equipment" name="Equipment" tokenGroup="reserveEquipmentInfo"
       xsi:type="StringToken">
      <description>Name of the equipment you want to reserve.rn.</description>
      <regularExpression>
         <expression>[a-zA-Z0-9_]+</expression>
         <message>Reserve Equipment IDs should only contain letters, numbers and
                  underscores.</message>
      </regularExpression>
      <regularExpression>
         <expression>[a-zA-Z][a-zA-Z0-9_]*</expression>
         <message>Reserve Equipment IDs should start with a letter.</message>
      </regularExpression>
      <regularExpression>
         <expression>[a-zA-Z0-9_]{0,20}$</expression>
         <message>Reserve Equipment IDs should be 20 characters or less.</message>
      </regularExpression>
   </token>
</tokens>

See the following topics for examples that demonstrate token use:

Defining Token Groups for Design Patterns

A token group represents a page in the Design Pattern wizard. You organize design pattern tokens into pages to control the manner in which information is collected by the Design Pattern wizard. You can define any number of token groups in a design pattern, and each token is associated with a single token group.

You can use token groups, for example, to group related input fields together on a single Design Pattern wizard page or to limit the number of input fields on each page to improve usability.

To define token groups for design patterns:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add a tokenGroups element and then add a child tokenGroup element for each page that you want to appear in the Design Pattern wizard.
Add and define values for the following tokenGroup attributes:
1. For the name attribute, enter the name of the page that will appear at the top of the Design Pattern wizard.
2. For the id attribute, enter a unique value to represent the token group. The token elements included in this group reference the value that you enter here.
In the tokenGroup element, add a child description element.
In the description element, enter the description of the page as it should appear in the Design Pattern wizard.
Click Save.

The following is an example of the tokenGroups element:

<tokenGroups>
   <tokenGroup name="Plug-in Information" id="reserveEquipmentInfo">
      <description>Define the information on this page to create reserved
                   equipment.</description>
   </tokenGroup>
</tokenGroups>

Defining the Manifest for Design Patterns

A design pattern manifest is the list of resources included in a design pattern. You define the manifest for a design pattern to determine how resources are generated and where they generated when the pattern is applied. A design pattern can generate Design Studio entities, cheat sheets, Java files, XML files, and so forth, in specified target projects.

When defining resources that you copied from an existing reference implementation, you can change the names of those resources to be less specific, which enables you to use the resources across different service domains. For example, if you copy a specification named ADSL_Port from a Broadband Internet reference implementation, you can rename the resource to Assigned_Interface for use in a design pattern that applies across service domains.To define the manifest in design patterns:

Identify all required resources from a reference implementation or a sample solution.
Open the pattern.xml file in the Design Studio default XML editor and click the Source tab.
Add a manifest element, and then add child resource elements.

When adding child resource elements, you can:
- Copy existing resources to your design pattern. You can copy resources from a reference implementation or from a sample solution or your can create new resource elements. You can copy any source file that you require in your solution, such as Design Studio entities, XML content, rules, and so forth.
- Define new child resource elements for additional required resources.
In the location child element, enter the path and file name from the pattern root to the copied resource.

You must retain the original name of all Design Studio entities in the source location of the resource (do not embed tokens). The location is the relative path of the resource from the location of the design pattern. For example, if the location of the design pattern is:

/pattern/myPattern

and one of the resources for the pattern from the project root is:

/pattern/myPattern/dataDictionary/pattern.xsd

then you define the value for the location element for the corresponding resource as:

dataDictionary/pattern.xsd
Append the extension .pat to all Design Studio entity file names in the resources element location element.

Note:

You must append the extension .pat to the Design Studio entity file names when working with Design Studio entity resources in a plug-in project. Resources that are not Design Studio entities, such as Java or XML files, do not need the .pat extension.

For example, if you add to the resource list an Order and Service Management order called myOrder.order, you must rename that order entity to myOrder.order.pat.

Design Studio refers to the original entity name while processing the design pattern to update references to entities in the pattern. Failure to append the .pat extension to the resource may result in problem markers and entries in your error log. When working with Data Dictionary companion files, Design Studio automatically deletes the resource from the workspace when it cannot resolve correctly to its associated schema file.
In the resource element, add an id attribute and enter an ID that is unique among all resources in the manifest.

Components in the design pattern use the id attribute when referencing the resource.
In the projectId element, enter the ID of the project into which the design pattern should save the resource when the design pattern is applied.

Note:

The ID that you define here must also be defined in the projects element of the pattern.xml file, which describes the projects that the design pattern can place resources into when the design pattern is applied. See "Defining Target Projects for Design Patterns" for more information.
(Optional) In the resource element, add a condition child element.

You use conditions to include simple or complex conditional logic when determining whether a design pattern adds the resource the workspace. See "About Conditions" for more information.
In the resource element, add a targetLocation child element.
In the targetLocation element, enter a path and file name of the location (in the user's workspace) where the design pattern-generated artifacts will be saved when the design pattern is applied.

The path is relative to the target project.

The targetLocation element can contain embedded tokens. Embedding tokens enables the user applying the design pattern to influence the name and location of the generated resource, implement naming conventions, and maintain referential integrity across resources that are included in a design pattern. When run, the design pattern substitutes the token references in the path with the values entered by the user.

For example, the following targetLocation includes a declared token called service to be used in the path and name of a Java class resource:
```
targetLocation="/src/oracle/communications/services/@@service@@/@@service@@Interface.java"
```
If the user applying the design pattern entered VOIP as the value for the service token, targetLocation would expand to:
```
targetLocation="/src/oracle/communications/services/VOIP/VOIPInterface.java"
```
and the design pattern copies the file into the workspace using this location and name.
In the resource element, add a type attribute.
In the type attribute, specify the type of resource to be copied to the user's workspace.

Use one of the following values:
- TEXT: use to identify the resource as a text file. You can use tokens in the content of text files. If you specify no resource type, the design pattern uses TEXT as the default value. For example, you can identify Design Studio entities, XML, XQuery, XSLT, and Java resources as TEXT types.
- DIRECTORY: use to identify the resource as a directory that will be created in the user's workspace.
- BINARY: use to identify the resource as a binary file (for example, a JPEG file). You cannot use tokens in binary resources.
- LIBRARY: use to identify the resource as a Java library (for example, a JAR file). After the design pattern copies the library to the user's workspace, the design pattern adds the library to the classpath of the appropriate project.
In resource element, add an overwritePolicy attribute.
In the overwritePolicy attribute, specify the design pattern response if a resource with the same name and location exists in the target project.

Use one of the following values:
- ALWAYS: use to specify that the existing file is to be overwritten by the resource contained in the design pattern. However, if the resource in the workspace is read-only, the design pattern cannot overwrite the existing resource. The log produced after the design pattern is completed lists all resources that cannot be overwritten. ALWAYS is the default value.
- NEVER: use to specify that the existing file is not to be overwritten by the resource contained in the design pattern. The design pattern performs no token substitutions for the resource when the overwritePolicy is defined with this value.
In resource element, add an overrideDisplayName attribute.

By default, the display name of a resource is generated from the resource name if the resource is Design Studio entity.
If you are using a token to define the display name of a resource, change the value of the overrideDisplayName attribute to true.

Changing the value of the overrideDisplayName attribute to true prevents Design Studio from overriding the display name value with the Design Studio entity name.
Click Save.

The following is an example of the manifest element:

<manifest>

<resource id="cheatSheet">
   <location>cheatSheet/reserveEquipmentCheatSheet.xml</location>
   <targetLocation>cheatSheet/reserveEquipment/DesignPatternCreation.xml
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="dd_companion" >
   <location>dataDictionary/reserveHardware_companion.xsdc.pat</location>
   <targetLocation>
      dataDictionary/@@equipment@@/reserve@@equipment@@_ companion.xsdc
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="dd" >
   <location>dataDictionary/reserveHardware.xsd.pat</location>
   <targetLocation>dataDictionary/@@equipment@@/reserve@@equipment@@.xsd
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="automation" >
   <location>model/OSM/reserveHardware.automationTask.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@.automationTask
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="baseTask" >
   <location>model/OSM/reserveHardwareBaseTask.manualTask.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@BaseTask.manualTask
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="falloutTask" >
   <location>model/OSM/reserveHardwareFallout.manualTask.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@FalloutTask.manualTask
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="function" >
   <location>model/OSM/reserveHardwareFunction.orderComponentSpec.pat</location>
   <targetLocation>
      model/@@equipment@@/reserve@@equipment@@Function.orderComponentSpec
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="process" >
   <location>model/OSM/reserveHardwareProcess.process.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@Process.process
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="query" >
   <location>model/OSM/reserveHardwareQueryTask.manualTask.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@QueryTask.manualTask
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="role" >
   <location>model/OSM/reserveHardwareRole.rolePermissions.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@Role.rolePermissions
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="summary" >
   <location>model/OSM/reserveHardwareSummaryTask.manualTask.pat</location>
   <targetLocation>model/@@equipment@@/reserve@@equipment@@SummaryTask.manualTask
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="compositeView" >
   <location>model/OSM/reserveHardwareView.compositeCartridgeView.pat</location>
   <targetLocation>
      model/@@equipment@@/reserve@@equipment@@View.compositeCartridgeView
   </targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="java" >
   <location>resource/reserveHardware.java</location>
   <targetLocation>src/oracle/communications/services/reservation/@@equipment@@/
                   Reserve@@equipment@@.java</targetLocation>
   <projectId>reserveEquipmentOSMProject</projectId>
</resource>

<resource id="equip" >
   <location>model/UIM/reservable.equipment.pat</location>
   <targetLocation>model/@@equipment@@/@@equipment@@.equipment</targetLocation>
   <projectId>reserveEquipmentUIMProject</projectId>
</resource>

</manifest>

Working with Design Pattern Actions

You define actions to enable design patterns to perform actions on entities, such as creating relationships between or adding data elements to inputs or resources.

Actions affect entities that exist in the target workspace, but the actions do not cause the existing entities to be replaced in the target workspace. This enables users who run design patterns and subsequently enrich the model to re-run patterns without losing the changes they make during an iterative design cycle.

Actions have two main components:

A subject: An action subject is the entity or element that is affected by the action. The subject is the entity or element to which, for example, a reference is added or data elements are added.
A participant: An action participant is the entity or element that provides the information for the action. For example, the participant is the entity providing the data elements to the subject.

About Action Elements

You include action elements in the pattern.xml file to define the action attributes. You define the following elements:

condition: Add simple or complex conditional logic to enable the design pattern to perform the action only under specific conditions. See "About Conditions" for more information.
actionType: Specify the type of action to be performed. See "About Design Pattern Action Types" for more information.
subject and participant: Specify the entity or data element that is affected by the action, and the entity or data element that provides the information for the action, respectively. The subject and participant elements require you to define a:
- participantType: Specify whether the subject or participant entity is a resource that is internal to the design pattern, or whether the subject or participant entity is input that the design pattern selects when the pattern is run. See "Defining Inputs for Design Patterns" for more information.
- id: specify a unique identification for the subject and participant entities.
name: Specify the name of the action.
actionKey: Specify the type of relationship that the action creates between the subject and participant. See "About the Design Pattern Action Reference Table" for more information.
executeOnExistingEntity: Specify whether to run actions on entities that already exist in the workspace. The default is true. Define this value as false to prevent actions on entities that exist in the workspace.

Note:

Resource definitions include an attribute called OverwritePolicy that specifies a design pattern response if a resource with the same name and the same location exists in the target project.

If the OverwritePolicy attribute for a resource is defined as Always, the existing resource is overwritten by the resource contained in the design pattern. In this scenario, a design pattern runs actions on the resource even when the executeOnExistingEntity attribute is defined as false. See "Defining the Manifest for Design Patterns" for more information.

About Design Pattern Action Types

Action types represent a category of action to be performed. For example, an action type can represent a relationship that is created between entities and elements, a copy action that copies data between entities, or an extend action that extends source entities.

You can define design pattern action types with one of the following values:

relationship: Use to create a relation between entities, between elements, or between elements and entities. For example, you can use this action type to establish a relationship between a conceptual model entity in the conceptual model and a resource in an application model.
interface: Use to copy data elements from a participant entity to a subject entity. For example, the data configured in a customer facing service in a conceptual model can be copied to an Inventory Service specification in an application model.
parameter: Use to pass a participant entity as an input to a subject entity. For example, a customer facing service in a conceptual model can be passed as an input to an Action entity that is supported on an Inventory Service specification in an application model.

When using the parameter action type, the data elements in the subject entity reference the participant entity (whereas in the interface action type, the data elements are copied to the subject entity).
extension: Use to define an extension relationship between a participant and a subject entity (the subject entity extends from the participant entity).

When applying design patterns that include this action type, existing subject entities must be writable and must not be included in a sealed project.

About Actions Used in Conceptual Modeling

You can use actions to realize entities in a conceptual model. For example, you can use actions to realize customer and resource facing services, resources, locations, and conceptual model actions.

You can use action type and action key combinations that are specific to the following conceptual modeling tasks.

For more information about action types and action keys, see the Design Pattern Action Reference table, which is available on the Oracle Help Center. Click the following link and then click the link for the current Design Studio version:

http://docs.oracle.com/en/industries/communications/design-studio/index.html

Copying Changeable Elements from Participant to Subject

You use the interface action type with the action key noted below if you want to copy from the participant to the subject configuration only those data elements that are tagged with Changeable tag. Data elements are that are not defined with the Characteristic tag or with the Changeable tag are copied to the Service specification but not to the corresponding Service Configuration.

Action Key: oracle.communications.common.configuration
Action Type: interface
Subject: configuration
Participant: customer facing service, location, product, resource, or resource facing service

Adding Components as Configuration Items to Service Configuration Specifications

You use the relationship action type with the action key noted below if you want to realize a conceptual model entity that includes components and add those components as configuration items to the Service Configuration specification.

Action Key: oracle.communications.common.configuration
Action Type: relationship
Subject: configuration
Participant: customer facing service, location, product, resource, or resource facing service

Copying Data Elements as Virtual Root Nodes to Conceptual Model Actions

You use the parameter action type with the action key noted below if you want to copy data elements from a conceptual model entity to a conceptual model action. The data elements are copied to the action, in this scenario, as virtual root nodes.

Action Key: oracle.communications.sce.common.entity.entities.action.actionclassification.action.parameter.helper
Action Type: parameter
Subject: action
Participant: customer facing service, location, product, resource, or resource facing service

Realizing Technical Actions for Inventory Entities

When working with Inventory entities, you can realize technical actions but maintain (rather than override) the data elements previously saved on the technical action by using the interface action type and action key noted below. Using this combination, you can keep existing data elements and save new data elements to the Data Dictionary.

Action Key: oracle.communications.sce.common.entity.action.relalization.ta.helper
Action Type: interface
Subject: technical action generation helper
Participant: service action

Copying Changeable Data Elements from a CFS to an RFS

You use the interface action type with the action key noted below if you want to copy data elements tagged as Changeable from a customer facing service to a resource facing service. This functionality is reserved for customer facing services and resource facing services only.

Action Key: oracle.communications.sce.common.entity.rfs.interface.helper
Action Type: interface
Subject: resource facing service
Participant: customer facing service

Copying Changeable Elements from a Service to a Service Specification

You use the interface action type with the action key noted below if you want to copy data elements tagged as Changeable from a service to a service configuration specification. Data elements not tagged as Changeable are copied from the service to the service specification.

Action Key: oracle.communications.common.configuration.enabled
Action Type: interface
Subject: service specification
Participant: customer facing service, location, product, resource, or resource facing service

Extending Actions

You use the extension action type with the action key noted below to extend one action from another (the subject action extends from the participant action). In this scenario, the data elements are copied from the participant to the subject only if the Extends option is not selected for the participant on the Conceptual Model Editor Properties tab.

Action Key: oracle.communications.sce.common.entity.entities.action.extends
Action Type: extension
Subject: action
Participant: action

Using Order Item Parameter Bindings to Link Conceptual Model Entities to OSM Projects

You use the relationship action type with the action key noted below to link conceptual model entities with an OSM project through an order item parameter binding. In this scenario, when a user applies a design pattern using a conceptual model entity as input and associates to that entity an order item parameter binding, the design pattern creates an XML file containing the attributes of the conceptual model entity, as well as an XQuery file.

Action Key: oracle.communications.studio.osm.transformation.entities.binding.psrentity.handler
Action Type: relationship
Subject: order item parameter binding
Participant: conceptual model entities

Filtering Action Codes

You use the relationship action type with the action key noted below to filter action codes when creating a relationship between an action and an action code. In this scenario, only those action codes defined in the associated functional area are added to the action.

Action Key: oracle.communications.sce.common.entity.entities.action.actioncodes.actionTypeRef
Action Type: relationship
Subject: action
Participant: action code

About the Design Pattern Action Reference Table

You use the Design Pattern Action Reference table to review all of the information required to define an action in a design pattern for Design Studio entities, including the valid relationship types and target entities for the actions that can affect each entity type.

For each entity type, the table lists the:

relationship name
action key
subject
participant
action type

The Design Pattern Action Reference table is available on the Oracle Help Center. Click the following link and then click the link for the current Design Studio version:

http://docs.oracle.com/en/industries/communications/design-studio/index.html

Defining Actions for Design Patterns

You include actions in a design pattern to define which actions to perform on entities in a workspace. See "Working with Design Pattern Actions" for more information.

To define actions for design patterns:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add an actions element, and then add an action element for each action that you want the design pattern to perform.
In the action element, add and define values for the following action attributes.
1. For the name attribute, enter the name of the field to appear in the design pattern.
2. For the id attribute, enter a unique value to represent the action.
Add and define the action child elements.

Some elements are common to all actions, and some are available only to specific action types. See "About Action Elements" for more information.
Click Save.

Defining Custom Actions

You define custom actions to call custom Java code from a design pattern.

Design patterns invoke custom actions last because custom actions can have dependencies on other design pattern artifacts. Design Studio performs a build before running the custom actions to ensure that the custom actions receive up-to-date Exchange Format model information. See "Invoking Custom Java Code from Design Patterns" for more information.

To define custom actions for design patterns:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add a customActions element, and then add a customAction element.
In the customAction element, add and define values for the following action attributes:
1. For the name attribute, enter the name of the field to appear in the design pattern.
2. For the id attribute, enter a unique value to represent the action.
Add and define the customAction child elements.
1. In the condition element, add simple or complex conditional logic to enable the design pattern to perform the custom action only under specific conditions. See "About Conditions" for more information.
2. In the exchangeFormat element, add model child elements for each studio model entity required for the custom action. A model element can be of type entityRef, project, or resource.
3. In the parameters element, add parameter child elements required by the custom action. A parameter element consists of name and value pairs.
4. In the classId element, enter a registered Java class ID.
Click Save.

About Conditions

You use conditions to build design patterns that can produce variable outcomes, depending on user input and the existing state of the solution. Conditions enable the design pattern user to define how resources are created and how actions are performed on those resources.

When creating design patterns, you can include simple conditional logic using common String operations, and you can include complex conditions by combining simple conditions using the Any and All operators and by nesting conditions. A condition must evaluate to true for Design Studio to add the associated resource to the workspace or for Design Studio to perform the associated action.

To define design pattern conditions:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
(Optional) In the resource element or in the action element, add a condition child element.
Expand the condition element, then select the All child element.
Add logical expressions for simple conditions.

Logical expressions include v1 and v2 string operands. You can embed tokens and token functions in the operand values. Token types are resolved to a string representation for evaluation.

The following simple conditions are supported:
- Equals: the expression evaluates to true when v1 and v2 are identical.
- Not Equals: the expression evaluates to true when v1 and v2 are different.
- Begins With: the expression evaluates to true when v1 begins with v2.
- Ends With: the expression evaluates to true when v1 ends with v2.
- Contains: the expression evaluates to true when v1 contains v2.
Add logical expressions for complex conditions.

The following complex conditions are supported:
- Any: the expression evaluates to true when any of the component expressions are true.
- All: the expression evaluates to true when all of the component expressions are true.

In the following example, an All condition is defined to ensure that a design pattern adds a resource to a workspace only when the implementation method of the resource is defined as a device and when the implementation system is UIM.

<resource id="resImpl" overwritePolicy="NEVER">
   <condition>
      <All>
         <equals v1="@@resource.implementationMethod@@" v2="DEVICE"/>
         <equals v1="@@resource.implementationSystem@@" v2="UIM"/>
      </All>
   </condition>

Defining Inputs for Design Patterns

You can use design pattern inputs to create design patterns that enable users to select and perform actions against existing entities in the workspace. The design pattern can use the selected entities or elements as the subject of an action if the design pattern includes an input defined for the selected entity or element type.

For example, if a design pattern is launched from a selected customer facing service (CFS), and in the design pattern there is an input defined for a CFS type, the design pattern can use the selected CFS as the subject of an action defined in the design pattern. The design pattern uses the selected CFS entity name as a default value in the appropriate fields in the Design Pattern wizard.

Design pattern input types can be defined as entityRefToken or as elementRefToken. See "Working with Tokens" for more information.

To define inputs for design patterns:

With the pattern.xml file open in the Design Studio default XML editor, click the Source tab.
Add an inputs element, and then add an input element for each type of element or entity for which you want to automatically populate token names in a design pattern.
In the input element, add and define values for the following attributes.
1. For the name attribute, enter the name of the field to appear in the design pattern.
2. For the id attribute, enter a unique value to represent the input.
Add and define values for the following input child elements.
- For the entityRefToken element, specify an entity for which to create an input.
- For the elementRefToken element, specify a data element for which to create an input.
Note:

You can define entity and element reference tokens for the same input element. When a user selects multiple entities or elements in a Design Studio view and launches a design pattern, the pattern randomly picks one of the entities or elements to display in token fields if multiple selected entities or elements match the design pattern input definitions.
Click Save.

Securing Design Pattern Information

Design patterns have no security for the information they include, and any user can apply design patterns. Do not include sensitive information in design patterns. If sensitive information is needed to complete the configuration of a design pattern, include a cheat sheet to run after the pattern is applied to manually configure the sensitive information.

Oracle recommends that you use model variables in design pattern templates to replace any sensitive information. Design Studio users can be prompted to configure a sensitive model variable with the name used in the template. See the Design Studio Help for information about working with model variables.

Invoking Custom Java Code from Design Patterns

You can create a design pattern that invokes custom Java code. For example, you can create a design pattern that accesses the Design Studio Exchange Format and generates artifacts based on the Exchange Format model information that is passed to the design pattern.

To invoke custom Java code from a design pattern:

Create a Java class that implements the IDesignPatternCustomAction Java interface.

See "About the IDesignPatternCustomAction Java Interface" for more information.
Register your Java class.

When you register your Java class, you define parameter attributes and Exchange Format model entity attributes. See "About Registering Your Java Class" for more information.
Call the Java code.

The code must pass values to the parameters and to the Exchange Format model entities in the design pattern. See "About Calling Your Custom Java Code" for more information.

About the IDesignPatternCustomAction Java Interface

Design Studio provides a Java interface, named IDesignPatternCustomAction, to facilitate the use of custom Java code. The interface contains one method, named performCustomAction, which provides parameters and Design Studio Exchange Format model entity information. Write your custom Java class to implement this interface and to use the values from the parameters and from the Exchange Format model entities to perform your business logic.

Example 2-9 demonstrates how to write a Java class that implements the IDesignPatternCustomAction Java interface.

Example 2-9 IDesignPatternCustomAction Java Interface Example

/**
 * DesignPatternCustomActionRITest demonstrates how to write a custom action class and how to access the Design Studio Exchange Format APIs.
 *
 */
public class DesignPatternCustomActionRITest implements IDesignPatternCustomAction {
 
    ModelLocator modelLocator = new ModelLocator(true);
 
    @Override
    public void performCustomAction(final Map<String, Object> parameters, final Map<String, Model> models) {
 
        CustomerFacingService cfs = null;
        Project project = null;
 
        // Output parameter details
        Set<String> keys = parameters.keySet();
        for (String key : keys) {
            StudioLog.logInfo("Parameter Key: " + key + "\t\tParameter Value: " + parameters.get(key));
        }
 
        // Get models: CFS and project
        Set<String> modelKeys = models.keySet();
        for (String key : modelKeys) {
            Model model = models.get(key);
            Entity entity = model.getEntity().get(0);
            StudioLog.logInfo("Model Key: " + key + "\t\tModel Entity Name: " + entity.getName());
            if (entity instanceof CustomerFacingService) {
                cfs = (CustomerFacingService) entity;
            } else if (entity instanceof Project) {
                project = (Project) entity;
            }
        }
 
        // Output CFS name and components
        if (cfs != null) {
            StudioLog.logInfo("CFS name = " + cfs.getName());
            List<ResourceFacingService> rfsList = getAllRFSComponentsFromCFS(cfs);
            for (ResourceFacingService rfs : rfsList) {
                StudioLog.logInfo("RFS name = " + rfs.getName());
            }
 
            List<CGBUResource> resourceList = getAllResourceComponentsFromCFS(cfs);
            for (CGBUResource resource : resourceList) {
                StudioLog.logInfo("Resource name = " + resource.getName());
            }
        }
 
        // Output project details
        if (project != null) {
            StudioLog.logInfo("Project name = " + project.getName());
        }
    }

About Registering Your Java Class

You register your Java class to enable Design Studio to validate the input from the design pattern.

You define the parameters with the following attributes:

name, which is the key used by the performCustomAction method.
type, which you define with one of the following values: boolean, string, date, dateTime, int, float, double, long.
optional, which is a boolean that indicates whether the parameter is optional (if omitted, the parameter is mandatory).

You define the Exchange Format model information with the following attributes:

name, which is the key used by the performCustomAction method.
entityType, which specifies the entity file extension. For example, you can define an entityType for actions (cmnAction), resources (cmnResource), locations (cmnLocation), customer facing services (custSrvc), resource facing services (rsrcSrvc), and model projects (ddCartridge).
optional, which is a boolean that indicates whether the parameter is optional (if omitted, the parameter is mandatory).

Note:

oracle.communications.sce.integration.test.design.pattern.apply.DesignPatternCustomActionRITest must implement IDesignPatternCustomAction.

Example 2-10 shows an example of how to register your Java class.

Example 2-10 Registering a Java Class

<extension point="oracle.communications.sce.pattern.core.customActionClass">
     <customActionClass 
         id="oracle.communications.sce.integration.test.design.
             pattern.apply.DesignPatternCustomActionTest.ri"              
         class="oracle.communications.sce.integration.test.design.
                pattern.apply.DesignPatternCustomActionRITest">
         <!-- Parameter hasPrefix is a boolean, and it is mandatory -->
         <parameter name="usePrefix" type= "boolean"/>
         <!-- Parameter prefix is a string, and it is optional -->
         <parameter name="prefix" type="string" optional = "true"/>  
         <!-- Exchange Format model cfs is a customer facing service defined
              with an extension custSrvc, and it is mandatory -->         
         <model name="cfs" entityType="custSrvc"/>
         <!-- Exchange format model uimProject is an inventory cartridge defined
              with an extension inventoryCartridge, and it is mandatory -->
         <model name="uimProject" entityType="inventoryCartridge"/>
     </customActionClass>
  </extension>

About Calling Your Custom Java Code

To call your custom Java code, you add a customActions element to your design pattern. Because custom actions can have dependencies on other design pattern artifacts, the design pattern invokes custom actions last. Design Studio builds the projects before running the custom actions to ensure that the custom actions receive up-to-date Exchange Format model information.

The customAction element requires:

A condition child element.
A list of Design Studio model entities, which can be entityRef, project, or resource. The design pattern generates an error if a model entity is not in the workspace and if a model entity in the design pattern does not match a model entity registered in the Exchange Format.
A list of parameters, which are name and value pairs.

The design pattern generates a validation error if the parameters in the design pattern do not match the registered parameters.
A registered Java class ID.

oracle.communications.sce.integration.test.design.pattern.apply.DesignPatternCustomActionTest.ri is the ID of the registered Java class oracle.communications.sce.integration.test.design.pattern.apply.DesignPatternCustomActionTest

Example 2-11 displays an example of the customActions element in the DesignPattern.xsd file.

Example 2-11 customActions Element

<customActions>
   <customAction id="riCustomAction" name="RI Custom Action">
      <condition>
         <equals v1="@@usePrefix@@" v2="true"/>
      </condition>
      <exchangeFormat>
         <model>
            <name>cfs</name>
            <id>cfs</id>
            <type>entityRef</type>
         </model>
         <model>
            <name>uimProject</name>
            <id>uimCfsProject</id>
            <type>project</type>
         </model>
      </exchangeFormat>
      <parameters>
         <parameter>
            <name>usePrefix</name>
            <value>@@usePrefix@@</value>
         </parameter>  
         <parameter>
            <name>prefix</name>
            <value>@@prefix@@</value>
         </parameter>
      </parameters>       
      <classId>oracle.communications.sce.integration.test.design.
               pattern.apply.DesignPatternCustomActionTest.ri</classId>
   </customAction>
        
   <customAction id="riCustomActionNoPrefix" 
                 name="RI Custom Action With No Prefix">
      <condition>
         <equals v1="@@usePrefix@@" v2="false"/>
      </condition>
      <exchangeFormat>
         <model>
            <name>cfs</name>
            <id>cfs</id>
            <type>entityRef</type>
         </model>
         <model>
            <name>uimProject</name>
            <id>uimCfsProject</id>
            <type>project</type>
         </model>
      </exchangeFormat>
      <parameters>
         <parameter>
            <name>usePrefix</name>
            <value>@@usePrefix@@</value>
         </parameter>
      </parameters>       
      <classId>oracle.communications.sce.integration.test.design.
               pattern.apply.DesignPatternCustomActionTest.ri</classId>
   </customAction>
        
</customActions>

Testing Design Patterns

You test design patterns by running them in the Design Pattern wizard. Testing design patterns directly in Design Studio shortens the design-test cycles by eliminating the need to build and deploy design patterns as features.

To test design patterns:

In Design Studio, from the Studio menu, select Design Pattern.

The Design Pattern wizard appears.
Select the Select a Design Pattern from File option.
Click Browse and locate and select the design pattern that you want to test.

Select the design pattern root folder for the design pattern project. The design pattern root folder contains the pattern.xml file.
Click Next.

Design Studio validates the integrity of the design pattern. If the selected design pattern contains structural problems (such as schema validation errors or invalid XML), an error message appears. The error message displays a specific schema validation error and the line and column in the document where the error exists. You must fix all errors before testing a design pattern.

If there are no errors, the Introduction page appears.
Navigate through the wizard to ensure that the design pattern works as intended.
Review the summary of changes on the Summary page.

Ensure that the entities created by the design pattern meet your expectations.
Finish running the design pattern and review the resources added to the workspace.

After the design pattern completes, examine the files that have been added to the workspace to ensure they are named correctly and that they contain the expected configuration. If they are configured incorrectly, review the token substitution configuration.
When the wizard completes, verify that all token replacements work as intended.

For example, you may need to correct any misspelled tokens in the pattern.xml file and all other documents.
(Optional) If the design pattern doesn't meet with your expectations, roll back to a previous version.

Oracle recommends that you use a version control system and employ a backup strategy to roll back to previous versions and to ensure against data loss if the design pattern creates unexpected results.

Applying Design Patterns

Design Studio users apply design patterns by accessing the Design Pattern wizard in the Design Studio user interface. Design patterns do not require reinstallation when changing workspaces or when importing or deleting projects.

Note:

Design patterns may overwrite resources or skip existing resources. Re-running a design pattern with the same input may result in a different output depending on the current state of the workspace and the configuration details of the design pattern.

Some design patterns can overwrite existing resources. Oracle recommends that you use a version control system and employ a backup strategy to ensure against data loss. See Design Studio System Administrator's Guide for more information about backing up and restoring Design Studio data.

See Design Studio Help for information about applying design patterns.

About the Design Pattern Summary Page

When design pattern users navigate through the Design Pattern wizard to completion, Design Studio displays the Design Pattern Summary page.

Users can review the Summary page to ensure that the pattern is applying the correct resources to the workspace, performing the correct actions, and recognizing appropriate inputs. The Summary page also displays expanded condition evaluations, enabling users to debug condition behaviors. Design Studio saves the Summary page in the root of the workspace.

The Summary page displays the following:

All field values that you provided.
All resources to be copied to the workspace. The original name, new name, resource type, and target project displays for each resource. This section also indicates whether any resources with identical names exist in the workspace and whether the design pattern will overwrite the existing values. For example, if a resource with the same name and type exist in the workspace and the resource override value is defined as true, when the design pattern is applied the local resource file will be overwritten.
All actions. The subject entity, the participant entity, and action type appear for each action. This information includes whether the relationships and parameters in existing entities can be overwritten by the design pattern. Restricted actions that cannot be performed because of the configuration appear in the Restricted Actions section.
All inputs. The input entity or element appears for each input.
All conditions, entity properties, and token functions used in a design pattern.

Design Pattern Examples

Use the following examples to help you create your design patterns.

Example: Adding Project Dependencies

Example 2-12 demonstrates how to make a new project created in a design pattern dependent on an existing base cartridge.

In the example, the design pattern creates a dependency from a newly created project to the existing base project OracleComms_Model_base. The user running the design pattern is not required to specify the name of the base project to create the dependency.

When a user runs the design pattern, and if the cartridge entity specified in the entityreftoken element (OracleComms_Model_base.ddCartridge) does not exist in the workspace, Design Studio displays the following message for the Action Add Dependency on the summary page:

This Action cannot be executed

Reason : Either subject or participant or both is/are evaluated as NULL/do(es) not exist.

Example 2-12 Adding Project Dependencies

<input id="DPProject1" name="input1"> 
     <entityRefToken>ref1</entityRefToken>
</input>
<input id="DPProject2" name="input2">
     <entityRefToken>ref2</entityRefToken>
</input> 
<project id="DPProject" name="DS Project" tokenGroup="ProjectCreation">
     <description>Model Project</description>
     <typeId>MODEL</typeId>
     <defaultValue>Test_CFS</defaultValue>
</project>
<tokenGroup name="Project Creation" id="ProjectCreation">
     <description>Create project silently using default value.</description>
</tokenGroup>
<tokenGroup name="Project Creation" id="DependencyCreation">
     <description>Create project silently using default value.</description>
</tokenGroup>
<token name="EntityName1" tokenGroup="DependencyCreation" 
             id="ref1" xsi:type="EntityRefToken">
     <condition>
          <equals v2="1" v1="2"/>
     </condition>
     <defaultValue>@@DPProject@@</defaultValue>
     <entityType>ddCartridge</entityType>
     <relationship>xxx</relationship>
</token>
<token name="EntityName2" tokenGroup="DependencyCreation" 
             id="ref2" xsi:type="EntityRefToken">
     <condition>
          <equals v2="1" v1="3"/>
     </condition>
     <defaultValue>OracleComms_Model_base</defaultValue>
     <entityType>ddCartridge</entityType>
     <relationship>xxx</relationship>
</token> 
 
<action name="Add dependency" id="dependendyaction"> 
     <actionType>relationship</actionType>
     <subject>
          <participantType>input</participantType>
          <id>DPProject1</id>
     </subject>
     <participant>
          <participantType>input</participantType>
          <id>DPProject2</id>
     </participant>
     <actionKey>unknown</actionKey>
 </action>

Example: Defining Tokens for Resources

Consider that you want to define a token called equipmentName and use it to give an equipment specification in a design pattern a different name.

<token name="Equipment ID" tokenGroup="Resources" id="equipmentName"> 
     <description> The Equipment specification</description>
</token>

In this example, you would define the resource element targetLocation element for the specification as:

<targetLocation>model/equipment/@@equipmentName@@.equipment</targetLocation>

If the user (who runs the design pattern) enters the value opticalDevice for the equipmentName token, the targetLocation value in this example expands to the following when the pattern is applied:

<targetLocation>model/equipment/opticalDevice.equipment</targetLocation>

You can also define tokens in other locations of the path in the targetLocation. For example, you might define a token named deviceVendor and use it to expand the previous example:

<targetLocation>model/equipment/@@deviceVendor@@/@@equipmentName@@.equipment</targetLocation>

If the user enters the value oracle for the deviceVendor token, the targetLocation value in this example expands to:

<targetLocation>model/equipment/oracle/opticalDevice.equipment</targetLocation>

Note:

Design Studio automatically creates directories as needed when copying resources into a workspace.

Example: Defining Tokens as Default Values

You can define tokens as default values of other tokens. For example, you might define a token called deviceGateway and define it with the following default value:

<defaultValue>@@equipmentName@@_gateway</defaultValue>

If the user enters the value opticalDevice for the equipmentName token, the default value in this example expands to:

<defaultValue>opticalDevice_gateway</defaultValue>

Note:

When using embedded tokens as default values for other tokens, ensure that the embedded token appears in an earlier token group than where it is used. If a value has not been assigned before the token is displayed to a user, the Design Pattern wizard displays the embedded token ID in the defaultValue element.

Example: Defining Action Subjects or Participants With Values External to Design Patterns

In design patterns, action subjects and participants can be populated with values provided by the user or populated with resources generated by the design pattern. If you have a project or entity to which you need to make a reference or with which you need to create a dependency, and that entity or project exists in the workspace and is not a resource generated by the design pattern or the result of user input, you can use a default value of a hidden token to populate a field that references the entity.

Example 2-13 demonstrates how you can define a token element default value with a pre-populated value (rather than with inputs captured when running the design pattern). By defining a condition that always evaluates to false, the token does not appear as a field in the design pattern, but the token value can be used by the design pattern to reference an existing entity in the workspace.

Example 2-13 Defining Action Subjects or Participants With Values External to Design Patterns

<token name="projectNameToken1" tokenGroup="PDHiddenInfo" id="projectName1"
      xsi:type="EntityRefToken">
      <condition>
         <equals v1="test" v2="test1"/>
      </condition>
      <defaultValue>testProject1</defaultValue>
      <entityType>ddCartridge</entityType>
      <relationship>unknown</relationship>
</token>
 
<token name="projectCommon" tokenGroup="PDHiddenInfo" id="projectCommon"
      xsi:type="EntityRefToken">
      <condition>
         <equals v1="test" v2="test2"/>
      </condition>
      <defaultValue>OracleComms_Model_Base</defaultValue>
      <entityType>ddCartridge</entityType>
      <relationship>unknown</relationship>
</token>
<input id="projectName1_input" name="Project">
      <entityRefToken>projectName1</entityRefToken>
</input>
 
<input id="projectOracleComm_input" name="Project">
      <entityRefToken>projectCommon</entityRefToken>
</input>
 
<action id="AssociateDependencyProject" name="Associate Dependency Project">
      <actionType>relationship</actionType>
      <subject>
           <participantType>input</participantType>
           <id>projectName1_input</id>
      </subject>
      <participant>
           <participantType>input</participantType>
           <id>projectOracleComm_input</id>
      </participant>
      <actionKey>unknown</actionKey>
      <executeOnExistingEntity>true</executeOnExistingEntity>
</action>

Example: Supporting Multiple Selections for Entity Reference Tokens

Example 2-14 illustrates how to use inputs, entity reference tokens, and actions in the pattern.xml file to enable a user to select multiple entities when defining a project dependency.

Example 2-14 defines two entity reference tokens that are used in two different inputs. When the user runs this design pattern, the Add dependency action creates a dependency from the Cartridge Project entity the user selects in the Conceptual Model Project field (specified in input1) to each Cartridge Project entity they select in the Conceptual Model Project Dependencies field (specified in input2).

Example 2-14 Supporting Multiple Selections for Entity Reference Tokens

<inputs>
   <input id="input1" name="input1">
      <entityRefToken>modelEntity</entityRefToken>
   </input>
   <input id="input2" name="input2">
      <entityRefToken>entityContainer</entityRefToken>
   </input>
</inputs>
<tokens>
   <token name="Conceptual Model Project" 
          tokenGroup="ProjectCreation" 
          id="modelEntity"
          xsi:type="EntityRefToken">
          <entityType>ddCartridge</entityType>
   </token>
   <token name="Conceptual Model Project Dependencies" 
          tokenGroup="ProjectCreation"
          id="entityContainer" xsi:type="EntityRefToken">
          <allowMultiple>true</allowMultiple>
          <entityType>ddCartridge</entityType>
   </token>
</tokens>
<actions>
   <action name="Add dependency" id="dependencyaction">
      <actionType>relationship</actionType>
      <subject>
         <participantType>input</participantType>
         <id>input1</id>
      </subject>
      <participant>
         <participantType>input</participantType>
         <id>input2</id>
      </participant>
      <actionKey>unknown</actionKey>
   </action>
</actions>

Working with Cheat Sheets

Design Studio supports cheat sheets, which refers to the integration of documented procedures with wizards in the application. Cheat sheets are XML documents that can be interpreted by the Eclipse Cheat Sheet framework, and developers can map cheat sheets to specific points in the Design Studio user interface (for example, in editors and views). You access the cheat sheets that are relevant to current tasks, and complete those tasks using the included instructions. Cheat sheets enable you to find documentation for relevant solution design procedures and facilitate the learning of those procedures.

For example, you can use cheat sheets with design patterns to describe the resources added to a workspace and to assist users with any manual steps required after a design pattern is applied. Cheat sheets are not mandatory for design patterns, but they are recommended.

You can develop and edit cheat sheets using the Eclipse Cheat Sheet editor.

For information about creating and developing cheat sheets, see "Building Cheat Sheets in Eclipse" on the Oracle Technology Network:

http://www.oracle.com/technetwork/articles/entarch/eclipse-cheat-sheets-092351.html