ODI 12.2.1: Exchange

 

Before You Begin

Purpose

This tutorial covers how to exchange custom objects within the ODI community via the Update Center. You can optionally add your own work to the library and download other people's contributions.

Time to Complete

Approximately 1 hour.

Background

As a developer, you should have an account at http://java.net for browsing and discussing Java development. Developers can share code via the exchange program. This is a moderated program (an Oracle administrator looks at your submitted code before they post anything you send up). ODI can browse and fetch new code (such as Knowledge Modules) or update existing code beyond what is supplied with the initial software release. All of this is optional, but certainly worth looking at.

Scenario

You just developed a very clever and exciting new Knowledge Module (KM) that you want to share with the ODI world, so you want to send it to the Upload Center via http://java.net. You also heard that someone else has developed another clever KM that sounds like just what you need for your current project. Rather than reinvent that second KM yourself, you decide to just download theirs, perhaps as a starting point for your modifications, or perhaps it is ready to go as-is.

What Do You Need?

The following is a list of software and hardware requirements used in this OBE:

  • Software
    • Oracle Enterprise Linux (OEL) 6.4 or higher
    • Oracle Database 12c Release 1 Enterprise Edition (12.1.0.2) - including Oracle Big Data SQL-enabled external tables, Oracle Advanced Analytics, Oracle OLAP, Oracle Partitioning, Oracle Spatial and Graph, and more
    • Oracle Data Integrator (ODI) 12.2.1 or higher
    • Alternatively, the Oracle Data Integrator Getting Started Virtual Machine (the VM) contains all of the above pre-installed.
  • Hardware
    • At least 2 GB RAM for each target (database or ODI)
    • At least 6 GB RAM for the VM (if you are using that)

Prerequisites

Before starting this tutorial, you should:

  • Have at least 6 GB RAM available if you're using the Oracle Data Integrator Getting Started VM
  • Have access to or have installed the sample lab artifacts
  • Have attended ODI 12c training, [D82167GC10] Oracle Data Integrator 12c: Integration and Administration, or equivalent experience.

Typographic Conventions

These are the conventions used throughout this practice to indicate who types what.

  • Filename or /path/subdirectory/. Often you can navigate to a destination without having to type it.
  • Command or value that you type, such as gedit .bashrc. Be mindful of periods at the end of sentences that are not part of the command.
  • Click this such as or .
  • Some variable or <variable> as something you replace. Often prefixed with "my" such as <myName> or <myHost>.
  • A Menu Item or dialog Field Prompt or Tab name. For example, "click the Designer tab and select Models > New Model".
  • Generally a red rectangle in the graphics is not part of the original image, but added to draw your attention to an item.
 

1. Download Custom Objects

To download new objects, start ODI and check for updates.

 

1.1 Start ODI Studio

  1. Double-click the ODI Studio icon on the Deskstop to start ODI Studio:

    Start ODI 12c Studio
    Splash screen progress bar

    Alternatively, if there is a Desktop Launcher shortcut, click on that.

  2. Click Connect to Repository. Login to ODI Getting Started repository.

    ODI Login
    ODI Init

    The User: SUPERVISOR and Password (welcome1) should be stored and pre-populated from the Wallet.

ODI is now started and ready to download new objects.

 

1.2 Download New Objects

  1. Go to the main menu bar, and click Help > Check for Updates.

    Help

  2. Make sure Official Oracle Update Center and Customers and Partners Update Center are selected.

    Updates 1of4

    Click .

  3. Search for Big Data. Key big in the search field and click Search (Magnifying).

    alt desc

    Select LKM Hive to Oracle (Big Data SQL).

    alt desc

    Review the information provided on the right hand side and then select its checkbox to download this KM. Do not click Next yet...

  4. Search for random and select the checkbox next to the RANDOM user function.

    alt desc

    Click to start downloading the custom objects.

    Wait for the files to be downloaded and then click .

  5. Wait for the objects to be imported and click to close the Import Report.

    alt desc

  6. Click to go back to ODI Studio.

    alt desc

The new objects were successfully identified and downloaded.

 

1.3 Verify Import of New Objects

  1. In Designer, click Refresh (circle arrows). Expand ([+]) the Global Objects accordion.

    alt desc

    Expand ([+]) Global User Functions to display the RANDOM user function.

    Expand ([+]) Global Knowledge Modules > Loading (LKM) to find LKM Hive to Oracle (Big Data SQL).

The new objects were successfully downloaded.

The new objects were successfully installed into the Global area of the repository.

 

2. Upload a Custom KM

