Created on 29 January 2021
icon_unfollowing
Login to follow
delivery

Delivery

Stable version 1.4.2 (Compatible with OutSystems 11)
Uploaded on 29 May 2023 by 
delivery

Delivery

Documentation
1.4.0

Deployments manual

Delivery application contains UI to manage and run deployments under “Deployments” menu.

It uses LifeTime API on behind, and all executed deployments appear in LifeTime as well.

Needs service center account to log in (but doesn’t have login screen itself).

Deployment pushes only applications which have modifications compared to the target environment. It doesn’t matter which side has later version - it will always be overwritten from source.

Two major sections are “Monitor”, where you can see status of the latest deployments, and “Setup” where you can configure and start them.

All times are in server time zone (the one which is shown in ServiceCenter, and is also displayed on top of Monitor section)

Running the deployment

Scroll down to “Setup” and find the needed deployment in the white area. Alternatively, you can select one of the packages (on the leftmost column) or one of the environments (on top) - this is called a “dynamic deployment”.


Hover mouse to get the balloon popup and click the “Rocket” icon - the modal will open.

If you got here from the Package - you will need to select source and target environments and this will deploy this package. You can also add more packages there.

If you got here from Environment - you will need to select second environment and one or more packages.

In both of these cases, you can also save this deployment for reuse, but providing a name in “Save as” input.

Turn on “Prepare only” to only run LT validation but not execute the deployment itself. Prepared deployment can be continued on demand. If there is prepared instance of this deployment available - there will be a switch to choose to continue it, which will start deployment with the same application versions which there were.

If you want to start it later then now - turn on “Specific time” and choose date and time to run at.

If you want it to start after another deployment completes - select one in “After completion of” dropdown. If precondition deployment is already running - the process will wait for it to finish. If not - it will wait for it to start and then finish. If precondition deployment fails - then the current (conditional) one is cancelled.

When all good, click “Run” button. You should then see it in Monitor section. Refresh the table to see updates in status.

Developers don’t need to stop publishing because source environment is not affected in any way. LT deployment seems to work similar to solutions: first it takes snapshot/version, validates it, then sends it to target environment, where the references are automatically updated, and then it gets published.

Huge advantage comparing to solutions is that you get error about “incompatible modules” soon after you start it and don’t need to wait several hours for it to complete. So this can also be used to only check if references are healthy (in prepare mode).


Monitoring

Active and past deployment executions are shown in “Monitor” table on top of the page.

The title section shows server time, link to LifeTime UI and Refresh button (this refreshes the table without querying anything additionally). Then there are filters (should be self-explanatory), and then the table itself. Records in the table are sorted from the latest modification time (unless if “Pending” status is selected in filters - in which case it is sorted from the nearest start time). The table has these fields:

  • Deployment: name of the deployment. For dynamic deployments this is autogenerated as <Package> from <Source env> to <Target environment>.

  • Created on: time when start button was clicked, or automatic run started.

  • Created by: who pushed the button, or (anonymous) in case of automatic run.

  • Applications: number of applications included. This can change while the deployment is prepared. It is clickable and opens a list of applications with status. Every application is also clickable and shows included modules, version and error details.

  • Modified on: last update time.

  • Status: deployment run status and details. See “Statuses” section below.

  • Delete button and Refresh button (note that unlike the top “Refresh”, this queries and updates status of this deployment from LT).

Status of active deployments is updated periodically (configured at site property of Deployments_Lib, default is 10 minutes), but the table itself is not refreshed automatically. To refresh it - click “Refresh” icon on top, or reload the page.

When deployment is completed or failed or needs user intervention - an email is set to configured address (site property of Delivery).

As of now, in our environment all emails are redirected to a predefined list, so it’s enough to set any single e-mail there, which will send to whole list.

To update and refresh status of particular deployment run without waiting for 10 minutes - click “Refresh” icon in its row.

You can check more details in LifeTime in deployment plans, a.k.a. “stagings”. Unfortunately, there is no direct link to find particular staging, only by time of execution. Also, failed deployment will be deleted on the next run of the same deployment - otherwise, LifeTime will not allow it to be started.

Clicking “Trash” icon will delete the deployment run. This will also terminate the process (if it is active) and attempt to delete corresponding LifeTime staging.

Old deployments are periodically cleaned (configured at site property of Deployments_Lib, default is after 14 days).

Statuses

  • Pending - deployment is scheduled to start, but not started yet. Hint: if you schedule multiple deployments in advance, filter by this status to see the plan, which is also sorted from the nearest to start.

  • Building - in the process of determining applications to include and tagging versions.

  • Cancelled - this happens when target environment is busy or there are no applications to deploy.

  • Sending - it was prepared on our side and is being sent to LifeTime. At this stage, errors can happen, and it can actually take a while reattempting it.

  • Failed to create - could not create deployment in LifeTime.

  • Validating - LifeTime validation is in progress.

  • Incompatible references - Incompatible references were found and need manual fixing.

  • Prepared - all good and ready to be launched.

  • Failed to start - failed to start deployment in LifeTime. One know reason of this is when applications appear as different versions, but have no changes in the modules.

  • Running - deployment in progress.

  • Unknown - unknown status was returned by LifeTime during the last check.

  • Needs user intervention - somebody need to go to LifeTime, find the staging and click “Approve” button.

  • Aborting

  • Aborted - cancelled manually or failed. Usually there is some internal error which can be (hardly) found in LifeTime logs.

  • Finished successfully - the perfect ending.

  • Finished with warnings - deployed, but there were some warnings.

  • Finished with errors - it can either mean it failed completely (not sure what is the difference from Aborted), or some modules were skipped because of errors.

