Skip to main content

 

The Detach Process

 

OutSystems

The Detach Process

This article applies to:OutSystems 11Other versions available:10.0

This document is a step-by-step guide for extracting the source code of your applications (web and mobile) from the .NET version of OutSystems and how to set it up to be executed and maintained independently of OutSystems, if you ever decide to detach from it. This is a complement to the OutSystems Platform – Standard Architecture with No Lock-in content that gives a high-level view on how OutSystems, unlike other proprietary technologies and frameworks, generates standard, optimized, and fully documented .NET source code that does not require runtime interpreters or engines.

Detach Process Overview

The detach process applies when you wish to completely remove OutSystems. It’s not possible to detach only some applications from OutSystems while keep other applications still using the OutSystems platform infrastructure. To perform a complete detach, you will need to:

  1. Guarantee that, before you start, you have all the requirements and followed all the recommendations from Chapter 2;
  2. Prepare the Application Server and Database Server according with Chapter 3;
  3. Detach, compile and deploy all individual modules and mobile apps as detailed in Chapter 4;
  4. Test the result application(s) without OutSystems as presented in Chapter 5.

Make sure you read the full content of this document before you start to get a better overview of all the steps required and to better plan the process.

If at any step you run into a problem, you may need to repeat the previous steps until you get things working properly. Be careful and do not skip any instructions in the document to minimize the chance of making mistakes. In the case of not being able to proceed at any of those steps, you are free to contact OutSystems Support and we will happily help you.

Before You Start

The steps described in this document are not for evaluation purposes and are to be used only if you decide to stop using OutSystems.

What will you lose?

If you choose to stop using OutSystems, you will no longer have access to all the application development, management, and operation capabilities of the platform. Also, you’ll no longer benefit from the embedded change technology (ECT), performance monitoring and logging capabilities, which means you’ll have to implement such functionality by resorting to other tools. You will however retain all core functionality of the applications you developed using Service Studio and Integration Studio, although any changes made to the detached source are not supported by OutSystems anymore.

After detaching the source code of your applications, all OutSystems tools and services will become unavailable (including Service Studio, Integration Studio, Service Center, and Lifetime), along with all of their features for visual development and composition, services repository, integration adapters automatic generation, database and application hot deployment, configuration management and versioning, packaging and staging, automatic code containment and optimization, factory access control management, performance monitoring and analytics.

Also notice that this is a one-way street. Once you detach the source code and start developing your applications using Visual Studio or Eclipse, there is no reverse engineering process to get those applications back into OutSystems.

Recommendations before you start the detach process

In order to minimize the risks of getting errors during and after the detach process:

  • Ensure that OutSystems applications are running with the expected behavior. Since OutSystems capabilities are lost, it will be more difficult to fix the majority of the problems after the detach.
  • Update to the latest release of your OutSystems version to benefit from having all known bugs for that specific version fixed; This translates to having the latest Release of your Major.minor.Release.revision version installed correctly.
  • Detaching Development source code and deploying it to a Production Environment is not a valid process. If you want to do this, first you need to stage your applications from one environment to another and only then you can proceed with the detach.

Personnel requirements

Since you will lose most of the OutSystems capabilities, you must guarantee that your personnel:

  • Fully understands the complete life cycle of .NET applications; This includes understanding how to create, modify and deploy those application, as well as creating and managing the references between them while having a good understanding of IIS.
  • Has access to the Database Server and have the ability to modify the existing data; During the detach process, it is necessary to change some of the OutSystems metadata. This is typically done by a DataBase Administrator (DBA);
  • Knows how to develop, build and deploy Android and/or iOS apps (applies to mobile apps only).

OutSystems Scheduler Service

If you are using Timers or BPT Activities in your applications, you will be able to keep this functionality even after detaching. Unlike other OutSystems services, the source code of the Scheduler Service will be provided for this purpose, just contact OutSystems by opening a Support Case and requesting it.

