Class Reference
IRIS for UNIX 2019.3
InterSystems: The power behind what matters   
Documentation  Search
  [ENSLIB] >  [Ens] >  [Deployment] >  [Deploy]
Private  Storage   

abstract class Ens.Deployment.Deploy

Ens.Deployment.Deploy provides an API to deploy code and settings changes to a production.

Dynamic SQL

Deployment

Overview

This is the main class of methods for applying the deployment of code changes that have been exported from one production to another production.

The primary deployment method is DeployCode() which is invoked from the portal or can be invoked from the command line:

Set tSC = ##class(Ens.Deployment.Deploy).DeployCode(DeploymentFile,TargetProduction,CreateRollback,RollbackFilename,WhereToLog,LogFile,AllowDeployToSource,AutoRevert) 

where

DeploymentFile is the name of file containing the export generated from the production portal.

TargetProduction is the name of the production to apply the changes to.

CreateRollback indicates if a rollback file is to be made. The default is true. If set to false the code checks that the rollback file specified by the next parameter exists.

RollbackFilename is the name of the file to create and use to rollback the changes.Deployment Files can be re-applied but rollback file names must be unique.

WhereToLog indicates the locations to log information during the deployment and can either be empty or a combination of:

			L - Write to the file name specified in the LogFile parameter
			C - write line text to current device
			H - write HTML version of text to temporary global for retrieval by portal
			EI - write text to event log Info

			The start and finish of the deployment will always be written to the event log.
		

LogFile is the name of the file to log deployment information to.

AllowDeployToSource specifies if the deployment file can be applied to the same machine,instance and namespace as that where it was created. The default is to not allow except for applying a rollback file

AutoRevert specifies if the deployment ought to undo any changes made after it encounters an error during the deployment. The default is to auto revert on error.

Inventory

Parameters Properties Methods Queries Indices ForeignKeys Triggers
1 47


Summary

Methods
ApplyDeploymentFile BuildContentsListToRemove ChangeProductionSettings
CheckSourceAndTargetSame ClearDeploymentInProgressFlag CloseDeploymentTokenAndInvocation
CompareItems DeleteObjects DeployCode
DisableItemsBeforeDeployment DisableOneItem EnableDisabledItemsThatAreFlaggedEnabled
GenerateListsFromProjectContents GeneratePTDXMLVDOC GeneratePackageXMLVDOC
GetDeploymentToken GetLastDeploymentInvocationId GetProjectContents
GetSourceInfo GetTargetInfo InitDeploymentToken
IsDeploymentTokenInProgress IsDeploymentTokenUnlocked LoadAndCompileCode
MakeHostItemChanges MakePreDeploymentRollback PTDCleanup
PreDeploymentTokenChecks RecordBasicContentsInfo RecordContentsInfoRelativeToTarget
RecordCurrentProductionSettings RecordDeploymentInvocationError RecordEndOfRollback
RecordIfRollback RecordProductionSettingsChanges RecordStartDeploymentToken
RemoveItemsFromProduction RevertDeleteObjects RevertDisableItemsBeforeDeployment
RevertLoadAndCompileCode RevertMakeHostItemChanges RevertRemoveItemsFromProduction
RollbackLastDeployment SaveToClass StoreFilesinInvocationObject
UpdateProduction ValidateDeploymentToken


Parameters

• parameter DOMAIN = "Ensemble";

Methods

