Software Development

Making extensions in Agile Platform's Integration Studio

Justin James presents a tutorial on how to use .NET code to make a simple extension in the OutSystems Agile Platform's Integration Studio.

The primary reason I like using OutSystems Agile Platform is the visual editing of logic in Service Studio. That said, there are times when Service Studio can't do what I need; fortunately, I can use Integration Studio to create an extension that lets me write .NET or Java code to accomplish my needs. It is rare for me to need to use Integration Studio (lately, I only find myself using it for dealing with REST-ful Web services, which are a notable hole in Agile Platform's capabilities), but all the same it is important to know how to do it.

How to make a simple extension

When you start Integration Studio and log in to your server, you are presented with an empty Extension (Figure A). You can see that the Extension is being edited; here you can set important metadata such as the Extension's name, if it is .NET or Java, and what database backend with which to work. From here, you can add Actions, Entities (imported from an external database), and Structures (which define a record layout, but unlike Entities, are stored only in memory, not permanently in a database). Figure A

Empty Extension
I've found that it is best to start by defining your Structures, since they are used for input and output. The Structure editor (Figure B) is similar to the Entity editor in Service Studio. Figure B

The Structure editor

If you want to have a Structure contain a record or a record list as an attribute, you need to have those types defined as Structures as well. Unfortunately, if you want a RecordList of Text or Integer or similar built-in types, you still need to make a Structure with just that one field as a value. You can use the arrows on the right hand side to shuffle the order of the fields.

Now that your Structures are made, let's create an Action definition. You have the option of importing an Action from external sources like .NET assemblies. This is a nice option to have, but I've found that just like wrapping code for use as a Web service, the definitions of the calls for in-code use and as-a-service typically need to be a bit different to serve the needs. In many ways, writing a good Action here is much like writing a Web service, and the Action definitions look a lot like what a Web service endpoint does in terms of the parameters needed. The end result is that I prefer to wrap existing .NET code in Actions rather than directly import them as Actions -- your mileage may vary. Again, the Action definitions (Figure C) are very similar to the Action definitions with Service Studio. Figure C

Editing an Action
Once the Action is defined, you can open the code in Visual Studio so you can fill in the blanks on the Action. One slight annoyance is that the Extensions are created as Visual Studio 2008 solutions, so if you are a Visual Studio 2010 user, you need to upgrade it when it opens. That's a small price for backwards compatibility. When you open the .cs file that has the same name as your Extension, you will see your Actions stubbed out, and the comments from the editor are placed into the code as XML comments. Note: Changes to the comments here will not be reflected back to the Extension. Of interest, the output for the Action is defined as out parameters, because there may be multiple outputs for an Action. This is true even when the Action is defined as a Function with only one output. Also, you will want to use special care when iterating over a RecordList as well as working with the data in them.

Once you have written your code, you save it in Visual Studio (no need to exit, just a save will do), return to Integration Studio, and publish to the server. From there, you can use the Add/Remove References (under the eSpace menu) feature of Service Studio to get the Action and Structures imported into your application and ready to use.

By combining the flexibility and raw power of straight .NET code with the rapid development abilities of Agile Platform, you do not have to sacrifice an existing investment in code or the ability to do tricky things in the Agile Platform. While I do not use the Java version, I imagine that the experience is similar.

J.Ja

Read my other TechRepublic posts about Agile Platform

About

Justin James is the Lead Architect for Conigent.

0 comments

Editor's Picks