Migrate Your Customizations With iSetup: Part I

So – your developers have been working on creating some new concurrent programs in your test environment. Or perhaps they’ve got some new request groups, printer setups, new responsibilities or other customized objects that need to be migrated out of the test environment and into production. Or perhaps you’d like to add users to a test environment that are already set up on production. It turns out you have three options: 1. Manually - Open up a screen pointing to your test environment and a screen pointing to your production environment, and manually copy (type) everything you want to move. Uggh – that’s how we did it in the olden days, but it is certainly not how we want to do it today. Manually making the changes takes too long, and it’s too easy to make mistakes. A thorough and time-consuming test of each migration would have to be included in your project plan. 2. FNDLOAD – Oracle’s utility can be used to download application data from an Oracle Applications instance into a portable, editable text file (.ldt file). The data in the FNDLOAD .ldt file can then be uploaded into another Oracle E-Business Suite instance. Check out Brad Simmons’ and Donna Campbell’s paper Customization Survival Guide: How to Use E-Business Utilities to Migrate Your Custom Code. They’ve included examples of commands and sample Unix scripts, and they’ve highlighted the potential “gotchas” that you need to keep in mind. With FNDLOAD, you’re working from a Unix account and have to have a thorough understanding of the objects that you want to move. You’ll still need to do a thorough test of the objects that you’ve migrated, but errors are less likely than if you hand-typed the information. 3. iSetup – iSetup is a module provided within the E-Business Suite that allows you to easily migrate setups using a user-friendly interface. You’ll work through EBusiness Suite screens rather than at the Unix level, so you do not have to be a programmer or DBA to feel comfortable using this tool. iSetup includes templates that make it easy to move commonly migrated objects, and, unlike our other two options, iSetup documents the configuration changes to allow you to compare changes across instances and timelines. There is one major caveat with iSetup – your source and target instances must be running the same patch set levels of the E-Business Suite, so iSetup would not be the tool to use for an upgrade, but would be very useful once the upgrade is complete for ongoing maintenance. For this paper, we’ll use two Release 12 Vision Instances that have been patched to Release Update Pack 12.0.5 (RUP5) Financials and HRMS. Besides the typical FND customizations that we expect iSetup to handle, like Roles, Users and Lookups, the Oracle E-Business Suite Release Content Document for Release Update Pack 12.0.5 (RUP5) Financials and HRMS says that iSetup also includes APIs for the General Ledger, Accounts Payable, Accounts Receivable, Assets, Cash Management, Credit Management, E-Business Tax, Legal Entity, Public Sector Financials, Payments, and WebExpense modules. It is worthwhile to stay current on your ATG Family Pack levels because Oracle continues to enhance iSetup.

Copyright 2008 TruTek


iSetup allows you to migrate Application Setup data (AOL). Administration To use iSetup. Once I have that working. I’ll describe how iSetup works and test moving some users created on one instance over to another instance. and then report on the configuration as well as compare configurations across instances or across time lines from the same instance. the screens used to set up iSetup. Foundation data and Operational data. Most companies would also include a migration test from your test instance into another test instance before migrating into production. Customizations must be tested thoroughly on your test environment. From an account with the iSetup responsibility assigned. Note that this is a powerful responsibility. you need to have an E-Business Suite account that has the iSetup responsibility. iSetup Reporter. Figure 1 shows the screen you’ll see after selecting iSetup: Copyright 2008 TruTek 2 . the tool that actually migrates data from one instance to another. someone still needs to test the customization after it is migrated. Only then should the customization be considered for migration into your production environment. even though iSetup makes migrating a simple process.For this first round of evaluation. And. A Functional Super User should sign off on the customization after thorough testing. iSetup consists of three main pieces – iSetup Migrator. so your Applications System Administrators are not likely to hand it out to just anyone. the tool that reports on what has been migrated. I’ll add more to the paper about issues encountered and ease of use. and Administration. Your company needs to incorporate using iSetup into your customization migration process.

and you’ll see ‘Home’. Figure 1 Your Applications System Administrator or your Applications DBA will need to do some configuration of your environment before you can start migrating customizations. In this case. Figure 2 Copyright 2008 TruTek 3 . Figure 2 shows the Administration screen.Click on iSetup. we haven’t configured iSetup yet. so we’ll need to tell iSetup which Applications instances can migrate data into this instance. ‘Migrations’. ‘Reports’ and ‘Administration’.

the Create Instance Mapping screen will give you an error. or if you type the DBC Filename incorrectly. click on the Create button on the target instance (see Figure 2) to set up a new instance. Enter the DBC Filename of that instance. Figure 3 Figure 4 Copyright 2008 TruTek 4 . In our example. Enter a Name for the instance that you’ll migrate from. Next.Before you can map an instance. If the DBC file is not in place where iSetup expects to find it. In Release 12. the VIS instance is the target instance. and VIS1 is the source instance. Enter the Responsibility Name that can migrate setups (you should choose iSetup). DBC files are located under $FND_SECURE. your Applications System Administrator or DBA will need to copy the source instance’s DBC file into the target instance.

