Topics

    Appian DevOps Quick Start

    This document serves as a guide to configure a generic automated process for versioning and importing Appian applications using a defined DevOps pipeline. This guide has been assembled as a holistic process that covers automated versioning, application import/export, and testing. While the pipeline described can be used as-is for many different projects, it can also be adapted to fit other configurations and environments.

    DevOps Overview

    What is DevOps?

    Development and Operations (DevOps) is a set of practices and tools that help foster a culture of collaboration between development and operations to enable the rapid, frequent, and reliable delivery of software.

    What is a DevOps Pipeline and how does it relate to CI/CD?

    Continuous Integration (CI) and Continuous Delivery (CD) describe a set of procedures many modern software companies follow in order to ensure their software is robust and compatible with current and previous versions. A DevOps pipeline breaks the CI and CD processes into discrete automated stages.

    Appian DevOps Pipeline Overview

    Why is the Appian DevOps Pipeline Important?

    Appian applications, though faster and simpler to build and maintain than traditional software applications, must also go through a basic life cycle that goes from conception to implementation and testing before they can be deployed to end users. Automating and modularizing this process makes Appian application development even faster and simpler.

    What tools are used by the Appian DevOps Pipeline?

     

    How does the Appian DevOps Pipeline work?

    The recommended Appian DevOps Pipeline leverages trunk-based development. The Appian Dev environment can be interpreted as a “branch”. Adding the Appian Applications to the “master” branch in version control is the equivalent of “merging”. After the “merge”, the Appian Dev environment can be interpreted as a “new branch”. The goal is to “merge” frequently to the “master” branch to keep the spirit of “short-lived branches”.

    Appian DevOps Pipeline

    Prerequisites

    1. Git
    2. GitHub
    3. Flyway
    4. Artifactory
    5. Jenkins
      1. Docker and Docker Compose need to be accessible in the Jenkins workspace
    6. Appian Automated Deployment Manager (ADM) (Only Appian Version Manager is leveraged in this Pipeline)
    7. FitNesse for Appian

    Pipeline Setup

    1. Download or re-create the recommended file structure
      1. Please refer to the documentation contained in the repository README.md files for more detailed guidance
    2. Connect the local repository copy to a new Github repository
    3. Update devops/f4a/test_suites/QuickStart<Integration/Acceptance>Test/content.txt files 
      |set appian url to |https://<integration/acceptance-site-url>/suite |
|set appian version to |<site-url-version> |
|set appian locale to |en_US |
|login with username |<username-for-site> |
    4. Update devops/deploymentmanager.properties files for each environment to specify site URL and API Key. 
      ### Environment-specific properties
