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_api_call_builder, #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]

## Custom Fields: Metadata Intro **Advanced Billing refers to Custom Fields in the API documentation as metafields and metadata.** Within the Advanced Billing UI, metadata and metafields are grouped together under the umbrella of “Custom Fields.” All of our UI-based documentation that references custom fields will not cite the terminology metafields or metadata. + **Metafield is the custom field** + **Metadata is the data populating the custom field.** Advanced Billing Metafields are used to add meaningful attributes to subscription and customer resources. Full documentation on how to create Custom Fields in the Advanced Billing UI can be located [here](maxio.zendesk.com/hc/en-us/articles/24266164865677-Custom-F ields-Overview). For additional documentation on how to record data within custom fields, please see our subscription-based documentation [here.](maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscri ption-Summary-Custom-Fields-Tab) Metadata is associated to a customer or subscription, and corresponds to a Metafield. When creating a new metadata object for a given record, **if the metafield is not present it will be created**. ## Metadata limits Metadata values are limited to 2kB in size. Additonally, there are limits on the number of unique metafields available per resource. ## Create Metadata This method will create a metafield for the site on the fly if it does not already exist, and populate the metadata value. ### Subscription or Customer Resource Please pay special attention to the resource you use when creating metadata. to which the metafields belong of the customer or the subscription for which the metadata applies

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: Example:

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)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .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]

## Custom Fields: Metafield Intro **Advanced Billing refers to Custom Fields in the API documentation as metafields and metadata.** Within the Advanced Billing UI, metadata and metafields are grouped together under the umbrella of “Custom Fields.” All of our UI-based documentation that references custom fields will not cite the terminology metafields or metadata. + **Metafield is the custom field** + **Metadata is the data populating the custom field.** Advanced Billing Metafields are used to add meaningful attributes to subscription and customer resources. Full documentation on how to create Custom Fields in the Advanced Billing UI can be located [here](maxio.zendesk.com/hc/en-us/sections/24266118312589-Custom-F ields). For additional documentation on how to record data within custom fields, please see our subscription-based documentation [here](maxio.zendesk.com/hc/en-us/articles/24251701302925-Subscrip tion-Summary-Custom-Fields-Tab). Metafield are the place where you will set up your resource to accept additional data. It is scoped to the site instead of a specific customer or subscription. Think of it as the key, and Metadata as the value on every record. ## Create Metafields Use this endpoint to create metafields for your Site. Metafields can be populated with metadata after the fact. Each site is limited to 100 unique Metafields (i.e. keys, or names) per resource. This means you can have 100 Metafields for Subscription and another 100 for Customer. ### Metafields “On-the-Fly” It is possible to create Metafields “on the fly” when you create your Metadata – if a non-existant name is passed when creating Metadata, a Metafield for that key will be automatically created. The Metafield API, however, gives you more control over your “keys”. ### Metafield Scope Warning If configuring metafields in the Admin UI or via the API, be careful sending updates to metafields with the scope attribute – **if a partial update is sent it will overwrite the current configuration**. to which the metafields belong

Parameters:

Returns:

  • (Array[Metafield]) —

    response from the API call.



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

def create_metafields(resource_type,
                      body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::POST,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .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.

This method removes the metadata from the subscriber/customer cited. ## Query String Usage For instance if you wanted to delete the metadata for customer 99 named weight you would request: “‘ acme.chargify.com/customers/99/metadata.json?name=weight “` If you want to delete multiple metadata fields for a customer 99 named: `weight` and `age` you wrould request: “` acme.chargify.com/customers/99/metadata.json?names[]=weight&names[ ]=age “` ## Successful Response For a success, there will be a code `200` and the plain text response `true`. ## Unsuccessful Response When a failed response is encountered, you will receive a `404` response and the plain text response of `true`. 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



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 342

def delete_metadata(resource_type,
                    resource_id,
                    name: nil,
                    names: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .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.

Use the following method to delete a metafield. This will remove the metafield from the Site. Additionally, this will remove the metafield and associated metadata with all Subscriptions 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



153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 153

def delete_metafield(resource_type,
                     name: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::DELETE,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .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

This request will list all of the metadata belonging to a particular resource (ie. subscription, customer) that is specified. ## Metadata Data This endpoint will also display the current stats of your metadata to use as a tool for pagination. 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:



256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 256

def list_metadata(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .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

This method will provide you information on usage of metadata across your selected resource (ie. subscriptions, customers) ## Metadata Data This endpoint will also display the current stats of your metadata to use as a tool for pagination. ### Metadata for multiple records ‘acme.chargify.com/subscriptions/metadata.json?resource_ids[]=1&re source_ids[]=2` ## Read Metadata for a Site This endpoint will list the number of pages of metadata information that are contained within a site. 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:



421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 421

def list_metadata_for_resource_type(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/metadata.json',
                                 Server::DEFAULT)
               .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

This endpoint lists metafields associated with a site. The metafield description and usage is contained in the response. 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:



93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 93

def list_metafields(options = {})
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::GET,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .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]

This method allows you to update the existing metadata associated with a subscription or customer. to which the metafields belong of the customer or the subscription for which the metadata applies

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: Example:

Returns:

  • (Array[Metadata]) —

    response from the API call.



285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 285

def update_metadata(resource_type,
                    resource_id,
                    body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/{resource_type}/{resource_id}/metadata.json',
                                 Server::DEFAULT)
               .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]

Use the following method to update metafields for your Site. Metafields can be populated with metadata after the fact. to which the metafields belong

Parameters:

Returns:

  • (Array[Metafield]) —

    response from the API call.



119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
 
# File 'lib/advanced_billing/controllers/custom_fields_controller.rb', line 119

def update_metafield(resource_type,
                     body: nil)
  new_api_call_builder
    .request(new_request_builder(HttpMethodEnum::PUT,
                                 '/{resource_type}/metafields.json',
                                 Server::DEFAULT)
               .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