How-To: Getting Familiar With The Studio Development Lifecycle (Beta 10.4)

Problem

You are familiar with the Predix Studio UI, having ingested your data, created your own workbenches, and maybe even customized MIx plugins with IDE. But how do you release this product to the end user? Just as engineering teams follow a software development lifecycle, you should follow the lifecycle for Predix Studio.

This guide uses a Studio customization scenario to illustrate how to walk through this lifecycle, from customizing Studio to releasing for users.

~

Dependencies

• Access to Cloud9 IDE

• Access to a CI, QA, and Jenkins environment setup

• Familiarity with using Studio

• Familiarity with writing and deploying plugins in Studio IDE

~

Overview

This guide will step through the basic end-to-end process of writing code to releasing your app as illustrated below:

• Writing the Code

  • Develop a new menu item

  • Test the new menu item

  • Debugging tips

• Committing Work

  • Commit your workbench

  • Commit your code

• Packaging and Verification

  • Package your product for CI

  • Move the package to Q

• Moving the Product to Release

  • Generating a download link for the package

• Resources

Note: If you want to simply push your UI changes through the lifecycle, you can skip straight to the Committing Work section.

~

Writing the Code

In this section, we’ll demonstrate steps for writing a plugin, building it, and making sure you’re working with the latest version of your team’s code. After that, you'll walk through writing unit tests for a report template, deploying a plugin to Studio, and checking in your code (and workbench) to your team's repository.

~

Develop a new menu item

1. Create a new workbench using the Menu Manager. In this example, we created the menu item SDLC Indicators.

   

2. Then add a General Counts indicator to the new workbench.

   

3. Navigate to the Studio IDE to create then deploy a sample report. In the example below, we created a simple report called sdlc_report.xml.

   Check out How to Get Started With the Predix Studio IDE and the IDE User Guide to familiarize yourself with the IDE.

   

   Note: Before making any changes in the IDE, make sure you have the latest version of your team's code by choosing Run > Build System > LatestVersion and then running Build.

   sdlc_report.xml:

      <mix:template xmlns:mix="http://bitstew.com/schemas/1.0/xml-template"
            xmlns:xfn="http://bitstew.com/schemas/1.0/extended-functions"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:xs="http://www.w3.org/2001/XMLSchema"
            xmlns:fn="http://www.w3.org/2005/xpath-functions"
            xsi:schemaLocation="http://bitstew.com/schemas/1.0/xml-template http://bitstew.com/schemas/1.0/xml-template/XMLTemplates.xsd">
               
            <!-- We will simply return to static key/value pairs -->
            <Report>
                <Record>
                    <Key>hello</Key>
                    <Value>200</Value>
                </Record>
                <Record>
                    <Key>world</Key>
                    <Value>300</Value>
                </Record>
            </Report>
            
            <!-- Catch any unhandled exceptions. -->
            __CATCH_ALL_
                    
        </mix:template>
   
   

4. Navigate back to the indicator in your workbench, and change the REPORT URL to the report you just deployed. Your indicator should populate after updating.

   

~

Test the new menu item

• Create a MIxUnit test file called mixunit_test_sdlc_report.xml in the com.devrel.reports.sdlc_report folder.

  

  The naming convention is to start with mixunit_test followed by an underscore (_) and text describing the test (preferably the plugin name).