To compile the scheduler, open the Scheduler.sln file, located in the Scheduler directory, with Visual Studio and build the solution. After that, open the Developer Command Prompt for Visual Studio (with Administrator privileges), go to the \Scheduler\bin\Debug folder and execute "installutil scheduler.exe". This will install a service called Detached Scheduler Service. To uninstall it, run "installutil /u scheduler.exe". If any problem happens, check the scheduler logs in the Event Viewer.

If you choose to re-implement these services using external tools you can later remove this dependency manually.

Understand how OutSystems structures the code

When you deploy an application module using 1-Click Publish operation, a standard .NET application is generated by the OutSystems Compiler. This is what is provided when you detach an application and download the source code.

The code is structured in the following folders:

  • OutSystems.Application.Core – interfaces to access runtime information.
  • OutSystems.Application.Session – shared code for the session runtime service.
  • OutSystems.Application.Session.Interfaces – session runtime service interface.
  • OutSystems.Application.Session.Persistent – session runtime service code that implements database persisted sessions.
  • DatabaseAbstractionLayer – the interfaces and base code responsible for allowing the Platform access and manage the data from the database.
  • DatabaseProviders
    • iDB2DatabaseProvider – the iDB2 implementation of the DatabaseAbstractionLayer used by the platform when connected to an iDB2 database
    • MySQLDatabaseProvider – the MySQL implementation of the DatabaseAbstractionLayer used by the platform when connected to a MySQL database
    • OracleDatabaseProvider – the Oracle implementation of the DatabaseAbstractionLayer used by the platform when connected to an Oracle database.
    • SQLServerDatabaseProvider – the SQLServer implementation of the DatabaseAbstractionLayer used when connected to a SQLServer database.
  • OutSystems.DebuggerClient – the debbuger protocol code.
  • OutSystems.Logging – the logging system code.
  • OutSystems.Logging.Database – interfaces for logging libraries that log to the database.
  • OutSystems.ModuleServices – shared code for BPT Activities.
  • OutSystems.Plugin.RabbitMQ – a RabbitMQ based implementation of the cache invalidation service.
  • OutSystems.PluginAPI – code and interfaces to manage plugin configurations.
  • OutSystems.Spreadsheet – runtime code to load and export Excel files.
  • OutSystems.RuntimeCommon – the basic runtime code used by all runtime libraries and modules.
  • Plugin.SAP
    • Runtime - runtime code responsible for consuming SAP services
    • RuntimeAPI – API exposed to extend the SAP functionalities
    • SapNcoConnectionManager – wrapper for the SAP .NET Connector libraries
  • Plugin.Widgets.Runtime – the runtime code for the various custom web controls using the WidgetsRuntimeAPI
  • <Project Name> – the module’s source code.
  • REST.RuntimeAPI – used to consume REST services and to extend REST behaviors using extensibility.
  • RESTService.Runtime – the runtime code used to expose REST services
  • RuntimePlatform – the Platform’s runtime code used by the module.
  • Scheduler.Core – the scheduler core code.
  • ThirdParty – Third party components that are necessary for the applications to work
    • EXIFExtractor – the EXIFextractor is a .NET component which allows the extraction and manipulation of image files information.
    • GemboxSpreadSheet – the GemboxSpreadSheet .NET component which enables developers to write, read or convert spreadsheet files (XLS, CSV, XLSX, HTML or ODS) from their .NET applications.
    • Json.NET – the Newtonsoft Json.NET is a library to serialize and deserialize between .NET objects and JSON formats.
    • SAP – the SAP.NET Connector libraries used by the SapNcoConnectionManager project.
    • WebApi2 – the ASP.NET Web API is a framework that makes it easy to build restful HTTP services.
  • WebWidgets – the runtime code for the various custom web controls
  • WidgetsRuntimeAPI – framework to allow building custom web controls

    Figure 1 - Code Structure of a generated Application.png
    Figure 1: Code Structure of a generated Application.

