Deployment

This user guide will walk you through all the processes relevant to deployment of Eftsure's extension: Eftsure inside Microsoft Dynamics for Finance and Operations.

Three distinct methods are used for deployment depending on the target environment.

The first deployment is for your initial Development environment. You will receive / download a copy of our latest release (deployable package) that your deployment team will first deploy into your Development environment and source control.

For all other Development environments, your developers will deploy our latest release to their development machine by calling a Get Latest in Visual Studio.

For all Tier2+, the Deployable Package will need to be built including all other packages (All In One Package) and deployed using LCS features.

note

We deploy binaries using Software Deployable Packages, the source code is not deployed. The Software deployable packages files are shipped by Eftsure. We encourage you to be on the latest version that you will find on LCS.

For Live environments, the same Deployable Package approved in Test will be deployed using LCS features, after testing and approval in Test.

It's important to understand each deployment technique prior to performing a deployment of our latest release.

For more information, please refer to the following:

Cloud deployment

For on premise deployments, please refer to the following:

On premises deployment

Updates are applied using deployable packages. Applying updates causes system downtime. All relevant services will be stopped, and you won't be able to use your environments while the package is being applied. You should plan accordingly.

On Premise

This user guide describes the release process for all environments deployed through Lifecycle Services, on-premise release documentation is not available at this date.

This user guide describes the LCS deployment features only, the Deployable Packages are standard, and therefore can also be deployed via command line to on premise environments or cloud environments:

Install deployable package

Upgrades

Upgrades are slightly different from first time installs, please see Upgrades for more details.

Troubleshoot package deployment failures

If package deployment fails, see the Troubleshoot package application issues topic.

Packages

Eftsure ships the following 3 packages:

Eftsure inside D365 (core features)

ExFlow and Eftsure inside D365 (to be installed for ExFlow customers)

Xe and Eftsure inside D365 (to be installed for Xe customers)

The packages architecture looks like the following:

The main package can be deployed on it's own,

The two partner packages require their matching partner packages and will fail if not available.

Please see our partners to get their packages.

Important:

In all scenarios, make sure to clean the packages folder for each package. For more information,

Please refer to Clean Packages.

Deployment from LCS

Receive an LCS invitation for the project from Eftsure,

Go to LCS, then Solution Management.

If the Eftsure solution is not yet available, select Import and import the solution.

Go to LCS > Project > Asset Library > Software deployable package > Find Eftsure package(s).

Deployable package to your environment.

Deployment from command line

Alternatively, the deployment can be achieved via command line.

Find the latest Eftsure package and download it to c:\Temp

Extract Eftsure package to C:\Temp (No spaces in the folder name)

Run the following script in PowerShell as Admin

Unblock (command)

dir -Path c:\\temp -Recurse | Unblock-File

Close PowerShell,

note

Due to previous issues, it is recommended to clean Eftsure package(s), see clean Packages

Deploy the latest Eftsure package:

[AxUpdateInstaller QuickInstallAll]

Download file, copy to c:\Temp

Clean Packages

We recommend cleaning packages before any attempt to deploy any new version of any Eftsure package. To clean packages, Kill the following processes:

• D365 batch (batch)
• IIS Service (w3wp)
• IISExpress (iisexpress)
• xppcAgent (xppcagent)

Then delete the following Eftsure packages, if they exist:

Eftsure, ExFlowAndEftsureInsideD365, XeAndEftsureInsideD365

Make sure the folder no longer exists on disk,

Disable Gated Checkins if necessary

Checkin deleted folder, make sure folder has been deleted from DevOps.

Enable Gated Checkins if necessary

Deployable Package

If you have a deployable package, install deployable packages from the command line or from LCS:

Install deployable package

Apply deployable package

Source control

After successful deployment, you can now check-in our new release into your source control for further references.

Go to Visual Studio and open the Source Control Explorer window,

For initial deployments, add the contents of the Eftsure folder into your source control, please make sure no files are excluded while adding our release folder to source control!

Include all items in source control, until there are no more excluded items:

