Class: Figshare::Institutions

Inherits:
Base
  • Object
show all
Defined in:
lib/institutions.rb

Overview

Figshare Institutions API

Instance Attribute Summary

Attributes inherited from Base

#api_url, #article_index_file, #auth_token, #base_dir, #hostname, #institute_id

Instance Method Summary collapse

Methods inherited from Base

#initialize

Constructor Details

This class inherits a constructor from Figshare::Base

Instance Method Details

#account {|Hash| ... } ⇒ Object

Get the institional account’s details (not a person’s account details)

Yields:

  • (Hash) —

    name: “institute”



20
21
22
 
# File 'lib/institutions.rb', line 20

def (&block)
  get(api_query: 'account/institution', &block)
end

#account_create(email:, first_name:, last_name:, group_id:, institution_user_id: nil, symplectic_user_id: nil, quota: nil, is_active: true, &block) ⇒ Object

Create new Institution Account

Parameters:

  • email (String)
  • first_name (String)
  • last_name (String)
  • group_id (Integer) —

    Figshare group ID

  • institution_user_id (string) (defaults to: nil)
  • symplectic_user_id (string) (defaults to: nil)
  • quota (Integer) (defaults to: nil) —

    Figshare user quota

  • is_active (Boolean) (defaults to: true) 


206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
 
# File 'lib/institutions.rb', line 206

def ( email:,
                    first_name:,
                    last_name:,
                    group_id:,
                    institution_user_id: nil,
                    symplectic_user_id: nil,
                    quota: nil,
                    is_active: true,
                    &block
                  )
  args = {}
  args['email'] = email unless email.nil?
  args['first_name'] = first_name unless first_name.nil?
  args['last_name'] = last_name unless last_name.nil?
  args['group_id'] = group_id unless group_id.nil?
  args['institution_user_id'] = institution_user_id unless institution_user_id.nil?
  args['symplectic_user_id'] = symplectic_user_id unless symplectic_user_id.nil?
  args['quota'] = quota unless quota.nil?
  args['is_active'] = is_active unless is_active.nil?
  post(api_query: 'account/institution/accounts', args: args, &block)
end

#account_embargo_options {|Array| ... } ⇒ Object

Get the institional account embargo options (IP Ranges)

Yields:

  • (Array) —

    list of embargo ip ranges [ type: ip_range, ip_name: Figshare_IP_Range ]



27
28
29
 
# File 'lib/institutions.rb', line 27

def (&block)
  get(api_query: 'account/institution/embargo_options', &block)
end

#account_search(search_for: nil, is_active: nil, institution_user_id: nil, email: nil, page: nil, page_size: nil, offset: nil, limit: nil) {|Hash| ... } ⇒ Object

Get the accounts for which the account has administrative privileges (assigned and inherited).

Parameters:

  • is_active (Boolean) (defaults to: nil) —

    user account is active

  • institution_user_id (String) (defaults to: nil) —

    As set in the HR upload

  • email (String) (defaults to: nil) —

    as set in the HR upload

  • page (Numeric) (defaults to: nil) —

    Pages start at 1. Page and Page size go together

  • page_size (Numeric) (defaults to: nil)
  • offset (Numeric) (defaults to: nil) —

    offset is 0 based. Offset and Limit go together

  • limit (Numeric) (defaults to: nil)

Yields:

  • (Hash) —

    first_name, last_name, institution_id, email, active, institution_user_id, quota, used_quota, user_id, orcid_id



298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/institutions.rb', line 298

def ( search_for: nil,
                    is_active: nil,
                    institution_user_id: nil,
                    email: nil,
                    page: nil,
                    page_size: nil,
                    offset: nil,
                    limit: nil,
                    &block
                  )
  args = {}
  args['search_for'] = search_for unless search_for.nil?
  args['is_active'] = is_active unless is_active.nil?
  args['institution_user_id'] = institution_user_id unless institution_user_id.nil?
  args['email'] = email unless email.nil?
  args['page'] = page unless page.nil?
  args['page_size'] = page_size unless page_size.nil?
  args['offset'] = offset unless offset.nil?
  args['limit'] = limit unless limit.nil?
  post_paginate(api_query: 'account/institution/accounts/search', args: args, &block)