In the application folder (<Project Name>) there is a set of packages that hold the different types of code. These folders are

  • Actions – the code generated for both built-in actions and functions, and user actions and functions;
  • Blocks – the code generated for both built-in and custom web blocks;
  • Entities – the code to manage entities;
  • Structures – the code to manage structures;
  • ProcExc<ProcessName> – the code generated for processes;
  • Exceptions – the declaration of user defined exceptions;
  • Roles – the code to support role based security enforcement;
  • TypeFactory – the code used by consumers of the module so they can access the referred elements;
  • WebServices – the code to support all Web Services exposed by your module;
  • WebReferences – the code to support all Web Services consumed by your module.

Preparing Your Systems to Run Detached

Preparing the Application Server to deploy the Generated Code

The machine that will run the detached applications must be prepared to that purpose. Making sure that all the requirements are met minimizes the chance of failure of this process.

Some web services of OutSystems communicate inside the machine through the HTTP protocol. This requires the machine to access itself using HTTP protocol, on port 80, in its local IP address, 127.0.0.1, most commonly known as localhost.

You must guarantee that this is correctly configured, even if you only want to use HTTPS to access your applications.

To check it:

  1. From Windows Start Menu search for ‘IIS’ and open ‘Internet Information Services (IIS) Manager’.
  2. In the left pane tree expand the following items:

    • <your machine name>
    • Sites
    • Default Web Site Default Web Site.png
  3. Make sure that there is a binding for the HTTP protocol on port 80 for IP address 127.0.0.1 at least. It is recommended that you an asterisk (*) instead as that means all IP address can access it. Leaving only the 127.0.0.1 address will mean that it can only be accessed locally.

    127.0.0.1.png

If you are using the same Application Server that previously hosted OutSystems check Section 3.1.1. Otherwise, if a brand new Application Server is going to be used, configure it according with Section 3.1.2.

Using the Application Server that previously hosted OutSystems

In case of having SEO Friendly URLs, you will need to remove the ISAPI Filter, since SEO Rules will no longer work after detaching. To accomplish that:

  1. Inside IIS (check Section 3.1), click on your Default Web Site.

  2. In the middle-pane, find ISAPI Filters and double-click it.

    ISAPI Filter.png

  3. Search for OutSystem ISAPI Filter and delete it.

    ISAPI Filter - remove.jpg

Using a brand new Application Server

If you want, you can deploy your module in a new server where you never installed OutSystems. If you’re not considering this option skip this section.

For the new Application Server to accommodate your applications, you must first set up the server with the needed configurations, as if you were installing OutSystems, skipping the OutSystems installation itself.

To do this, you will need to either decommission the OutSystems server, or get a database copy to use with the new server.