Important: When you check-in the upgraded version to TFS, there should be exactly the same files in repository as if you would install and check-in the new version on a clean environment. TFS does not automatically detect and include all upgrade changes for check-in. It requires some manual steps that can be error prone.

Go to Team Explorer - Pending changes and check-in your code, following your Team rules, making sure to only check-in code from this release.

info

The files resulting from compilation might appear in your Pending Changes, and are not required to be version control, just make sure all files from the original zip file are checked-in.

Your source control folder should look like:

Upgrades

During upgrade installation, the model folders and descriptor files will be automatically updated. New files will be added and old ones removed, except DLL files in the bin folder of the any package, where the old files may remain.

When you check-in the upgraded version to TFS, there should be exactly the same files in repository as if you would install and check-in the new version on a clean environment. TFS does not automatically detect and include all upgrade changes for check-in. It requires some manual steps that can be error prone.

If you would like to check-in all the changes of the upgraded models, make sure all these changes are listed in Team Explorer\Included Changes, before checking-in them to TFS. Updates are included automatically, while deleted files have to be manually promoted from Team Explorer\Excluded Changes > Detected. New files have to be added manually as well (Add Items to Folder). Obsolete DLLs in  bin folder have to be manually deleted.

Therefore, we recommend the following, for a more reliable UPGRADE PROCEDURE:

1. Stop IIS (or IIS Express) and the Batch service.

2. Delete all Eftsure models (i.e. packages) from TFS and [check-in the changes].

3. Delete all the Eftsure package folders from the hard drive:.

4. Redeploy Eftsure packages from LCS or command line

5. Add all the artifacts from Eftsure models to TFS . Make sure that the correct DLLs from the \bin folder are added to TFS.

6. Check-in the changes and verify on the  Azure DevOps portal that you really have the right code in place in the repository.

7. Build the new Eftsure models.

8. Synchronize the database.

9. Start IIS (or IIS Express) and the Batch service.

All in one package

Your package can be created using DevOps pipelines or Visual Studio.

For Cloud hosted build pipelines, we recommend the following step to be added into the pipeline:

Upload package to LCS

This deployable package should now be uploaded to LCS for testing in non-developer environments.

Head to lcs.dynamics.com/, select your project(s), go to the Asset library, Click the Add button, enter a Deployable Package name and description, upload your newly created Deployable Package, and Confirm.

Your new deployable package is now ready to be deployed into your sandbox environments.

Deployments to cloud hosted environments (DEV,Test, Live)

Before you begin, verify that the deployable package has been uploaded to the Asset library in LCS.

Open the Environment details view for the environment where you want to apply the update.

Click Maintain > Apply updates to apply an update.

Select the package to apply. Use the filter at the top to find your package.

Click Apply. Notice that the status in the upper-right corner of the Environment details view changes from Queued to In Progress, and an Environment updates section now shows the progress of the package. You can refresh the page to check the status.

Continue to refresh the page to see the status updates for the package application request. When the package has been applied, the environment status changes to Deployed, and the servicing status changes to Completed).

Apply a package to a production environment by using LCS

In a production environment, customers can schedule a downtime for when they want the update to be applied.

Important: A prerequisite for applying a package to a production environment is that the package must be successfully applied to at least one sandbox environment in the same project.

After the update is successfully applied in a sandbox environment, go to the project's asset library. On the Asset library page, select the Software deployable package tab, select the package that you want to move to production, and click Release candidate. This indicates that this package is ready for production deployment.

Open the Environment details view for the production environment where you want to apply the package.

Select Maintain > Apply updates to apply the package.

Select the package to apply in your production environment, and then click Schedule to submit a request to apply it.

note

The list of packages includes only the packages that have been successfully signed off in the sandbox environment, and that have been marked as release candidates.

Specify the date and time to schedule the package application. Click Submit, and then click OK to confirm.

warning

Your environments will be unavailable to perform business while the package is being applied.

At the scheduled downtime, package deployment will start.

After the environment is serviced, you can monitor the status. The Servicing status field indicates the status of package application. Additionally, a progress indicator shows the number of steps that have been run, out of the total number of steps that are available.

After the deployment is successfully completed, the Servicing status field is set to Completed.

