Page Comparison

...

Expand

title	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.

Expand

title	Start with a copy of new Custom component

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

Image Added

Expand

title	Import the SHELL library and associate it with a new repo

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

...

Expand

title	Make sure the ATTLclient function gets the parameters needed to authenticate

Code Block

language	lua

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:

Code Block

language	lua

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

Expand

title	Add API access key to this project

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.

Expand

title	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.

Expand

title	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.

...

Expand

title	Not to forget the Help files

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.

Expand

title	Time to put all of this to good work.

Let’s create a simple main.lua file

Code Block
require "ATTL.ATTLclient" A = ATTLclient{ key = component.fields().

First

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 test time while testing.

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

...

Versions Compared

Old Version 20

New Version 21

Key