8 Importing Entities into Design Studio
This chapter describes how to use Design Studio examples as a starting point for importing externally created Inventory entities into Oracle Communications Design Studio.
Importing Conceptual Model Entities
You can import conceptual model entities from external catalogs. You import external definitions using Exchange Format XML files. Earlier versions of Design Studio enabled you to use the Exchange Format XML files only for exporting entities. This enhancement enables you to also import entities, more fully integrating Design Studio into an overall design environment that includes other systems.
You can import the following conceptual model entities, along with supporting data elements, data schemas, and model projects, into Design Studio:
-
Product
-
Customer facing service
-
Resource facing service
-
Resource
-
Service action
-
Technical action
The Exchange Format XML file is a consistent representation of Design Studio entities and external catalog system entities. You can import multiple entities across multiple projects with a single input XML file.
You can perform a partial or complete import of the XML file. A partial import is intended to preserve existing definitions, allow new projects, entities, and elements to be added, and allow information on existing projects, entities, and elements to be added or updated. In addition to supporting incremental operations, complete imports remove enumerations and information from existing entities when this information is not included in the import file.
For more information on performing the import, see Importing Exchange Format Data from External Catalog.
Note:
Partial import is the default option.
A partial import:
-
Creates new projects, entities, and elements if they are not present in the workspace
-
Appends new information and updates the existing information for entities or elements
-
Leaves existing information on entities and elements, if information is not included in the import file
Note:
Partial import does not support the removal of information from existing entities or elements.
A complete import:
-
Creates new entities or elements if they are not present in the workspace
-
Replaces existing information on entities and elements with information that is provided in the import file
-
Removes information from existing entities or elements if that information is not included for these entities or elements in the input file
-
Handles enumerations as follows:
-
Removes existing information of entities or elements if they are missing from the input file
-
Updates existing entities or elements with information that is modified in the input file
-
-
Handles non-list or elements (for example, Copyright information, project name) as follows:
-
Defaults existing entities or elements with information that is missing from the input file
-
Updates existing entities or elements with information modified in the input file
-
Note:
Unique external identifiers must be provided for new instances of projects, entities, and elements that are imported.
Identifiers for existing or imported projects, entities, and elements cannot be modified by import operations.
The limitations on Conceptual Model imports are as follows:
-
Import operations will not update sealed projects, read-only projects, or read-only entities
-
Import operations will not rename existing projects, entities, or elements
-
Import operations will not delete existing projects, entities, or elements of an entity
Importing Exchange Format Data from External Catalog
To import exchange format data from an external catalog:
-
Open Design Studio.
-
Ensure all changes made in workspace are saved.
-
Run a full build to ensure all model files are up-to-date.
-
Open Studio Projects or Solution view.
-
Open the Context menu by right-clicking the page.
-
Select Import > Import Exchange Format.
-
Click Browse and select the required exchange format file (.xml file).
-
(Optional) Select Complete for a complete import.
-
Click Next.
The Summary Page appears.
-
Check all the entities and elements that are imported and then click Finish.
A dialog box appears to open the generated import log.
-
Click Yes to open the log file, or click No to go back to the previous view.
Importing Inventory Entities
You can use the published API information included in the Exchange Format to import Inventory entities from a different application or import entities from a different Inventory application.
You can import Service specifications, Service Configuration specifications, Logical Device specifications, Custom Object specifications, Ruleset extension points, and Rulesets from external Inventory systems into Design Studio. After import, Design Studio creates an Inventory project and adds these specifications to that project.
For example, by leveraging the information in the Design Studio Exchange Format, you can enable Design Studio users import Inventory entities by creating an Import menu action that appears in the Studio Projects view.
Adding the Design Studio Import Inventory Examples to a Workspace
Design Studio includes the Design Studio Import Inventory Examples example, which includes projects that demonstrate how to import external Inventory entities into Design Studio. These example projects are included in the Design Studio installation and can be added to your workspace.
To add the Design Studio Import Inventory Examples example to a workspace:
-
From the Design Studio File menu, select New, and then select Example.
The New Example wizard appears.
-
Expand the Design Studio Examples folder and select Design Studio Import Inventory Examples.
-
Click Next.
The Example Projects page appears. The Design Studio Import Inventory Examples example includes three example projects.
-
Click each of the following example projects to read a summary of the example project:
-
The design.studio.example.import.inventory.update.site project creates a project that demonstrates how to export installable features into an update site.
-
The design.studio.example. import.inventory.feature project creates a project that demonstrates how to add the import inventory example plug-in project to a feature project.
-
The design.studio.example.import.inventory project creates a project that contains sample code for importing external Inventory entities into Design Studio.
-
-
Click Finish.
The example projects are added to the current workspace.
About the design.studio.example.import.inventory Example Project
The design.studio.example.import.inventory example project includes a plugin.xml file that illustrates how to import Inventory entities and by leveraging the information published by the Design Studio Exchange Format.
Note:
The examples presented in this chapter are displayed in text form, such as that displayed on the plugin.xml tab of the Plug-in Manifest editor. You can configure extensions in the Plug-in Manifest editor using the form-based representation that appears on the Extensions tab as well. The plugin.xml tab and the Extensions tab display two views of the same information.
The design.studio.example.import.inventory example project illustrates how to complete the following tasks:
Adding Import Commands to the Studio Projects View Context Menu
The design.studio.example.import.inventory example project demonstrates how to add an import command to the Studio Projects view context menu. Example 8-1 displays an example of the configuration of the extensions for each of the following command classes:
design.studio.example.action.command.handler.ImportInventoryCommandHandler
design.studio.example.action.command.handler.ImportInventoryFileCommandHandler
Note:
These command classes are provided to demonstrate two different examples, where each example uses a different menu action. You can use either menu action example as a starting point to import your inventory data.
In Example 8-1, italics represent code that requires customization to meet your business needs. Add and review the Design Studio Import Inventory Examples project for more information.
Example 8-1 Adding Import Commands to the Studio Projects View Context Menu
<extension point="org.eclipse.ui.commands"> <command defaultHandler="design.studio.example.action.command.handler. ImportInventoryCommandHandler" id="design.studio.example.action.command.importInventoy.command" name="Import Example Inventory"> </command> <command defaultHandler="design.studio.example.action.command.handler. ImportInventoryFileCommandHandler" id="design.studio.example.action.command.importInventoyFile.command" name="Import Example Inventory File"> </command> </extension> <extension point="org.eclipse.ui.menus"> <menuContribution allPopups="true" locationURI="popup:imports?after=additions"> <command commandId="design.studio.example.action.command. importInventoyFile.command" icon="icons/sample.gif" id="design.studio.example.action.command. importInventoyFile.command" label="Import Example Inventory File" mnemonic="%contributions.menu.importInventoryDataFile.mnemonic" tooltip="Import Example Inventory Data"> </command> </menuContribution> <menuContribution allPopups="true" locationURI="popup:imports?after=additions"> <command commandId="design.studio.example.action.command. importInventoy.command" icon="icons/sample.gif" id="design.studio.example.action.command.importInventoy.command" label="Import Example Inventory" mnemonic="%contributions.menu.importInventoryData.mnemonic" tooltip="Import Example Inventory"> </command> </menuContribution> </extension>
Invoking the Import Inventory API Using an XML File
The design.studio.example.import.inventory example project demonstrates how to import inventory data from an XML file using the Design Studio Import Inventory Data Job Java API. Example 8-2 illustrates the example using the following command class:
design.studio.example.action.command.handler.ImportInventoryFileCommandHandler
In Example 8-2, italics represent code that requires customization to meet your business needs. Add and review the Design Studio Import Inventory Examples project for more information.
Example 8-2 Invoking the Import Inventory API Using an XML File
IWorkbenchWindow window = HandlerUtil.getActiveWorkbenchWindowChecked(event); ImportInventoryDataDialog diag = new ImportInventoryDataDialog(window.getShell()); int result = diag.open(); if (result == 0) { final File dataFile = diag.getInventoryDataFile(); if (dataFile != null) { final ImportInventoryDataJob job = new ImportInventoryDataJob("Import Example Inventory File", dataFile); job.setUser(true); job.setRule(ResourcesPlugin.getWorkspace().getRoot()); job.schedule(); } else { ExampleLogger.logError("Unable to import inventory data file.", null); } }
Invoking the Import Inventory API Using a Resource Object
The design.studio.example.import.inventory example project demonstrates how to import inventory data from an XML resource object using the Design Studio Import Inventory Data Job Java API.
Example 8-3 illustrates the example using the following command class:
design.studio.example.action.command.handler.ImportInventoryCommandHandler
The example demonstrates how to create an inventory resource object using the Design Studio Import Inventory Data Utility (ImportInventoryDataUtil) and how to populate the project details using Exchange Format APIs. In Example 8-3, italics represent code that requires customization to meet your business needs. Add and review the Design Studio Import Inventory Examples project for more information.
Example 8-3 Invoking the Import Inventory API Using a Resource Object
Resource inventoryResource = ImportInventoryDataUtil.createInventoryResource(); Mappings mappings = INVENTORY_FACTORY.createMappings(); inventoryResource.getContents().add(mappings); InventoryMappingList mappingList = INVENTORY_ FACTORY.createInventoryMappingList(); InventoryMapping inventoryMapping = INVENTORY_FACTORY.createInventoryMapping(); StudioModelEntityType inventoryCartridgeType = StudioModelEntityType.getTypeById (InventoryCartridgeModelFactory.ID); Project project = MODEL_FACTORY.createProject(); final String projectName = "ExampleInventory"; project.setName(projectName); project.setTargetVersion(getTargetVersion()); project.setVersion(getBuildVersion()); project.setKind(ElementKind.ENTITY); project.setIdentifier(projectName); project.setType(inventoryCartridgeType.getExternalKey()); project.setTypeName(inventoryCartridgeType.getName()); project.setId(inventoryCartridgeType.getExternalKey() + "=" + projectName); inventoryMapping.setProject(project); mappingList.getElement().add(inventoryMapping); mappings.setInventoryMappings(mappingList); // Below line shows creation of DataElementList DataElementList dataElements = DataFactory.eINSTANCE.createDataElementList(); final ImportInventoryDataJob job = new ImportInventoryDataJob ("Import Example Inventory Resource", inventoryResource); job.setUser(true); job.setRule(ResourcesPlugin.getWorkspace().getRoot()); job.schedule(); // Adds a job change listener to add external metadata to Resource after // finishing import job. See ExampleJobChangeListener for more // information. job.addJobChangeListener(new ExampleJobChangeListener(projectName));
Adding External Data to an Inventory Project
After you import specifications, you add all external data files required by the Inventory project to the resources directory. The design.studio.example.import.inventory example project demonstrates how to add external data to the Inventory project that is created by the Design Studio Import Inventory Data Job Java API (ImportInventoryDataJob). The Design Studio Import Inventory Data Job Java API is asynchronous, so you must add a job change listener to listen to the job state changes.
Example 8-4 illustrates how to add external data files using the following class:
design.studio.example.inventory.job.ExampleJobChangeListener
In Example 8-4, italics represent code that requires customization to meet your business needs. Add and review the Design Studio Import Inventory Examples project for more information.
Example 8-4 Adding External Data to an Inventory Project
URL fileURL = Platform.getBundle(Activator.PLUGIN_ID).getEntry("samples/sample.xml"); File dataFile; try { dataFile = new File(FileLocator.toFileURL(fileURL).toURI()); IProject project = ResourcesPlugin.getWorkspace().getRoot().getProject(projectName); if ((project != null) && (project.isOpen())) { IFolder resourcesFolder = project.getFolder(IStudioCartridge.DIR_RESOURCES); if (resourcesFolder.exists()) { IFile newFile = resourcesFolder.getFile("sample_copy.xml"); FileInputStream fileStream = new FileInputStream(dataFile); if (!newFile.exists()) newFile.create(fileStream, false, null); } } } catch (CoreException | URISyntaxException | IOException e) { e.printStackTrace(); }
Accessing Import Errors and Warnings
The design.studio.example.import.inventory example project demonstrates how to access errors and warnings generated when you import specifications. The Design Studio Import Inventory Data Job Java API (ImportInventoryDataJob) is asynchronous, so you must add a job change listener to listen to the job state changes.
Example 8-5 illustrates how to access import errors and warnings using the following class:
design.studio.example.inventory.job.ExampleJobChangeListener
In Example 8-5, italics represent code that requires customization to meet your business needs. Add and review the Design Studio Import Inventory Examples project for more information.
Example 8-5 Accessing Import Errors and Warnings
Job job = event.getJob();
if (job instanceof ImportInventoryDataJob) {
IStatus status = ((ImportInventoryDataJob) job).getStatus();
if (status.isMultiStatus()) {
// This can be used to find out any errors or warnings,
// such as, missing dependencies and invalid files, and how to
// take necessary action.
}
ExampleLogger.log(status);
}
Viewing the Design Studio Inventory Data Schema
You can view the details of the Design Studio Inventory data model by viewing the Design Studio Inventory data schema.
Note:
To view the Design Studio Inventory data schema, you must first add the Design Studio Import Inventory example. See "Adding the Design Studio Import Inventory Examples to a Workspace" for more information.
To view the Design Studio Inventory data schema:
-
In Design Studio, switch to the Java perspective.
See the Design Studio Help for more information about switching perspectives.
-
Click the Package Explorer tab.
-
In the Package Explorer view, expand the design.studio.example.import.inventory folder, and then expand the schemas folder.
-
Double-click a schema file.
The schema opens in the Data Schema editor.