Help on Migrating Agile Platform from 4.2 to 5.0

Help on Migrating Agile Platform from 4.2 to 5.0


Is there any manual that I can use to make this Update?

Current system : Windows server 2003 32bit - Agile Platform 4.2
New System : Windows server Standart 2008 64bit - Agile Platform 5.0

The Database is on another server (Database Server).


- Is there a simple way to transport the eSpaces existing on the old server to the new server?
- Can I configure the AP 5.0 to use the current database? (is there any step-by-step to help on this process?)

Hi Nuno,

From what you say, you are facing 2 upgrades and 1 migration at the same time:

  • Operating System upgrade: Windows server 2003 32bit to Windows server Standart 2008 64bit 
  • OutSystems Agile Platform upgrade: 4.2 to 5.0
  • Database server migration: changing to another server

There is no step-by-step document that explains this, but I can give give you some insight on what has to be done.

Please bare in mind that if you are talking about a production server upgrade, you must always do two things before upgrading:
1. Validate and fix any breaking changes that might affect your applications. Please read through the Side Effects and Breaking Changes in Version 5.0 to get the full list of breaking changes in version 5.0 of the OutSystems Agile Platform;
2. Install your (fixed) applications in an OutSystems Agile Platform 5.0 staging environment and execute regression tests in your running applications;

In a high level, the steps to do to perform your upgrade are the following:
- Download a FULL 4.2 SOLUTION with all eSpaces and extensions from your OutSystems Agile Platform 4.2 server
- Request the License for your 5.0 server - Before installing, you should guarrantee you have a license available for your new 5.0 server. In case you only have licensing for 4.2 servers, you should contact to deal with the license upgrade process.
- Backup the original database and restore it in the new Database Server (this way you'll have your Outsystems 4.2 database in the new DB server)
   - Please read through the technical note Migrating an Environment Using a Database Clone. This technical note explains how you must clear some data that cannot be moved from one server to the other (eg. which are the outsystems servers IPs where applications are deployed, etc.)
- Install the new the Agile Platform 5.0 in the new Windows Standard 2008 64 bit server
  - To do this installation follow the Platform Server 5.0 - .NET Install Checklist (In the Configure Database step, you must configure the database shema and users to access the restored database. When you press the "Create/Upgrade Database", this will upgrade your OS 4.2 database to version 5.0)
  - Read the Agile Platform 5.0 - Systems Requirements
- Publish a FULL 4.2 SOLUTION you downloaded in the first step in your new 5.0 server (this will upgrade and publish all your eSpaces and extensions to 5.0)
- Reconfige you applications in the new server - if the Outsystems Server name or IP address changes, you might have to change some configurations in your applications.

See also the document What's New in Agile Platform version 5.0.

I hope this information helps.

Best Regards,
Daniel Lourenço

How do we do it in the following scenario: migrate from an old 4.2 server to an existing, already filled, 5.0 server.
We need to migrate eSpaces using the documentation you supplied.

But how about migrating all (relevant) data from 4.2 server to existing 5.0 server.
There are already eSpaces on the 5.0 server and also there is already lots of data in the new one.
Hi Joop,

To migrate 4.2 eSpaces to a 5.0 server, all you have to do is publish the eSpaces in the 5.0 server (this will upgrade and publish the eSpace). Regarding the data, only the Static Entities will be filled  with the information that is specified in the eSpace. All the remaining data/configurations will have to be migrated with a specific migration process (or manually).

For the data migration, you can easily know which physical database tables correspond to a specific eSpace entity by executing the following query:

SELECT * FROM ossys_entity
INNER JOIN ossys_espace ON (ossys_entity.espace_id =

You can use several different solutions for the data migration depending on how complex it is to do (for example, will you have to "merge" table data?):
  1. Create an OutSystems application in the 5.0 server with all the data migration logic. This application connects to the 4.2 database (With the SQL Integration Services) and inserts it in the 5.0 application entities (that lives in the same server);
  2. Do the migration directly at the database level (with solutions like DTS or SQL Scripts);
  3. Create Excel export/import functionality to pass the data from one server to the other.
In case there is any kind of business logic in the migration process, I would definitely go for the first one - for example, normally the USER_MASTER table would need to be merged, what will affect all the tables that reference it (chaging/colliding IDs, etc.). I have participated in a complex scenario like that before and doing the migration in an OutSystems application was a huge benefit due to all the auditing and control that we had over the operation.


Daniel Lourenço

When I try to execute the above query I get the following error.

Msg 208, Level 16, State 1, Line 1
Invalid object name 'ossys_entity'.

Hi David,

I tried it in my local community installation an it worked. Are you sure you are executing the query in the catalog where you have the OutSystem database?
If you are using the community edition, that would be the outsystems catalog in the outsystems instance. See the forum post SQL Server databases and users created by Community Edition

Oh kewl, thanks Daniel.  Not being a DBA I'm still learning my way around Server Management Studio.  Most of the time when cruising around SMS that box is greyed out so I guess I stopped paying attention to it.  :P

Thanks Again, you guys have been a great help in building my applications.

Hi David,

I'm glad I could help.

Whenever you have any other questions, just share them with the community!


Daniel Lourenço

Hi Daniel,

This SQL is useful info.
We'll need to see what's the easiest way to migrate the data.

Keep you posted.