• Add the following code to the test file you've just created:

  mixunit_test_sdlc_report.xml:

     <?xml version="1.0" encoding="UTF-8"?>
       <mix:template xmlns:mix="http://bitstew.com/schemas/1.0/xml-template"
           xmlns:xfn="http://bitstew.com/schemas/1.0/extended-functions"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xmlns:xs="http://www.w3.org/2001/XMLSchema"
           xmlns:fn="http://www.w3.org/2005/xpath-functions"
           xsi:schemaLocation="http://bitstew.com/schemas/1.0/xml-template http://bitstew.com/schemas/1.0/xml-template/XMLTemplates.xsd"
           xmlns:mixunit="http://example.com/namespace">
             
           <?include plugins/mixunit/com.bitstew.tests.library/1_00_00/main.xml ?>
              
             
           <!-- __ SETUP  __ -->
           <!-- If your report needs parameters you can easily pass it into it -->
           <mix:variable name="params">
               <Param1>end_device_events_*</Param1>
               <Param2>cheers</Param2>
           </mix:variable>
             
           <mix:variable
               name="report"
               select="mixunit:getTemplate('plugins/reports/com.devrel.reports.sdlc_howto/sdlc_report.xml', 'director-services', $params, 'GET')"
               as="xml"
           >
               <mix:exception-handler name="getTemplateException" dump="yes">
                   <mix:exit message="The error code {$getTemplateException/getCause()}"/>
               </mix:exception-handler>
           </mix:variable>
             
           <!-- __ RUN TESTS __ -->
           <testcases name="Testing reports (with common library) " className="">
                         
               <testcase name="Confirm number of records in the list">
                   <mix:variable name="countOfNodes" select="count($report/Report/Record)" />
                   <mix:copy-of select="mixunit:assertEqual($countOfNodes, 2)" />
               </testcase>
               <testcase name="Confirm key 'hello' exist in the list">
                   <mix:copy-of select="mixunit:assertNodeExists($report,'/Report//Record/Key/text()=&quot;hello&quot;')" />
               </testcase>
               <!-- This test below will fail! -->
               <testcase name="Confirm key 'temperature' exist in the list">
                   <mix:copy-of select="mixunit:assertNodeExists($report,'/Report//Record/Key/text()=&quot;world&quot;')" />
               </testcase>
           </testcases>
              
       </mix:template>
  

~

• Choose Run > Build System > DeployAll to deploy the test directory, then flush the service cache in the Studio UI to load the new file.

  

  Note: DeployAll is a catch-all mechanism for deployment for now. A method to deploy unit tests along with plugin code using DeployPlugin is in the works.

• To see the results of your tests, open a browser and go to the following address, replacing <yourdevenvironmentaddress> with your development address.

  https://<yourdevenvironmentaddress>/director/SystemServices/main?system:runTemplate=plugins/mixunit/com.bitstew.tests.library/1_00_00/services_proxy.xml≺oxyTo=plugins/reports/com.devrel.reports.sdlc_report/mixunit_test_sdlc_report.xml&isHuman=yes

  Your test results should look something like this.

  

  Here's a breakdown of the address:

  • yourdevenvironmentaddress: Your Studio environment address (for example, hello-world-develop.studio.predix.io).

  • proxyTo: Link to where your mixunit test lives. If your tests live in the director folder, you can runTemplate directly as follows:

    https://<yourdevenvironmentaddress>/director/SystemServices/main?system:runTemplate=tests/plugins/reports/com.devrel.reports.sdlc_indicator/mixunit_test_sdlc_indicator.xml

  • isHuman: Formats the tests for easier readability.

  For more details on testing, check out the Testing and Automation

~

Debugging Tips

If you are not sure your plugins were deployed to your DEV environment, try searching for it using Director Debugger or Director Service Debugger (in the Tools menu) depending on where your plugins live.

For example, you can search for the sdlc_report.xml file to verify it exists.

You can also issue a GET, POST, or PUT command directly in the debugger to verify that it behaves correctly.

For a more in-depth look at debugging tools and strategies, check out Debugging Tools

~

Committing Work

Now that you’ve configured the workbench and have tested the code, we can move on to the next phase of the lifecycle: Pushing your changes to the team's code repository.

~

Commit your workbench

1. Choose Run > Build System > ExportMenu to export the workbench you created in the UI.

   The script for exporting a menu runs, and generates the exported data into a file. This is the file that will be committed to the repository.

2. At the prompt, enter the title of the menu.

   

   Now when a new package is created and deployed to your CI platform (to be covered in the next section), you should be able to see the same workbench (SDLC Indicators) in the CI environment.

   Note: In addition to menus, you can export several items created within the UI, such as business rules, dynamic adapters, indicators, and more. You can find more details on how to do this at Exporting Configuration Data (UI Changes)

~

Commit your code

The most common method we use to commit code is using the CheckIn build target. An alternate method, if you’d like more fine-grained control, is using Git at the command line. We’ll walk through both approaches below:

1. Choose Run > Build System > CheckInAll to commit your code changes, then run Build.

   

   In the terminal you’ll see a list of files you have modified and are prompted to commit your files.