Proceed as follows:

  1. Install IIS component (as described in the installation checklist). If you want to use Visual Studio remotely (from a workstation) install also Frontpage Extensions;

  2. Install .NET Framework 4.7.2 or above and configure it for use with IIS. Use the instructions in the install checklist;

  3. Configure Windows Management Instrumentation service;

  4. Configure the Application Pool associated with Default Web Site in IIS to use .NET Framework 4.0 and Managed pipeline mode set to Integrated;

  5. Update the data model in the OutSystems server:

    1. Update OSSYS_SERVER entity. Replace new_hostname with the output of the hostname command ran in a command line (in the new server).

      update ossys_server
      set name = 'new_hostname'
      where name = 'old_hostname'
      
    2. Update OSSYS_PARAMETER entity. Replace new_hostname with the output of the hostname command in a command line (in the new server) and old_hostname with the output in the old server.

      update ossys_parameter
      set host = 'new_hostname'
      where host = 'old_hostname'
      
  6. Update OSSYS_MODULEFRONTEND entity. Replace new_hostname with the output of the hostname command in a command line (in the new server) and old_hostname with the output in the old server.

    update ossys_modulefrontend
    set frontendname = 'new_hostname'
    where frontendname = 'old_hostname'
    
  7. Update OSSYS_MODULEINTERNALADDRESS entity to reflect your factory deployment zones configurations, which maps each module to the respective deployment zone internal address. Replace old_address with the old deployment zone address and new_address with the new address where the module is deployed.

    update ossys_moduleinternaladdress
    set deploymentzoneaddress = 'new_address'
    where deploymentzoneaddress = 'old_address'
    

    If you’ll be running modules in different frontends, you can identify each module with the MODULEKEY column and update its DEPLOYMENTZONEADDRESS accordingly:

    select ossys_moduleinternaladdress.modulekey, ossys_espace.name
    from ossys_moduleinternaladdress
    inner join ossys_espace
        on ossys_espace.ss_key = ossys_moduleinternaladdress.modulekey
    
    update ossys_moduleinternaladdress
    set deploymentzoneaddress = 'new_address'
    where modulekey = 'target_module_key'
    
  8. Copy the <appSettings> from machine.config of the machine that previously hosted OutSystems to the machine.config file of the new machine. To do this:

    1. Locate the machine.config files for .NET Framework 4.0, on both the old and the new server.
      Open them with a text editor;

      • On 64-bit machines you should update both the 32 and the 64-bit configuration files. These are usually available in the following locations:
        %WINDIR%\Microsoft.NET\Framework\v4.0.30319\CONFIG\
        %WINDIR%\Microsoft.NET\Framework64\v4.0.30319\CONFIG\
    2. Locate the <appSettings> tag from the machine.config of the machine that previously hosted OutSystems and copy its content.

      <appSettings>  
      …  
      </appSettings>
      

      Note that actual tag contents may vary, and even include settings that are not related to OutSystems. As a rule of thumb we recommend that you copy only the entries (keys) with the “OutSystems” prefix.

    3. Locate the <appSettings> tag from the machine.config of the new Application Server and paste the content inside this tag.

  9. Configure the DefaultAppPool to run as Local System. This is needed at least for first-time run, since some settings are written in the registry. To accomplish that:

    1. Open IIS Manager (see section 3.1) and expand the menu of your machine.

    2. Search for Application Pools and double-click it.

    3. In the middle-pane, find DefaultAppPool and right-click it and open Advanced Settings….

    4. Inside Process Model, find the Identity field. By clicking it a button with … will appear.
      Click on it.

      Process Model-Identity.png

    5. Inside Application Pool Identity, select Built-in account and choose LocalSystem from the options provided.

      Application Pool Identity.png

Preparing the database to host the data of your applications

Your application data will be preserved either in the same databases/schemas and database server, or by moving the databases/schemas from the current database server to a new one. In case you are keeping the same database follow the procedure of section 3.2.1, on the contrary, if you are moving database server go to section 3.2.2.

Using the Database that previously kept the OutSystems data

OutSystems encrypts sensitive configuration data such as passwords. To secure that data, an encryption key was generated when you installed OutSystems.

That key is stored in the private.key file under the Platform installation folder (C:\Program Files\OutSystems\Platform Server). To allow your application to decrypt sensitive data you need to ensure that it uses that key.

By default, your application will use the private.key file located in the Platform installation folder and after uninstalling it will be removed. For that reason, create a copy of the private.key file in a path where an IIS user can read and change the configuration file accordingly. To change the configuration file:

  1. Locate the machine.config files for .NET Framework 4.0, on both the old and the new server.
    Open them with your favourite text editor;

    • On 64-bit machines you should update both the 32 and the 64-bit configuration files. These are usually available in the following locations:
      %WINDIR%\Microsoft.NET\Framework\v4.0.30319\CONFIG\
      %WINDIR%\Microsoft.NET\Framework64\v4.0.30319\CONFIG\
  2. Under <appSettings>, locate the <add> element with the key = "OutSystems.HubEdition.SettingsKeyPath(DEFAULT)".
    Change the value attribute of this element to point to the new location of the private.key file.

Using a brand new Database

