your_membership 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,85 @@
1
+ module YourMembership
2
+ # The Profile object provides a convenient abstraction that encapsulates a person's profile allowing clear and concise
3
+ # access to both the core fields provided by YourMembership and the custom fields added by site administrators
4
+ #
5
+ # A new profile for a new person should be instantiated through the create_new method
6
+ #
7
+ # A profile can be loaded by passing a hash directly to the initializer (Profile.new) method this can be useful in
8
+ # creating a profile object from an API response
9
+ #
10
+ # A profile can be created empty or by passing a hash for standard and/or custom fields. This is useful for
11
+ # updating an existing profile without changing unnecessary records.
12
+ #
13
+ # @attr_reader [Hash] data These are fields that are part of the core YourMembership profile implementation
14
+ # @attr_reader [Hash] custom_data These are fields that are the ones added as Custom Fields to a YourMembership
15
+ # Community
16
+ class Profile
17
+ attr_accessor :data, :custom_data
18
+
19
+ # @param [Hash] options Initial Values for the profile.
20
+ def initialize(options = {})
21
+ @data = {}
22
+ @custom_data = {}
23
+
24
+ options.each do |k, v|
25
+ if k == 'CustomFieldResponses'
26
+ @custom_data = parse_custom_field_responses(v)
27
+ else
28
+ @data[k] = v
29
+ end
30
+ end
31
+ end
32
+
33
+ # Returns the full contents of the profile in a Hash without items that have a Nil value
34
+ # @return [Hash]
35
+ def to_h
36
+ temp_data = clean @data
37
+ temp_custom_data = clean @custom_data
38
+ temp_data['CustomFieldResponses'] = temp_custom_data
39
+ temp_data
40
+ end
41
+
42
+ # @param [String] last_name
43
+ # @param [String] member_type_code
44
+ # @param [String] email
45
+ # @param [String] username
46
+ # @param [String] password
47
+ # @param [Hash] options
48
+ # @return [YourMembership::Profile] Builds a new profile with required and optional fields
49
+ # @note: It has been found that for some users you must also specify a 'Membership' field as well as the
50
+ # 'MemberTypeCode' The official documentation does not say this field is required but many times the user
51
+ # cannot log in if no membership is provided. This means that the system cannot masquerade as this user until a
52
+ # membership is specified.
53
+ def self.create_new(first_name, last_name, member_type_code, email, username, password, options = {})
54
+ options['FirstName'] = first_name
55
+ options['LastName'] = last_name
56
+ options['MemberTypeCode'] = member_type_code
57
+ options['EmailAddr'] = email
58
+ options['Username'] = username
59
+ options['Password'] = password
60
+ new(options)
61
+ end
62
+
63
+ private
64
+
65
+ # @param [Hash] custom_fields The 'CustomFieldResponses' Hash
66
+ # @return [Hash] Single dimension hash containing keys and values as strings or arrays
67
+ def parse_custom_field_responses(custom_fields)
68
+ output_hash = {}
69
+ custom_fields['CustomFieldResponse'].each do |field|
70
+ output_hash[field['FieldCode']] = field['Values']['Value'] if field['Values']
71
+ end
72
+ output_hash
73
+ end
74
+
75
+ # Removes nil values
76
+ def clean(data_hash)
77
+ clean_hash = {}
78
+ # Remove Nils
79
+ data_hash.each do |k, v|
80
+ clean_hash[k] = v if v
81
+ end
82
+ clean_hash
83
+ end
84
+ end
85
+ end
@@ -0,0 +1,6 @@
1
+ module YourMembership
2
+ # The SA Namespace encapsulates System Administrator functions of the API. These functions are a special case that
3
+ # do not usually require a session or user scope.
4
+ module Sa
5
+ end
6
+ end
@@ -0,0 +1,34 @@
1
+ module YourMembership
2
+ module Sa
3
+ # YourMembership System Administrator Member Authentication
4
+ class Auth < YourMembership::Base
5
+ # Authenticates a member's username and password and binds them to the current API session.
6
+ #
7
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Auth_Authenticate.htm
8
+ #
9
+ # @param [YourMembership::Session] session
10
+ # @param [String] user_name The Username of the user the session should be bound to.
11
+ # @param [String] password The Password (Optional) pf the specified user.
12
+ # @param [String] password_hash The Password Hash for the specified user which allows the system to perform
13
+ # actions on behalf of a user as if they were signed in without knowing the user's cleartext password.
14
+ # @return [YourMembership::Member] Returns a Member object for the authenticated session.
15
+ def self.authenticate(session, user_name, password = nil, password_hash = nil)
16
+ options = {}
17
+ options[:Username] = user_name
18
+ options[:Password] = password if password
19
+ options[:PasswordHash] = password_hash if password_hash
20
+
21
+ response = post('/', :body => build_XML_request('Sa.Auth.Authenticate', session, options))
22
+
23
+ response_valid? response
24
+ if response['YourMembership_Response']['Sa.Auth.Authenticate']
25
+ session.get_authenticated_user
26
+ else
27
+ return false
28
+ end
29
+
30
+ YourMembership::Member.create_from_session(session)
31
+ end
32
+ end
33
+ end
34
+ end
@@ -0,0 +1,22 @@
1
+ module YourMembership
2
+ module Sa
3
+ # YourMembership System Administrator Certifications Namespace
4
+ class Certifications < YourMembership::Base
5
+ # Return a list of all certification records for the community.
6
+ #
7
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Certifications_All_Get.htm
8
+ #
9
+ # @param [Boolean] is_active Include active certification records in the returned result. Default: True
10
+ # @return [Array] Returns an Array of Hashes representing Certification Records
11
+ def self.all_get(is_active = true)
12
+ options = {}
13
+ options[:IsActive] = is_active
14
+
15
+ response = post('/', :body => build_XML_request('Sa.Certifications.All.Get', nil, options))
16
+
17
+ response_valid? response
18
+ response_to_array_of_hashes response['YourMembership_Response']['Sa.Certifications.All.Get'], ['Certification']
19
+ end
20
+ end
21
+ end
22
+ end
@@ -0,0 +1,22 @@
1
+ module YourMembership
2
+ module Sa
3
+ # YourMembership System Administrator Commerce Namespace
4
+ class Commerce < YourMembership::Base
5
+ # Returns the order details, including line items and products ordered, of a store order.
6
+ #
7
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Commerce_Store_Order_Get.htm
8
+ #
9
+ # @param [String] invoice_id The Invoice ID of the store order to be returned.
10
+ # @return [Hash] Returns a Hash representing a store order
11
+ def self.store_order_get(invoice_id)
12
+ options = {}
13
+ options[:InvoiceID] = invoice_id
14
+
15
+ response = post('/', :body => build_XML_request('Sa.Commerce.Store.Order.Get', nil, options))
16
+
17
+ response_valid? response
18
+ response['YourMembership_Response']['Sa.Commerce.Store.Order.Get']
19
+ end
20
+ end
21
+ end
22
+ end
@@ -0,0 +1,66 @@
1
+ module YourMembership
2
+ module Sa
3
+ # YourMembership System Administrator Events Namespace
4
+ class Events < YourMembership::Base
5
+ # Returns a list of Events for the community optionally filtered by date or event name.
6
+ #
7
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Events_All_GetIDs.htm
8
+ #
9
+ # @param [Hash] options
10
+ # @option options [DateTime] :StartDate Starting date to filter the Event Start Date.
11
+ # @option options [DateTime] :EndDate Ending date to filter the Event Start Date.
12
+ # @option options [String] :Name Filter the returned events by Event Name.
13
+ # @return [Array] Returns an Array of Event IDs
14
+ def self.all_getIDs(options = {}) # rubocop:disable Style/MethodName
15
+ response = post('/', :body => build_XML_request('Sa.Events.All.GetIDs', nil, options))
16
+
17
+ response_valid? response
18
+ if response['YourMembership_Response']['Sa.Events.All.GetIDs']
19
+ response['YourMembership_Response']['Sa.Events.All.GetIDs']['EventID']
20
+ else
21
+ return[]
22
+ end
23
+ end
24
+
25
+ # Returns Event Registration details for the provided Event and Event Registration ID. If the Event Registration
26
+ # contains a related Custom Form, the form data will be included in the <DataSet> element as it is stored in our
27
+ # database.
28
+ #
29
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Events_Event_Registration_Get.htm
30
+ #
31
+ # @param [Integer] event_id The ID number for the Event from which you wish to retrieve the Event Registration.
32
+ # @param [Hash] options Either RegistrationID or Badge Number are required.
33
+ # @option options [String] :RegistrationID RegistrationID of the Registration data to return.
34
+ # @option options [Integer] :BadgeNumber The Badge Number / Registration Number for an Event Registration record.
35
+ # @return [Hash] Returns a Hash representing an event registration
36
+ def self.event_registration_get(event_id, options = {})
37
+ options[:EventID] = event_id
38
+
39
+ response = post('/', :body => build_XML_request('Sa.Events.Event.Registration.Get', nil, options))
40
+
41
+ response_valid? response
42
+ response['YourMembership_Response']['Sa.Events.Event.Registration.Get']
43
+ end
44
+
45
+ # Returns a list of Registration IDs for the specified Event ID.
46
+ #
47
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Events_Event_Registrations_GetIDs.htm
48
+ #
49
+ # @param [Integer] event_id The ID number for the Event from which you wish to retrieve the Event Registration.
50
+ # @return [Array] Returns an Array of registration IDs for a specific event.
51
+ def self.event_registrations_getIDs(event_id) # rubocop:disable Style/MethodName
52
+ options = {}
53
+ options[:EventID] = event_id
54
+
55
+ response = post('/', :body => build_XML_request('Sa.Events.Event.Registrations.GetIDs', nil, options))
56
+
57
+ response_valid? response
58
+ if response['YourMembership_Response']['Sa.Events.Event.Registrations.GetIDs']
59
+ response['YourMembership_Response']['Sa.Events.Event.Registrations.GetIDs']['RegistrationID']
60
+ else
61
+ return []
62
+ end
63
+ end
64
+ end
65
+ end
66
+ end
@@ -0,0 +1,195 @@
1
+ module YourMembership
2
+ module Sa
3
+ # The Export object provides a convenient abstraction that encapsulates the export process
4
+ #
5
+ # @attr_reader [String] export_id The unique ID assigned by the API when an export is initiated
6
+ # @attr_reader [Symbol] status The status of the current export request
7
+ # @attr_reader [String] export_uri The uri from which to download the requested report once the status is :complete
8
+ class Export < YourMembership::Base
9
+ attr_reader :export_id, :status, :export_uri
10
+
11
+ # Export Initializer - Use any of the public class methods to create objects of this type.
12
+ #
13
+ # @note There is not yet a compelling reason to call Export.new() directly, however it can be done.
14
+ #
15
+ # @param [String] export_id The ID of the export job for which to create the object.
16
+ def initialize(export_id)
17
+ @export_id = export_id
18
+ @status = nil
19
+ @export_uri = nil
20
+ end
21
+
22
+ # Instance implementation of the Sa::Export.status method that also sets the export_uri if the status is :complete
23
+ # @return [Symbol] Returns the symbol for the current status state.
24
+ def status
25
+ unless @status == :complete || @status == :error || @status == :failure
26
+ status_response = self.class.status(@export_id)
27
+ @status = convert_status(status_response['Status'])
28
+ update_export_uri(status_response) if @status == :complete
29
+ end
30
+ @status
31
+ end
32
+
33
+ # Returns the status of an export by ExportID. This method should be called until a status of either
34
+ # FAILURE or COMPLETE is returned.
35
+ #
36
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Status.htm
37
+ #
38
+ # @param [String] export_id ID of the Export on which to check status.
39
+ # @return [Hash] Returns a hash with the status code for the current export as well as the URI of the exported
40
+ # data if available
41
+ def self.status(export_id)
42
+ options = {}
43
+ options[:ExportID] = export_id
44
+
45
+ response = post('/', :body => build_XML_request('Sa.Export.Status', nil, options))
46
+
47
+ response_valid? response
48
+ response['YourMembership_Response']['Sa.Export.Status']
49
+ end
50
+
51
+ # Starts an export of all invoice items.
52
+ #
53
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_All_InvoiceItems.htm
54
+ #
55
+ # @param [DateTime] date Date to export records from.
56
+ # @param [Boolean] unicode Export format.
57
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
58
+ def self.all_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
59
+ generic_export('Sa.Export.All.InvoiceItems', date, unicode)
60
+ end
61
+
62
+ # Starts an export of career openings.
63
+ #
64
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Career_Openings.htm
65
+ #
66
+ # @param [DateTime] date Date to export records from.
67
+ # @param [Boolean] unicode Export format.
68
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
69
+ def self.career_openings(date, unicode)
70
+ generic_export('Sa.Export.Career.Openings', date, unicode)
71
+ end
72
+
73
+ # Starts an export of donation transactions.
74
+ #
75
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Donations_Transactions.htm
76
+ #
77
+ # @param [DateTime] date Date to export records from.
78
+ # @param [Boolean] unicode Export format.
79
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
80
+ def self.donations_transactions(date, unicode)
81
+ generic_export('Sa.Export.Donations.Transactions', date, unicode)
82
+ end
83
+
84
+ # Starts an export of donation invoice items.
85
+ #
86
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Donations_InvoiceItems.htm
87
+ #
88
+ # @param [DateTime] date Date to export records from.
89
+ # @param [Boolean] unicode Export format.
90
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
91
+ def self.donations_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
92
+ generic_export('Sa.Export.Donations.InvoiceItems', date, unicode)
93
+ end
94
+
95
+ # Starts an export of dues transactions.
96
+ #
97
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Dues_Transactions.htm
98
+ #
99
+ # @param [DateTime] date Date to export records from.
100
+ # @param [Boolean] unicode Export format.
101
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
102
+ def self.dues_transactions(date, unicode)
103
+ generic_export('Sa.Export.Dues.Transactions', date, unicode)
104
+ end
105
+
106
+ # Starts an export of dues invoice items.
107
+ #
108
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Dues_InvoiceItems.htm
109
+ #
110
+ # @param [DateTime] date Date to export records from.
111
+ # @param [Boolean] unicode Export format.
112
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
113
+ def self.dues_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
114
+ generic_export('Sa.Export.Dues.InvoiceItems', date, unicode)
115
+ end
116
+
117
+ # Starts an export of store orders.
118
+ #
119
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Store_Orders.htm
120
+ #
121
+ # @param [DateTime] date Date to export records from.
122
+ # @param [Boolean] unicode Export format.
123
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
124
+ def self.store_orders(date, unicode)
125
+ generic_export('Sa.Export.Store.Orders', date, unicode)
126
+ end
127
+
128
+ # Starts an export of store order invoice items.
129
+ #
130
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Store_InvoiceItems.htm
131
+ #
132
+ # @param [DateTime] date Date to export records from.
133
+ # @param [Boolean] unicode Export format.
134
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
135
+ def self.store_invoiceItems(date, unicode) # rubocop:disable Style/MethodName
136
+ generic_export('Sa.Export.Store.InvoiceItems', date, unicode)
137
+ end
138
+
139
+ # Starts an export of registration records for an event
140
+ #
141
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Event_Registrations.htm
142
+ #
143
+ # @param [Integer] event_id Event ID of the event to view registrations.
144
+ # @param [Boolean] unicode Export format.
145
+ # @param [Hash] options
146
+ # @option options [String] :SessionIDs Comma Delimited List of Session IDs to filter the results. ex: "1234,9876"
147
+ # @option options [Integer] :ProductID Filter the results to only those that have purchased supplied Product ID.
148
+ # @option options [Integer] :Processed Filter the results by their Process Status.
149
+ # Options: 0 = All, 1 = Open Records, 2 = Processed Records
150
+ # @option options [String] :LastName Filter registrations by the supplied Last Name.
151
+ # @option options [Boolean] :AttendedEvent Filter registrations check in status.
152
+ # @return [YourMembership::Sa::Export] Returns an Export object that can be queried for status and the export data
153
+ def self.event_registrations(event_id, unicode, options = {}) # rubocop:disable Style/MethodName
154
+ options[:EventID] = event_id
155
+ generic_export('Sa.Export.Event.Registrations', nil, unicode, options)
156
+ end
157
+
158
+ private
159
+
160
+ def self.generic_export(api_method, date, unicode, options = {})
161
+ options[:Unicode] = unicode
162
+ options[:Date] = date
163
+
164
+ response = post('/', :body => build_XML_request(api_method, nil, options))
165
+ response_valid? response
166
+ new(response['YourMembership_Response'][api_method]['ExportID'])
167
+ end
168
+
169
+ def update_export_uri(status_response)
170
+ @export_uri = status_response['ExportURI']
171
+ end
172
+
173
+ # Convert YourMembership API codes to readable symbols
174
+ #
175
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Export_Status.htm
176
+ #
177
+ # @param [Integer] status The status code
178
+ # @return [Symbol] The status as a Symbol
179
+ def convert_status(status)
180
+ case status
181
+ when '-1'
182
+ return :failure
183
+ when '0'
184
+ return :unknown
185
+ when '1'
186
+ return :working
187
+ when '2'
188
+ return :complete
189
+ else
190
+ return :error
191
+ end
192
+ end
193
+ end
194
+ end
195
+ end
@@ -0,0 +1,30 @@
1
+ module YourMembership
2
+ module Sa
3
+ # YourMembership System Administrator Groups Namespace
4
+ class Groups < YourMembership::Base
5
+ # Returns a list of group membership log entries by Group ID that may be optionally filtered by timestamp.
6
+ # This method will return a maximum of 1,000 results.
7
+ #
8
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Groups_Group_GetMembershipLog.htm
9
+ #
10
+ # @param [Integer] group_id The Group ID of the Membership Log records to be returned.
11
+ # @param [Hash] options
12
+ # @option options [DateTime] :StartDate Filter the returned results by date/time. Only those membership log items which
13
+ # have been created or updated after the supplied date/time will be returned.
14
+ # @option options [Integer] :ItemID Filter the returned results by sequential ItemID. Only those membership log items
15
+ # which have a ItemID greater than the supplied integer will be returned. A typical usage scenario for this
16
+ # parameter would be to supply it when making additional calls while 1,000 records are being returned. You would
17
+ # supply the last record's ItemID to retrieve the next batch of up to 1,000 records, repeating the process until
18
+ # no records are returned.
19
+ # @return [Hash] Returns an Hash representing a group's membership Log
20
+ def self.group_getMembershipLog(group_id, options = {}) # rubocop:disable Style/MethodName
21
+ options[:GroupID] = group_id
22
+
23
+ response = post('/', :body => build_XML_request('Sa.Groups.Group.GetMembershipLog', nil, options))
24
+
25
+ response_valid? response
26
+ response['YourMembership_Response']['Sa.Groups.Group.GetMembershipLog']
27
+ end
28
+ end
29
+ end
30
+ end
@@ -0,0 +1,49 @@
1
+ module YourMembership
2
+ module Sa
3
+ # YourMembership System Administrator Member Namespace
4
+ class Member < YourMembership::Base
5
+ # Returns a list of Certifications for the specified user.
6
+ #
7
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Member_Certifications_Get.htm
8
+ #
9
+ # @param [Integer] member_id ID of the person whose certifications to return.
10
+ # @param [Hash] options
11
+ # @option options [Boolean] :IsArchived Include archived certification records in the returned result. Def: True
12
+ # @return [Array] Returns an array of Hashes representing a member's certifications
13
+ def self.certifications_get(member_id, options = {})
14
+ options[:ID] = member_id
15
+
16
+ response = post('/', :body => build_XML_request('Sa.Member.Certifications.Get', nil, options))
17
+
18
+ response_valid? response
19
+ response_to_array_of_hashes response['YourMembership_Response']['Sa.Member.Certifications.Get'], ['Certification']
20
+ end
21
+
22
+ # Returns a list of Certification Journal Entries for the specified user that may be optionally filtered by
23
+ # date, expiration, and paging.
24
+ #
25
+ # @see https://api.yourmembership.com/reference/2_00/Sa_Member_Certifications_Journal_Get.htm
26
+ #
27
+ # @param [Integer] member_id ID of the person whose certifications to return.
28
+ # @param [Hash] options
29
+ # @option options [Boolean] :ShowExpired Include expired journal entries in the returned result.
30
+ # @option options [DateTime] :StartDate Only include Journal Entries that are newer that the supplied date.
31
+ # @option options [Integer] :EntryID Filter the returned results by sequential EntryID. Only those Certification
32
+ # Journals which have an EntryID greater than the supplied integer will be returned.
33
+ # @option options [String] :CertificationID Filter the Journal Entries returned by the specified Certification ID.
34
+ # @option options [Integer] :PageSize The number of items that are returned per call of this method.
35
+ # Default is 200 entries.
36
+ # @option options [Integer] :PageNumber PageNumber can be used to retrieve multiple result sets.
37
+ # Page 1 is returned by default.
38
+ # @return [Array] Returns an array of Hashes representing a member's certification journal entries.
39
+ def self.certifications_journal_get(member_id, options = {})
40
+ options[:ID] = member_id
41
+
42
+ response = post('/', :body => build_XML_request('Sa.Member.Certifications.Journal.Get', nil, options))
43
+
44
+ response_valid? response
45
+ response_to_array_of_hashes response['YourMembership_Response']['Sa.Member.Certifications.Journal.Get'], ['Entry']
46
+ end
47
+ end
48
+ end
49
+ end