Tutorial for finding, using and creating plugins in the 'Air' framework by Urbancode.

1. Air Plugins
Extending and customizing
uDeploy (IBM UrbanCode Deploy)
and uBuild (IBM UrbanCode Build)

2. IBM Corporation ©2013
Presenting Today
Matt: Lead Developer Eric: Consulting

3. IBM Corporation ©2013
Out of the box integrations – a good start

4. IBM Corporation ©2013
But your team is unique

5. So our integrations are “Plug-ins”

6. IBM Corporation ©2013
Why Plugin-ins?
Make Integrating Easy

7. IBM Corporation ©2013
Why Plugin-ins?
Wrap existing scripts

8. IBM Corporation ©2013
Why Plugin-ins?
Custom Fit

9. IBM Corporation ©2013
The Plan
 Plugin Basics
 Finding and Uploading Plugins
 The Anatomy of a Plugin
 Basic Plugin Authoring
 Tools for Bidirectional Integrations

10. IBM Corporation ©2013
The Plan
 Plugin Basics
 Finding and Uploading Plugins
 The Anatomy of a Plugin
 Basic Plugin Authoring
 Tools for Bidirectional Integrations

11. IBM Corporation ©2013
What is a Plugin?
 A package that provides new automation capabilities
 Format is a zip file containing:
- Description of ‘steps’
- Description of inputs to those steps
- Scripts or code that execute those steps
- Upgrade rules
 uBuild & uDeploy share a plugin architecture: Air

12. IBM Corporation ©2013
The Plan
 Plugin Basics
 Finding and Uploading Plugins
 The Anatomy of a Plugin
 Basic Plugin Authoring
 Tools for Bidirectional Integrations

13. Getting Plugins

14. IBM Corporation ©2013
1) Go to Plugins.urbancode.com.

15. IBM Corporation ©2013
2) Download some plugins

16. IBM Corporation ©2013
3) Load them via the browser

17. IBM Corporation ©2013
New steps are immediately available

18. IBM Corporation ©2013
Plugin -> Agent
How: Pulled automatically
When: As it gets used
- This first execution will appear to take longer as plugin
transport time is rolled into the step.

19. IBM Corporation ©2013
The Plan
 Plugin Basics
 Finding and Uploading Plugins
 The Anatomy of a Plugin
 Basic Plugin Authoring
 Tools for Bidirectional Integrations

20. IBM Corporation ©2013
The Anatomy of an Air Plugin
 Definition: What steps, input and how to invoke
 Upgrade Rules
 Info.xml: Versioning
 Payload: Scripts, libraries and tools that accomplish
the plugin’s goals
 Packaging: Wrap contents in a zip file

21. IBM Corporation ©2013
Plugin Definition
 Expressed in the plugin.xml
 Definition of properties (settings) used by various
levels of the plugin
 Lists the steps the plugin makes available and
which commands or scripts to execute

22. IBM Corporation ©2013
Upgrade Definition
 Supports upgrading from one plugin version to the
next
 Required when:
- Adding or renaming steps or properties

23. IBM Corporation ©2013
Payload
 Everything that makes the integration “go”

24. IBM Corporation ©2013
The Plan
 Plugin Basics
 Finding and Uploading Plugins
 The Anatomy of a Plugin
 Basic Plugin Authoring
 Tools for Bidirectional Integrations

25. IBM Corporation ©2013
Example: Atlassian Jira
Plugin.xml header:

26. IBM Corporation ©2013
Example: Atlassian Jira
Plugins contain one or more steps. Each has:
- A description (what is it)
- Properties (inputs)
- Post-processing (how do we know if it passed?)
- A command (how to make it go)

27. IBM Corporation ©2013
Example: Atlassian Jira
Step properties look like this:

28. IBM Corporation ©2013
Example: Atlassian Jira - Properties

29. IBM Corporation ©2013
Example: Atlassian Jira - Properties

30. IBM Corporation ©2013
Example: Atlassian Jira - Properties

31. IBM Corporation ©2013
Example: Atlassian Jira – Post-Processing
<post-processing>
<![CDATA[
if (properties.get("exitCode") != 0){
properties.put( "Status”, "Failure”);
} else {
properties.put("Status", "Success");
}
]]>
</post-processing>