If you will use a new database, you have to manually reconfigure your database connection strings. To do this:

  • Locate the machine.config files for .NET Framework 4.0, on both the old and the new server.
    Open them with a text editor;

    • On 64-bit machines you should update both the 32 and the 64-bit configuration files. These are usually available in the following locations:
      %WINDIR%\Microsoft.NET\Framework\v4.0.30319\CONFIG\
      %WINDIR%\Microsoft.NET\Framework64\v4.0.30319\CONFIG\
  • Change the connection strings under <appSettings>. You will not be able to use them since their value attribute is encrypted, hence the need to convert them to plain text format. These strings vary with the different database providers and are provided in Section 6.1. There are 10 connection strings to declare. You can find them searching for the values presented in the table in the key attribute:

    Connection
    OutSystems.DB.Logging.Application.Admin.ConnectionString
    OutSystems.DB.Logging.Application.Runtime.ConnectionString
    OutSystems.DB.Logging.Services.Admin.ConnectionString
    OutSystems.DB.Logging.Services.Runtime.ConnectionString
    OutSystems.DB.Platform.Application.Admin.ConnectionString
    OutSystems.DB.Platform.Application.Runtime.ConnectionString
    OutSystems.DB.Platform.Application.Session.ConnectionString
    OutSystems.DB.Platform.Services.Admin.ConnectionString
    OutSystems.DB.Platform.Services.Runtime.ConnectionString
    OutSystems.DB.Platform.Services.Session.ConnectionString

    An example using SQL Server and one of the connection strings is provided:

    <add key="OutSystems.DB.Logging.Services.Runtime.ConnectionString"
        value=" User ID={LogUser};Password={LogPassword};Data Source={Server};Initial Catalog={Database}; />
    

    Depending on the connection string, you must use the corresponding user and password. For the example given, the Log user was used since it was the one referenced.

  • In the OutSystems database, find the OSSYS_DBCONNECTION table. You need to update the DATABASE_CONFIGURATION connection string since it is encrypted by OutSystems. Change it to the following format:

    ProviderKey=SqlServer
    <DBConfiguration><ConnectionStringOverride>{CONNECTION_STRING_IN_PLAIN_TEXT}</Co nnectionStringOverride></DBConfiguration>
    

    In order to create a correct {CONNECTION_STRING_IN_PLAIN_TEXT}, follow the Section 6.1.

Detaching an Application from OutSystems

This chapter covers how to detach, compile and deploy a single module.

In order to have a system that replicates your previous factory, you must deploy all the applications published by OutSystems. This way you guarantee that all dependencies are met, further reducing the chances of failure.

Since there are some specific OutSystems applications for application and environment configuration and management, like Service Center and Lifetime, those cannot be detached.

If your OutSystems is running on the OutSystems PaaS, in order to detach the source code of your applications, first you need to build a hybrid deployment, where you installed one OutSystems environment either on-premises or on another public cloud.

You must follow sections 4.1 to 4.6 for a successful detach of all modules. This includes OutSystems modules that your applications, most likely, depends on, like RichWidgets and Users applications.

Get the source code of Web applications

To obtain the source code of a web application module, open the Licensing page under the Administration tab in Service Center and detach the source code as follows:

  1. Click on ‘eSpaces Source Code’.

    eSpaces Source Code.png

  2. Click on ‘Detach’ for the module whose source code you want to obtain.

    Detach.png

  3. Wait until OutSystems has finished packing the module source code and click on ‘Download’.

    Download.png

  4. Save the zip file and extract it.

Get the source code of Mobile apps

To fully detach a mobile app from OutSystems you will need to:

  • Detach the back-end source code of the mobile app by following the same procedure outlined in section 4.1 (Web applications), selecting the eSpace corresponding to your mobile app when doing the detach;
  • Detach the native app source code used to build the installable APK or IPA application package (known as the ‘native shell’) by following the procedure presented below.

You will need to obtain and deploy/build these two detached components to get a fully working mobile app detached from OutSystems.

To obtain the native app source code of an Android or iOS mobile app, open the Applications page under the Factory tab in Service Center and proceed as follows:

  1. Search for the application corresponding to your mobile app and click on its name to go to the detail page.

    Select application.png

  2. In the Native Platforms tab click in the ‘Download source code’ icon for the desired platform build (Android or iOS).

    Download source code.png

  3. Save the tar.gz file and extract it.

