Install Shift4 Payment Connector via Command Line

Description: The following steps are strict to environments where the deployment of packages via LCS is not available, most commonly for internal development environments. In these cases, we have the option to install the payment connector via Windows Command Prompt (CMD) directly from the Virtual Machine hosting the environment for Dynamics 365.

---

Shift4 Payment Connector package comes with many files and folders inside of it. For the purpose of this installation, we will focus mainly on the following files, which are necessary to accomplish this task:

AXUpdateInstaller

• This file is included on both deployable packages and will be used to install the connector via Command Prompt.

DefaultTopologyData

• This file is included in both deployable packages and will be used to establish the services that we will be installing into D365.

Runbook file

• For each deployable package, we will generate one runbook xml file, which contains the series of steps required for a controlled installation to apply to the target environment. 

Downloading the Application Packages from the Asset Library

1. Remote into your server virtual machine (VM) that’s hosting your D365 environment. 
2. From the Server VM, log into LCS using your Azure credentials to download the Payment Connector Packages.
   
3. Once logged in, navigate to Recent projects and select the one you’re looking to install the Payment Connector to.
   
4. Scroll over to the left, and under More tools, select Asset library.
   
5. From the list of Asset types, locate and select Software deployable packages. Once there, select the Hyperlinked package names to download the files. Make sure these are downloaded/stored in a non-user folder.
   

Important: If you are not seeing the Shift4 Connector packages in the Shared Asset library, contact Shift4 to request to have them shared with your LCS project.

Backoffice Package - Installation Steps

This package contains the core functionalities for the connector to be used in the Call center environment. If you are only using the Call center Module, this is the only package you require to have installed. 

1. Before extracting the files, right-click on them and then select Properties. On the General tab, make sure Unblock is checked off (if present).
2. Extract the zip file.
3. Open a Command Prompt Terminal as Administrator.
4. On Windows Command Prompt (CMD), type cd and include the path of the Package Root Directory (PRD) from the Backoffice Package folder (where the zip file was extracted). Once in the directory, type the following into the terminal and press Enter. This will take time to complete as it will go through a series of many installation steps.
   
5. Inside the Backoffice Package folder, locate DefaultTopologyData.xml file and open it with the Notepad application. Locate the <Machine> element and change localhost in the <Name> to the VM you are installing the connector to. 
   
   Note: To find out the VM Name, go to \Control Panel\System and Security\System, and enter it inside of the <Name> element as shown
6. We need to add all services included in the deployable package to the DefaultTopologyData.xml file. To find them, go to CMD🡪PRD on the command terminal.
   
7. Copy all of the services you obtained from the previous step and paste them into the DefaultTopologyData.xml inside of the <ServiceModelList> element as follows: 
   
8. Now, we need to generate a new runbook on the root directory based on the DefaultTopologyData.xml. To make sure the name of each runbook is unique and to easily identify the Retail from the AX package, you can use the following format: AXrunbookPackageVersion.  

Example: AXRunbook10.0.25.2

Go to CMD🡪PRD and enter the following: 

AXUpdateInstaller.exe generate -runbookid="AXRunbook10.0.25.2" -topologyfile="DefaultTopologyData.xml" -servicemodelfile="DefaultServiceModelData.xml" -runbookfile="AXRunbook10.0.25.2.xml"

Example above shows runbook001; yours should be AXrunbookPackageVersion.

9. Root directory below shows an example of a newly generated runbook:
   
10. We are ready to import your newly generated runbook. To do so, navigate to the AX Package Root Directory (PRD) in CMD and enter:   
                   AXUpdateInstaller.exe import -runbookfile="AXRunbook10.0.25.2.xml"
    
11. Verify the imported runbook by entering into CMD🡪PRD:
                                                     AXUpdateInstaller.exe list
    
    
12. Below is an imported example runbook001. Your imported runbook should be AXrunbookPackageVersion.
    
13. Now is the time to execute your runbook. Go to CMD🡪PRD and enter:
                AXUpdateInstaller.exe execute -runbookid="AXRunbook10.0.25.2"
    
14. Once you have executed your runbook, it will take some time to complete. At the end, you should see a total of 12 steps being executed and your terminal will look like this for each step:
    
15. Verify your runbook was properly executed by going into CMD🡪PRD and entering:
                              AXUpdateInstaller.exe list