end

#account_update(account_id:, email: nil, first_name: nil, last_name: nil, group_id: nil, institution_user_id: nil, symplectic_user_id: nil, quota: nil, is_active: true, &block) ⇒ Object

Update Institution Account

Parameters:

  • account_id (Integer) —

    Whose account

  • email (String) (defaults to: nil)
  • first_name (String) (defaults to: nil)
  • last_name (String) (defaults to: nil)
  • group_id (Integer) (defaults to: nil) —

    Figshare group ID

  • institution_user_id (string) (defaults to: nil)
  • symplectic_user_id (string) (defaults to: nil)
  • quota (Integer) (defaults to: nil) —

    Figshare user quota

  • is_active (Boolean) (defaults to: true) 


239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/institutions.rb', line 239

def ( account_id:,
                    email: nil,
                    first_name: nil,
                    last_name: nil,
                    group_id: nil,
                    institution_user_id: nil,
                    symplectic_user_id: nil,
                    quota: nil,
                    is_active: true,
                    &block
                  )
  args = {}
  args['email'] = email unless email.nil?
  args['first_name'] = first_name unless first_name.nil?
  args['last_name'] = last_name unless last_name.nil?
  args['group_id'] = group_id unless group_id.nil?
  args['institution_user_id'] = institution_user_id unless institution_user_id.nil?
  args['symplectic_user_id'] = symplectic_user_id unless symplectic_user_id.nil?
  args['quota'] = quota unless quota.nil?
  args['is_active'] = is_active unless is_active.nil?
  put(api_query: "account/institution/accounts/#{}", args: args, &block)
end

#accounts(is_active: nil, institution_user_id: nil, email: nil, id_lte: nil, id_gte: nil, page: nil, page_size: nil, offset: nil, limit: nil, cursor_pagination: true) {|Array| ... } ⇒ Object

Get the accounts for which the account has administrative privileges (assigned and inherited). Accounts are returned in account id order, and there is a 9000 user upper limit. See id_gte.

Parameters:

  • is_active (Boolean) (defaults to: nil) —

    user account is active

  • institution_user_id (String) (defaults to: nil) —

    As set in the HR upload

  • email (String) (defaults to: nil) —

    as set in the HR upload

  • id_lte (Integer) (defaults to: nil) —

    ID is <= Introduced to get around the buffer limit of 9000 users

  • id_gte (Integer) (defaults to: nil) —

    ID is >= Introduced to get around the buffer limit of 9000 users

  • page (Numeric) (defaults to: nil) —

    Pages start at 1. Page and Page size go together

  • page_size (Numeric) (defaults to: nil)
  • offset (Numeric) (defaults to: nil) —

    offset is 0 based. Offset and Limit go together

  • limit (Numeric) (defaults to: nil)

Yields:

  • (Array) —

    [{ id:, first_name:, last_name:, institution_id:, email:, active:, institution_user_id:, quota:, used_quota:, user_id:, orcid_id: }]



152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
 
# File 'lib/institutions.rb', line 152

def accounts( is_active: nil,
              institution_user_id: nil,
              email: nil,
              id_lte: nil,
              id_gte: nil,
              page: nil,
              page_size: nil,
              offset: nil,
              limit: nil,
              cursor_pagination: true,
              &block
            )
  args = {}
  args['is_active'] = is_active unless is_active.nil?
  args['institution_user_id'] = institution_user_id unless institution_user_id.nil?
  args['email'] = email unless email.nil?
  args['id_lte'] = id_lte unless id_lte.nil?
  args['id_gte'] = id_gte unless id_gte.nil?
  args['page'] = page unless page.nil?
  args['page_size'] = page_size unless page_size.nil?
  args['offset'] = offset unless offset.nil?
  args['limit'] = limit unless limit.nil?
  if cursor_pagination
    highest_id_gte = 0
    args['id_lte'] = nil
    args['page_size'] = 100
    loop do
      count = 0
      args['page'] = 1
      args['id_gte'] = highest_id_gte + 1
      get_paginate(api_query: 'account/institution/accounts', args: args, once_only: true) do ||
        next if .nil? || ['id'].nil?

        count += 1
        highest_id_gte = ['id'].to_i if highest_id_gte < ['id'].to_i
        yield 
      end
      break if count < 100 # Didn't reach the page_size limit.
    end
  else # Do it the old broken way (Pagination only works for the first 9000 entries)
    get_paginate(api_query: 'account/institution/accounts', args: args, &block)
  end