For purposes of this exercise, the custom KM will be only a trivial change to an existing KM. To upload a custom KM, perform the following steps:

 

2.1 Create a Custom KM

  1. In Designer, expand ([+]) Global Objects > Global Knowledge Modules > Loading (LKM) > LKM Hive to Oracle (Big Data SQL).

    Right-click LKM Hive to Oracle (Big Data SQL) and select Duplicate Selection.

    Duplicate Selection
    Confirm Duplicate

    Click .

  2. Double-click Copy of LKM Hive to Oracle (Big Data SQL) to open it.

    In the Definition tab, rename the KM into <FIRST_NAME_LAST_INIT> LKM Hive to Oracle (Big Data SQL).

    alt desc

  3. Click Tasks tab. Select Create external table and click Add (green +).

    alt desc

  4. In the Properties panel, under General, change the task Name to Custom Task and select Ignore Errors.

    alt desc

    Click Save (diskette) to save the KM. Leave the tab open.

  5. Click Target Command tab, set Technology: Jython, and set Command to raise '''My custom exception''' (that is three straight quotes in a row).

    alt desc

    Click Save (diskette) again to save the KM. Close the LKM tab.

You have created a custom (albeit trivial) KM.

 

2.2 Bundle the KM as a Zip File

  1. Right-click on your new custom LKM in the Loading (LKM) tree and select Export.

    LKM Export

  2. Set Export to directory: /home/oracle/Desktop.

    alt desc

    Click to export the KM.

  3. Click to close the Export Key warning.

    Warning

    Click to close the Export finished dialog.

  4. Go to the Linux Desktop. Right-click on an empty space on the Desktop and select Create Folder to create a META-INF directory on the Desktop.

    alt desc

    Make sure you use ALL CAPS, and a hyphen (not an underscore) in the name.

  5. Open the OBE_Files directory and then open the ODI Exchange folder.

    alt desc

    Right-click on bundle.xml and select Copy.

  6. Open up the META-INF directory, right-click in it and select Paste.

    alt desc

  7. Right-click on bundle.xml and select Open with gedit.

    alt desc

    You can use another text editor, such as vi if you wish.

  8. Replace {KM NAME}, {KM VERSION}, {AUTHOR}, {URL} and {DESCRIPTION} (including the curly braces) with new values of your choosing. Before editing: 

    
 <update-bundle version="1.0" xmlns="http://xmlns.oracle.com/jdeveloper/updatebundle">
   <update id="{GLOBAL ID}" xmlns="http://xmlns.oracle.com/jdeveloper/update">
     <name>{KM NAME}</name>
     <version>{KM VERSION}</version>
     <author>{AUTHOR}</author> 
     <author-url>{URL}</author-url>
     <description>{DESCRIPTION}</description>
   </update>
 </update-bundle>

    After editing, it should look similar to this (but with your name and email): 

    
 <update-bundle version="1.0" xmlns="http://xmlns.oracle.com/jdeveloper/updatebundle">
   <update id="{GLOBAL ID}" xmlns="http://xmlns.oracle.com/jdeveloper/update">
     <name>myKM</name>
     <version>1.2.3</version>
     <author>Joe Programmer</author>
     <author-url>joe.programmer@example.com</author-url>
     <description>Does cool new things for the OBE!</description>
   </update>
 </update-bundle>

    Leave the file open, do not close it yet.

  9. Right-click on the KM export file and select Open with gedit.

    alt desc

    Look around line 16.

  10. Locate the GlobalId field in the <Object class=com.sunopsis.dwg.dbobj.SnpTrt node. 

    
 <?xml version="1.0" encoding="ISO-8859-1"?>
 <SunopsisExport>
 <Admin RepositoryVersion="05.02.01.01" IsLegacyIdCompatible="false" />
 <Encryption algorithm="AES" keyLength="128" exportKeyHash="/zaFSZVcVL9g85h5/zp4ove9BfYktdE50NNn8LXZkLM="
   keyVect="6FEK5Lhjozxqa55Sw+ZMwA==" exportKeySalt="5796d8ac-1744-4f62-9f53-64979e4d6923"
   containsCipherText="false"/>
 <Object class="com.sunopsis.dwg.dbobj.SnpTrt">
     <Field name="BaseKmType" type="java.lang.String">null</Field>
     <Field name="CleanupOnError" type="java.lang.String">null</Field>
     <Field name="CompType" type="java.lang.String">null</Field>
     <Field name="DelegateClass" type="java.lang.String">null</Field>
     <Field name="DelegateScript" type="java.lang.String">null</Field>
     <Field name="ExpectedAstClass" type="java.lang.String">null</Field>
     <Field name="ExtVersion" type="java.lang.String">null</Field>
     <Field name="FirstDate" type="java.sql.Timestamp"><![CDATA[2015-01-16 13:38:02.0]]></Field>
     <Field name="FirstUser" type="java.lang.String"><![CDATA[SUPERVISOR]]></Field>
     <Field name="GenType" type="java.lang.String">null</Field>
     <Field name="GlobalId" type="java.lang.String"><![CDATA[5db724b3-044c-4b6f-ae66-484a57bacb0a]]></Field>
     <Field name="IndChange" type="java.lang.String"><![CDATA[I]]></Field>
     <Field name="IndJrnMethod" type="java.lang.String"><![CDATA[S]]></Field>
     <Field name="IndSuppSetBased" type="java.lang.String">null</Field>
     <Field name="IntgType" type="java.lang.String">null</Field>

    (...more lines not shown, omitted for clarity...)

  11. Copy its hex value (CDATA[VALUE_TO_COPY]) and replace {GLOBAL ID} in the bundle.xml file with it. 

    
 <update-bundle version="1.0" xmlns="http://xmlns.oracle.com/jdeveloper/updatebundle">
   <update id="5db724b3-044c-4b6f-ae66-484a57bacb0a" xmlns="http://xmlns.oracle.com/jdeveloper/update">
     <name>myKM</name>
     <version>1.2.3</version>
     <author>Joe Programmer</author>
     <author-url>joe.programmer@example.com</author-url>
     <description>Does cool new things for the Beta class!</description>
   </update>
 </update-bundle>

    Your hex value may be different. Save bundle.xml file and close gedit.

  12. Select both the custom KM file and its META-INF directory, then right-click one of them and select Compress.

    alt descK

    Enter a name for the zip file (should start with KM_LKM_ and end with yourname) and select .zip then click .

    alt desc

