Module: MyobAcumatica::Api::Ledger

Defined in:
lib/myob_acumatica/api/ledger.rb

Overview

Provides methods to interact with the Ledger API endpoints.

All methods follow the same conventions as other entities in this gem:

  • Paths, query params, and headers are set via Http.request

  • Keys are joined with “/” when addressing composite primary keys

  • Binary uploads use ‘application/octet-stream’

Class Method Summary collapse

Class Method Details

.delete_by_id(access_token:, id:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ nil

Deletes a ledger by session identifier (GUID).

Examples:

Delete a ledger by ID

MyobAcumatica::Api::Ledger.delete_by_id(
  access_token: '...',
  id: '00000000-0000-4000-8000-000000000000',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • id (String) —

    The session GUID of the record.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (nil) —

    Always nil.



30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
 
# File 'lib/myob_acumatica/api/ledger.rb', line 30

def delete_by_id(access_token:, id:,
                 instance_name: INSTANCE_NAME,
                 endpoint_name: ENDPOINT_NAME,
                 endpoint_version: ENDPOINT_VERSION,
                 logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :delete,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Ledger/#{id}",
    logger: logger
  )
end

.delete_by_keys(access_token:, keys:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ nil

Deletes a ledger by composite keys.

Examples:

Delete a ledger by keys

MyobAcumatica::Api::Ledger.delete_by_keys(
  access_token: '...',
  keys: ['LEDGER-ACTUAL'],
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    The key values identifying the record.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (nil) —

    Always nil.



62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
 
# File 'lib/myob_acumatica/api/ledger.rb', line 62

def delete_by_keys(access_token:, keys:,
                   instance_name: INSTANCE_NAME,
                   endpoint_name: ENDPOINT_NAME,
                   endpoint_version: ENDPOINT_VERSION,
                   logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :delete,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Ledger/#{keys.join('/')}",
    logger: logger
  )
end

.get_ad_hoc_schema(access_token:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Retrieves the ad-hoc schema (custom fields) for Ledger.

Examples:

Retrieve the ad-hoc schema

MyobAcumatica::Api::Ledger.get_ad_hoc_schema(
  access_token: '...',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The ad-hoc schema document.



92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
 
# File 'lib/myob_acumatica/api/ledger.rb', line 92

def get_ad_hoc_schema(access_token:,
                      instance_name: INSTANCE_NAME,
                      endpoint_name: ENDPOINT_NAME,
                      endpoint_version: ENDPOINT_VERSION,
                      logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: 'Ledger/$adHocSchema',
    logger: logger
  )
end

.get_by_id(access_token:, id:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Retrieves a ledger by session identifier (GUID).

Examples:

Retrieve a ledger by ID

MyobAcumatica::Api::Ledger.get_by_id(
  access_token: '...',
  id: '00000000-0000-4000-8000-000000000000',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • id (String) —

    The session GUID of the record.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $filter, etc.).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The ledger record.



125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
 
# File 'lib/myob_acumatica/api/ledger.rb', line 125

def get_by_id(access_token:, id:, query_params: {},
              instance_name: INSTANCE_NAME,
              endpoint_name: ENDPOINT_NAME,
              endpoint_version: ENDPOINT_VERSION,
              logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Ledger/#{id}",
    query_params: query_params,
    logger: logger
  )
end

.get_by_keys(access_token:, keys:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Retrieves a ledger by its key values.

Examples:

Retrieve a ledger by keys

MyobAcumatica::Api::Ledger.get_by_keys(
  access_token: '...',
  keys: ['LEDGER-ACTUAL'],
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    The key values identifying the record.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $filter, etc.).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The ledger record.



159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
 
# File 'lib/myob_acumatica/api/ledger.rb', line 159

def get_by_keys(access_token:, keys:, query_params: {},
                instance_name: INSTANCE_NAME,
                endpoint_name: ENDPOINT_NAME,
                endpoint_version: ENDPOINT_VERSION,
                logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Ledger/#{keys.join('/')}",
    query_params: query_params,
    logger: logger
  )
end

.get_list(access_token:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Array<Hash>

Retrieves a list of ledgers matching optional filters.

Examples:

Retrieve a list of ledgers

MyobAcumatica::Api::Ledger.get_list(
  access_token: '...',
  query_params: { '$top' => 10 },
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $top, etc.).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Array<Hash>) —

    A list of ledger records.



192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
 
# File 'lib/myob_acumatica/api/ledger.rb', line 192

def get_list(access_token:, query_params: {},
             instance_name: INSTANCE_NAME,
             endpoint_name: ENDPOINT_NAME,
             endpoint_version: ENDPOINT_VERSION,
             logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :get,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: 'Ledger',
    query_params: query_params,
    logger: logger
  )
end

.invoke_action(access_token:, action_name:, entity:, parameters: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash?

Invokes a custom action on the Ledger entity.

The API may respond with 202 (accepted, in progress) or 204 (completed).

Examples:

Invoke a custom action

MyobAcumatica::Api::Ledger.invoke_action(
  access_token: '...',
  action_name: 'RebuildBalances',
  entity: { 'LedgerID' => { 'value' => 'LEDGER-ACTUAL' } },
  parameters: { 'FromPeriod' => { 'value' => '2024-01' } },
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • action_name (String) —

    The action name (e.g., ‘RebuildBalances’).

  • entity (Hash) —

    The entity on which to invoke the action.

  • parameters (Hash) (defaults to: {}) —

    Optional parameters for the action.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash, nil) —

    The action response, if any.



319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
 
# File 'lib/myob_acumatica/api/ledger.rb', line 319

def invoke_action(access_token:, action_name:, entity:, parameters: {},
                  instance_name: INSTANCE_NAME,
                  endpoint_name: ENDPOINT_NAME,
                  endpoint_version: ENDPOINT_VERSION,
                  logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :post,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: "Ledger/#{action_name}",
    body: { 'entity' => entity, 'parameters' => parameters },
    logger: logger
  )
end

.put_entity(access_token:, entity:, query_params: {}, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ Hash

Creates or updates a ledger record.

Examples:

Upsert a ledger

MyobAcumatica::Api::Ledger.put_entity(
  access_token: '...',
  entity: {
    'LedgerID' => { 'value' => 'LEDGER-ACTUAL' },
    'Description' => { 'value' => 'Actuals' }
  },
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • entity (Hash) —

    The ledger entity payload.

  • query_params (Hash) (defaults to: {}) —

    Optional query params ($select, $custom, etc.).

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (Hash) —

    The created or updated record.



229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
 
# File 'lib/myob_acumatica/api/ledger.rb', line 229

def put_entity(access_token:, entity:, query_params: {},
               instance_name: INSTANCE_NAME,
               endpoint_name: ENDPOINT_NAME,
               endpoint_version: ENDPOINT_VERSION,
               logger: nil)
  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :put,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: 'Ledger',
    body: entity,
    query_params: query_params,
    logger: logger
  )
end

.put_file(access_token:, keys:, file_path:, instance_name: INSTANCE_NAME, endpoint_name: ENDPOINT_NAME, endpoint_version: ENDPOINT_VERSION, logger: nil) ⇒ nil

Attaches a file to a specific ledger record by resolving the ‘files:put’ link.

Examples:

Upload a PDF to a ledger record

MyobAcumatica::Api::Ledger.put_file(
  access_token: '...',
  keys: ['LEDGER-ACTUAL'],
  file_path: 'examples/sample.pdf',
  logger: Logger.new($stdout)
)

Parameters:

  • access_token (String) —

    The OAuth2 access token.

  • keys (Array<String>) —

    Key(s) identifying the record.

  • file_path (String) —

    Full path to the file to upload.

  • instance_name (String) (defaults to: INSTANCE_NAME) —

    The instance name.

  • endpoint_name (String) (defaults to: ENDPOINT_NAME) —

    The endpoint name.

  • endpoint_version (String) (defaults to: ENDPOINT_VERSION) —

    The endpoint version.

  • logger (Logger, nil) (defaults to: nil) —

    Optional logger.

Returns:

  • (nil) —

    Returns nil if successful.

Raises:



266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
 
# File 'lib/myob_acumatica/api/ledger.rb', line 266

def put_file(access_token:, keys:, file_path:,
             instance_name: INSTANCE_NAME,
             endpoint_name: ENDPOINT_NAME,
             endpoint_version: ENDPOINT_VERSION,
             logger: nil)
  ledger = get_by_keys(
    access_token: access_token,
    instance_name: instance_name,
    keys: keys,
    logger: logger
  )

  put_url_template = ledger.dig('_links', 'files:put')
  raise MyobAcumatica::Error, 'files:put link not found' unless put_url_template

  filename = File.basename(file_path)
  path = put_url_template.gsub('{filename}', filename)

  Http.request(
    instance_name: instance_name,
    access_token: access_token,
    method: :put,
    endpoint_name: endpoint_name,
    endpoint_version: endpoint_version,
    path: path,
    body: File.binread(file_path),
    content_type: 'application/octet-stream',
    logger: logger
  )
end