The obtained source code corresponds to the source code of the most recent build of the mobile app for the selected platform.

Note: The mobile app source code is only kept for 7 days after a successful build. You will need to generate the mobile app again if the last build was made more than 7 days ago.

Compiling and Deploying Web applications

Before you open the application’s solution in Visual Studio, you need to make sure that no application or module publication has occurred in the local machine or otherwise you will get errors. To do this, check for any existing application publication data in Internet Information Services (IIS) and clear it out with the following steps:

  1. From Windows Start Menu search for ‘IIS’ and open it.

  2. In the left pane tree expand the following items:

    1. <your machine name>

    2. Sites

    3. Default Web Site

      Default Web Site.png

  3. Look for a virtual directory ( virtual directory.png ) that has the same name has the module you have detached and remove it; either by clicking on it and then pressing the Del key, or by right-clicking on it to open the popup menu and then choosing the ‘Remove’ option.

    virtual directory remove.png

If your application uses the OutSystems SAP plugin, then the SAP .NET Connector libraries have to be manually added to the detached source code. To ensure that the application compiles successfully, you need to copy the sapnco.dll and sapnco_utils.dll files, located in the \thirdparty\lib\ folder in the Platform Server installation directory, into the ThirdParty\SAP folder that came with the detached source code.

In order to deploy applications to IIS, you will need Visual Studio 2017 15.9.7+ with the following workloads and components:

  • .NET desktop development workload
  • ASP.NET and web development workload
  • .NET Core cross-platform development workload
  • .NET Framework 4.7.2 SDK and targeting pack individual components

To deploy your applications, proceed as follows:

  1. Open the <Project Name>.sln file that is provided in the extracted source code of the detached application.

  2. Execute the Visual Studio’s Build Solution command to compile your application.

  3. Execute the Visual Studio’s Publish <Project Name> command to publish your application to IIS by creating a Custom profile. When asked choose the Custom option and give a name to the profile.

  4. Configure the new profile and press Save:

    Publish Web.jpg

  5. After a successful publication, open IIS and search under your Default Web Site for the virtual directory with the name of your published module and click on it.

  6. Make sure that your application is running under an Application Pool that uses .NET 4.0.
    To change the application pool of the underlying web site, select the web site and in the Actions pane click on Basic Settings. Click Select, and select an application pool that is configured to use .NET 4.0.

  7. Locate the application configuration file, appSettings.config, present on deployment folder and change database connection strings:

    1. Open IIS, right-click over the desired application and select Explore option;

    2. Open the appSettings.config;

    3. Change connection string configurations like you did for machine.config (see section 3.2.2).

Compiling and Deploying Mobile apps

Before you start
If you detached the back-end source code of the mobile application and deployed it outside OutSystems, update the back-end endpoint in the <extract_path>\source\config.xml file by changing the following entries:

<content src="https:// <new_endpoint_hostname> /MyAppName/" />
<preference name="DefaultHostname" value=" <new_endpoint_hostname> " />

Android mobile apps

To build a detached Android mobile app you will need:

  • Android Studio installed in your computer.

  • Android SDK (it should have been installed together with Android Studio).

  • (optional) Your own keystore to sign generated app packages (APKs) . If you don’t use a specific keystore, a default keystore will be used to sign the app. You may encounter issues in updating applications when you generate the mobile app in different machines without using your own keystore, since each machine will have its own default keystore.

Build your Android app by following these steps:

  1. Open Android Studio;
  2. Click on the ‘Open an existing Android Studio project’ option and select the
    extract_path>\source\platforms\android folder;

  3. When the Gradle sync operation finishes, choose one of the following:

    • Build > ‘Build APK’ menu option to generate an application package signed using a default keystore ; OR
    • Build > ‘Generate Signed APK…’ to generate an application package signed with your own keystore (you will be asked for some data related to the keystore).

iOS mobile apps