end

#articles_filter_by(resource_id: nil, filename: nil) {|Hash| ... } ⇒ Object

Requests an institute file

Parameters:

  • resource_id (Integer) (defaults to: nil) —

    Figshare resource_id (publisher ID?)

  • filename (String) (defaults to: nil) —

    Figshare file name

Yields:

  • (Hash) —

    title, doi, handle, group_id, url, url_public_html, url_public_api, url_private_htm, url_private_api, published_date, timeline {…, thumb, defined_type, defined_name }



80
81
82
83
84
85
 
# File 'lib/institutions.rb', line 80

def articles_filter_by(resource_id: nil, filename: nil, &block )
  args = {}
  args['resource_id'] = resource_id unless resource_id.nil?
  args['filename'] = filename unless filename.nil?
  get(api_query: "institutions/#{@institute_id}/articles/filter-by", args: args, &block)
end

#categories {|Array| ... } ⇒ Object

Get institution categories (including parent Categories)

Yields:

  • (Array) —

    [ { parent_id: 1, id: 11, title: “Anatomy”, path:”/450/1024/6532”, source_id: “300204”, taxonomy_id: 4 } ]



113
114
115
 
# File 'lib/institutions.rb', line 113

def categories(&block)
  get(api_query: 'account/categories', &block)
end

#curation_review(group_id: nil, article_id: nil, status: nil, offset: nil, limit: nil) {|Hash| ... } ⇒ Object

Get a list of curation reviews for this institution

Parameters:

  • group_id (Integer) (defaults to: nil) —

    Figshare group ID

  • article_id (Integer) (defaults to: nil) —

    Figshare article ID

  • status (String) (defaults to: nil) —

    One of: pending, approved, rejected, closed

  • offset (Numeric) (defaults to: nil) —

    offset is 0 based. Offset and Limit go together

  • limit (Numeric) (defaults to: nil)

Yields:

  • (Hash) —

    {id, group_id, account_id, assigned_to, article_id, version, comment_count, status, created_date. modified_date }



336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/institutions.rb', line 336

def curation_review(  group_id: nil,
                      article_id: nil,
                      status: nil,
                      offset: nil,
                      limit: nil,
                      &block
                   )
  args = {}
  args['group_id'] = group_id unless group_id.nil?
  args['article_id'] = article_id unless article_id.nil?
  args['status'] = status unless status.nil?
  args['offset'] = offset unless offset.nil?
  args['limit'] = limit unless limit.nil?
  # Odd one, as has offset,limit not page,page_size
  get_paginate(api_query: 'account/institution/reviews', args: args, by_offset: true, &block)
end

#curation_review_comments(curation_id:, offset: nil, limit: nil) {|Hash| ... } ⇒ Object

Get a certain curation review’s comments.

Parameters:

  • curation_id (Integer) —

    Figshare curation ID

  • offset (Numeric) (defaults to: nil) —

    offset is 0 based. Offset and Limit go together

  • limit (Numeric) (defaults to: nil)

Yields:

  • (Hash) —

    { id, account_id, type, text}



367
368
369
370
371
372
373
 
# File 'lib/institutions.rb', line 367

def curation_review_comments(curation_id:, offset: nil, limit: nil, &block)
  # Odd one, as has offset,limit not page,page_size.
  args = {}
  args['offset'] = offset unless offset.nil?
  args['limit'] = limit unless limit.nil?
  get_paginate(api_query: "account/institution/review/#{curation_id}/comments", args: args, by_offset: true, &block)
end

#curation_review_comments_update(curation_id:, comment:, &block) ⇒ Object

Add a new comment to the review.

Parameters:

  • curation_id (Integer) —

    Figshare curation ID

  • comment (String) —

    Comment text



379
380
381
 
# File 'lib/institutions.rb', line 379