Setup

Packages

Before you can use a deployment, you need to setup at least one package to include into it. Package is simply a selection of applications, which must be all present in current environment (DEV). A deployment can include one or several packages.

To create a package, click “New package” on top of the “Setup” section. To edit an existing package, hover over it in the leftmost column of the “Setup” section, and click the edit icon.

Deployments

Deployment is a saved combination of one or more packages, source and target environments. To create a new deployment, click “New deployment” in the “Setup” section. To edit existing deployment, hover mouse over it and click “Edit” icon. When starting a dynamic deployment - you can also save it for reuse by filling “Save as” field.

Deployment can be set up to be run automatically in the given time once per day.

There is also “continuous” option, which makes it run every hour. Note that any deployment run includes only modified applications - so you shouldn’t worry about it publishing to often and on the weekends. If there are not many changes - this will usually update only few applications at a time. Also, continuous deployment doesn’t start if there is any other deployment ongoing, even if to the different environment (to save system resources).

Generating solution

If you need a deployment solution generated based on particular package or deployment configuration:

  1. Hover over the needed deployment or application group and click “Create solution” (stack) icon

  2. In the popup dialog, you can choose other environment to generate at (will work only if Applications_Lib, part of Delivery application, is present there!). No selection means current environment (DEV).

  3. This will generate a solution named according to the name chosen, and it will include all modules from all applications in the package(s) included.

Troubleshooting

 

Problem: “Failed to create a new deployment. There is already another deployment saved for <environment>”

Reason: Another deployment is active in LifeTime, targeting the same environment. Even though Delivery attempts to fix this case automatically, sometimes it happens, for example if another deployment was started in LifeTime directly, or if attempt to delete it automatically has failed.

Solution: Either wait for current deployment to finish, or delete if in LifeTime UI, then start your deployment again.

 

Problem: “Failed to include application version in staging because it was never published in source environment”

Reason: This doesn’t make sense off course. This seems to be caused by some internal refresh happening between environments. There is an SQL which looks up for the application info in LifeTime DB and if it returns nothing - then this error is returned. Outsystems support have once shown me that SQL (can’t find it now), and actually someone with DB access to our LT server could analyze it more.

Solution: Try again later. Delivery does automatic retry in this case X times (SP in Deployments_Lib, default is 4), waiting for Y minutes in between (another SP in Deployments_Lib, default is 10). But it depends, sometimes you need to wait for at least an hour. Another solution is to try using different source environment (but which has valid versions and same applications, for example deploy from DEV instead of CI/CD). If this also doesn’t work - you can deploy the same applications using LifeTime UI (Delivery shows a list of applications included in the Monitor table), or using a ServiceCenter solution (but this should really be avoided because it’s difficult, long and fragile). If you use solution, then Delivery can be used to generate solution for the deployment (see relevant section above).

 

Problem: Incompatible references mentioning an application which is not even included in the deployment

Reason: LifeTime prevents deployment from happening if it will create incompatible references on target environment. But why does this mentions applications not even included? Usually this is because one module of the application exists on target, even if in different application. It could have been present in one of the included applications and then moved, or was simply deleted from source as obsolete.

Solution: Check which modules from the application are present on target and delete them if they are not needed. If they are needed, then put into proper application to be included. LifeTime UI is helpful with it - you can go into details of the conflict. 

 

Problem: “Command ‘start' can't be executed for deployment '…’”

Reason: Usually this means that there are no changes to be deployed, even though applications themselves look like having differences. This can happen if a module was moved outside of the application deployed, but still exists on target. When building the plan, LifeTime will tell that there are differences, but after deployment is validated, it turns out that there is nothing to deploy.

Solution: Check which modules from the application are present on target and delete them if they are not needed. If they are needed, then put into proper application to be included. LifeTime UI is helpful with it - you can go into details of the application. Try again, you should get “Nothing to deploy” message.

 

Problem: “There was an error calculating outdated apps for deployment with key '…': Invalid status change: trying to change Staging with id  '…' from 'Validating' to 'Calculating apps to redeploy'.”

Reason: This is an error in validation process. It seems to be matched with error message shown in LifeTime UI, saying just “Error happened during validation”.

Solution: Sometimes it disappears on the next attempt. Sometimes you need to exclude one or more applications (in LifeTime UI) and retry. Those applications can get fixed after republishing them.

 

Problem: “Application version is already in use”

Reason: Every changed application needs to be tagged with next version before deployed. This error says that this version (or higher than it) is already used in some other environment. Delivery logic attempts to solve this by checking all environments to find next version to use, but sometimes it can still happen.

Solution: Go to LifeTime UI and tag the source application with higher version

 

Problem: “The mobile version '…' for '…' of application '…' must be higher than '…'. Insert a new version.”

Reason: When applications are tagged, application version and mobile version should be in sync, but sometimes mobile version is higher then any application version, probably because it was regenerated with changes. Delivery logic attempts to solve this by checking mobile versions in all environments to find next version to use, but sometimes it can still happen.

Solution: Go to LifeTime UI, find the application mentioned, and tag the source application and mobile versions with higher version


Support options
This asset is not supported by OutSystems. You may use the discussion forums to leave suggestions or obtain best-effort support from the community, including from  who created this asset.
Dependencies
See all 1 dependencies