To build a detached iOS mobile app you will need a Mac with Xcode installed. You will also need an Apple Developer or an Apple Enterprise Developer account to test your mobile app on an real iOS device.

To build the app and run it on your device, do the following in Xcode:

  1. Open the <your_application_name>.xcodeproj project file available in
    <extract_path>\source\platforms\ios folder;

  2. Make sure that your Apple ID is correctly set up in Xcode so that it is associated with your Apple Developer account;

  3. Make sure that you have defined your team (set it in Project editor > ‘General’). If your Apple Developer account doesn’t have any provisioning profiles or certificates yet, Xcode should create a team provisioning profile and a development certificate for you;

  4. Connect your iOS device to your Mac;

  5. Select your connected device as the target in the ‘Scheme’ toolbar menu;

  6. Click the ‘Run’ button.

Xcode will build and install the app on the device and then launch it.

Custom Database plugins

OutSystems already includes database plugins that come within the source code of the detached application. In case of having custom plugins, put those inside the <your_application_name>/bin folder of the detached application. In Visual Studio add a reference from the detached project to the database provider assembly that you just copied to the bin folder.

Extensions

Extension modules don’t generate source code. As such, source code for custom extensions are always available for detachment and reuse. Just use Integration Studio, as usual, to open and compile the source code using Visual Studio.

Microsoft Excel files

If your application handles, either reads or writes, data stored in MS Excel files, you will have to change the SetLicense() method.

To setup the professional license you will need to:

  1. Find the SetLicense() method on RuntimePlatform/GemBoxLicensing.cs and set the method to use your own Gembox Spreadsheet license;

  2. Request from GemBox a DLL for the GemBox Professional version;

  3. Go to the detached source code solution and replace in References the GemBox free version DLL with the Professional version DLL in both RuntimePlatform and application projects.

In case of not having such a license, you can use the limited Gembox Spreadsheet free edition. Although this license offers the same performance as the paid version, there are limitations in the number of rows per sheet, and the number of sheets per workbook. You should investigate these values further, as they are subject to change.

Managing .NET references

When publishing an application, OutSystems automatically compiles that specific module and also its references. It then propagates the files generated from the referenced application to the application that references them.

Take as an example application A that uses a web block of application B. Application B is referenced by application A. When publishing application A, first OutSystems compiles application B and uses the files generated in that compilation to be used as reference to application A. Only then does OutSystems compiles and deploys application A.

When you detach an application, you lose this automatic procedure and you will need to perform those steps (either manually, creating scripts or by managing references through Visual Studio). This means that, after you detach, when you modify application B and then publish application A without any other action, the changes made were not reflected.

In order to manage the references manually:

  • Compile the referenced application, in this case only application B.
  • Go to the Application B/bin folder and copy all the .dll files.
  • Paste the content to Application A/bin folder.

Now application A is ready to be compiled and deploy. This procedure is the same as described in section 4.1 and 4.2.

If an application depends on another applications, you might need to deploy all its dependencies in order to guarantee that it keeps working correctly.

Container Hosting Technologies

When publishing an application to a Deployment Zone configured with a supported Container Hosting Technology (Docker Container, Amazon ECS, Azure Container Service and Pivotal Cloud Foundry), OutSystems automatically generates an archive with the application files, all the necessary artifacts to deploy that application to the selected technology and the unified configuration file for the application's modules and its Application Scheduler.

When you detach an application, you lose the automatic creation of these artifacts. We recommend that before detaching an application, you publish any application to a Deployment Zone with the desired Container Hosting Technology so that you have access to the necessary artifacts.

However, to have an application running on a container some modifications to these artifacts will be required.

Docker Based Technologies

This procedure applies to Docker Container, Amazon ECS and Azure Container Service.

Before you start, follow the steps in the Compiling and Deploying Web applications section so you have your application compiled and ready to deploy. The generated archive for Docker Based Technologies, has the following structure:

archive docker

Your archive will be different since the folders inside the modules folder are dependent on the modules an application has.