16. All executed steps during installation were recorded on the AXrunbookPackageVersion file, it is necessary to update the <StepState> fields as well:
    
17. To update the <StepState> fields on your runbook file, go to CMD🡪PRD and enter: AXUpdateInstaller.exe execute -runbookid="AXRunbook10.0.25.2" -setstepcomplete=2
18. After applying the above command, notice not only the <StepState> fields are updated on your AXrunbookPackageVersion file but also the <StartTime> and <EndTime> fields.
    
19. Next, you will need to export your runbook file. To do so, go to CMD🡪PRD and enter the following into the terminal:
    AXUpdateInstaller.exe export -runbookid="AXRunbook10.0.25.2" - runbookfile="AXRunbook10.0.25.2.xml"
    Above is an example runbook001 as being exported; yours should say AXrunbookPackageVersion.

20. Once this update is complete, you may begin working on the configuration of Shift4 Payment Connector for the Call center module or proceed to the next steps to install the Retail Package.

Retail Package – Installation Steps

This package contains the core functionalities for the connector to be used in the Retail environment. If you are only using the Retail Module, you will need to install both the Backoffice and Retail Packages. 

We will go straight into generating a new runbook, but to differentiate it from the previous one, we will add Retail at the start, i.e. RetailRunbookPackageVersion.

1. Before we start the installation process, we need to obtain all services included in the package and import them into the DefaultTopologyData.xml. To find them, type cd into Command Prompt (CMD) and include the path to the Package Root Directory (PRD) of the Retail Package folder this time. Once in the directory, type the following into the terminal and press Enter.
                                         AXUpdateInstaller.exe list
   
   
2. Copy them into the DefaultTopologyData.xml under <ServiceModelList> as follows: 
   
3. Go to CMD🡪PRD on your terminal and enter:
   AXUpdateInstaller.exe generate -runbookid=”RetailRunbook10.0.25.2” -topologyfile=”DefaultTopologyData.xml” -servicemodelfile=”DefaultServiceModelData.xml” -runbookfile=”RetailRunbook10.0.25.2.xml”
   Example above shows runbook002; yours should be RetailRunbookPackageVersion.
   
4. At this point, you have generated a new runbook file in your Retail Package root directory. 
5. We are ready to install Retail Package. For this, we will need to import your newly generated runbook file. Go to CMD🡪PRD and enter:   
           AXUpdateInstaller.exe import -runbookfile="RetailRunbook10.0.25.2.xml"
   Example above shows runbook002 as the file to be imported.
6. Verify the imported RetailRunbookPackageVersion file, go to CMD🡪PRD and enter:
                                         AXUpdateInstaller.exe list
   Example above shows runbook001 and runbook002 was successfully imported. You should be able to see both your AXRunbookPackageVersion and RetailRunbookPackageVersion.
   
7. Next, execute your runbook file. To do so, go to CMD🡪PRD and enter:
            AXUpdateInstaller.exe execute -runbookid="RetailRunbook10.0.25.2"
   Example above shows runbook002 to be executed; yours should be RetailRunbookPackageVersion.
   
8. Once you have executed your runbook file, it will take some time to complete. At the end, you should see a total of 18 steps being executed and your terminal will look like this for each completed step: 
   
9. Verify your runbook file was properly executed by going into CMD🡪PRD and enter:
                                              AXUpdateInstaller.exe list
   
10. All executed steps during installation were recorded on the RetailRunbookPackageVersion file, it is necessary to update the <StepState> fields as well.
    
11. To update the <StepState> fields on your runbook file, go to CMD🡪PRD and enter:
    AXUpdateInstaller.exe execute -runbookid="RetailRunbook10.0.25.2" -setstepcomplete=2
    
12. After applying the above command, notice not only <StepState> fields are updated on your RetailRunbookPackageVersion file, but also <StartTime> and <EndTime> fields:
    
13. Finally, export your runbook file, go to CMD🡪PRD and enter:
        AXUpdateInstaller.exe export -runbookid="RetailRunbook10.0.25.2" -runbookfile="RetailRunbook10.0.25.2.xml”
    Example above shows runbook002 as being exported; yours should be RetailRunbookPackageVersion.
    
14. You have successfully installed Retail Package and completed the process.
15. Once this update is complete, you may begin working on the configuration of Shift4 Payment Connector for the Retail, Call center, or eCommerce module.