Class: Confluence::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/confluence-client.rb,
lib/confluence-client/version.rb

Overview

Confluence::Client - Ruby client for the Confluence XML::RPC API.

Usage

Confluence::Client.new(url) do |confluence|

  if confluence.(user, pass)

    # Was last API call successful?
    confluence.ok?

    # Print error message if error on last API call.
    puts confluence.error if confluence.error?

    ##########
    # Spaces #
    ##########
    space = confluence.get_space('foo')
    if space
      puts "found space: #{space.inspect}"
    else
      space = confluence.add_space( 'foo', 'space name', 'space description' )
      if space
        puts "created space: #{space.inspect}"
      else
        puts "unable to create space: #{c.error}"
      end
    end

    if confluence.remove_space('foo')
      puts 'removed space'
    else
      puts "unable to remove space: #{c.error}"
    end

    #########
    # Users #
    #########
    user = confluence.get_user('stan')
    if user
      puts "found user: #{user.inspect}"
    else
      user = confluence.add_user( 'stan', 'stan has a name', '[email protected]' )       
    end

    if confluence.remove_user('stan')
      puts 'removed user'
    else
      puts "unable to remove user: #{c.error}"
    end

    #########
    # Users #
    #########
    group = confluence.get_group('some:group')
    if group
      puts "found group: #{group.inspect}"
    else
      group = confluence.add_group('some:group')
    end

    if confluence.remove_group('some:group')
      puts 'removed group'
    else
      puts "unable to remove group: #{c.error}"
    end

    ##########
    # Groups #
    ##########
    if confluence.member?('stan', 'some:group')
      if confluence.remove_user_from_group('stan', 'some:group')
        puts 'removed user from group'
      else
        puts "unable to remove user from group: #{c.error}"
      end
    else
      if confluence.add_user_to_group('stan', 'some:group')
        puts 'added user to group'
      else
        puts "unable to add user to group: #{c.error}"
      end
    end

    ###############
    # Permissions #
    ###############
    if confluence.add_permission_to_space('Edit', 'stan', 'foo')
      puts 'added permission to space'
    else
      puts "unable to add permission to space: #{c.error}"
    end
    if confluence.remove_permission_to_space('View', 'some:group', 'foo')
      puts 'removed permission from space'
    else
      puts "unable to remove permission from space: #{c.error}"
    end

    ########## 
    # Logout #
    ########## 
    confluence.logout
  end

end

Constant Summary collapse

VERSION = 
'0.0.8'

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(url) {|_self| ... } ⇒ Client

Create new Confluence client.

Params:

url

Base URL for the Confluence XML/RPC API. ‘rpc/xmlrpc’ appended if not present.

Yields:

  • (_self)

Yield Parameters:

Raises:

  • (ArgumentError) 


120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
 
# File 'lib/confluence-client.rb', line 120

def initialize(url)
  raise ArgumentError if url.nil? || url.empty?
  url += '/rpc/xmlrpc' unless url =~ /\/rpc\/xmlrpc$/
  @server         = XMLRPC::Client.new2(url)
  # TODO Ugly, ugly hack!
  # http://stackoverflow.com/questions/4748633/how-can-i-make-rubys-xmlrpc-client-ignore-ssl-certificate-errors
  @server.instance_variable_get(:@http).instance_variable_set(:@verify_mode, OpenSSL::SSL::VERIFY_NONE)
  #@server.timeout = 305                          # XXX 
  @confluence     = @server.proxy('confluence1')  # XXX

  @error          = nil
  @password       = nil
  @token          = nil
  @user           = nil

  yield self if block_given?
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(method_name, *args) ⇒ Object 



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/confluence-client.rb', line 262

def method_missing(method_name, *args)
  unless @token
    @error = "not authenticated"
    return false
  end
  begin
    @error = nil
    return @confluence.send( method_name, *( [@token] + args ) )  
  rescue XMLRPC::FaultException => e
    @error = tidy_exception( e.faultString )
  rescue Exception => e
    @error = tidy_exception( e.message )
  end
  return ok?
end

Instance Attribute Details

#error ⇒ Object (readonly)

Error message from last request (if any).



112
113
114
 
# File 'lib/confluence-client.rb', line 112

def error
  @error
end

#token ⇒ Object (readonly)

Security token.



114
115
116
 
# File 'lib/confluence-client.rb', line 114

def token
  @token
end

Instance Method Details

#add_group(name) ⇒ Object

Create Confluence group. Returns group hash or nil.

Params:

name

Group name.



142
143
144
145
146
 
# File 'lib/confluence-client.rb', line 142

def add_group(name)
  addGroup(name)
  return { 'name' => name } if ok?
  return nil
end

#add_permission_to_space(permission, entity, space) ⇒ Object

Add permission for entity to space.

Params:

permission

‘View’ or ‘Edit’

entity

User or group name.

space

Space key.



154
155
156
 
# File 'lib/confluence-client.rb', line 154

def add_permission_to_space(permission, entity, space)
  addPermissionToSpace(permission, entity, space)      
end

#add_space(key, name, description) ⇒ Object

Create Confluence space. Return space hash or nil.

Params:

key

Key for space.

name

Name of space.

description

Description for space.



177
178
179
180
181
182
183
184
185
 
# File 'lib/confluence-client.rb', line 177

