Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 26 Next »

The SHELL adapter library is just intended to something you copy and rename and make it into a real adapter for a real system. It has all the boiler plate you need. I made it because I wanted to try to build a few adapters to Solve the calendar management problem.

I took the Slack Notifier Adapter and hollowed it out to make this empty adapter. Should help me write a few adapters fast (remove bottlenecks )

The shell adapter ships with Iguana just add the Shell Example - see Create a Component .

So how do we use it say to create an Atlassian adapter.

 The Goal - A good adapter will have very little code and be easy for the user to extend

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.

 Start with a copy of new Custom component

Let’s use a copy of new Custom component (Create a Component ) and name it ‘Confluence adapter’

 Import the SHELL library and associate it with a new repo
 Rename the Library folder and all the files in it to a new prefix

For instance:

 Search and replace SHELL for ATTL in the project

This gets all the prefixes consistent.

 Make sure the ATTLclient function gets the parameters needed to authenticate
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@interfaceware.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
 Add API access key to this project

The API access key needs 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.

 Implement a good custom method

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.

 Implement a good API method

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.

 More about API methods

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.

 Update Client Constructor

Append to Client’s meta table the three newly added methods and the ‘space_id’ variable declaration

local MT={}

MT.__index = {}
MT.__index.descendants     = require 'ATTL.ATTLdescendants'
MT.__index.getSpaceId      = require 'ATTL.ATTLgetSpaceId'
MT.__index.getDescendants  = require 'ATTL.ATTLgetDescendants'

help.map{dir='ATTL/help',methods=MT.__index}

function ATTLclient(T)
   local S= {}
   setmetatable(S, MT)
   S.key           = T.key
   S.space         = T.space
   S.user          = T.user
   S.organization  = T.organization
   S.space_id      = T.space_id
   return S
end
 Not to forget the Help files

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

image-20240319-153543.png
 Time to put all of this to good work.

Let’s create a simple main.lua file

require "ATTL.ATTLclient"

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

function main(Data)
   A:getSpaceId() 
   local count = 2 
   A:descendants{count = count, live = true}
end
 How does this main.lua works?

Right after declaration of Client instance and passing the 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 to return the listing of descendants for 50 pages.

image-20240319-154423.png
 Share a little of 'what is next'?

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 the API methods true to vendors 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.

  • No labels