Shell Adapter

It’s better to have a simple ‘incomplete’ adapter that is easily understood and altered by the user than an over elaborate one.

Iguana X is a open system which is intended to allow our customers and do anything. Overly elaborate adapters means that the code is a what we call a Code dump which makes it difficult for other people to adapt and use the code to their own purposes.

This is problem with a lot of Open Source projects.

Sure you have access to the code but that isn’t helpful if it takes months of study to understand it and it the code has many many design flaws that you cannot solve without with years of commitment.

Less is more.

Let’s use a new Custom component and name it ‘Confluence adapter’

Let’s say git@bitbucket.org:interfaceware/atlassian

For instance:

Use ‘View Remote’ for the now named ATTL library

… and specify new REPOSITORY name for this Library to be associated with

This gets all the prefixes consistent.

function ATTLclient(T)
   local S= {}
   setmetatable(S, MT)
   S.key = T.key
   return S
end

So in the case of Atlassian we need:

• user - I.e. fred.smith@acme.com

• space - i.e. ABC for a Confluence space that has this ID

• key - A unique personal API key for a confluence user

• organization - to construct base URL to our Confluence space, e.g. https://acme.atalassian.net

This adheres with Naming convention for table parameters in Iguana.

These should just be passed through in the table arguments. So the code becomes:

function ATTLclient(T)
   local S= {}
   setmetatable(S, MT)
   S.key           = T.key
   S.space         = T.space
   S.user          = T.user
   S.organization  = T.organization
   return S
end

The API access key need to be treated as password. Thus we create in config.json a custom field named ‘key of type 'Password’ and store in it the personal Atlassian API access key, respective to the user name in use.

The custom method should do most the guts of the adapter. Most web APIs have some magic sauce that you have to make an API call. The custom method does this and should make it easy to call methods on the API which have not been wrapped explicitly.

Let’s call our new Custom method ATTLdescendants. We can rename ATTLhello into ATTLdescendants and to rewrite its content.

This method will help us to invoke the API method ATTLgetDescendants.

Let’s call our new API method ATTLgetDescendants. We can rename ATTLcustom into ATTLgetDescendants and to rewrite its content.

This method will returns all pages in a space.

Sometimes an API method would require a parameter which can be discovered only programmatically. In our example of Confluence Adapter this is Confluence Space Id parameter, which isn’t the same as a Space Key above. The API method ATTLgetSpaceId will help us to discover this value. Let’s create new Lua file, name it ATTLgetSpaceId and write its content.

Append to Client’s meta table the three newly added methods

Add Help files to explain what parameters your custom methods expect. Other users will appreciate this!

Take opportunity to obsolete the ATTLclient.help file and to publish this information as client.help file in the ‘help’ folder, along with the rest of help files.

Let’s create a simple main.lua file

require "ATTL.ATTLclient"

A = ATTLclient{
   key          = component.fields().key,
   space        = 'EC',
   user         = 'lev.blum@interfaceware.com',
   organization = 'interfaceware'
} 

function main(Data)
   A:getSpaceId() 
   local count = 2 
   A:descendants{count = count, live = true}
end

Right after declaration of Client instance and passing parameters to it, we discover the Confluence Space ID. This value couldn’t be known without running this API call.

Next we prepare for paginated API call and require only 2 calls to be executed by setting ‘count’ variable to number 2. This will save the time while testing.

And finally, we request from API and get a listing of descendants for 50 pages.

So, we can query Atlassian API for Confluence! What it is good for? We can query documents, we can edit documents, we can modify/export/add/delete content in any manner we imagine. The complete documentation for this API is available here.

Just create more API methods and more Custom methods.

Custom methods are very helpful to keep API methods true to API documentation. Custom methods will help to create your specific parameters combination, and to massage the responses. Custom methods are the interface, between your code, to clean and true API methods.