def curation_review_comments_update(curation_id:, comment:, &block)
  post(api_query: "account/institution/review/#{curation_id}/comments", args: { 'text' => comment }, &block)
end

#curation_review_detail(curation_id:) {|Hash| ... } ⇒ Object

Get a curation review record

Parameters:

  • curation_id (Integer) —

    Figshare curation ID

Yields:

  • (Hash) —

    see Figshare API docs for response sample



357
358
359
 
# File 'lib/institutions.rb', line 357

def curation_review_detail(curation_id:, &block)
  get(api_query: "account/institution/review/#{curation_id}",  &block)
end

#group_custom_fields(group_id: nil) {|Array| ... } ⇒ Object

Get an institute group’s custom fields

Parameters:

  • group_id (Integer) (defaults to: nil) —

    Figshare group_id

Yields:

  • (Array) —

    [ {id:, name: field_name, field_type: text } ]



91
92
93
94
95
 
# File 'lib/institutions.rb', line 91

def group_custom_fields(group_id: nil, &block )
  args = {}
  args['group_id'] = group_id unless group_id.nil?
  get(api_query: 'account/institution/custom_fields', args: args, &block)
end

#group_embargo_options(group_id:) {|Array| ... } ⇒ Object

Get the institional account group’s embargo options (IP Ranges)

Parameters:

  • group_id (Integer)

Yields:

  • (Array) —

    list of embargo ip ranges [ type: ip_range, ip_name: Figshare_IP_Range ]



128
129
130
 
# File 'lib/institutions.rb', line 128

def group_embargo_options(group_id:, &block)
  get(api_query: "account/institution/groups/#{group_id}/embargo_options", &block)
end

#group_role_delete(account_id:, role_id:, group_id:, &block) ⇒ Object

Delete Institution Account Group Role

Parameters:

  • account_id (Integer) —

    Figshare user account id

  • role_id (Integer) —

    Figshare role id

  • group_id (Integer) —

    Figshare group id



283
284
285
286
 
# File 'lib/institutions.rb', line 283

def group_role_delete( account_id:, role_id:, group_id:, &block)
  args = {}
  delete(api_query: "account/institution/roles/#{}/#{group_id}/#{role_id}", args: args, &block)
end

#group_roles(account_id:) {|Hash| ... } ⇒ Object

Get institution Account Group Roles for an account

Parameters:

  • account_id (Integer) —

    Figshare user account id

Yields:

  • (Hash) —

    { role_id [ { category, id, name }, … ], … }



266
267
268
 
# File 'lib/institutions.rb', line 266

def group_roles(account_id:, &block)
  get(api_query: "account/institution/roles/#{}", &block)
end

#group_roles_add(account_id:, body:, &block) ⇒ Object

Add Institution Account Group Roles

Parameters:

  • account_id (Integer) —

    Figshare user account id

  • body (Hash) —

    see figshare api cryptic docs { “2”: [ 2, 7], “3”: [7,9] }. Array of roles, per group



274
275
276
 
# File 'lib/institutions.rb', line 274

def group_roles_add(account_id:, body:, &block)
  post(api_query: "account/institution/roles/#{}", args: body, &block)
end

#group_set_custom_fields(custom_field_id:, filename:) {|Hash| ... } ⇒ Object

Set institute group’s custom fields, from a CSV file

Parameters:

  • custom_field_id (Integer) —

    Figshare group_id

  • filename (Integer) —

    Figshare group_id

Yields:

  • (Hash) —

    {code: 200, message: ok } ]



102
103
104
105
106
107
108
 
# File 'lib/institutions.rb', line 102

def group_set_custom_fields(custom_field_id:, filename: )
  File.open(filename, 'rb') do |fin|
    custom_fields_csv = fin.read
    args = { 'name' => 'external_file', 'filename' => filename }
    post(api_query: "account/institution/custom_fields/#{custom_field_id}/items/upload", args: args, data: custom_fields_csv, content_type: 'multipart/form-data', &block)
  end
end

#groups {|Array| ... } ⇒ Object

Get the groups for which the account has administrative privileges (assigned and inherited).

Yields:

  • (Array) —

    [ { id: 1, name: “Materials”, resource_id: “string”, parent_id: 0, association_criteria: “IT” } ]



