Upgrading the user registry data source

Prior to NexJ Contact version 5.1, NexJ user information was stored in the User table in the default relational database.

Starting with NexJ Contact version 5.1, user information is defined in a separate user registry data source in the environment file. The user registry data source uses the same database as the rest of the application. This allows multiple NexJ Model Engines to work together in an enterprise environment.

If you are migrating NexJ Contact from any version prior to 5.1, you need to move the user information to a separate data source.

Before you upgrade your user registry, back up your current database.

Follow these instructions before you begin migrating your NexJ application.

In NexJ Studio, add the required new data source and SOA connections to the environment or connection file.
1. Add a relational database connection, where the data source name is ecr:ECR. For example,
```
<RelationalDatabaseConnection adapter="MSSQL"
                dataSource="ecr:ECR" database="crm" host="localhost"
                password="nexj" path="jtds-1.2.3.jar" port="1433"
                unicode="true" user="nexj"/> 
```
  For more information about configuring relational database connections, see Configuring a relational database connection.
2. Add two SOA connections, for the nexj:soa:UserRegistryClient:1.0 service and the nexj:soa:UserRegistry:1.0 service. For example,
```
<SOAConnection auth="basic" binding="context"
                service="nexj:soa:UserRegistryClient:1.0" user="nexjsa"/>
                <SOAConnection auth="basic" binding="context"
                service="nexj:soa:UserRegistry:1.0" user="nexjsa"/>
                
```
  For more information about configuring SOA connections, see Creating SOA connections.
Using the Data Load Tool, recreate the ecr:ECR data source.
Complete the Data Load Tool dialog as required, but ensure you specify the following information:
- In the Command field, select recreate.
- In the Data Source field, select ecr:ECR.
- Click the Advanced button. In the VM Arguments field, enter -Dseed.enabled=false on its own line.
For more information about recreating databases, see Recreating databases.
Update the Main.upgrade file to add a database-specific synonym to the user registry.
1. In the Persistence layer, click the Upgrades tab. Open the Main.upgrade file.
2. In the Upgrades section, select the DefaultRelationalDatabase upgrade with version number 3.48.25.soabase.
3. In the Upgrade Steps section, select the step named Provide sample scripts for generating a synonym to the user registry.
4. Remove the double hyphens (--) to include the SQL steps for your database type. Leave the steps for the other database types commented out.
5. Save your changes.
Using the Data Load Tool, upgrade the DefaultRelationalDatabase data source.
Complete the Data Load Tool dialog as required, but ensure you specify the following information:
- In the Command field, select upgrade.
- In the Data Source field, select DefaultRelationalDatabase.
For more information about upgrading databases, see Upgrading databases.

The user information is now stored in the ecr:ECR data source, not in the DefaultRelationalDatabase data source.

To validate that the upgrade steps were completed correctly, perform the following steps in your database manager.

Check that the NJUser table in the DefaultRelationalDatabase data source has a new userGUID column. Issue an SQL script similar to the following:
```
SELECT id, loginName, userGUID FROM NJUser
          ORDER BY loginName ASC
```
The userGUID column should now have non-null values for all users, except system users (such as nexjsa). The values for system users should be NULL.
Check that there is an UREnterpriseUser table in the ecr:ECR data source and that it is populated with records corresponding to records in the User table in the DefaultRelationalDatabase data source. Issue an SQL script similar to the following:
```
SELECT id, alias, firstName, lastName,
          loginName FROM UREnterpriseUser ORDER BY loginName
          ASC
```
The values in the id column in the UREnterpriseUser table should correspond to the values in the userGUID column in the NJUser table. System users such as nexjsa should not appear in the UREnterpriseUser table.