## REQUIRED. URL of the environment
url=[Enter URL of the appian site e.g. https://yourCloudSite.appiancloud.com/suite]
siteApiKey=[Enter the API key for the deployment service account created in Appian]
packageFileName=app-package.zip
### Import-specific properties
## REQUIRED Name for the deployment
deploymentName=[ Enter a name for the deployment, to appear in the deployment tab within Appian]
## REQUIRED Description for the deployment
deploymentDescription=[ Enter a description for the deployment, to appear in the deployment tab within Appian]
    5. Update devops/f4a/users.properties 
      # List of username/password combination with access to Appian environment
# Example: fitnesse.user=password
<username-for-site>=<password>
    6. Update Jenkinsfile
      1. The following parameters need to be accessible to the Jenkinsfile as environmental variables:

        REPOUSERNAME

        Username for remote repository

        REPOPASSWORD

        Password for remote repository.

        ARTIFACTORYAPIKEY

        API Key to access Artifactory repo containing ADM and F4A

        ARTIFACTORYURL

        URL to access Artifactory repo containing ADM and F4A
    7. Create a generic repository in Artifactory to store the .zip files for ADM and FitNesse for Appian based on the recommended file structure.
    8. Create a Jenkins Job
      1. Create a ‘New Item’
        1. Pick a descriptive name, such as “My-App-QuickStart”
        2. Select “Pipeline” Job
      2. Check the box “This project is parameterized” and add the following parameters:
        1. String: APPLICATIONNAME
          1. Name of application being deployed (Should correspond directly with folder name in repository)
      3. Check the box “Poll SCM”
        1. Schedule: “0 2 * * *”
      4. In the Pipeline definition, “Pipeline script from SCM”
        1. SCM: Git
        2. Repository URL: URL to remote repository
        3. Script Path: Jenkinsfile

    Developer Environment Setup

    1. Install ADM locally
    2. Override the default Automated Versioning Manager’s version-manager.properties file with the copy from the repo located at devops/adm/version-manager.local.properties
    3. Adjust the version-manager.properties file as necessary to match your local preferences 
      ### Environment-specific properties
## REQUIRED. Username of the version control account
vcUsername=<remote-repo-username>
## REQUIRED. Password of the version control account
vcPassword=<remote-repo-password>
## REQUIRED. URL to access the remote repository
repoUrl=<remote-repo-url>
## REQUIRED. Path to the folder containing the local repository
localRepoPath=<local-repo-path>
## Path to the folder containing the Appian objects in the repository. This path is relative to the path of the local repository. If not specified, the Appian objects are checked out to and committed from the root of the local repository path.
## Assure that the path does not contain any preceding or trailing forward slashes. Example: appian/applications/Hello_World
appianObjectsRepoPath=appian/applications/<application-name>


### Action-specific properties
## REQUIRED. Valid choices are addContents, buildAllApps, buildSingleApp, or updateLocalRepo
action=addContents
## Path for the application ZIP file to add to version control. Used for the addContents action.
applicationPath=<path-to-local-application-ZIP>
    4. Install FitNesse for Appian locally

    How to use

    1. Use git to update your local repository with any remote changes
    2. Use Version Manager to add your Appian application/patch to the repo
      1. Include any necessary Flyway migration files associated to the application changes
    3. Wait for the pipeline to be triggered or manually trigger it
    4. Use the Jenkins pipeline dashboard to monitor the automated tests and deployments
    5. In the “Promotion Decision” stage, either promote or abort the pipeline job

    Verify Setup

    1. Verify the Jenkins job pipeline ran successfully and all stages are reported green
    2. Navigate to “Releases” in your GitHub repository and verify that a release has been made
      1. The release should include the application zip as well as a custom import properties file, if specified in appian/properties

    Appendix

    Code Repository File Structure

    Download Sample Code Repository File Structure

    •  appian
      •  applications
        •  README.md
      •  properties
        •  README.md
    •  devops
      • deploymentmanagement.prod.properties
      • deploymentmanagement.test.properties
      • deploymentmanagement.stag.properties
      •  adm
        •  import-manager.prod.properties
        •  import-manager.stag.properties
        •  import-manager.test.properties
        •  version-manager.local.properties
        •  version-manager.properties
      •  f4a
        •  test_suites
          •  QuickStartAcceptanceTest
          •  QuickStartIntegrationTest
        •  README.md
        •  fitnesse-automation.acceptance.properties
        •  fitnesse-automation.integration.properties
        •  users.properties
      •  README.md
    •  Jenkinsfile
    •  README.md

    Artifact Repository File Structure

    Download ADM and FitNesse for Appian. Rename the .zip files as adm.zip and f4a.zip respectively. Upload them to an Artifactory repo named appian-devops.

    •  appian-devops
      •  adm.zip
      •  f4a.zip

    Security

    • It is recommended to configure the pipeline infrastructure to limit access to node machines executing the pipeline to ensure sensitive information required for execution is properly secured.
    • The sample Jenkinsfile document relies on credentials stored in plaintext directly in the properties files or environment variables. This is intended for demonstration purposes only. It is recommended to store credentials in a secure system such as Hashicorp Vault. Update the Jenkinsfile stages to retrieve them at runtime.
    • For sensitive configuration properties, such as those used in the staging and production environments, it is recommended to store their values in a secure system such as Hashicorp Vault. Update the Jenkinsfile stages to retrieve them at runtime. Consider updating the sample properties files to use a single tokenized file if all the values for each environment are stored in a separate system.

    Appian Cloud Considerations

    • All plugins needed by your Appian applications should be deployed to all the Appian environments before running the pipeline.

    Environments

    • The pipeline is setup to automatically add git tags to keep track of the version of the applications that is deployed on each environment. This is simpler than using separate branches or a different system. It’s also fully automated and traceable via the git tags.
    © 2024 Appian. All rights reserved.
    We want to hear from you! Submit a review on Gartner or G2.