Class: AdvancedBilling::CustomFieldsController

Inherits:
BaseController show all
Defined in:
lib/advanced_billing/controllers/custom_fields_controller.rb

Overview

CustomFieldsController

Constant Summary

Constants inherited from BaseController

BaseController::GLOBAL_ERRORS

Instance Attribute Summary

Attributes inherited from BaseController

#config, #http_call_back

Instance Method Summary collapse

Methods inherited from BaseController

#initialize, #new_parameter, #new_request_builder, #new_response_handler, user_agent, user_agent_parameters

Constructor Details

This class inherits a constructor from AdvancedBilling::BaseController

Instance Method Details

#create_metadata(resource_type, resource_id, body: nil) ⇒ Array[Metadata]

Creates metadata and metafields for a specific subscription or customer, or updates metadata values of existing metafields for a subscription or customer. Metadata values are limited to 2 KB in size. If you create metadata on a subscription or customer with a metafield that does not already exist, the metafield is created with the metadata you specify and it is always added as a text field. You can update the input_type for the metafield with the [Update Metafield]($e/Custom%20Fields/updateMetafield) endpoint. >Note: Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for Subscriptions and another 100 for Customers. to which the metafields belong. of the customer or the subscription for which the metadata applies description here

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

  • resource_id (Integer) —

    Required parameter: The Advanced Billing id

  • body (CreateMetadataRequest) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:

  • (Array[Metadata]) —

    Response from the API call.



206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 206

def create_metadata(resource_type,
                    resource_id,
                    body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(resource_id, key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metadata.method(:from_hash))
                .is_response_array(true)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      SingleErrorResponseException))
    .execute
end

#create_metafields(resource_type, body: nil) ⇒ Array[Metafield]

Creates metafields on a Site for either the Subscriptions or Customers resource. Metafields and their metadata are created in the Custom Fields configuration page on your Site. Metafields can be populated with metadata when you create them or later with the [Update Metafield]($e/Custom%20Fields/updateMetafield), [Create Metadata]($e/Custom%20Fields/createMetadata), or [Update Metadata]($e/Custom%20Fields/updateMetadata) endpoints. The Create Metadata and Update Metadata endpoints allow you to add metafields and metadata values to a specific subscription or customer. Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for Subscriptions and another 100 for Customers. > Note: After creating a metafield, the resource type cannot be modified. In the UI and product documentation, metafields and metadata are called Custom Fields.

  • Metafield is the custom field

  • Metadata is the data populating the custom field.

See [Custom Fields Reference](docs.maxio.com/hc/en-us/articles/24266140850573-Custom- Fields-Reference) and [Custom Fields Tab](maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscripti on-Summary-Custom-Fields-Tab) for information on using Custom Fields in the Advanced Billing UI. to which the metafields belong. description here

Parameters:

Returns:

  • (Array[Metafield]) —

    Response from the API call.



37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 37

def create_metafields(resource_type,
                      body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{resource_type}/metafields.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metafield.method(:from_hash))
                .is_response_array(true)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      SingleErrorResponseException))
    .execute
end

#delete_metadata(resource_type, resource_id, name: nil, names: nil) ⇒ void

This method returns an undefined value.

Deletes one or more metafields (and associated metadata) from the specified subscription or customer. to which the metafields belong. of the customer or the subscription for which the metadata applies removed. Use in query: ‘names[]=field1&names=my-field&names[]=another-field`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

  • resource_id (Integer) —

    Required parameter: The Advanced Billing id

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

    Optional parameter: Name of field to be removed.

  • names (Array[String]) (defaults to: nil) —

    Optional parameter: Names of fields to be



330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 330

def delete_metadata(resource_type,
                    resource_id,
                    name: nil,
                    names: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(resource_id, key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(name, key: 'name'))
               .query_param(new_parameter(names, key: 'names'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::UN_INDEXED))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException))
    .execute
end

#delete_metafield(resource_type, name: nil) ⇒ void

This method returns an undefined value.

Deletes a metafield from your Site. Removes the metafield and associated metadata from all Subscriptions or Customers resources on the Site. to which the metafields belong. deleted

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

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

    Optional parameter: The name of the metafield to be



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 169

def delete_metafield(resource_type,
                     name: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/{resource_type}/metafields.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(name, key: 'name'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .is_response_void(true)
                .local_error_template('404',
                                      'Not Found:\'{$response.body}\'',
                                      APIException))
    .execute
end

#list_metadata(options = {}) ⇒ PaginatedMetadata

Lists metadata and metafields for a specific customer or subscription. to which the metafields belong. of the customer or the subscription for which the metadata applies pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query ‘page=1`. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

  • resource_id (Integer) —

    Required parameter: The Advanced Billing id

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