120
121
122
 
# File 'lib/institutions.rb', line 120

def groups(&block)
  get(api_query: 'account/groups', &block)
end

#hr_upload(hr_xml_filename:) {|Hash| ... } ⇒ Object

Upload hr file

Parameters:

  • hr_xml_filename (String) —

    Filename. See https://docs.figshare.com/#hr_feed_hr_feed_private_endpoint

Yields:

  • (Hash) —

    { message:, data: null, errcode:}



9
10
11
12
13
14
15
 
# File 'lib/institutions.rb', line 9

def hr_upload(hr_xml_filename:, &block)
  File.open(@file_name, 'rb') do |fin|
    hr_xml = fin.read
    args = { 'name' => 'hrfeed', 'filename' => hr_xml_filename }
    post(api_query: 'institution/hrfeed/upload', args: args, data: hr_xml, content_type: 'multipart/form-data', &block)
  end
end

#private_articles(status: nil, published_since: nil, modified_since: nil, item_type: nil, resource_doi: nil, order: 'published_date', order_direction: 'desc', page: nil, page_size: nil, offset: nil, limit: nil) {|Hash| ... } ⇒ Object

Requests a list of private institute articles

Parameters:

  • status (Integer) (defaults to: nil) —

    Only return items with this status

  • published_since (Time) (defaults to: nil) —

    Return results if published after this time

  • modified_since (Time) (defaults to: nil) —

    Return results if modified after this time

  • resource_doi (String) (defaults to: nil) —

    Matches this resource doi

  • item_type (String) (defaults to: nil) —

    Matches this item_type. See Figshare API docs for list (https://docs.figshare.com/#articles_list)

  • order (String) (defaults to: 'published_date') —

    “published_date” Default, “modified_date”, “views”, “cites”, “shares”

  • order_direction (String) (defaults to: 'desc') —

    “desc” Default, “asc”

  • page (Numeric) (defaults to: nil) —

    Pages start at 1. Page and Page size go together

  • page_size (Numeric) (defaults to: nil)
  • offset (Numeric) (defaults to: nil) —

    offset is 0 based. Offset and Limit go together

  • limit (Numeric) (defaults to: nil)

Yields:

  • (Hash) —

    title, doi, handle, group_id, url, url_public_html, url_public_api, url_private_htm, url_private_api, published_date, timeline {…, thumb, defined_type, defined_name }



46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
 
# File 'lib/institutions.rb', line 46

def private_articles( status: nil,
                      published_since: nil,
                      modified_since: nil,
                      item_type: nil,
                      resource_doi: nil,
                      order: 'published_date',
                      order_direction: 'desc',
                      page: nil,
                      page_size: nil,
                      offset: nil,
                      limit: nil,
                      &block
                    )
  args = {}
  args['status'] = status unless status.nil?
  args['item_type'] = item_type unless item_type.nil?
  args['resource_doi'] = resource_doi unless resource_doi.nil?
  args['published_since'] = published_since unless published_since.nil?
  args['modified_since'] = modified_since unless modified_since.nil?
  args['order'] = order unless order.nil?
  args['order_direction'] = order_direction unless order_direction.nil?
  args['page'] = page unless page.nil?
  args['page_size'] = page_size unless page_size.nil?
  args['offset'] = offset unless offset.nil?
  args['limit'] = limit unless limit.nil?
  get_paginate(api_query: 'account/institution/articles', args: args, &block)
end

#roles {|Array| ... } ⇒ Object

Get the roles available for groups and the institution group.

Yields:

  • (Array) —

    [ { id:, name:, category:, description: } ]



135
136
137
 
# File 'lib/institutions.rb', line 135

def roles(&block)
  get(api_query: 'account/roles', &block)
end

#user(account_id:) {|Hash| ... } ⇒ Object

Get institution user information using the account_id

Parameters:

  • account_id (Integer) —

    Figshare user account id

Yields:

  • (Hash) —

    { id, first_name, last_name, name, is_active, url_name, is_public, job_title, orcid_id }



324
325
326
 
# File 'lib/institutions.rb', line 324

def user(account_id:, &block)
  get(api_query: "account/institution/users/#{}", &block)
end