♦ For each node. ♦ Confirm that the view RESOURCE VIEW exists with the sql command: describe resource_view. AZ: CP Number of Batches (Oracle’s recommended value: 5.ora file.<target>) o On the target instance. The database instances need to be able to connect to each other via sqlnet. The ability to transform data is a very useful feature. If you receive any “no rows selected” errors. tcp. add: tcp. ID: 243554. since you will lose your iSetup configurations if the instance that handles extracting and migrating the data is refreshed. including AZ: VO Fetch Size (Oracle’s recommended value: 100). optionally transforms the data. use 1).<central>.validnode_checking = yes to the sqlnet. you’ll need to install XDB using the instructions in MetaLink Doc. tcp. tcp.1. I am testing whether you can work with just a source and target instance because at least for now we don’t feel like using a third instance. except if running Manufacturing APIs to extract or load. How to troubleshoot iSetup issues describes how to check your database’s XML DB Setup: ♦ Check to see if the user XDB exists with the sql query: select * from all_users where username=’XDB’. AZ: Reporter Max Records (Oracle’s recommended value: 100) 2. ID: 560719.According to Oracle’s R12: Oracle iSetup Functional Overview online training class.invited_nodes needs to be updated on the database tier in $TNS_ADMIN/sqlnet. But you can see that having a separate instance where all the setup configurations are maintained would be preferred.invited_nodes=(<source>.invited_nodes=(<source>. then: o On the source node. Profile Options. MetaLink Doc.invited_nodes=(<central>. How to Deinstall and Reinstall XML Database (XDB). XML DB must be enabled for the database for both iSetup Migrator and iSetup Reporter.1. iSetup allows you to transform certain attributes within an Extract prior to loading the data into the target instance. additional settings that need to be reviewed to run iSetup are: 1. AZ: Commit Row Counts (Oracle’s recommended value: 1000). This feature means that users can save a transformed set of data just once and then reuse that transformed data the next time they Copyright 2008 TruTek 5 . so tcp.<target>) The “central instance” is an instance that just runs iSetup. iSetup extracts data from a source instance. AZ: Number of Records For Home Tab (Oracle’s recommended value: 4).<central>) o On the central instance. and then loads the data into a target instance. iSetup Migrator To migrate data.ora. 3. ♦ Determine if the Oracle XML DB status is valid with the sql query: select status from dba_registry where comp_id=’XDB’.

While there are a number of options. This Selection Set is used to migrate AOL Foundation setups.need to load data. from the SYSTEM ADMINISTRATOR responsibility. I created three new users on our VIS1 instance: MARYJOBEAKLEY. For a simple example. including user accounts: Copyright 2008 TruTek 6 . I’ll extract those three users from VIS1: 1. JONATHANHOWARD and JUMPINJEHOSEPHAT. you get to choose what type of information you want to extract. Create a new Selection Set Figure 5 When you click on the Create button. the one we’re interested in is General Foundation. and to register Generic Loader interfaces and set filters for them to extract a subset of the data. Next. Additional iSetup Migrator features include the ability to create a custom selection set.

Figure 6 Choose a pre-defined Selection Set from the list Figure 7 Additional Select Sets that you may choose in the Create Selction Set: Select Template screen Next. we see the Create Selection Set: Set Parameters screen. where we can choose what we want to migrate: Copyright 2008 TruTek 7 .

“New Users”. I unchecked all the boxes under the Select column except the one for Users. “New Users for Production”. I gave my Selection Set a Description.1. And then I clicked on the Filter to limit which users will be extracted: Copyright 2008 TruTek 8 . Notice that our Source Instance VIS1 is automatically available 2. Click on the Filter for “users” to see how much control we have over choosing users Figure 8 I gave my Selection Set a Name. Uncheck all the Select boxes except ‘Users’ 3. I chose VIS1 from the list of values for the Source Instance.

just before filtering out users Figure 10 If I click on the magnifying glass next to “USER_NAME”.Figure 9 – The Create Selection Set: Set Parameters screen. Copyright 2008 TruTek 9 .

Figure 11 Figure 12 Copyright 2008 TruTek 10 .

Copyright 2008 TruTek 11 . Uncheck all the Select boxes except ‘Users’ All we want are these three users. so I unclicked the checkmarked Select boxes for everything except “Users”.2. Click on the Filter for “users” to see how much control we have over choosing users 1. Then I clicked on the “Filter” icon to see how much help I might get in pulling the three users.

Click on Extracts 2. then migrate the extract into my VIS1 database instance. In the meantime.Figure 13 Stay Tuned… This is as far as I got before my lovely VIS instance was refreshed. users can compare setup data between snapshots of the data. My biggest concern as I tackled this migration was to see how simple it would be to find the three users and extract them. Next I’ll create an extract to get our new users from VIS1 Figure 14 The extract is next iSetup Reporter With iSetup Reporter. The comparisons can be between two different instances. Just how user friendly is the iSetup User Interface? Stay tuned! 1. or on a single instance between two Copyright 2008 TruTek 12 . I believe my next steps will be to finish the extract of my three users. so I’ll take a break and come back to finish off the migration next month. read on to understand some of iSetup’s other features.

The DBC file name is case-sensitive. 2. A user must have an account on both the source and target instances. The Source and Target instances must be on the same patchset before migrating setup data. “How to troubleshoot iSetup issues” – caveats include: 1. all very helpful: R12: Oracle iSetup Functional Overview R12: Oracle iSetup Technical Overview R12: Oracle Payables iSetup Technical Overview Copyright 2008 TruTek 13 . I’ll move on to detailing more about the reports. Also. Release 12. Oracle iSetup User Guide. This note references some patches for performance issues and java. August 2007 Oracle offers three self-paced learning topics.lang. 3. The file $TNS_ADMIN/sqlnet. With this reporting capability.OutOfMemory Errors. Stay tuned! Sources MetaLink Note: 560719. 4. Once I finish the migration.different timelines. so be careful when filling out the Instance Mapping screen.1. the ATG Family Pack level has to be the same. users can determine differences between the setups of two different instances. B31430-02.ora on both the source and target instances must have the corresponding instance invited. 5. or determine what setups have changed over a period of time. Part No.

Sign up to vote on this title
UsefulNot useful