This is documentation for Apprenda 7 and 8.
Documentation for newer version is available at https://new.docs.apprenda.com.

Conditional App Configuration and Tokens

When applications are developed in a local environment, there are many things that need to be configured in order to make the applications work. For example, connection strings must be configured to contact the database, resources must be referenced in specific locations, services must be targeted in certain areas, etc. The point of the Platform's conditional configuration system is to allow Developers to configure their applications to work in their local environment and, at the same time, prepare the configuration so that it will work when the applications are deployed on the Platform.

The Platform's conditional configuration system allows Developers to mark certain types of files with specific comments to denote sections of code to be 'swapped' when the configuration goes from a local environment to a live environment. This swap is handled by the Platform at runtime.

Files Configured by the Platform

Platform Registry Settings configured by your Platform Operator determine the defaults by which files will be conditionally configured:

  • For .NET components, the default files are configured by the Hosting.Windows.TokenFilePatterns setting.
  • For Java and Linux Service components, the default files are configured by the Hosting.Linux.TokenFilePatterns setting.

Developers may replace or supplement these defaults at the component level through an application's Deployment Manifest.

Conditional Configuration

The Platform has the ability to configure files depending the stage of development or deployment of the application. You can set up your application to have different setting values for local or deployed instances, or have different setting values for each stage of your application's deployment on the Platform (Sandbox or Publish).
 
Conditional configuration is easily implemented for applications by placing comment tags around the settings that should be used for local or on-Platform deployments. The examples below show how you can use the conditional configuration in your applications.

Conditional Configuration  Example

The following block of code shows how your 'App.config' might look if you were planning to use the Platform's database capabilities and conditional configuration system (this particular usage will work for multi-tenant applications only).

Notice that the only difference between the local configuration and the live configuration is that the local configuration uses the 'System.Data.SqlClient' and the live configuration uses 'SaaSGrid.Data.SqlClient'.  However, by defining the Data.SqlClient with the surrounding comment tags as indicated below, the Platform can make configuration changes that enable you to run your applications in a live environment while allowing you to develop your applications in a local environment.

When the application is deployed on-Platform the local configuration the Platform will change the comment tags to uncomment the live configuration settings and comment the local configurations settings.

<connectionStrings>
	<!--Apprenda Local Configuration--> 
	<add name="Taskr"
		providerName="System.Data.SqlClient"
			connectionString="Server=atlas\devsql01; 
				Database=Taskr; Trusted_Connection=True;"/>
	 <!--End Apprenda Local Configuration-->

	 <!--Apprenda Live Configuration
	 <add name="Taskr"
		  providerName="SaaSGrid.Data.SqlClient"
		  connectionString="Unused by Apprenda"/>
	 End Apprenda Live Configuration-->
</connectionStrings>

Stage-Based Conditional Configuration Example

In addition to local/live configuration switching shown in the previous example, the Platform supports live configuration switching as determined by the stage (Sandbox or Published) of a guest application. The following block of code shows how your 'App.config' might look if you were planning to use different databases for an application in each of the Sandbox and Published stages:

By defining the appSetting with the surrounding comment tags as indicated above, the Platform can make configuration changes that enable you to run your applications in a live environment with different configurations per application stage. Note that stage-based configuration tags may be used in addition to the Apprenda Live Configuration tags from the previous example, which will apply to the app in both the Sandbox and Published stages.

As the application is promoted and deployed on-Platform, the Platform will change the comment tags to uncomment the live configuration settings and comment the local configurations settings. The Platform will uncomment the configuration settings for the stage the matching the current stage of the Platform.

<appSettings>
	<!--Apprenda Local Configuration--> 
	<add key="FileService"
		value="http://localhost:8043"/>
	 <!--End Apprenda Local Configuration-->

	 <!--Apprenda Live Sandbox Configuration
	 <add key="FileService"
		  value="http://devfs:8043"/>
	 End Apprenda Live Sandbox Configuration-->

	 <!--Apprenda Live Published Configuration
	 <add key="FileService"
		  value="https://fs_rt01:8043"/>
	 End Apprenda Live Published Configuration-->
</appSettings>

 