If package application isn't successfully completed, Microsoft will investigate the issue. The Servicing status field will indicate that package application has failed. The environment will be rolled back to a good state.

Deployment to Developer environments

For all developer machines that require to run our extension,

Clean the packages folder for all Eftsure extensions (see Clean Packages)

Go to Visual Studio, Connect to your Team Project, locate the appropriate branch where the Eftsure extension has been added, perform a Get Latest on the Eftsure folder and/or entire branch.

This process will download the copy of our extension onto your local machine,

Refresh Models in Visual Studio > Extensions > Dynamics 365 > Model Management > Refresh Models.

Then, compile the new or updated models and dependencies if any custom extension has been created on top of our extension.

Then synchronize your database.

Important: Resource files are not automatically deployed as part of the Get Latest process, see this article for more information. In order to force the deployment of resources, we recommend each developer to run this powershell script to redeploy resources manually after each GetLatest.

Then your developer machine is fully updated, ready to be configured and start testing / debugging / troubleshooting your environment.

Post deployment activities

After the deployment of any new version of Eftsure inside Dynamics 365, you will also need to perform the following actions:

Data entity refresh

New or updated entities are likely to be published in between new versions. In order to make sure that new entities are deployed, please run the standard entity refresh script available in Data Management > Framework Parameters > Entity Settings > Refresh Entity List.

Check Batches

New or updated batches are likely to be published in between new versions. In order to make sure that you make the most of the new version, please run the Check Batches script available in Eftsure > Admin > Batches > Check Batches and this process will check all batches and create missing batches according to your configuration.

Cross company data sharing

If the configuration is using cross company data sharing, check for new PES fields on VendTable, VendBankAccount. Deprecated fields to be deleted, otherwise will result in SQL error - See Cross Company Data Sharing.

Re-Init legal entity

Go to Eftsure parameters and run init on all enabled legal entities:

Post DB Refresh activities

We recommend adding the following script to your SQL DB Refresh scripts, in order to avoid Password encryption errors for passwords coming from another environment.

These SQL Scripts will clear all Eftsure credentials that are no longer valid on the new target environment.

UPDATE PESUSERINFO SET PASSWORDENCRYPTED = NULL

UPDATE PESPARAMETERS SET PASSWORDENCRYPTED = NULL

If such scripts aren't performed as part of DB Refresh, the following errors are likely to occur throughout the system:

See Export Database

Uninstall

If you no longer require our ISV product or haven't renewed the license, you must remove the package.

Follow the steps in:

Uninstall deployable package

Customers using Cross Company Data Sharing will need to start by removing their CCDS configuration, see Cross Company Data Sharing

Troubleshooting

Using a second dev box:

In case of deployment issues, the developer can try to use a second dev environment to validate that no files are missing from source control.

On the second dev environment:

• Clean package

• Perform get latest

• Redeploy package

• Go to Source Control Explorer

• Select "Add items to folder" on the EFTSure folder

• Make sure that there are no files listed (in either include or exclude)

• Check-in / Redeploy

Other ideas that might have helped on troublesome deployments:

Deploying ISV extensions on an empty DB, then restoring DB over.

Turning off all flighting options (Feature Management)

Reprovisionning environments

Deployable packages:

The deployable packages shipped at Eftsure are zip files containing a single model, all clearly labelled with a version number.

This software package is usually bundled by the customer or their partner into an 'All in One' package to be deployed with additional code to Tier2+ environments.

This 'all in one' package should Eftsure files with the same version number that you are expecting and the Eftsure zip file should contain the same number of files as the SDP shipped by Eftsure.

If that's not the case or the Eftsure package is versioned as 1.0.0.0, an issue is likely present and files might be missing, this software deployable package will be unlikely to deploy successfully.

Please revisit your deployment and release pipeline, checking for version number and file numbers after each and every step. To this day, the likely causes for such errors are the following:

Issues with services not stopping

Files being locked by the system during deployment

Missed files during checkin/merge

Eftsure does not ship any package with v1.0.0.0, clearly indicating an error. Please involve support if you are struggling.