You should now have a zip file on the Desktop with the bundle.xml and the KM.xml together.

 

2.3 Upload the New Object to the Web

On a production machine, you would have direct access to the web. On these lab machines, the firewalls prevent that direct access, so you will need to copy the files from the VM to the PC and then access the web from the PC (outside of the VM).

  1. From the VM, open a Terminal session and navigate to the Desktop. As root, copy the bundle.xml to the /shared folder. 

    
 [OS]$ cd /home/oracle/Desktop 
 [OS]$ su - root 
 [OS]# mount -t vboxsf shared /shared 
 [OS]# exit 
 [OS]$ cp KM_LKM_User.zip /shared     
 [OS]$

    Substitute User with your name.

  2. On your Windows host, go to C:\VMs to access the file you created in the VM.

    Windows PC C:

  3. On your Windows host, open a web browser and go to https://home.java.net/.

    alt desc

    Create an account by clicking Join Now if you do not have one yet. Otherwise, click Login.

  4. Log into Java.net.

    alt desc

  5. Go to https://java.net/projects/oracledi. Click on Join This Project.

    alt desc

    Click Downloads in the Project Features menu on the left hand-side, or on the right-hand side, they both take you to the same place.

  6. Navigate to ODI > Knowledge Modules > 12c .

    alt desc

    Click Add File / Link for Download.

  7. Specify the zip file to upload from C:\VMs, and enter a required title and description.

    Upload zip file

    Click to start the upload.

    Make sure you get a Success message.

    Status Success bottom half w/Done

    Click to complete the upload.

  8. The Java.net administrator has been notified automatically and the Update Center will be updated in a couple of days. Your new KM should then show up on other people's VM since it is a new option for them, but on your VM, since you already have your KM, it will not display as an available update. To fix this, delete it from your VM and then it will appear as an available update. (You would not do this in real life.)

    Delete KM Delete Confirm

    Click to continue.

  9. Back in Studio, on the main menu bar, click Help > Check for Updates and search for the object you just uploaded.

    Check for Updates

    Notice that the description and title match what is in bundle.xml in step 2.2.8, not what you called it in the java.net upload in step 2.3.5.

You have just uploaded a new object to be shared on https://home.java.net.

You have just create and uploaded a new KM to be shared with the ODI community.

 

Want to Learn More?

In this tutorial, you learned to:

  • Download custom objects from the Update Center
  • Upload custom objects to the Update Center via java.net.

Resources

Conceptual or procedural Help topics relevant to the topic of this tutorial:

Credits

As always, a team effort. This is a partial list of the team:

  • Lead Curriculum Developer: Julien Testut
  • Other Contributors: Steve Friedberg, Alex Kotopoulis, Ayush Ganeriwal