Tokens and Token Switching

Apprenda Tokens are unique markers that are replaced with a resolved text value at runtime when applications get deployed on you Platform. This allows you to reference Platform-specific environment variables without having explicit knowledge of them beforehand.

For example, the Platform uses registered hardware resources to deploy instances of your application's .NET services as needed, which means that you do not have predetermined knowledge of where your services might be deployed. If any of your .NET services reference a set of resource files on disk, during development you will not have path information to read those files from disk. By using an Apprenda Token, you can establish a marker in your configuration files that Apprenda replaces at deployment time with an absolute base directory path.

Using Apprenda Tokens

To use Apprenda Tokens, you must surround the token name you wish to use like this: $#TOKEN_NAME#$ (where TOKEN_NAME is the name of the token you wish to use). The Platform will then replace all occurrences of your token definition with the runtime environment values according to where your services and user interfaces are deployed. 

You can use conditional configuration (described in the previous section on this page) with token switching while developing your application to make transitioning from your local environment to deployed on the Platform easier. The example below show how to implement token switching with conditional configuration.

Apprenda Tokens: an Example

This configuration block uses the Platform's conditional configuration system, which will automatically uncomment the contents on deployment. Everything inside the 'Apprenda Live Configuration' block will be uncommented on deployment and everything titled 'Apprenda Local Configuration' will be commented out on deployment.

<!--Apprenda Live Configuration
<parameter property="ProbePath" 
  value="$#BASEPATH#$" type="string" />
End Apprenda Live Configuration-->

<!--Apprenda Local Configuration-->
<parameter property="ProbePath" 
  value="" type="string" />
<!--End Apprenda Local Configuration-->

The example above demonstrates how to use Apprenda Tokens with Apprenda's conditional configuration system. The end result when this application is deployed in a live Apprenda instance will look like this:

<!--Apprenda Live Configuration-->
<parameter property="ProbePath" 
    value="C:\path\to\root\of\application\" type="string" />
<!--End Apprenda Live Configuration-->

<!--Apprenda Local Configuration
<parameter property="ProbePath" value="" type="string" />
End Apprenda Local Configuration-->

Special Considerations when using "--"

When information contained within a comment requires the string "--" (e.g., when constructing the URL for an application in the Sandbox stage), certain XML parsers (such as SAX) require that each "-" be encoded as "&#45;". In the example below, the string "--" in the value $#CLOUDURL#$/$#APPLICATIONALIAS#$--$#VERSIONALIAS#$ has been replaced with the string "&#45;&#45;".

Failing to use this notation may result in promotion failures to the Sandbox and/or Published stages,

<appSettings>
  <!--Apprenda Local Configuration-->
  <add key="DeploymentPath 
       value="http://localhost:8043"/>
   <!--End Apprenda Local Configuration-->
 
   <!--Apprenda Live Sandbox Configuration
   <add key="DeploymentPath”
        value="$#CLOUDURL#$/$#APPLICATIONALIAS#$&#45;&#45;$#VERSIONALIAS#$"/>
   End Apprenda Live Sandbox Configuration-->
 
   <!--Apprenda Live Published Configuration
   <add key="DeploymentPath"
        value=”$#CLOUDURL#$/$#APPLICATIONALIAS#$”>
   End Apprenda Live Published Configuration-->
</appSettings>

The Deployment Manifest and Token Replacement

Additionally, replacement of Apprenda Tokens is performed on the values of Environment Variables and System Properties configured for an application through its Deployment Manifest.  A Deployment Manifest can also be used to perform custom token replacements on a per-component basis.

Apprenda Tokens for .NET Apps

The following table lists currently available Apprenda Tokens for .NET applications and their use:

Token Name Description
APPLICATIONALIAS The application alias of the application that is
specified when it is created using the Developer Portal.
APPLICATIONCONNECTIONSTRING Used to configure connection information for databases deployed as part of your guest application.
APPLICATIONURL The URL to the application's user interface; e.g., "http://apps.apprendainstance.com/appalias" 
Only applicable to user interfaces.
BASEPATH The absolute path to the root directory of
where each .NET service is deployed or the
bin directory if used in an ASP.NET application.
CLOUDAPIURL The URL to the API root of the
Apprenda instance
(e.g. http://api.apprendainstance.com).
CLOUDHOST The part of the URL that is considered the root URL (without http:// or https://); e.g., "apprendainstance.com"
CLOUDURL The URL to the root of the
Apprenda instance
(e.g. http://apprendainstance.com).
ISBEINGSTAGED Applies to .NET services; is "true" if the service is being staged or "false" if the service is being hosted for actual use. Only applicable to .NET services.
PATHBASEDHOST The part of the URL that is used for hosting path-based applications; e.g., the "apps" part of "http://apps.apprendainstance.com/appalias"
SECUREAPPLICATIONURL The secure URL to the application's user interface; e.g., "https://apps.apprendainstance.com/appalias"  
Only applicable to user interfaces.
SECURECLOUDAPIURL The secure URL to the API root of the
Apprenda instance
(e.g. https://api.apprendainstance.com).
SECURECLOUDURL The secure URL to the root of the
Apprenda instance
(e.g. https://apprendainstance.com).
VERSIONALIAS The alias of the specific version of the application that is referenced.
VERSIONLIFECYCLESTAGE Applies to both user interfaces and .NET services; represents the current stage of the application (either "Sandbox" or "Published").
WEBSITEBIN The absolute path to the bin directory of an
ASP.NET IIS user interface's data, normally under WEBSITEROOT/bin. 
Only applicable to user interfaces.
WEBSITEROOT The absolute path to the root directory of an
ASP.NET IIS user interface's data. Only applicable to user interfaces.

Apprenda Tokens for Java Apps

The following table lists currently available Apprenda Tokens for Java applications and their use:

Token Name Description
APPLICATIONALIAS The application alias of the application that is
specified when it is created using the Developer Portal.

APPLICATIONCONNECTIONSTRING

Used to configure connection information for databases deployed as part of your guest application.
APPLICATIONURL The URL to the application's user interface; e.g., "http://apps.apprendainstance.com/appalias" 
Only applicable to user interfaces.
BASEPATH This is the equivalent to $CATALINA_HOME and points to the root of the Java container installation for the workload.
CLOUDAPIURL The URL to the API root of the
Apprenda instance
(e.g. http://api.apprendainstance.com).
CLOUDHOST The part of the URL that is considered the root URL (without http:// or https://); e.g., "apprendainstance.com"
CLOUDURL The URL to the root of the
Apprenda instance
(e.g. http://apprendainstance.com).
DBNAME Represents the name of the Database (or "Schema" in Oracle) where application-specific data is hosted.
DBPASSWORD Represents the Password that corresponds to the Database (or "Schema" in Oracle) where application-specific data is hosted.
DBPORT Port used by the hosting Database Service.
DBSERVER Represents the name of the Database Server where application-specific data is hosted.
DBSERVICENAME Database Service Name (valid for Oracle only) that corresponds to the hosting Database Server.
DBUSER Represents the User that corresponds to the Database (or "Schema" in Oracle) where application-specific data is hosted.
INSTANCEID The instance ID of the workload; typically a GUID.
ISBEINGSTAGED Is "true" if the service is being staged or "false" if the service is being hosted for actual use.
PATHBASEDHOST The part of the URL that is used for hosting path-based applications; e.g., the "apps" part of "http://apps.apprendainstance.com/appalias"
SECUREAPPLICATIONURL The secure URL to the application's user interface; e.g., "https://apps.apprendainstance.com/appalias"  
Only applicable to user interfaces.
SECURECLOUDAPIURL The secure URL to the API root of the
Apprenda instance
(e.g. https://api.apprendainstance.com)
SECURECLOUDURL The secure URL to the root of the
Apprenda instance
(e.g. https://apprendainstance.com).
VERSIONALIAS The alias of the specific version of the application
that is referenced.
VERSIONLIFECYCLESTAGE Represents the current stage of the application (either "Sandbox" or "Published").
WEBSITEBIN Points to the /bin directory for the deployed application (should always and forever be $CATALINA_HOME/bin).
WEBSITEROOT Points to the root directory of the deployed application within the Java container

Apprenda Tokens for Linux Services

The following table lists currently available Apprenda Tokens for Linux Services and their use:

Token Name Description
APPLICATIONALIAS The application alias of the application that is
specified when it is created using the Developer Portal.
BASEPATH This is the equivalent to $CATALINA_HOME and points to the root of the Java container installation for the workload.
CLOUDAPIURL The URL to the API root of the
Apprenda instance
(e.g. http://api.apprendainstance.com).
CLOUDHOST The part of the URL that is considered the root URL (without http:// or https://); e.g., "apprendainstance.com"
CLOUDURL The URL to the root of the
Apprenda instance
(e.g. http://apprendainstance.com).
DBNAME Represents the name of the Database (or "Schema" in Oracle) where application-specific data is hosted.
DBPASSWORD Represents the Password that corresponds to the Database (or "Schema" in Oracle) where application-specific data is hosted.
DBPORT Port used by the hosting Database Service (valid for Oracle only).
DBSERVER Represents the name of the Database Server where application-specific data is hosted.
DBSERVICENAME Database Service Name (valid for Oracle only) that corresponds to the hosting Database Server.
DBUSER Represents the User that corresponds to the Database (or "Schema" in Oracle) where application-specific data is hosted.
INSTANCEID The instance ID of the workload; typically a GUID.
ISBEINGSTAGED Is "true" if the service is being staged or "false" if the service is being hosted for actual use.
PATHBASEDHOST The part of the URL that is used for hosting path-based applications; e.g., the "apps" part of "http://apps.apprendainstance.com/appalias"
SECURECLOUDAPIURL The secure URL to the API root of the
Apprenda instance
(e.g. https://api.apprendainstance.com)
SECURECLOUDURL The secure URL to the root of the
Apprenda instance
(e.g. https://apprendainstance.com).

SSLCERTIFICATEPATH

The path to the .PEM certificate file

SSLPRIVATEKEYPATH

The path to the .PEM private key file
VERSIONALIAS The alias of the specific version of the application
that is referenced.
VERSIONLIFECYCLESTAGE Represents the current stage of the application (either "Sandbox" or "Published").

 Kubernetes Tokens

The following table lists currently available Apprenda Tokens for Kubernetes. Tokens may be placed in the spec file of the Kubernetes component.

Token Name Description
APPLICATIONALIAS The application alias of the application that is specified when it is created using the Developer Portal.
APPLICATIONURL The URL to the application's user interface; e.g., "http://apps.apprendainstance.com/appalias" 
Only applicable to user interfaces.
APPLICATIONCONNECTIONSTRING Used to configure connection information for databases deployed as part of your guest application.
CLOUDURL The URL to the root of the
Apprenda instance
(e.g. http://apprendainstance.com).
CLOUDHOST The part of the URL that is considered the root URL (without http:// or https://); e.g., "apprendainstance.com"
CLOUDAPIURL The URL to the API root of the
Apprenda instance
(e.g. http://api.apprendainstance.com).
DBNAME Represents the name of the Database (or "Schema" in Oracle) where application-specific data is hosted.
DBPASSWORD Represents the Password that corresponds to the Database (or "Schema" in Oracle) where application-specific data is hosted.
DBPORT Port used by the hosting Database Service (valid for Oracle only).
DBSERVER Represents the name of the Database Server where application-specific data is hosted.
DBSERVICENAME Database Service Name (valid for Oracle only) that corresponds to the hosting Database Server.
DBUSER Represents the User that corresponds to the Database (or "Schema" in Oracle) where application-specific data is hosted.
PATHBASEDHOST The part of the URL that is used for hosting path-based applications; e.g., the "apps" part of "http://apps.apprendainstance.com/appalias"
SECURECLOUDAPIURL The secure URL to the API root of the
Apprenda instance
(e.g. https://api.apprendainstance.com)
SECUREAPPLICATIONURL The secure URL to the application's user interface; e.g., "https://apps.apprendainstance.com/appalias"  
Only applicable to user interfaces.
VERSIONALIAS The alias of the specific version of the application
that is referenced.