Deploying Your Applications
The information in this section covers the following:
provides you with background on how application deployment works on the Apprenda Platform
helps you select and configure the ideal application services, database model, and user interface deployment model that meet your deployment goals
walks you through the steps of using the Developer Portal to deploy your application
Please note that while this section contains basic use-case driven information relevant to all types of applications, it does not cover Apprenda's Billing system or information specific to Multi-tenant or SaaS (Software-as-a-Service) applications.
For information on deploying and managing applications with Multi-tenancy and Billing (including how to take advantage of Apprenda's Billing system) can be found in the Deploying SaaS Apps section of our documentation.
How the Apprenda Platform Deploys Your Application
This section discusses at a deeper level how Apprenda deploys your application onto the servers that constitute your Apprenda environment. This topic does not discuss how to take advantage of an Apprenda feature or otherwise program your application, but rather gives someone who desires a deeper knowledge of Apprenda information about how the application will ultimately be deployed on the grid.
A thorough understanding of the Getting Started section is recommended prior to reading this topic.
Introduction to the Deployment Process
Recall from the Application Fundamentals section that an Apprenda application consists of a specifically-structured ZIP file. The structure determines the tiers (web application, web service, or database) to which each application component belongs.
Apprenda, partly during upload and partly during publishing, will parse this structure to extract the various component tiers of your application and will statically analyze both the binaries and configuration of each to discover how your application components are related to one another. Apprenda creates a metadata map of your application that describes how the different tiers and components within tiers relate to one another. This map is useful to Apprenda in many different scenarios, including deployment and execution.
Once your application is uploaded, parsed, and mapped, Apprenda copies all files that make up your archive to the Apprenda Repository. The Apprenda Repository is a centralized location (typically configured during installation as a network path or share) that Apprenda uses to manage both application and node file assets. Once your
application has been uploaded, you can promote the application to the Sandbox or Published stages via the
Developer Portal, causing the items included with your application to be deployed onto the various servers making up your grid instance.
The deployment process occurs in a matter of minutes, but the workflow that results in the safe and successful deployment of your application is quite complex. Apprenda deploys the actual components of your application to servers that are profiled to support that sort of tier in a location- and instance-transparent fashion. For example, your database will only be installed on a database server node, and the Platform will supply the necessary configuration
information for the database so that web applications and services may communicate with it.
Web Application Tier
Besides application data and WCF services, Apprenda natively manages the deployment of your web applications to the Apprenda instance. There are two steps, described in detail further below, that occur whenever a web application is deployed to or otherwise managed by Apprenda.
The web application is deployed to one of the frontend servers.
Any Apprenda server that has Internet Information Services (IIS) and Apprenda's User Interface
Manager service running is designated as a frontend server. During installation, Apprenda asks the user to denote which servers should be used for hosting web applications and ensures that they are configured appropriately.
The reverse proxy is configured to direct traffic to the actual frontend server hosting the application. Because there can be many frontend servers, there needs to be a reverse proxy. This server is responsible for responding to all inbound traffic for the Apprenda instance. Apprenda uses Application Request Routing (ARR), an add-on to IIS, to route requests to the web server that is actually hosting your application's user interface. Apprenda's Load Management service must also run on the reverse proxy server, as it is responsible for configuring ARR. Like standard frontend servers, the reverse proxy server is chosen and configured appropriately during installation.
It should be noted that the reverse proxy can also be a frontend server. This is common for single-node and smaller instances of the Apprenda platform. The only difference in this scenario is that traffic for a given web application may simply be redirected onto itself. Alternately, the reverse proxy server runs independently and need not participate in the Platform instance in any other capacity, which is useful for high-availability scenarios.
The following diagram illustrates how all incoming web requests are handled for your Apprenda application. The specifics of this routing and how Apprenda chooses the initial server for deployment are discussed in the next few sub-sections:
Application URLs
Before discussing what happens when Apprenda deploys your application, we'll cover how the URLs used to access the user interface of your application are constructed. Apprenda bases your application's URL on your application's alias. This alias, coupled with the application version alias and Apprenda Root URI, is used to direct all incoming requests to your Apprenda application.
Apprenda supports two patterns for accessing your web application:
Subdomain: http[s]://$applicationAlias[--$versionAlias].$ApprendaRootUri
Path: http[s]://apps.$ApprendaRootUri/$applicationAlias[--$versionAlias]
The pattern must be selected prior to deployment of the application by the Development Team that publishes the application. The default pattern can be specified for new applications by the Platform Administrator. In the patterns above, items in square brakets denote optional items. In the case of http[s] this denotes an SSL connection. Apprenda will automatically redirect non-SSL traffic to SSL if SSL connections are enforced by the Platform
the specific version is not defined in the URL. Note that this moniker permits multiple versions of an application to be in the Sandbox stage at the same time.
Suppose one wishes to access Version 2 of an Apprenda application called Northwind, which was deployed to an Apprenda instance available at contososoftware.com; they would use the following URLs:
Subdomain: http://northwind--v2.contososoftware.com
Path: http://apps.contososoftware.com/northwind--v2
If and only if Version 2 is in the Published stage, they could access Version 2 of the application with the following URLs:
Subdomain: http://northwind.contososoftware.com
Path: http://apps.contososoftware.com/northwind
Custom URLs
For applications deployed with the Subdomain pattern (custom URLs are not available for applications deployed with the Path pattern), Apprenda can configure your application to respond at the URL of your choice (configured in the Developer Portal). When a custom URL is specified, the appropriate bindings are configured on the websites so that they resolve the URL. No other intervention is needed, although the Network Administrator must point this URL to your Apprenda instance.
For example, assume that Contoso wishes to make the Northwind application available online at northwindonline.com. When configuring the application, their Development Team would select the Subdomain pattern for UI deployment, and would specify the custom URL as "northwindonline.com"; the URL used to access the application would then be: http://northwindonline.com
Deployment Mechanics
Deployment of a web application can be triggered by either of the following events:
An application is promoted to the Sandbox or Published stages
Either a Platform Administrator or Development Team relocates or replicates the web application The following steps must occur to deploy the application onto the instance:
1. Apprenda Chooses a Frontend Server 2. Apprenda Bootstraps the Web Application 3. IIS is Configured
4. The Reverse Proxy is Configured
The remainder of this section covers each of these steps in more detail. How Apprenda Chooses a Frontend Server
Unless the Platform Administrator has specified a server for web application deployment, Apprenda must appropriately choose a frontend server for the application at deployment time. This varies depending on whether or not Resource Throttling is enabled and, if it is, which Resource Policies are in use.
When the Platform Administrator has disabled Resource Throttling, new web applications are deployed to a randomly selected server. The number of and type of pre-existing web applications is not considered.
When the Platform Administrator has enabled Resource Throttling, the Resource Policy assigned to that web application is taken into account. In this case, the Platform calculates for each frontend server the number of slots available on each server. The number of CPU slots is calculated by taking the server's total of CPU (CPU speed x Number of Cores), multiplying it by the allocation factor, subtracting the allocated CPU (based on the resource policies in effect for previously deployed web applications), and dividing the amount into the CPU required by the web
application's assigned Resource Policy. The same calculation is used to calculate the number of memory slots. If the Resource Policy is unlimited, no calculation is conducted.
If no slots of either memory or CPU are available on any given server, it is removed from the list of potential
deployment targets. If no servers are able to deploy the web site, no deployment will occur and an appropriate error will be logged.
Of the remaining potential deployment targets, one is chosen depending on the Distribution Strategy chosen by the Platform Administrator:
Balanced by CPU: The server with the most CPU slots available is chosen for deployment Balanced by Memory: The server with the most memory slots availalbe is chosen for deployment Compressed by CPU: The server with the fewest CPU slots available is chosen for deployment Compressed by Memory: The server with the fewest memory slots availalbe is chosen for deployment How Apprenda Bootstraps the Web Application
Once a server has been selected to host the web application, Apprenda will:
1. Create a new folder on the server to store the user interface binaries of the application, located by default at C:\ApprendaPlatform\SiteData\$applicationAlias\$versionAlias\root.
2. Copy the binaries (previously uploaded or patched) to the new folder that was just created.
3. Copy bootstrap assemblies from the Apprenda Repository into the bin folder of the site, so that the necessary dependencies for your application to run on Apprenda are available. If your site has Silverlight XAP files, special DLR-based versions of the bootstrap assemblies are placed inside of your Silverlight application. 4. Modify Web.config and other configuration files -- including those in compressed Silverlight XAP files -- to:
Re-configure all WCF clients to address their services via Apprenda's router (for those that are hosted on Apprenda).
Apprenda’s ASP.NET authentication gateway and configurable login screen at the front of the HTTP pipeline (unless authentication is not required for your application).
Apply token replacements and conditional configuration directives as required.
5. Record and catalog information regarding the web application as required for tracking and management by the platform.
How IIS is Configured
Now that the web application's binaries are present on the machine chosen to host the web application, Apprenda's User Interface Manager will dynamically configure IIS on the machine.
A new web application is created in IIS, either at the root level or beneath the built-in apps.$ApprendaRootUri web application depending on the URL format specified for the given application.
If the application uses a subdomain, a binding is added so that it can respond to incoming traffic at the site's URL. Path-based applications need no binding, and Apprenda will set the name of the application appropriately so the site is
resolveable to incoming traffic.
Note that all traffic comes inbound to the site on Port 8080 by default. The reverse proxy will listen to traffic on Port 80 and 443 and redirect traffic to the appropriate site. This permits a server to host both the reverse proxy and actual websites. Reverse proxy configuration is discussed below.
The new web application is linked to a new application pool. This isolates the activity of one web application from other web applications on the server instance. This provides a safeguard, since if the web application experiences a crash, it will not affect other web applications while IIS deploys a new worker process. Additionally, Apprenda will throttle the memory usage and/or processor usage of the web application if it was deployed using a specific resource policy. How Apprenda Configures the Reverse Proxy
DNS or HOST file entries result in all inbound traffic being routed to the reverse proxy. Apprenda creates the necessary ARR URL re-write rules to break down the requested URL for the application and forwards it to the
appropriate frontend server chosen above that is now hosting the application. Custom URLs, if specified, are re-written here as well.
So that the reverse proxy may also host Apprenda applications, Apprenda uses internal ports when the request is forwarded from the reverse proxy to the web server hosting the application (which may or may not be the same server). By default, the primary web server's processing of URL's occurs on Port 80 and the internal port used for forwarding the request is Port 8080. Stated differently, all web applications deployed by Apprenda respond to Port 8080.
To secure actions involving sensitive data such as login, purchasing, and sometimes all application usage in general, Apprenda supports SSL natively and seemlessly with no further action needed by the application developer. Apprenda will automatically configure a wildcard security certificate on all web servers participating on your Apprenda instance. Whereas ports 80 (and 8080 internally) are used for your http connection by default, ports 443 will be used for
your https connection by default. To ensure better performance, Apprenda terminates external SSL connections at the primary web server using the ARR module and uses http connections internally.This strategy of SSL traffic
management is known as SSL Offloading and is a common technique to route HTTP traffic among servers that inherently trust one another.
Websites on Apprenda are not considered durable resources. In other words, a server may go offline either in a planned or unplanned scenario. To provide high availability for web applications (and assist with performance under high load), Apprenda natively supports the replication of websites on multiple servers. If the deployment request is to replicate the website, Apprenda will create a web farm in IIS on the reverse proxy server, and route requests through the web farm. This web farm is updated when one subsequently removes, relocates, or again replicates the website in a future action.
Apprenda's Authentication Gateway
Note: This section applies only to applications requiring authentication.
Once a web application is deployed on Apprenda, the application can start accepting HTTP requests. Apprenda uses cookies (both in the ASP.NET and in-browser Silverlight case) to manage authorized interactions with the User's browser. When a browser makes a request and doesn’t provide Apprenda with a well-known cookie, Apprenda’s HTTP pipeline requests that the User authenticate. Login is either conducted through a special website controlled by Apprenda called authentication, or by supplying claims as part of a SAML or WS-Federation token if the environment and End User are configured to support federated identity.
Once the User provides authentication information, this creates an active session on the entire Apprenda system (this session is omnipresent and has nothing to do with HTTP) and creates an encrypted, tamper-proof cookie that is used as a trust token for future requests. A screenshot of the cookie (as per Chrome developer tools) can be seen in the
illustration below:
When the user logs in and an Apprenda session is created, Apprenda also establishes an inactivity window (configurable by the End User's Company Administrator); if the User is inactive for some period of time beyond the established inactivity window, the session is expired. The cookie is subservient to the Apprenda session, so even if future requests have a valid Apprenda authorization cookie, the request will be rejected and the User will be required to log in.
Multiple Web Applications
All sections in the Web Application Tier topic to this point assume that your Apprenda application contains exactly one web application. In Apprenda, this web application is known as the root application. Notice that this same name is used in the application archive structure and as part of the folder path when partitions are created.
It is possible, however, to have multiple web applications inside of a single Apprenda application, and Apprenda will manage and deploy them all for you. The key difference, however, is that a virtual directory will be created beneath the physical website. The name of the virtual directory will be the same as the name of the folder indicated in the
application archive or patch, as illustrated in the following example.
Application Archive Folder Name Sample Web Address
~\interfaces\root http://northwind.contososoftware.com
~\interfaces\goods http://northwind.contososoftware.com\goods
~\interfaces\services http://northwind.contososoftware.com\services
Web Farms
In Apprenda, web farms are created when a new user interface partition is deployed to a new web server, effectively creating another copy of the UI. When a Developer or cloud operator sends a request for a new UI deployment, Apprenda does the following:
1. Apprenda will deploy a new copy of the UI to a web server that is currently not hosting this application. 2. The Load Manager Service will be notified of this new deployment and take the following actions:
a. Create a web farm in IIS for this particular application if there is none. If there is a web farm available for this application, the new server will be added to it.
b. Modify the rewrite rules to route requests for that application to the web farm. Diagram of the Web Application Tier with a Web Farm
The following steps represent the path taken by the request across the web tier of the Apprenda instance when a web farm is in place:
1. A request is received for a particular application.
2. The request is forwarded to the Revere Proxy server, which is where the root URL is pointing to.
3. The Reverse Proxy server has the Application Request Routing (ARR) module installed, which handles the rewrite and forwarding of the request.
4. ARR will rewrite and forward the request to the web farm. The web farm will choose a server to handle the request using a Round Robin strategy.
WCF Service Tier
Apprenda's own architecture is centralized around WCF services. As one could expect, Apprenda provides plenty of capability in the management and deployment of these services on the grid.
All servers that take part in your Apprenda instance are capable of hosting WCF services, though that doesn't necessarily mean all of them will be used to host applications published to the instance. This section introduces what happens when Apprenda deploys a service, and then explains how the Platform facilitates communication between multiple service instances.
Deployment Mechanics
New service instances are created when any of the following actions occur:
A service call is made and no instance of the service exists on the Platform. A service call is made and no existing instance responds to the service request.
An application is promoted to Sandbox or Published and the Platform is configured to automatically deploy services upon promotion.
The Apprenda instance owner invokes the creation of a new instance via the System Operations Center. The Development Team that published the service invokes the creation of a new instance via the Developer Portal (if permitted by the instance owner).
When a new instance of the service is created, the following workflow is executed:
1. The Platform Coordination service chooses an appropriate server, described in further detail below. 2. The Platform Coordination service asks the Service Container running on the chosen server to initiate the
deployment of a new service.
3. The Service Container generates a random GUID that will be known as the service instance ID. 4. Apprenda creates a local folder at
C:\ApprendaPlatform\Container\LaunchPads\$serviceInstanceId (chosen from the root of C:\
to reduce the directory length from Windows' folder path length).
5. The Service Container will copy the binaries consisting of that service from the Apprenda Repository to the local folder. However, existing Apprenda DLLs are not copied.
6. The Service Container copies the Service Bootstrap and its dependencies (including the Apprenda Live API) from the repository into the local folder. This results in the
executable Apprenda.SMART.ServiceBootstrap.exe, which will host the service being created.
7. The Service Bootstrap executable is configured appropriately, using your service's application configuration file as a base. This results in the generation of the file Apprenda.SMART.ServiceBootstrap.exe.config. Among other things, the service is configured to work with the Platform, and any conditional configuration sections and tokens are changed to their appropriate "live" values.
8. The executable is launched in a separate process by the Service Container. The Apprenda service account configured during installation is used to launch the process.
9. The Service Container registers with the Platform Coordination service that the new service instance is available.
Now that the service is running, it becomes available to fulfill requests. How Apprenda configures the service and actually directs service calls to the new instance is covered in further detail in the next section.
How Apprenda Chooses a Server
a server for the service at deployment time. This varies depending on whether or not Resource Throttling is enabled and, if it is, which Resource Policies are in use.
When the Platform Administrator has disabled Resource Throttling, a server is chosen at random among all of the servers that do not host web applications or databases. If there are no servers that do not host these items, one server is simply chosen at random. The number of and type of pre-existing services is not considered.
When the Platform Administrator has enabled Resource Throttling, the Resource Policy assigned to that service is taken into account. In this case, the Platform calculates for all servers the number of slots available on each server. The number of CPU slots is calculated by taking the server's total of CPU (CPU speed x Number of Cores), multiplying it by the allocation factor, subtracting the allocated CPU (based on the Resource Policies in effect for previously deployed web applications and services), and dividing the amount into the CPU required by the service's assigned Resource Policy. The same calculation is used to calculate the number of memory slots. If the Resource Policy is unlimited, no calculation is conducted.
If no slots of either memory or CPU are available on any given server, it is removed from the list of potential
deployment targets. If no servers are able to deploy the service, no deployment will occur and an appropriate error will be logged.
Of the remaining potential deployment targets, one is chosen depending on the Distribution Strategy chosen by the Platform Administrator:
Balanced by CPU: The server with the most CPU slots available is chosen for deployment Balanced by Memory: The server with the most memory slots availalbe is chosen for deployment Compressed by CPU: The server with the fewest CPU slots availalbe is chosen for deployment Compressed by Memory: The server with the fewest memory slots availalbe is chosen for deployment
Removal of Services
Service instances are removed from the grid when any of the following actions occur:
When the instance is idle (has not responded to any service calls) for the configured amount of time (unless the service is configured as non-volatile).
Faulty application code causes a crash.
The service exceeds the amount of memory it is permitted to use according to the service's assigned Resource Policy.
Apprenda Service Routing
Apprenda maintains a sophisticated meta-typing system to help route service calls on the grid. This provides the following benefits:
Multiple versions of your service can be deployed on the same grid instance.
Services can be accessed via well-known names from outside of the grid via the Remote API or a Silverlight client.
Clients accessing the service from within the grid are configured to use Apprenda's Router as an intermediary, removing location awareness and providing service call completion guarantees.
Upon promotion of your application to the Sandbox and Published stages, Apprenda catalogs details about your web service. Specifically, Apprenda maintains an inheritance tree for versioning your web services and to provide other system components with a way to logically reference your web services. For each web service, Apprenda creates Service Types representing the abstract WSDL proposed by your web service’s WCF Service Contract. As you evolve your application and service through Apprenda’s versioning system, Apprenda creates a new Service
Implementation that is a concrete representation of the Service Type.
The identifiers are guaranteed to be unique, which allows Apprenda to perform targeted, version-based routing and gives a uniquely identifiable logical system to target web service calls. Because of this, Apprenda can guarantee clients that some instance of the web service will satisfy a request without knowing the physical location of any instances. When you see Apprenda references (in documentation, portals, etc.) to metadata, it is typically referring to artifacts of this "typing system."
The following illustration shows the relationship between service types and Service Implementations as multiple versions of the service are created as the application evolves:
Each Service Implementation is linked directly to the WCF binaries that resulted in its creation. In fact, Apprenda treats the Service Implementation as a synonym for the WCF service itself. Understanding this hierarchy is critical to
understanding web service request dispatching in Apprenda. The metadata defined at this stage creates a logical representation that Apprenda uses to target arbitrary web service instances deployed on the grid. How this targeting and routing works is covered below.
Service Addressing
Apprenda will configure all clients to point to the local Router, which runs on all Apprenda servers, upon deployment. The following illustration indicates at a high level how service calls are routed on the grid.
Being a generic web service intermediary, the Router, upon receipt of the request, needs to determine what service the request is targeting. This is done via Apprenda's service metadata. The Apprenda Router accepts logical service targets and, from a pool of available physical targets, translates those logical service targets to single specific physical targets.
All service calls in Apprenda are logically addressed through the Apprenda Router. The Apprenda Router accepts SOAP messages via well-known URL patterns that inform the Router of the logical service target. The URL pattern is of the following specific format:
<scheme>://localhost[:port]/[listenPath/]<i|t>,<r|s>(<metaGUID>)
Each Apprenda Router starts a number of listeners waiting on requests matching this pattern; all adhering to the protocol will have a specific understanding of the URL parts after the ‘listenPath.’ The first component, '<i|t>,' specifies the type of logical target, ‘i’ for a ‘Service Implementation’ or ‘t’ for a ‘Service Type.’ The next
component, ‘<r|s>,’ instructs the Router that the call style is either ‘r’ for ‘request/reply,’ meaning that the client expects a reply message, or ‘s’ for a one-way ‘simplex’-style call. The last parenthesized component, the
‘<metaGUID>,’ specifies the unique ID of the logical ‘Service Type’ or ‘Service Implementation’ target (as defined via the first ‘<i|t>.’ To help solidify an understanding of this pattern, consider the following example:
net.pipe://localhost/services/soap12/pipe/i,r(36b08605-e79c-46c4-ab9f-bc113ccb0a93)
This URL is targeting an Apprenda Router’s SOAP 1.2-named pipe listening port via the ‘listenPath’
‘services/soap12/pipe.’ The client targeting this URL is expecting that the request will be handled by a service instance of the specific ‘Service Implementation’ (because of the ‘i') identified by the ID
‘36b08605-e79c-46c4-ab9f-bc113ccb0a93.’ Furthermore, because of the ‘r,’ the client is expecting that the request will generate a SOAP reply that the Apprenda Router has returned.
Targeting a ‘Service Type’ versus a ‘Service Implementation’ has implications. A ‘Service Implementation’ is a metadata leaf; no more specific logical representation exists. This means that a caller targeting a ‘Service
Implementation’ can expect that a specific physical instance of the ‘Service Implementation’ will behaviorally manifest itself in a well-expected fashion since ‘Service Implementation’ maps 1-to-1 to a WCF class in a .NET assembly that defines very specific logic behind a WSDL contract. Targeting a ‘Service Type’ is not as concrete, since it simply acts as a WSDL abstraction that may have many specific implementations. A request targeting a ‘Service Type’ is instead a request where selection of a more specific representation is left up to Apprenda. Every ‘Service Type’ keeps track of the ‘Service Implementation’ belonging to the newest version of the application owning the ‘Service Type’ as the default implementation. When the Router receives a request targeting a logical ‘Service Type,’ it will re-target the default ‘Service Implementation’ of that ‘Service Type.’ Having multiple ‘Service Implementations’ is important for allowing ‘Published’ and ‘Sandbox’ deployments for different versions of the same application to co-habit the same Apprenda instance. By having multiple ‘Service Implementations,’ Apprenda can logically target different physical instances of different versions.
Service Routing and Availability
Circling back and following the path of a web service request originating from your client, the Router parses the targeted URL for the previously described pattern, identifies the logical target, and checks it memory routing tables for the target. If the Apprenda Router has no address information for a physical instance matching the logical target specified, it immediately queries the Platform for a suitable web service that is a representation of the logical criteria. If no web service instance exists, the Router enters a "holding pattern," keeping the SOAP message in its in-memory pipeline and dispatches a dynamic deployment request to the service grid for an instance matching the targeted logical type. Once the Apprenda Router is notified that an instance matching the targeted logical type has come online, it will flush the held message and add the new location information of the instance to its cache for future use.
Besides offering an explanation of how service instances are located and automatically deployed to the grid, the previous explanation exemplifies one of Apprenda's high-availability mechanisms. Not explicitly mentioned in the workflow description above is that Apprenda will detect and attempt to re-start non-responsive services and will make multiple attempts to deploy services, all while holding your original service request noticeable to the client in the form of a delay in getting the response.
Architectural Considerations
While these considerations are not necessarily linked to your application, it can be useful to know how Apprenda architecturally provides routing.
Apprenda’s architecture is based on decentralized peer-based routing. Rather than proving a single, centralized “be-all” service bus and SOAP router, Apprenda runs local routing services on each individual server node. Client proxies, when under Apprenda’s management, are dynamically re-routed to target logical targets rather than physical targets. All service requests are, through inter-process communication, pushed to the local Router service. The Router service then takes over dispatching as described earlier, targeting a well-known service. This architecture provides a number of key advantages:
“greedy” clients may be generating significant load only overload local services, and will not flood and starve a centralized shared Routing service. This allows for a better distribution of routing throughput based on point of origin. The Apprenda Router was built with the notion that it will typically share machine resources with its clients, so it was written to provide high throughput while minimizing its own requirements as much as possible. 2. A higher level of overall resiliency when under duress. Decentralized architectures prove to be more resilient
when taxed and can provide more consistent aggregate guarantees. Systems with centralized routers tend to bottleneck under high load, requiring significant scale-up and/or clustering.
3. Lack of a risky central point of failure. Any failures can prove disastrous in a centralized routing system since the centralized dispatch services tend to be a “weakest link.” Instead, Apprenda can ensure that failures are isolated to only certain parts of the network (affecting only local clients).
While there is seemingly a substantial overhead in adding this intermediary, care has been taken to optimize this process. Our performance testing shows that this is marginal after the first service request, and is minimal compared to the time to contact the target service itself.
Development Considerations
It is required that the developer create fully stateless services. Besides permitting deployment using the fully shared model, this is important because Apprenda may, as a part of its normal operation, direct service calls to a new service instance. One example of this is how Apprenda's recoverability mechanics work: if a server with an instance of the service goes offline, Apprenda will deploy a new instance to another machine automatically, as opposed to denying a service call.
Database Tier
Given the importance of databases to most applications, Apprenda manages database definitions supplied by your application archive as first-class citizens. The Apprenda platform will provision both the artifacts that make up the database (tables, views, etc) and populate initial data as required. Apprenda's advanced lifecycle mechanisms ensure that your database is updated appropriately by the Platform when new versions of your application are published. The remainder of this topic describe the mechanics of these processes.
SQL instances, which is where guest application databases are deployed, ideally should be conifigured on separate nodes that do not serve as Apprenda servers (i.e., they do not host WCF web services), and may be configured as a failover cluster; however, in smaller Apprenda installations and single-node Apprenda Express installs, a SQL instance may be housed on an Apprenda server.
Any Apprenda server that hosts Apprenda's Storage Manager service (which requires that the server have SQL Server Management Objects [SMO] installed) will have the Storage Manager role. The Storage Manager interfaces with SQL server to create, delete, and otherwise configure databases.
During installation, Apprenda will prompt for information about which servers should host SQL/database instances, and configure them appropriately. One of the instances (also chosen during installation) must host the Core Databases, which are the databases used by the Apprenda Platform itself. In addition, the Apprenda Installer will select an appropriate host for the Storage Manager service; if none is found (i.e., none has SMO installed) among the servers you have selected to host services, you will be prompted with steps to install SMO to one of these servers during the Installer's validation steps.
Deployment Mechanics
summarize, the following steps occur as a part of this process:
1. Apprenda chooses a SQL instance.
2. Apprenda provisions the database and inserts initial data. 3. Apprenda establishes connection information.
Apprenda chooses a SQL instance at random. Once the server has been chosen, the Storage Manager service manages the remaining steps.
How Apprenda Provisions the Database
First, Apprenda creates a virtual organization. All of the data ultimately created will belong to this single virtual organization. For applications configured to use Authentication or Authorization services, all of the Users granted access to the application will be joined to the virtual organization. The virtual organization is a useful construct for the Apprenda Platform in light of the fact that the Platform supports multi-tenancy, which can be summarized as the segmenting of data when many organizations are sharing the same website or service (see Multi-Tenant Database Deployment for more information about this topic).
The aforementioned virtual organziation has a unique GUID, as does each version of an application. These two GUIDs form the name of the database as follows:
${versionID}__${organizationID}
Once this database is created, the application provisioning script is executed to create the views, stored procedures, tables, and other artifacts. Then, the tenant provisioning script, if provided, is executed against the database to insert initial data.
The provider database is a special database created in order to permit the querying of data belonging to multiple Organizations along with other advanced features at the same time. As this is only useful for multi-tenant applications, it is not discussed further here. The database is still created, however, as a part of the Platform's functionality. Its name is as follows:
${versionID}__PROVIDER
Now that the application's database is available, Apprenda then creates a database login for each of the databases. These logins will be used only for your application's database and only by your application, and the credentials are encrypted and stored in the SaaSGrid Core database. They'll have the following pattern:
tenant-${organizationID} provider-${organizationID}
Now that the database name and login information are set, all of the necessary information needed by the Platform to construct a connection string to the database is in place. The connection string used by the WCF services and web applications that accompany your application can be accessed via Apprenda's API, or the connections can be dynamically configured by the Platform via configuration when those items are deployed. See the Developer Topic called Working with Data for more information on how to work with database connections in other application components.
Other application components such as WCF web services and web applications are disposable: when a future version of the application is Published, the old versions are simply removed and replaced with brand-new versions. Databases, as expected, must receive a completely different treatment by the Platform so that the data is preserved. The following steps explain how the database is patched:
1. The database used for the Sandbox version is permanently deleted.
2. The set of schema changes and/or data changes defined during the patch process are applied to the database.
3. The database is renamed so that it uses the newly published version's ID instead of the previous version's ID. 4. The logins to the old database are re-mapped to the new database.
The process described above is transacational so that, in the event that a patch script is invalid as applied to the existing data in the database or some other issue occurs, the previous version of the application remains Published. The exception to this rule is that data left in the Sandbox version of the database that was deleted in Step 1 is not guaranteed to be preserved.
Setting Up the Developer Portal
Initial Setup of the Account and Developer Portals
During the installation process, information about your Organization (such as name and location) and your Account Administrator is captured. After installing the Apprenda components, the Installer onboards your Organization as an Application Developer. This establishes an Account Portal for your Organization and configures your Account Administrator using the information supplied during installation. Because the Organization is designated as an
Application Developer, your Developer Portal is also established and a subscription to the Developer Portal is granted automatically to the Account Administrator.
Following the initial process, your Account Administrator is the only member of your Organziation that can log in to your Account and Developer Portals.
Access to the Account Portal and the Developer Portal are restricted to Users who have been assigned subscriptions to them; a separate subscription is required for each Portal. Account Portal subscriptions are automatically created and assigned when a new User Account is created. While a Developer Portal subscription is automatically created and assigned to the Account Administrator, a Developer Portal subscription must be created and assigned manually for all other Users who require to access the Developer Portal.
Unless your Platform Administrator has configured the Platform otherwise, upon login the Account Administrator and other Users who have been assigned a subscription to the Developer Portal will be directed to the Developer Portal Dashboard. Users who do not have a subscription to the Developer Portal will be directed to the Account Portal Dashboard and will not have access to the Developer Portal.
The Account Portal can be accessed from any page in the Developer Portal through the “Manage Your Organization” link located in the taskbar in the upper right side of the screen. From the Account Portal, Users who have a
subscription to the Developer Portal can access it through the “Publish Applications” link.
For a more detailed explanation of all Account Portal functions, see Using the Account Portal.
The following resources outline the basic steps that the Account Administrator must perform in the Account Portal in order to enable other members of your Organization to access the Developer and Account Portals:
Create New Platform Users (this link will take you to the relevant section of Using the Account Portal) Create Subscriptions for the Developer Portal
Assign Developer Portal Subscriptions to Users
Create Roles and Assign Securable Permission for the Developer Portal
Create Subscriptions for the Developer Portal
1. In the Account Portal, click on the Applications option in the menu bar at the top of the screen. This will take you to your Applications page. On the left side of the Your Applications matrix, you will see a list of all the related applications to which your Organization subscribes, including the Account Portal and the Developer Portal.
2. Click on the Buy More Subscriptions icon to the right of the Developer Portal. This will take you to an Add or Change Subscriptions page for the Developer Portal.
3. In the Current Offering matrix to the right, indicate the number of individual subscriptions you would like to “purchase” for the plan in the corresponding blank field at the bottom of the “basic” plan. Please note that these subscriptions are free even though, for consistency, the process of acquiring them takes you through the same checkout procedures encountered when purchasing all products and plans for Apprenda applications. 4. Click on the Continue button. This will take you to the Confirmation page, where you can complete your
purchase.
Assign Developer Portal Subscriptions
1. Return to the Applications page by clicking on the Applications option in the menu bar at the top of the screen. 2. Click on the Subscriptions & Usage icon to the right of the Developer Portal, which will take you to the
Developer Portal Subscriptions & Usage page.
3. In the Your User Subscription Groups box to the right, click on the group name Basic, which will take you to the Basic Subscription Group page.
4. Click on either the Subscriptions icon listed on the top right menu, or the View Subscriptions option under the Subscription Breakdown section in the upper right portion of the Group Profile box. This will take you to a page that lists each individual subscription in this Group.
5. In the User Auto Assignment box on the bottom left of the page, select the names of the Users (up to the number of vacant subscriptions available) you wish to assign from the list provided. This list contains the name of all Users who do not currently have a subscription to the Developer Portal.
6. Click the Auto Assign button.
Create Roles and Assign Securable Permissions for the Developer Portal
Now that you have created Users and granted them access to the Developer Portal, you will need to use the Account Portal to Create Roles and grant Securable permissions that allow them to perform many of the Developer Portal's functions. A general walkthrough of Creating Roles and Assigning Securable Permissions can be found in Using the Account Portal, as can a more specific outline of Security Permissions for the Account Portal.Once you have created Roles and assigned Users to them, you can assign Security Permissions for the Developer Portal by selecting its corresponding Acces Control & Security icon in the Applications page of the Account Portal. This will take you to the Security page for the Developer Portal, where you can grant Securable permissions to a Role by marking the appropriate check boxes:
Defining a New Application
This section outlines the procedures for creating a new product in the Devloper Portal as well as steps required to take your product through the Definition and Sandbox phases and to Publish your Application. For information on
developing your Application, integrating elements such as Features or Securables into code, or packaging your product for upload to the Developer Portal, see the Developer Topics section of our documentation.
Create a New Application in the Developer Portal
Click on the Applications option from the menu bar at the top of the screen in the Developer Portal. This will take you to your Applications page, where you will see a New Application box on the left side of the page.
1. Enter your application Name and Description as you would like them to appear to End Users. You can edit these later if you choose.
2. Enter an application Alias, which represents a unique application identifier and will appear as part of the application URL unless a custom URL is specified later. An application alias cannot be changed once the application is created.
3. If you wish to go directly to the Application overview for your newly added application, check the box as
indicated; otherwise you will remain on the Applications page after creation, where you will see your application appear in the list to the right.
4. Click on the Create Application button.
Each application alias in the Apprenda Platform must be unique. If you attempt to use an application alias that is already in use, you will be prompted to create a different one before you can continue.
If you did not select the Go to Application overview option when creating your application, click on the application’s name in the Application List box on the right side of your Applications page, which will take you to the Application Overview page:
When an application is created, Apprenda automatically creates Version 1 of the application, which will be listed in the Other Versions box on the right side of the page (as shown below). All newly created versions of an application begin in the Defintion stage.
From the Application Overview page, you can edit the name or description of your application by clicking on the Edit Application button on the lower left side of the page. This will generate editable fields that will allow you to make and save your desired changes. As noted above, you cannot change an application’s alias once the application has been created.
Although Apprenda automatically creates and names Version 1 of your application, you can edit the version name and provide a version-specific description. To do this, you must first click on the Version 1 link in the Other Versions box, which will take you to the Version 1 Overview page for the application:
Click on the Definition icon in the upper right corner, which will take you to the Definition page. Click on the Edit Information button in the General Information box on the left. This will generate editable fields that will allow you to change the version name and create notes for its changelog. You will also be able to edit the version Alias as long as the version is still in the Definition stage.
?
Application Settings
Many of the elements discussed below, such as Runtime Binaries and Entitlement Definitions, are linked to specific versions of your application and can vary from version to version. Applications settings, however, are not
version-specific and govern how all versions of an application are deployed. Some settings cannot be changed once a version of the application is promoted to the Sandbox stage, so it is important to consider how you would like your application to deploy before promoting it to the Sandbox stage and subsequently Publishing it.
To access Application Settings for an application, navigate to the Application Overview page, where you can click on the Application Settings icon listed on the top right menu. This will take you to the Application Settings page:
Please note that your Platform Administrator may limit the availability of some Application Settings options (in which case they will not appear on this page).
Application Services
Application Services are enhancements to the way your application is deployed. They build on each other in that higher-level Application Services such as Multi-tenancy require lower-level Application Services such as Authentication and Authorization. Below is a brief description of how your application will be deployed based on the highest-level Application Service selected:
No Application Services: the application will deployed as a single-tenant application with no
Apprenda-regulated restrictions. For instance, if the application's website is publicly accessible, anyone will be able to launch the application; if it is restricted to an internal network, anyone with network permissions to
access the site can launch the application.
Authentication: the application will be deployed as a single-tenant application, and Apprenda will restrict access to Platform Users. This means that all registered Users on a given Apprenda Platform will be able to launch the application.
Authorization: the application will be deployed as a single-tenant application, and Apprenda will restrict access to Platform Users who have been granted explicit access rights to the application. The Development Team that deploys the application controls which Platform Users can launch and access different parts of the application through controls in the Developer Portal.
Multi-tenancy: the application will be deployed as a multi-tenant application, and Apprenda will restrict access to Platform Users who have been granted explicit access rights to the application. User access is controlled through subscriptions configured through the Account Portal, and can be either configured either by the Development Team that deploys the application or can be left for potential User groups to self-provision.
Billing: the application will be deployed as a multi-tenant application, and Apprenda will restrict access to Platform Users who have been granted explicit access rights to the application. User access is controlled through subscriptions configured through the Account Portal, and can be configured either by the Development Team that deploys the application or can be left for potential User groups to self-provision. The Development Team can configure pricing and billing options for the application through the Developer Portal.
Please note: the selection made for some Application Settings will limit the choices available for other Application Settings and will also enable/disable some of the functionality described in this documentation. Please see the tables below to learn more about these restrictions.
Table 1a: Application Setting Availability by Applicaton Service:
Application Services UI Deployment Strategy Commingled app.root Commingled root/app Isolated app-tenant. root Isolated root/app/ tenantt
None Available Available Not Available Not Available
Authentication Available Available Not Available Not Available
Authorization Available Available Not Available Not Available
Multi-tenancy Available Available Available Available
Billing Available Available Available Available
Table 1b: Application Setting Availability by Applicaton Service:
Application Services
Pipeline Mode Database Deployment
Integrated Classic Commingled Isolated
None Available Available Not Available Available
Authentication Available Not Available Not Available Available
Authorization Available Not Available Not Available Available
Multi-tenancy Available Not Available Available Available
Table 2: Application & Entitlement/Pricing Definition Availability by Applicaton Service:
Application Services
Application Definitions Entitlement/Pricing Definitions
Features & Editions Securables Entitlement Definitions Pricebooks & Billing
None Not Available Not Available Not Available Not Available
Authentication Not Available Not Available Not Available Not Available
Authorization Available Not Available Required Not Available
Multi-tenancy Available Available Required Not Available
Billing Available Available Not Available Required
Data Model
This setting determines how End User data is stored.
For applications with Multi-tenancy or Billing, you can choose either a Commingled data model, which stores data from multiple End Users in the same database and conserves resources because the number of End Users does not determine the number of databases, or an Isolated Database data model, which creates a physical database for each End User. Applications with Authentication, Authorization or no Application Services will automatically be
deployed with an Isolated Database model, as multi-tenant data storage is not relevant for these applications. Once you have promoted your application to the Sandbox stage, you will not be able to change this option.
User Interface
This setting determines how User Interfaces are deployed and accessed.
For applications with Multi-tenancy or Billing , you can choose either a Commingled UI deployment model, which will map all End Users to one website, or an Isolated UI deployment model, which will create a unique website for each End User. Applications with Authentication, Authorization or no Application Services are limited to the
Commingled UI deployment model, as multi-tenant website creation is not relevant for these applications.
Each deployment model offers more than one URL scheme (unless your Platform Administrator has restricted these choices) :
Commingled UI Deployment Model URL schemes:
http://apps.rooturl/app http://app.rooturl
Isolated UI Deployment Model URL schemes:
http://app-tenant.rooturl http://apps.rooturl/app/tenant
In the schemes above, "app"=application alias, "rooturl"=the url of your Platform instance, and "tenant"=the End User's Organization alias.
Login Page Stylesheet
End Users who access the application URL prior to login will be prompted to enter their Apprenda login username and password before they are granted access to their subscribed applications. If desired, a custom stylesheet can be referenced here to customize the look of the login page that will appear when your End Users access their applications through this method.
For more information on creating a custom stylesheet, download the Custom Login Style Guide available as a ZIP file in this section of the Application Settings Page.
Once you have created and customized your stylesheet and uploaded the resulting CSS file to a URL you control, you must specify the stylesheet URL in the Specify Custom Login Stylesheet field in the Login Stylesheet section of the Application Settings page.
Payment Options
This section allows you to regulate the type of payment options available to your End Users for Billing applications. Automatic Payment Only will only offer your End Users the option of purchasing this application by means such as a credit card. These payments can be processed automatically by the Developer Portal. Manual Payment Only allows your End Users to pay for this option by manually submitting payment to you by means external to the
Developer Portal (such as cash or check); you can then manually update invoices to reflect payment. Selecting Both will allow your End Users to choose from both options upon purchasing subscriptions.
Regardless of what payment option you choose, your End Users will have the ability to view invoices related to the application, and will have the option to generate a PDF version of each invoice. Should you choose, you can use this section of the Deployment Settings page to specify a custom stylesheet that will determine how PDF files generated for invoices related to this application will appear.
For more information on creating a custom stylesheet, download the Custom Invoice Style Guide available as a ZIP file in this section of the Deployment Page.
Once you have created and customized your stylesheet and uploaded the resulting CSS file to a URL you control, you must specify the stylesheet URL in the Specify Custom Invoice Stylesheet field in the Payment Options section of the Application Settings page.
Application URL
Your End Users can always access their Multi-tenant and Billing applications through the Applications page of their End User Portal by clicking on the Launch icon to the right of the desired application. End Users can access all applications by visiting the Apprenda-generated application URL directly.
In addition, you can provide your End Users with a custom URL controlled by your Development Team that has been configured to access your application.
As part of this process, you must input the URL in the Specify Application URL field in the Application URL box under Application Settings. Once you click on the Save Changes button, Apprenda will honor requests from your URL to link to the application URL hosted on your Apprenda instance after your application is deployed and your Domain Administrator has made the necessary configurations.
http://app-tenant.rooturl http://app.rooturl
Upload a Deployment Archive
From the Version 1 Definition page, click on the Runtime Binaries link in the upper right corner, which will take you to the Runtime Binaries page.
Apprenda requires a valid application archive. For more information on building and packaging code that will function on Apprenda, please see the Developer Topics section of our documentation.
In the Runtime Binaries box, click on the Browse button. This will allow you to navigate to and select the ZIP file containing the Deployment Archive for your application. Click on the Upload Archive button.
The uploading process may take a few minutes and will generate an Uploading Your Archive message that includes an updated timer for the upload:
You will then see either a message that indicates that the archive was uploaded successfully, or a list of errors incurred in the attempted upload. Indicated errors must be resolved before the archive can be successfully uploaded. If an upload is attempted after a previous archive upload has been successful, content established by the previous upload will not be replaced if the current upload is unsuccessful.
While the first version of an application is still in Definition, or has been promoted to the Sandbox stage and then demoted back into Definition, you must re-upload the entire archive if you wish to make changes to Runtime Binaries. The Patchbuilder utility will be present and available for you to download files and to view the content of an archive you have uploaded, but you will not be able to use it to make changes to files or databases in this version of the application.
Code-related additions made to Features and Securables in any archive upload subsequent to the initial archive upload will automatically repopulate the Feature and Securable tokens that appear in the Definition section of the Developer Portal based on the updated DeploymenManifest.xml file. Please note that this process will only add new Feature and Securable tokens and will not remove existing ones. As needed, Feature and Securable tokens can be removed by manually updating the Features and Securables sections of the Definition.
Define Features & Editions
Features and Editions can be configured for applications with Authorization, Multi-tenancy, or Billing.
Features
As a short-cut for the initial upload of a Deployment Archive, Feature tokens will be populated automatically based on the Features defined in the DeploymentManifest.xml file.
For all subsequent uploads and patches, you will need to either update the DeploymentManifest.xml file or update Feature tokens manually to correspond with changes made in the code. In addition, you may wish to add Features that are not tied to your application’s code to your monetization strategy.
There are four specific types of Features: Toggle, Block, Boundary and Limiter Features (for more on the four types of Features, see Key Concepts & Terminology).
The quantities associated with Blocks, Boundaries and Limiters are determined in the Pricebook (see below:
Pricebooks and Your Monetization Strategy). However, before a Feature can be used in an Entitlement Definition or Pricebook, you must create a Feature token that defines the Feature’s name and type; this is done on the Features page of each application version.
To add or update Feature tokens manually:
From the Version 1 Overview page, click on the Definition icon in the upper right corner. This will take you to the Version 1 Application Definitions page. Click on the Features icon in the submenu that has now appeared. This will take you to the Version 1 Features page:
In the Feature Listing table to the right, you will see the code-linked Features automatically populated when you first uploaded your Deployment Archive. You can use the New Feature box on the left to add a Feature that is not linked to the code, or to include a code-linked Feature added in a later upload or patch. Simply input a name for your new Feature and select a Feature Type from the pull-down menu. If you are adding a Feature to correspond with changes made to your application’s code, the Feature name and type must match the name and type defined in your code.
Click on the Create Feature button and your new Feature token will now appear in the Feature Listing table.
To delete an existing Feature token, simply click on the red box containing the white “X” to the right of the Feature that you wish to delete. Click “Yes” on the confirmation prompt to complete the process.
To edit an existing Feature token, click on the paper and green pencil icon to the right of the Feature you wish to edit. This will generate editable fields that will allow you to make and save changes to the Feature’s name and type.
Editions
Once you have configured Features, you can create Editions for Version 1 of your product. If you prefer to use the Entitlement Definitions or Pricebooks rather than the Editions configuration to limit and monetize Features, you should omit the steps below for configuring Editions and proceed to the section below on Defining Securables.
Please note: If you do not set any Editions, you will be able to use the Pricebook without restriction to configure
which Features will be available in the plans you create. However, when Editions have been configured, the process of including a Feature in an Edition restricts how that Feature can be used in other plans. A plan based on an Edition that includes that Feature can be configured to include that Feature as part of the plan, include that Feature for an additional fee, or not include that Feature. Plans based on an Edition that does not include that Feature, as well as plans based on no Edition, cannot include that Feature, as it will be listed as Unavailable to those plans.
To configure Editions for Version 1
From the Version 1 Defintions page, click on the Editions icon in the submenu to the upper right.
Use the New Edition box on the lower left of the page to name and create as many different Editions as you choose. Once you have created your Editions, they will appear in the Edition List to the right where you will also see a list of available Features for Version 1 on the left hand of the matrix. Select which Features you would like available for each Edition by marking the appropriate check-boxes.
To delete or update the name of an Edition, mouse over its name in the Edition List. To delete the Edition, click on the red box containing the white “X” that will appear to the right. To update the name of the Edition, click on the paper-and-pencil icon that will appear to the right of the Edition you have selected. This will generate editable fields that will allow you to make and save your desired changes.
Define Securables
Securables can be configured for applications with Authorization, Multi-tenancy, or Billing.
There are two types of Securables: Standard and Runtime. Both are defined in your product’s code.
Runtime Securables are a special type of Securable built in to some—but not all—applications. The list of Runtime Securables will change to accommodate changes Users make within the application, as Apprenda creates or deletes Runtime Securables as needed in the “Runtime” Securables section of the Account Portal. Developers define how these behave in their code, and there is no need for the Developer to accommodate these changes via the Developer Portal.
Standard Securables will not change unless you make changes to your application’s code through the release of a new version of the software. Standard Securables require Securable tokens created in the Developer Portal so that
they can then be assigned in the Account Portal.
As a short-cut for the initial upload of a Deployment Archive, Securable tokens will be populated automatically based on the Standard Securables defined in the DeploymentManifest.xml file.
For all subsequent uploads and patches, you will need to update the DeploymentManifest.xml file or update Securable tokens manually to correspond with changes made in the code.
To add or update Securable tokens manually:
From the Versoin 1 Defintion page, click on the Securables icon in the submenu to the upper right. This will take you to the Version 1 Securables page:
In the Securables List table to the right, you will see the Standard Securables automatically populated when you first uploaded your Deployment Archive. You can use the New Securable box on the left to create a Securable token for a Standard Securable added in a later upload or patch. Simply supply the name of the Securable as it appears in your code, add a description, and click the Create Securable button. Your new Securable token will now appear in the Securable List to the right.
To delete an existing Securable token, simply click on the red box containing the white “X” to the right of the Securable that you wish to delete. Click “Yes” on the confirmation prompt to complete the process.
To edit an existing Securable token, click on the paper-and-pencil icon to the right of the Securable you wish to edit. This will generate editable fields that will allow you to make and save changes to the Securable’s name and description.
Test and Publish Your Application
In order to promote Version 1 from the Definition stage to the Sandbox stage, the following must be completed:
1. You must successfully upload your Deployment Archive and set all your application definitions for Version 1. 2. You must configure the Application Settings for the application.
3. You must set an active Entitlement Definition for applications with Authorization or Multi-tenancy; an applicaton with Billing requires that you set an active Pricebook.
Once these steps have been completed, you can Promote Version 1 to the Sandbox Stage.
From the Version 1 Overview page, click on the Promote to Sandbox link in the Application Version Overview box (you can access promotion and demotion options from this page and through the Lifecycle icon in the upper right corner):
Promoting to the Sandbox stage may take a few minutes, as Apprenda validates user interfaces, web services and database schemas during this process. At this time Apprenda also deploys these elements to ensure that they will work. This includes inspecting database scripts for illegal statements as well as launching web services if they are included in the archive.
During this process you will see a Promoting message that includes an updated timer for the process. You will then see the report card, indicating actions taken, or a list of errors incurred in the attempted promotion. Indicated errors must be resolved before the application can be successfully promoted to the Sanbox stage.
Using the Testing Sandbox
For applications deployed with Authentication or without any Application Services, a "Launch this Version" link will appear in the Application Overview page. Clicking on this link will launch the Sandbox version of your application (please note that you must be logged in as a Platform User in order ot launch applications with Authentication). For applications deployed with Authorization, Multi-tenancy, or Billing, once Version 1 has been successfully promoted to the Sandbox stage, you can access your application through the Testing Sandbox. In order to replicate how your application will appear to your End Users, the Testing Sandbox is located in the Applications page of your Account Portal:
When Version 1 is promoted to the Sandbox stage, Apprenda will automatically create one test subscription for each plan listed in the active Version 1 Entitlment Definition or Pricebook and will assign the subscription for the first plan listed in the Pricebook to the User who promoted the application to the Sandbox stage.
When a version is in the Sandbox stage, you can also add subscriptions through the Assign Subscriptions for Sandbox link that appears next to the version’s listing in the Application Overview page.
Additional test subscriptions can be added through the Add Subscriptions for Testing link to the right of the application name on the application overview page in the Developer Portal, or through the Add Sub