32. IBM Corporation ©2013
Post Processing Fanciness
 Look for all instances of “Downloading file x” in the
log, and create a property listing all ‘x’.
scanner.register("Downloading file .*",
function(lineNumber, line) {
line = line.substring("Downloading file '".length);
line = line.substring(0, line.length-1)
var changedFiles = properties.get("changedFiles");
if (changedFiles == null) {
changedFiles = "";
}
changedFiles = changedFiles+line+"n";
properties.put("changedFiles", changedFiles);
});
scanner.scan();

33. IBM Corporation ©2013
Commands
<command program="${GROOVY_HOME}/bin/groovy">
<arg file="replace_tokens.groovy"/>
<arg file="${PLUGIN_INPUT_PROPS}"/>
<arg file="${PLUGIN_OUTPUT_PROPS}"/>
</command>
Args may be: value, file or path.

34. IBM Corporation ©2013
Payloads: Example script
 Cross platform un-tar

35. IBM Corporation ©2013
Payloads: Example script (setup)
final def workDir = new File('.').canonicalFile
final def props = new Properties();
def inputPropsFile = new File(args[0]);
inputPropsStream = new FileInputStream(inputPropsFile);
props.load(inputPropsStream);
def dirOffset = props['dir']?:'.'
def tarball = props['tarball'];
def compression = props['compression'];
def overwrite = Boolean.valueOf(props['overwrite']);

36. IBM Corporation ©2013
Payloads: Example script (execution)
def ant = new AntBuilder()
if (overwrite) {
ant.untar(
dest:dirOffset,
failOnEmptyArchive: 'true',
compression: compression,
overwrite: 'true',
src: tarball)
}
else {
ant.untar(
dest:dirOffset,
failOnEmptyArchive: 'true',
compression: compression,
overwrite: 'false',
src: tarball)
}

37. You don’t have to use Groovy

38. IBM Corporation ©2013
Why do we?
 Steps can run any script you write. Why does
Urbancode usually use Groovy?
- Groovy is on every agent
- Groovy cross platform
- Groovy is very good at XML
- Groovy is fun to learn, concise and effective
 Other good choices:
- Perl, Ruby, VBScript, Python
- Etc, etc, etc

39. IBM Corporation ©2013
Common plugin strategies
 Construct a command line call
 Web services
 Wrap existing shell & perl scripts
 Exploit utilities installed with the agent (Ant)

40. IBM Corporation ©2013
The Plan
 Plugin Basics
 Finding and Uploading Plugins
 The Anatomy of a Plugin
 Basic Plugin Authoring
 Tools for Bidirectional Integrations

41. IBM Corporation ©2013
uDeploy
 Post-processing
- Easily capture deployment information
 Rest services API
- 2 Wrappers: Command line and Java.

42. IBM Corporation ©2013
uBuild
 Web services accept metrics
- Construct an XML message
- Post to web message

43. IBM Corporation ©2013
uBuild
 Web services accept metrics
- Construct an XML message
- Post to web message
String url =
baseUrl +
"rest/buildlife/${buildLifeId}/testcoverage?reportName=${name}”
ProtocolSocketFactory socketFactory = new OpenSSLProtocolSocketFactory()
Protocol https = new Protocol("https", socketFactory, 443)
Protocol.registerProtocol("https", https)
PostMethod postMethod = new PostMethod(url)
if (authToken) {
postMethod.setRequestHeader("Authorization-Token", authToken)
postMethod.setRequestHeader("Content-Type", "application/xml")
}
postMethod.setRequestEntity(new StringRequestEntity(xml));
HttpClient client = new HttpClient()
def responseCode = client.executeMethod(postMethod)

44. IBM Corporation ©2013
uBuild
 Web services accept metrics
- Construct an XML message
- Post to web message
 Easiest to work from examples

45. IBM Corporation ©2013
In Summary
 Plugins extend Urbancode product’s automation
 They get you a custom fit
 Get them from plugins.urbancode.com
 Creating your own isn’t too hard

46. IBM Corporation ©2013
Additional Resources on Plugins
 Plugins.urbancode.com
- Plenty of examples
 Online Docs
- Schemas and additional how-to reference.
- Process flows

47. Q&A
eminick@us.ibm.com
Slideshare.net/Urbancode