Continuous Integration (CI) is the process of automating the build and testing of code every time a team member commits changes to version control. With K2 platform we have a number of problems here. First of all, the artifacts created on K2 are versioned and stored inside K2, which itself is a source control for Smartobjects, Views, Forms and Workflows. But even though K2 stores all the versions of the artifacts, it does not allow to revert the version back, at least for Smartobjects, Forms and Views and at least for now. Secondly, it is not quite clear how to test different artifacts inside K2. For example, there is an out-of-the-box Test Manager for Smartforms testing, but it is not quite clear yet, how to automate this.
It is also worth mentioning PowerToolz – a powerful tool by jeylabs , which can do a lot of testing and even more. But in this article I would like to show you only a small and at the same time very important part of the continuous integration – Automatic Build of K2 projects.
There are a lot of platforms on the market, that can automate your builds, tests and deployments, but in the current example I will use Visual Studio Team Services (aka Visual Studio Online). Below you will see how to create a Build definition, how to run it and get the release package in the end with all your artifacts. Let’s start then.
Step 0 – Installation and configuration of a build agent.
First of all, I would recommend to create a separate agent pool for your development server.
I will name my agent pool: K2-CI-Demo. You then will need this name, when configuring a build agent.
Download an agent, unpack it and install it on your machine, where K2 is installed.
After you successfully configured the agent, you might see something like this.
Everything, which you see on the screenshot, is just an example. You by no means are obliged to start your agent as a service OR give the names, which I gave. The most important is to be able finally to see your agent listed inside your VSTS under the pool you created. The agent must be online and green:
Now we are ready to move to the Build Configuration. For the demo purposes, I will use an ExpenseClaim project, which can be installed from the Smartstarters pack. Please, pay your attention, that the path to the ExpenseClaim category is “AppsK2SmartStartersExpenseClaim”. This is very important, cause it will be used in the script, specified below
1. Create a project on VSTS.
The automated package will be created with the help of a powershell script. Therefore, we need to upload it and all the dependencies to the VSTS. Moreover, your VSTS project might also contain a lot of other project-related artifacts, e.g. SQL DB Schema, SSRS Reports, Custom ServiceBrokers etc. So you can automate the build of all other artifacts as well. Unfortunately, this is not in the scope of this post, cause you can find tons of info on the Internet how to automate SQL Database projects build etc.
So I created a project with the name K2-CI-Demo and I am using Git as a Version Control. Afterwards, I cloned the git repository to my machine, created Visual Studio Powershell project with a Package Script, added the necessary Assemblies to the folder and committed all the changes:
Here is a copy of the VSTS repository on Github – K2-CI-Demo Github. The main script, which I will run with the help of VSTS, is Package.ps1. If you wish, you can add your own logging or specific output to the console to this file, so that you are able to see all this inside your VSTS console log.
Its main dependency is K2Field.Powershell.Module.dll. This is the module, whose source code is available here: K2 Management Pack. If you need more information on how it all works, just post a comment or send me an email. But for now, it should be enough to note, that with the help of VSTS I will run the Package.ps1 script with certain parameters.
2. Create a Build Definition on VSTS
Since all our scripts are already inside the remote repository, we can move to creation of a Build Definition.
Select your Team project, Repository and Branch:
On the next page, click Empty process:
You will see a canvas for designing your Build process. In the Process section, you need to give a name to your Process (mine is K2-CI-DEMO-CI) and select the Agent queue, we created in the first step:
If you wish, you can change the default options of the Get-Sources step, but meanwhile I will leave them untouched.
What I do want to change is the Build Definition Options. This will create final artifacts packages with a certain file name format (e.g. ExpenseClaim_20180228.2):
Return back to the tasks panel and add 3 tasks:
- Copy Files
Here is an example, how you can add a task to your Build Process:
3. Configure your PowerShell task
Options of the task:
- Display Name: Powershell Script (You can enter whatever you want)
- Type: File Path
- Script Path: K2-CI-Demo/K2-CI-Demo.Powershell.Scripts/Package.ps1
- Arguments: -appName “ExpenseClaim” -categoryPath “AppsK2SmartstartersExpenseClaim”
- Working Folder: K2-CI-Demo/K2-CI-Demo.Powershell.Scripts
You can specify the Script Path manually OR you can select it from the pop-up:
4. Configure Copy Files task
- Display Name: Copy Files to Staging (You can enter whatever you want)
- Source Folder: K2-CI-Demo/K2-CI-Demo.Powershell.Scripts/PND
- Content: **
- Target Folder: $(Build.ArtifactStagingDirectory)/$(Build.BuildNumber)
If you looked inside the Powershell script, you could have noticed, that the K2 package as well as its xml deployment config are created inside the PND folder. You might not have the PND folder in the Select Path pop-up window. This means, you will have to write it manually in the Source Folder options.
$(Build.BuildNumber) – this is an internal variable, which takes the value of our Build Number, the format of which we specified in the Process Options-> Build Number Format (e.g. ExpenseClaim_$(Date:yyyyMMdd)$(Rev:.r)).
$(Build.ArtifactStagingDirectory) – this is an internal variable, which stores the local path on the agent where any artifacts are copied to before being pushed to their destination.
For more information on the internal variables in VSTS, please, refer to the following link Build variables.
4. Configure Publish Artifacts task.
- Display Name: Publish Artifacts (You can enter whatever you want)
- Path to publish: $(Build.ArtifactStagingDirectory)/$(Build.BuildNumber)
- Artifact Name: $(Build.BuildNumber)
- Artifact publish location: Visual Studio Team Services/TFS
This task will zip all our artifacts and publish them to the VSTS.
5. Run and check the results
You can save your Build Definition and Queue it. Navigating to your Build Definition, you can see all Queues, which are in progress, completed or in error state:
I will open the latest build, which in my case has a name #ExpenseClaim_20180228.3. You can see all the details from the console of the server, where the agent is running. If you implement logging OR console output inside your powershell scripts, you will see all this information on the right side:
Navigating to the artifacts section of your build, you can see the artifacts, that were created and built with the help of VSTS:
Clicking Explore, you can see what is inside:
You can even download and open the package inside your Package and Deployment tool to check, what is inside. The package should contain all the items under the Category Path, you specified in your script, as well as all the dependencies.
This is it. The K2 package is created automatically. In the next part of the Continuous Integration series, I will show you how you can automatically deploy your projects from VSTS.
But before I finish, there are still some notes to be made:
- The code inside the Powershell module as well as the whole approach is not an official way of building your packages. If you encounter any errors, K2 Support will more than likely reject the ticket and will ask you to created the package in a conventional way with the use of Package and Deployment tool.
- The automatic build was never tested with any packages, which contain Sharepoint artifacts. Thus, you should apply it with due caution.
- In the next release of the Powershell module it is planned to add the functionality to include non-dependent artifacts. Currently, if the dependency is missing, the artifact will not be included into the folder, unless it is located inside the Category Path, provided in the script.
Feel free to post comments or ask questions. I hope, this article will be useful and it proves, that K2 can be used with the DevOps best practices.