Returns:



252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 252

def list_metadata(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['resource_type'], key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(options['resource_id'], key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PaginatedMetadata.method(:from_hash)))
    .execute
end

#list_metadata_for_resource_type(options = {}) ⇒ PaginatedMetadata

Lists metadata for a specified array of subscriptions or customers. to which the metafields belong. pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query ‘page=1`. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`. you would like to apply to your search. YYYY-MM-DD) with which to filter the date_field. Returns metadata with a timestamp at or after midnight (12:00:00 AM) in your site’s time zone on the date specified. YYYY-MM-DD) with which to filter the date_field. Returns metadata with a timestamp up to and including 11:59:59PM in your site’s time zone on the date specified. time (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns metadata with a timestamp at or after exact time provided in query. You can specify timezone in query - otherwise your site’s time zone will be used. If provided, this parameter will be used instead of start_date. (format YYYY-MM-DD HH:MM:SS) with which to filter the date_field. Returns metadata with a timestamp at or before exact time provided in query. You can specify timezone in query - otherwise your site’s time zone will be used. If provided, this parameter will be used instead of end_date. fetch deleted metadata. metadata for multiple records based on provided ids. Use in query: ‘resource_ids[]=122&resource_ids=123&resource_ids[]=124`. in which results are returned. Use in query `direction=asc`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • date_field (BasicDateField) —

    Optional parameter: The type of filter

  • start_date (Date) —

    Optional parameter: The start date (format

  • end_date (Date) —

    Optional parameter: The end date (format

  • start_datetime (DateTime) —

    Optional parameter: The start date and

  • end_datetime (DateTime) —

    Optional parameter: The end date and time

  • with_deleted (TrueClass | FalseClass) —

    Optional parameter: Allow to

  • resource_ids (Array[Integer]) —

    Optional parameter: Allow to fetch

  • direction (SortingDirection) —

    Optional parameter: Controls the order

Returns:



399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 399

def list_metadata_for_resource_type(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/metadata.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['resource_type'], key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['date_field'], key: 'date_field'))
               .query_param(new_parameter(options['start_date'], key: 'start_date'))
               .query_param(new_parameter(options['end_date'], key: 'end_date'))
               .query_param(new_parameter(options['start_datetime'], key: 'start_datetime'))
               .query_param(new_parameter(options['end_datetime'], key: 'end_datetime'))
               .query_param(new_parameter(options['with_deleted'], key: 'with_deleted'))
               .query_param(new_parameter(options['resource_ids'], key: 'resource_ids'))
               .query_param(new_parameter(options['direction'], key: 'direction'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth'))
               .array_serialization_format(ArraySerializationFormat::UN_INDEXED))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(PaginatedMetadata.method(:from_hash)))
    .execute
end

#list_metafields(options = {}) ⇒ ListMetafieldsResponse

Lists the metafields and their associated details for a Site and resource type. You can filter the request to a specific metafield. to which the metafields belong. metafield. pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned. Use in query ‘page=1`. many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200. Use in query `per_page=200`. in which results are returned. Use in query `direction=asc`.

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

  • name (String) —

    Optional parameter: Filter by the name of the

  • page (Integer) —

    Optional parameter: Result records are organized in

  • per_page (Integer) —

    Optional parameter: This parameter indicates how

  • direction (SortingDirection) —

    Optional parameter: Controls the order

Returns:



82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 82

def list_metafields(options = {})
  @api_call
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/metafields.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(options['resource_type'], key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .query_param(new_parameter(options['name'], key: 'name'))
               .query_param(new_parameter(options['page'], key: 'page'))
               .query_param(new_parameter(options['per_page'], key: 'per_page'))
               .query_param(new_parameter(options['direction'], key: 'direction'))
               .header_param(new_parameter('application/json', key: 'accept'))
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(ListMetafieldsResponse.method(:from_hash)))
    .execute
end

#update_metadata(resource_type, resource_id, body: nil) ⇒ Array[Metadata]

Updates metadata and metafields on the Site and the customer or subscription specified, and updates the metadata value on a subscription or customer. If you update metadata on a subscription or customer with a metafield that does not already exist, the metafield is created with the metadata you specify and it is always added as a text field to the Site and to the subscription or customer you specify. You can update the input_type for the metafield with the Update Metafield endpoint. Each site is limited to 100 unique metafields per resource. This means you can have 100 metafields for Subscription and another 100 for Customer. to which the metafields belong. of the customer or the subscription for which the metadata applies description here

Parameters:

  • resource_type (ResourceType) —

    Required parameter: The resource type

  • resource_id (Integer) —

    Required parameter: The Advanced Billing id

  • body (UpdateMetadataRequest) (defaults to: nil) —

    Optional parameter: TODO: type

Returns:

  • (Array[Metadata]) —

    Response from the API call.



290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 290

def update_metadata(resource_type,
                    resource_id,
                    body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .template_param(new_parameter(resource_id, key: 'resource_id')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metadata.method(:from_hash))
                .is_response_array(true)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      SingleErrorResponseException))
    .execute