To deploy your detached application to a Docker container, follow these steps:

  1. In the generated archive, delete all folders inside the folder modules but keep the web.config file.

  2. Delete all folders inside the folder bin but keep the hwc.exe file.

  3. (Optional) Delete the Appname file.

  4. Copy the folder with your application binaries to the folder modules.

  5. Replace the code in init.ps1 with the following:

    $env:PORT=80
    Stop-Service -Name w3svc
    c:/bin/hwc.exe -appRootPath modules -multipleApps true
    
  6. Build a Docker image using the Dockerfile and spin up the containers running the application.

Pivotal Cloud Foundry

Before you start, follow the steps in the Compiling and Deploying Web applications section so you have your application compiled and ready to deploy. The generated archive for Pivotal Cloud Foundry (PCF) has the following structure:

pivotal archive

Your archive will be different since the folders inside the modules folder are dependent on the modules an application has.

To deploy your detached application to a PCF container, follow these steps:

  1. In the generated archive, delete all folders inside the folder modules but keep the web.config file.

  2. Delete all folders inside the folder bin but keep the hwc.exe file.

  3. (Optional) Delete the Appname file, the configs folder and secrets folder.

  4. Copy the folder with binaries of your application to the folder modules.

  5. In the manifest.yml files, replace the line starting with command with the following:

    command: bin/hwc.exe -appRootPath modules -multipleApps true

  6. Push your application to PCF and run it.

Final Steps

When all applications have been successfully published, it is recommended that you test everything first before uninstalling OutSystems Plaform Server. If you moved from Application Server, skip section 5.1 and test your applications, since no uninstallation needs to be performed.

Before uninstalling

If no error was found there’s a great chance you followed everything correctly, nevertheless some errors may appear when you uninstall the application. To safely test this without having to reinstall everything follow this steps:

  • Stop all OutSystems services;

  • Store a copy of C:\Program Files\OutSystems\Plaform Server on another location. After that, you can either change the name of C:\Program Files\OutSystems\Plaform Server, for example to C:\Program Files\OutSystems1\Plaform Server or simply delete this folder.

This way you can simulate an uninstall and you should be able to access all your applications.

Testing

Test your application extensively to guarantee no errors are found. If any issue is found, repeat all the steps to confirm that you didn’t miss any. If the error persists, contact OutSystems Support.

When you are sure everything is working correctly and no OutSystems files are present (other than the ones we asked you to keep), you have successfully performed the detach.

If you changed the name of the folders where OutSystems server was installed, to uninstall you must change the names back to the original values.

Appendix

Connection strings

When you need to convert your connections string to plain text, use the corresponding string according with your database provider(s).

An example is provided so that you can easily map the placeholders from the Configuration Tool, which can be found under Windows Start Menu -> OutSystems -> Administration Tools .

Appendix - Configuration Tool.png

If it is an external database connection, you can get the same information accessing ServiceCenter - > Administration -> Database Connections, since the names are exactly the same.

Appendix - Database Connections.png

Do not forget to change the placeholders, wrapped around curly brackets {}, with your own information. Also, each connection string refers to a different User; this mean that for each string you must check which User it refers to.

SQL Server / Azure SQL

User ID= {User}; Password= {Password};Data Source= {Server}; Initial Catalog= {Database};

Appendix - SqlServer1.png

Appendix - SqlServer2.png

Appendix - SqlServer3.png

Oracle

User ID= {User}; Password= {Password}; Data Source= (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST= {Host} )(PORT= {Port} ))(CONNECT_DATA=(SER VICE_NAME= {Service Name} )));

Appendix - Oracle1.png

Appendix - Oracle2.png

Appendix - Oracle3.png

iDB2

DataSource= {Server}; Database= {Database}; UserId= {Username}; Password= {Password}; Def aultCollection= {Schema};

Appendix - iDB2.png

MySQL

Server= {Server}; Database= {Schema}; Uid= {User}; Pwd= {Password}; Allow User Variables=true; ConnectionLifeTime=6000; ConnectionReset=true;

Appendix - Mysql1.png

  • Was this article helpful?