• classmethod ApplyDeploymentFile(ByRef pDeploymentToken, ByRef pDeploymentInvocation, pFilename As %String, pRollbackFilename As %String, pLogFile As %String, pTargetProduction As %String = "", ByRef pDeployDetails, ByRef pPTDToDelete, ByRef pStandardOBJLoadList, ByRef pHostItemsToRemove, ByRef pObjectsToDelete, Output pSingleFailure As %String = "", Output pRequiresManualIntervention As %String = "", pAutoRevert As %Boolean = 1, Output pHadToTryRevert=0) as %Status
Apply the Deployment file to the target production based upon pDeployDetails and ItemsToRemove
• classmethod BuildContentsListToRemove(pDeploymentFile As %String, pDeploymentVDOC As %RegisteredObject, pTargetProductionName As %String = "", ByRef pDeployDetails As %String) as %Status
Convert Export Remove Project Document to array.
• classmethod ChangeProductionSettings(pTargetProductionName As %String, ByRef pDeployDetails As %String) as %Status
Make the changes to the target production settings
• classmethod CheckSourceAndTargetSame(ByRef pSourceInfo As %String, ByRef pTargetInfo As %String) as %Boolean
Returns true if the deployment source machine, instance and production are the same as the deployment target machine,instance and production
• classmethod ClearDeploymentInProgressFlag() as %Status
Clear DeploymentToken and Deployment Invocation Object InProgress flag
• classmethod CloseDeploymentTokenAndInvocation(ByRef pDeploymentToken As %RegisteredObject, ByRef pDeploymentInvocation As %RegisteredObject, pCompletedSuccessfully As %Boolean, pReverted As %Boolean = 0, pLogFile As %String = "") as %Status
Close DeploymentToken and Deployment Invocation Object While InProgress is set no other deployment to the given namespace can take place.
• classmethod CompareItems(pItem1 As %RegisteredObject, pItem2 As %RegisteredObject, Output pItem1SettingChanges As %String) as %Status
Given 2 items report what changes are made to first item to make the static values the same as the second item.
• classmethod DeleteObjects(ByRef pDeployDetails, ByRef pObjectsToDelete As %String, pRollbackFilename As %String, Output pSingleFailure As %String = "", Output pRequiresManualIntervention As %String = "", pAutoRevert As %Boolean = 1) as %Status
• classmethod DeployCode(pDeploymentFile As %String = "", pTargetProduction As %String = "", pCreateRollback As %Integer = 1, pRollbackFilename As %String = "", pWhereToLog As %String = "", pLogFile As %String = "", pAllowDeployToSource As %Boolean = 0, pAutoRevert As %Boolean = 1, pTempPortalNode As %String = "") as %Status
Deploy the code to the target production in the current namespace. This method is called from the portal page and can be called independently. If called directly from a web page it is possible that this job can take longer than the Gateway Server Timeout - hence calling via %RunBackgroundMethod is preferrable.
• classmethod DisableItemsBeforeDeployment(pDeployDetails As %String, Output pItemsDisabled As %String, Output pSingleFailure As %String = "", Output pRequiresManualIntervention As %String = "", pAutoRevert As %Boolean = 1) as %Status
Disable items that are to be changed. Record original state. Disable all business services first and then Business Processes and Operations. Do not disable Business Processes which have an actor pool size = 0.
• classmethod DisableOneItem(pConfigItemName As %String, pConfigType As %Integer, Output pIsStillEnabled, ByRef pItemsDisabled As %String) as %Status
• classmethod EnableDisabledItemsThatAreFlaggedEnabled(ByRef pDeployDetails As %String) as %Status
This method enables all items that ought to be enabled. This covers those disabled at the start of deployment, those items added by the deployment and those items whose Enabled flag was turned on by the deployment.
• classmethod GenerateListsFromProjectContents(ByRef pDeployDetails As %String, Output pPTDToDelete, Output pStandardOBJLoadList, Output pHostItemsToRemove As %String, Output pObjectsToDelete As %String) as %Status
Separate production items from code
• classmethod GeneratePTDXMLVDOC(pDeploymentFile As %String, pDeploymentVDOC As %RegisteredObject, pPTDNameWanted As %String, Output pPTDVDOC As %RegisteredObject) as %Status
Generate an XML VDOC for a ProjectTextDocument in the DeploymentDOC. Pass in DeploymentVDOC and the PTD Name being searched for. Uses regular expression for the name. Returns a VDOC. If error then GetValueAt("/1/name()") = "Error"
• classmethod GeneratePackageXMLVDOC(pDeploymentFile As %String, Output pDeploymentVDOC As %RegisteredObject) as %Status
Generate XML VDoc Deployment File by converting a Deployment file to an XML VDoc
• classmethod GetDeploymentToken(ByRef pSourceInfo As %String, ByRef pTargetInfo As %String, Output pSC As %Status) as Ens.Deployment.Token
Obtain a deployment token for this namespace on this instance on this machine
• classmethod GetLastDeploymentInvocationId(ByRef pSC As %Status) as %String
• classmethod GetProjectContents(pDeploymentFile As %String, pDeploymentVDOC As %RegisteredObject, ByRef pTargetProductionName As %String = "", Output pDeployDetails) as %Status
Find contents of the Deployment file and also find new items and populate in pDeployDetails("Remove") If the Target Production name is not specified and the target cannot be identified in the source then the current active production in the namespace will be used. If a production has not been run in the current namespace then this method returns an error of "Cannot identify a target production"
• classmethod GetSourceInfo(pDeploymentNotesVDOC As %RegisteredObject, Output pSourceInfo As %String) as %Status
Get deployment source information from the deployment notes
• classmethod GetTargetInfo(Output pTargetInfo As %String) as %Status
Get deployment target system information The target production might be changed at deployment
• classmethod InitDeploymentToken(ByRef pDeploymentToken As Ens.Deployment.Token, pFilename As %String = "", pTargetProduction As %String = "", Output pSC As %Status) as Ens.Deployment.Invocations
Initialise DeploymentToken and create Deployment Invocation Object
• classmethod IsDeploymentTokenInProgress(Output pUsername As %String = "", Output pJob As %String = "", Output pSC As %Status) as %Integer
Checks if the Deployment token object for this namespace is marked as InProgress whether or not the deployment token object is locked.
• classmethod IsDeploymentTokenUnlocked() as %Boolean
Checks if the Deployment token object for this namespace is held open. To reduce delay if it is in use the lock timeout is reduced to 2 seconds whilst testing.
• classmethod LoadAndCompileCode(ByRef pDeployDetails As %String, pFilename As %String, pRollbackFilename As %String, Output pErrors, Output pLoadedList, ByRef pStandardOBJLoadList As %String, Output pSingleFailure As %String, Output pRequiresManualIntervention As %String = "", pAutoRevert As %Boolean = 1)
• classmethod MakeHostItemChanges(Output pItemsInsertedId As %String, ByRef pDeployDetails As %String, pTargetProduction As %String, pFilename As %String, pRollbackFilename As %String, Output pSingleFailure As %String, Output pRequiresManualIntervention As %String = "", pAutoRevert As %Boolean = 1) as %Status
Make changes to host items.
• classmethod MakePreDeploymentRollback(pDeploymentFile As %String, pRollbackFilename As %String, ByRef pDeployDetails As %String, pProjectName As %String = "", pDescription As %String = "") as %Status
Make rollback instructions of the items that will be modified by the deployment file. This rollback file can be applied as a deployment file.
• classmethod PTDCleanup(ByRef pPTDToDelete As %String) as %Status
Remove temporary Project Text Documents created during deployment
• classmethod PreDeploymentTokenChecks(pDeploymentFile As %String, pRollbackFilename As %String, pCreateRollback As %Boolean, pAllowDeployToSource As %Boolean, Output pDeploymentVDOC As %RegisteredObject, Output pDeploymentNotesVDOC As %RegisteredObject, Output pSourceInfo As %String, Output pTargetInfo As %String) as %Status
Carry out necessary checks before requesting the deployment token Converts DeploymentFile to XMLVDoc Extracts EnsExportNotes to XMLVDoc Checks if allowed to deploy to same as source(note needed when applying a rollback Checks if the rollback file either exists if not doing a rollback or if does not exist if doing a rollback
• classmethod RecordBasicContentsInfo(pDeploymentVDOC As %RegisteredObject, Output pDeployDetails) as %Status
Go through XML file and record the locations in the array pDeployDetails This will create pDeployDetails and also calculate extension based on type and generate the unique ItemName.
• classmethod RecordContentsInfoRelativeToTarget(pDeploymentFile As %String, pDeploymentVDOC As %RegisteredObject, pTargetProductionName As %String = "", ByRef pDeployDetails As %String) as %Status
For each item listed in pDeployDetails examine if the item is in the target production
• classmethod RecordCurrentProductionSettings(pTargetProductionName, ByRef pDeployDetails As %String) as %Status
Save current production settings
• classmethod RecordDeploymentInvocationError(ByRef pDeploymentToken As %RegisteredObject, ByRef pDeploymentInvocation As %RegisteredObject, pSC As %Status, pSingleFailure As %String, pRequiresManualIntervention As %String, pReverted As %Boolean) as %Status
Record in the deployment invocation object the errors and if reverted.
• classmethod RecordEndOfRollback(ByRef pDeploymentInvocation As %RegisteredObject) as %Status
Record completion of rollback
• classmethod RecordIfRollback(pRollbackFilename As %String, pDeploymentNotesVDOC As %RegisteredObject, ByRef pDeploymentToken As Ens.Deployment.Token, ByRef pDeploymentInvocation As Ens.Deployment.Invocations, Output pIsARollback As %Boolean = 0) as %Status
Record if this is a rollback
• classmethod RecordProductionSettingsChanges(pDeploymentFile As %String, pDeploymentVDOC As %RegisteredObject, pTargetProductionName, pItemName As %String, ByRef pDeployDetails As %String) as %Status
Retrieve production setting changes relative to a ProductionSettings project text document in the deployment file.
• classmethod RecordStartDeploymentToken(ByRef pDeploymentToken As %RegisteredObject, ByRef pDeploymentInvocation As %RegisteredObject, pTargetProduction As %String, pFilename As %String, pRollbackFilename As %String, pLogFile As %String, pAutoRevert As %Boolean) as %Status
• classmethod RemoveItemsFromProduction(pTargetProduction As %String, pHostItemsToRemove As %String, Output pHostItemRemovedStream As %String, pRollbackFilename As %String, Output pSingleFailure As %String, Output pRequiresManualIntervention As %String = "", pAutoRevert As %Boolean = 1) as %Status
• classmethod RevertDeleteObjects(ByRef pDeployDetails As %String, ByRef pObjectsToDelete As %String, pRollbackFilename As %String, Output pRequiresManualIntervention As %String) as %Status
• classmethod RevertDisableItemsBeforeDeployment(ByRef pItemsDisabled As %String, Output pRequiresManualIntervention As %String = "") as %Status
Re-enable items that had been disabled - alphabetical order
• classmethod RevertLoadAndCompileCode(ByRef pDeployDetails As %String, pRollbackFilename As %String, ByRef pStandardOBJLoadList As %String, Output pRequiresManualIntervention As %String = "") as %Status
• classmethod RevertMakeHostItemChanges(ByRef pItemsInsertedId, ByRef pDeployDetails As %String, pRollbackFilename As %String, pTargetProduction As %String, Output pRequiresManualIntervention As %String = "") as %Status
Revert changes made to host items
• classmethod RevertRemoveItemsFromProduction(ByRef pHostItemRemovedStream, pRollbackFilename As %String, pTargetProduction As %String, Output pRequiresManualIntervention As %String = "") as %Status
• classmethod RollbackLastDeployment(pDeploymentFile As %String = "", pRollbackFilename As %String = "", pLogFile As %String = "", pWhereToLog As %String = "LHEI", pAutoRevert As %Boolean = 0)
Applies the rollback of the last deployment started.
• classmethod SaveToClass(pTargetProduction As %String, ByRef pDeployDetails As %String) as %Status
• classmethod StoreFilesinInvocationObject(ByRef pDeploymentInvocation As %RegisteredObject, pDeploymentFile As %String, pRollbackFilename As %String) as %Status
Move pDeploymentFile and pRollbackFile into stream storage of invocation object - ready to be able to get them back later if crash and move to a mirror.
• classmethod UpdateProduction() as %Status
• classmethod ValidateDeploymentToken(ByRef pDeploymentToken As %RegisteredObject, ByRef pDeploymentInvocation As %RegisteredObject) as %Status


Copyright (c) 2019 by InterSystems Corporation. Cambridge, Massachusetts, U.S.A. All rights reserved. Confidential property of InterSystems Corporation.