end

#update_metafield(resource_type, body: nil) ⇒ Array[Metafield]

Updates metafields on your Site for a resource type. Depending on the request structure, you can update or add metafields and metadata to the Subscriptions or Customers resource. With this endpoint, you can:

  • Add metafields. If the metafield specified in current_name does not

exist, a new metafield is added.

>Note: Each site is limited to 100 unique metafields per resource. This

means you can have 100 metafields for Subscriptions and another 100 for Customers.

  • Change the name of a metafield. >Note: To keep the metafield name the same and only update the metadata

for the metafield, you must use the current metafield name in both the ‘current_name` and `name` parameters.

  • Change the input type for the metafield. For example, you can change a

metafield input type from text to a dropdown. If you change the input type from text to a dropdown or radio, you must update the specific subscriptions or customers where the metafield was used to reflect the updated metafield and metadata.

  • Add metadata values to the existing metadata for a dropdown or radio

metafield.

>Note: Updates to metadata overwrite. To add one or more values, you

must specify all metadata values including the new value you want to add.

  • Add new metadata to a dropdown or radio for a metafield that was created

without metadata.

  • Remove metadata for a dropdown or radio for a metafield. >Note: Updates to metadata overwrite existing values. To remove one or

more values, specify all metadata values except those you want to remove.

  • Add or update scope settings for a metafield. >Note: Scope changes overwrite existing settings. You must specify the

complete scope, including the changes you want to make. to which the metafields belong. description here

Parameters:

Returns:

  • (Array[Metafield]) —

    Response from the API call.



137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 137

def update_metafield(resource_type,
                     body: nil)
  @api_call
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/{resource_type}/metafields.json',
                                 Server::PRODUCTION)
               .template_param(new_parameter(resource_type, key: 'resource_type')
                                .is_required(true)
                                .should_encode(true))
               .header_param(new_parameter('application/json', key: 'Content-Type'))
               .body_param(new_parameter(body))
               .header_param(new_parameter('application/json', key: 'accept'))
               .body_serializer(proc do |param| param.to_json unless param.nil? end)
               .auth(Single.new('BasicAuth')))
    .response(new_response_handler
                .deserializer(APIHelper.method(:custom_type_deserializer))
                .deserialize_into(Metafield.method(:from_hash))
                .is_response_array(true)
                .local_error_template('422',
                                      'HTTP Response Not OK. Status code: {$statusCode}.'\
                                       ' Response: \'{$response.body}\'.',
                                      SingleErrorResponseException))
    .execute
end