2. Provide a commit message as shown below then hit Enter to proceed.

   

   Note: The CheckIn menu item can be used to commit plugin code (sdlc_report.xml in this example), but as with DeployAll earlier, the CheckInAll menu item commits all files that have changed in your workspace including unit tests.

• (Optional) Alternatively, use Git in the terminal to commit and push changes as follows:

      $ git-status                           # Check on the files you've modified and are staging for commit
       $ git-add <files-you-are-adding>       # Add files after checking on status
       $ git-commit -m "commit message here"  # Commit files to get set for pushing to your team's repository
       $ git-push                             # Push to your team's branch.
  
  

When you push changes to the master branch of your repo using either method, a Jenkins build is triggered to deploy your code into the CI server. For more information on Git and using different branches, check out Git Functionality for Predix Studio Workspaces

After a successful commit, you should see something like this.

~

Packaging and Verification

Packaging your product for verification is one of the key software development lifecycle steps. A dedicated QA platform allows testers to quickly verify functionality before finally releasing a plugin package.

After pushing your work to the master repository, a build package is deployed for CI. After that is done, it is important to do the following:

• Verify that the package build was successful.

• Verify that the package deployed on the CI server successfully.

• Verify that automated and manual testing is done on the CI server and passes without regression of functionality.

~

Package your product for CI

1. Choose Run > Build System > CreatePackage, then run Build to deploy a newly created package for CI.

   Note: As previously mentioned, pushing work to the master branch triggers a build for CI. However, running commands such as ExportMenu might update your repo, but does not trigger creating a new package. This is where manually running CreatePackage comes in handy.

   

   When the build starts, you should see the message above. Take note of the build job number (#9 in this example) as this will come in handy when verifying the build.

2. Log in to Jenkins and verify that the package build was successful on the CI server.

   After logging in, you should see a list of build jobs as seen below:

   

3. Click on the Deploy to CI Server job, then click on your build job number under Build History on the left.

   The build summary below shows a job with a failed test (#7). You can see the test that failed is from one of our unit tests.

   

4. Log in to the CI environment in Predix Studio. The CI environment allows you to do verification necessary of your environment.

   For more information on the CI server and debugging builds, check out Continuous Integration and Build Server

~

Move the package to QA

After your package has been verified on CI, a release manager or developer can deploy (promote) the same package to QA for further verification.

1. Login to Jenkins, click on the plugin package build job, and then click the build number that you'd like to promote.

   

2. In the left menu bar, click Promotion Status. The Promotion Status page shows the promotions available for this build, including a section called Deploy on QA Server.

   

3. In the Deploy on QA Server section, click Approve. This triggers the Deploy to QA Jenkins job to Install the Plugin Package to the QA Platform.

   The installation may take some time. To keep track of progress, you can navigate to the Deploy to QA job in the Jenkins main menu.

4. If there's debugging to be done, you can iterate the same process that you have for CI server to see what's wrong with the Jenkins build.

   For more information on verifying your package on the QA Predix Studio platform and troubleshooting, check out Verification on the QA Predix Studio Platform.

After you’ve successfully promoted your plugin to QA and addressed all issues, it’s time to move it to the release phase.

~

Moving the Product to Release

At this point on Studio, you have coded, deployed, packaged, and verified your MIx plugin through the Software Development Lifecycle. Now, you are ready to release your plugin package externally. We will guide you through the steps to release your software

~

Generate a download link for your package

1. Login to Jenkins, click on the plugin package build job, click the build number that you'd like to promote, and then click Promotion Status.

   The Promotion Status page shows the promotions available for this build, including a section called Download Plugins Package.

2. In the Download Plugins Package section, click Approve.

   This triggers the Download Package Jenkins job to create a download link.

3. Navigate to the Download Package job in the Jenkins dashboard.

   Your new package is listed under Last Successful Artifacts.

4. Click the package link to download it locally, or right-click and copy the link address to use elsewhere.

   For further instructions on how to install your package on a production instance of the platform, see Installing a Plugin Package.

~

Resources

• Predix Studio SDLC

• Best Practices

• Testing and Automation

• Debugging Tools

• Export Configuration Data (UI Changes)

• Git Functionality for Predix Studio Workspaces

• Continuous Integration and Build Server

• Verification on the QA Predix Studio Platform

• Releasing Plugin Packages