def add_space(key, name, description)
  if key =~ /^[a-zA-Z0-9]*$/
    space = addSpace( { 'key' => key, 'name' => name, 'description' => description } )
    return space if ok?
  else
    @error = 'space keys may only contain [a-zA-Z0-9]'
  end
  nil 
end

#add_user(login, name, email, password = nil) ⇒ Object

Create Confluence user. Return user hash or nil.

Params:

login

User login.

name

User name.

email

User email.

password

User password. Defaults to Time.now.to_i.to_s.



194
195
196
197
198
 
# File 'lib/confluence-client.rb', line 194

def add_user(, name, email, password = nil )
  addUser( { 'email' => email, 'fullname' => name, 'name' =>  }, password || Time.now.to_i.to_s )
  return get_user() if ok?
  nil
end

#add_user_to_group(user, group) ⇒ Object

Add user to group. Returns boolean.

Params:

user

User to add.

+group

Add user to this group.



163
164
165
166
167
168
169
 
# File 'lib/confluence-client.rb', line 163

def add_user_to_group(user, group)
  if member?(user, group)
    @error = 'already a member'
    return false
  end
  addUserToGroup(user, group)
end

#error? ⇒ Boolean

Was there an error on the last request?

Returns:

  • (Boolean) 


201
202
203
 
# File 'lib/confluence-client.rb', line 201

def error?
  !ok?
end

#get_group(name) ⇒ Object

Return Confluence group hash or nil.

Params:

name

Group name.



209
210
211
212
213
214
215
216
 
# File 'lib/confluence-client.rb', line 209

def get_group(name)
  groups = getGroups
  if ok?
    return { 'name' => name } if groups.include?(name)
    @error = 'group not found'
  end
  nil
end

#get_space(key) ⇒ Object

Return Confluence space hash or nil.

Params:

key

Fetch this space.



222
223
224
225
226
 
# File 'lib/confluence-client.rb', line 222

def get_space(key)
  space = getSpace(key)
  return space if ok?
  nil
end

#get_user(login) ⇒ Object

Return Confluence user hash or nil.

Params:

login

Fetch this user.



232
233
234
235
236
 
# File 'lib/confluence-client.rb', line 232

def get_user()
  user = getUser()
  return user if ok?
  nil
end

#login(user, password) ⇒ Object

Login to the Confluence XML/RPC API.

Raises:

  • (ArgumentError) 


239
240
241
242
243
244
245
246
247
248
249
250
251
 
# File 'lib/confluence-client.rb', line 239

def (user, password)
  raise ArgumentError if user.nil? || password.nil?
  @user, @password = user, password
  begin
    @token  = @confluence.(@user, @password)
    @error  = nil
  rescue XMLRPC::FaultException => e
    @error = tidy_exception( e.faultString )
  rescue => e
    @error = tidy_exception( e.message )
  end
  return ok?
end

#member?(user, group) ⇒ Boolean

Is user a member of this group? Returns boolean.

Params:

user

Check membership for this user.

group

Check for membership in this group.

Returns:

  • (Boolean) 


258
259
260
 
# File 'lib/confluence-client.rb', line 258

def member?(user, group)
  getUserGroups(user).include?(group)
end

#ok? ⇒ Boolean

Was the last request successful?

Returns:

  • (Boolean) 


279
280
281
 
# File 'lib/confluence-client.rb', line 279

def ok?
  @error.nil?
end

#remove_group(name, default_group = '') ⇒ Object

Remove Confluence group. Returns boolean.

Params:

name

Remove group with this name.

default_group

If specified, members of name will be added to this group. Defaults to ”.



288
289
290
 
# File 'lib/confluence-client.rb', line 288

def remove_group(name, default_group='')
  removeGroup( name, default_group )
end

#remove_permission_from_space(permission, entity, space) ⇒ Object

Remove permission for entity from space.

Params:

permission

‘View’ or ‘Edit’

entity

User or group name.

space

Space key.



298
299
300
 
# File 'lib/confluence-client.rb', line 298

def remove_permission_from_space(permission, entity, space)
  removePermissionFromSpace(permission, entity, space)      
end

#remove_space(key) ⇒ Object

Remove Confluence space. Returns boolean.

Params:

key

Confluence key for space to remove.



306
307
308
 
# File 'lib/confluence-client.rb', line 306

def remove_space(key)
  removeSpace(key)
end

#remove_user(login) ⇒ Object

Remove Confluence user. Returns boolean.

Params:

login

Remove this user.



314
315
316
 
# File 'lib/confluence-client.rb', line 314

def remove_user()
  removeUser()
end

#remove_user_from_group(user, group) ⇒ Object

Remove user from group. Returns boolean.

Params:

user

User to remove.

group

Remove user from this group.



323
324
325
326
327
328
329
 
# File 'lib/confluence-client.rb', line 323

def remove_user_from_group(user, group)
  unless member?(user, group)
    @error = 'not a member'
    return false
  end
  removeUserFromGroup(user, group)
end

#tidy_exception(txt) ⇒ Object

Make the Confluence exceptions more readable.

Params:

txt

Exception text to clean up.



335
336
337
338
 
# File 'lib/confluence-client.rb', line 335

def tidy_exception(txt)
  txt.gsub!( /^java.lang.Exception: com.atlassian.confluence.rpc.RemoteException:\s+/, '' )
  txt ||= 'unknown exception'
end