1. Developer's Guide
  2. Importing Entities into Design Studio

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 Service Catalog and Design - 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:

  1. Open Design Studio.

  2. Ensure all changes made in workspace are saved.

  3. Run a full build to ensure all model files are up-to-date.

  4. Open Studio Projects or Solution view.

  5. Open the Context menu by right-clicking the page.

  6. Select Import > Import Exchange Format.

  7. Click Browse and select the required exchange format file (.xml file).

  8. (Optional) Select Complete for a complete import.

  9. Click Next.

    The Summary Page appears.

  10. Check all the entities and elements that are imported and then click Finish.

    A dialog box appears to open the generated import log.

  11. 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:

  1. From the Design Studio File menu, select New, and then select Example.

    The New Example wizard appears.

  2. Expand the Design Studio Examples folder and select Design Studio Import Inventory Examples.

  3. Click Next.

    The Example Projects page appears. The Design Studio Import Inventory Examples example includes three example projects.

  4. 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.

  5. 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. Adding Import Commands to the Studio Projects View Context Menu 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:

  1. In Design Studio, switch to the Java perspective.

    See the Design Studio Help for more information about switching perspectives.

  2. Click the Package Explorer tab.

  3. In the Package Explorer view, expand the design.studio.example.import.inventory folder, and then expand the schemas folder.

  4. Double-click a schema file.

    The schema opens in the Data Schema editor.