Journals

The Journals module exposes contextual information related to journal entries. Widgets can retrieve journal identifiers and accounting attributes when loaded in supported locations. This module supports extending accounting and ledger-related workflows.

Methods

Methods

Get Journal Details

Retrieves data related to the current context. This method allows your widget to fetch record details, field values, or metadata required for rendering or processing logic.

Commonly used for :

• Fetch record information
• Read field values
• Access contextual module data

Supported Locations :

journals.details.sidebarjournals.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.get('journal').then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
approver_id	journal.approver_id
approvers_list	journal.approvers_list
available_payables_credits	journal.available_payables_credits
available_payables_credits_formatted	journal.available_payables_credits_formatted
available_receivables_credits	journal.available_receivables_credits
available_receivables_credits_formatted	journal.available_receivables_credits_formatted
bcy_total	journal.bcy_total
bcy_total_formatted	journal.bcy_total_formatted
bills_credited	journal.bills_credited
branch_difference	journal.branch_difference

Show More Supported Input Keys

Property	Request
comments	journal.comments
created_time	journal.created_time
currency_code	journal.currency_code
currency_id	journal.currency_id
currency_symbol	journal.currency_symbol
custom_fields	journal.custom_fields
documents	journal.documents
entity_type	journal.entity_type
entity_type_formatted	journal.entity_type_formatted
entry_number	journal.entry_number
exchange_rate	journal.exchange_rate
exchange_rate_formatted	journal.exchange_rate_formatted
fiscal_year	journal.fiscal_year
imported_transactions	journal.imported_transactions
invoices_credited	journal.invoices_credited
is_accrual_journal	journal.is_accrual_journal
is_period_end_journal	journal.is_period_end_journal
journal_date	journal.journal_date
journal_date_formatted	journal.journal_date_formatted
journal_id	journal.journal_id
journal_number_prefix	journal.journal_number_prefix
journal_number_suffix	journal.journal_number_suffix
journal_template_name	journal.journal_template_name
journal_type	journal.journal_type
journal_type_formatted	journal.journal_type_formatted
last_modified_time	journal.last_modified_time
line_item_total	journal.line_item_total
line_item_total_formatted	journal.line_item_total_formatted
line_items	journal.line_items
notes	journal.notes
price_precision	journal.price_precision
project_id	journal.project_id
project_name	journal.project_name
reference_number	journal.reference_number
reversal_date	journal.reversal_date
status	journal.status
status_formatted	journal.status_formatted
submitted_by	journal.submitted_by
submitted_by_email	journal.submitted_by_email
submitted_by_name	journal.submitted_by_name
submitted_by_photo_url	journal.submitted_by_photo_url
submitted_date	journal.submitted_date
submitted_date_formatted	journal.submitted_date_formatted
submitter_id	journal.submitter_id
total	journal.total
total_formatted	journal.total_formatted
account	journal.account
currency	journal.currency

Set Journal Details

Updates or sets data within the current context. This method allows your widget to modify field values, update state, or pass data back to the host application.

Commonly used for :

• Update field values
• Set widget or module state
• Pass data to the parent application

Supported Locations :

journals.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('journal.name', <value>).then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
approver_id	journal.approver_id
approvers_list	journal.approvers_list
available_payables_credits	journal.available_payables_credits
available_payables_credits_formatted	journal.available_payables_credits_formatted
available_receivables_credits	journal.available_receivables_credits
available_receivables_credits_formatted	journal.available_receivables_credits_formatted
bcy_total	journal.bcy_total
bcy_total_formatted	journal.bcy_total_formatted
bills_credited	journal.bills_credited
branch_difference	journal.branch_difference

Show More Supported Input Keys

Property	Request
comments	journal.comments
created_time	journal.created_time
currency_code	journal.currency_code
currency_id	journal.currency_id
currency_symbol	journal.currency_symbol
custom_fields	journal.custom_fields
documents	journal.documents
entity_type	journal.entity_type
entity_type_formatted	journal.entity_type_formatted
entry_number	journal.entry_number
exchange_rate	journal.exchange_rate
exchange_rate_formatted	journal.exchange_rate_formatted
fiscal_year	journal.fiscal_year
imported_transactions	journal.imported_transactions
invoices_credited	journal.invoices_credited
is_accrual_journal	journal.is_accrual_journal
is_period_end_journal	journal.is_period_end_journal
journal_date	journal.journal_date
journal_date_formatted	journal.journal_date_formatted
journal_id	journal.journal_id
journal_number_prefix	journal.journal_number_prefix
journal_number_suffix	journal.journal_number_suffix
journal_template_name	journal.journal_template_name
journal_type	journal.journal_type
journal_type_formatted	journal.journal_type_formatted
last_modified_time	journal.last_modified_time
line_item_total	journal.line_item_total
line_item_total_formatted	journal.line_item_total_formatted
line_items	journal.line_items
notes	journal.notes
price_precision	journal.price_precision
project_id	journal.project_id
project_name	journal.project_name
reference_number	journal.reference_number
reversal_date	journal.reversal_date
status	journal.status
status_formatted	journal.status_formatted
submitted_by	journal.submitted_by
submitted_by_email	journal.submitted_by_email
submitted_by_name	journal.submitted_by_name
submitted_by_photo_url	journal.submitted_by_photo_url
submitted_date	journal.submitted_date
submitted_date_formatted	journal.submitted_date_formatted
submitter_id	journal.submitter_id
total	journal.total
total_formatted	journal.total_formatted
account	journal.account
currency	journal.currency

Get Journals List

Retrieves multiple data points or a collection of records related to the current context. This method is useful for fetching lists, related records, or bulk data required for your widget's functionality.

Commonly used for :

• Fetch related records
• Retrieve collections of data
• Access lists or tables of information

Supported Locations :

journals.list.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.get('journals').then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Supported Input Keys :

Property	Request
bcy_total	journal.bcy_total
bcy_total_formatted	journal.bcy_total_formatted
entity_type	journal.entity_type
entity_type_formatted	journal.entity_type_formatted
journal_date	journal.journal_date
journal_date_formatted	journal.journal_date_formatted
journal_id	journal.journal_id
journal_number	journal.journal_number
journal_type	journal.journal_type
journal_type_formatted	journal.journal_type_formatted

Show More Supported Input Keys

Property	Request
last_modified_time	journal.last_modified_time
notes	journal.notes
reference_number	journal.reference_number
status	journal.status
status_formatted	journal.status_formatted
total	journal.total
total_formatted	journal.total_formatted
currency	journal.currency
created_by	journal.created_by
documents	journal.documents

Set Journal customfields

Specifically designed to update custom field values within the current context. This method allows your widget to target and modify custom fields without affecting standard fields, ensuring precise data management.

Commonly used for :

• Update custom field values
• Manage user-defined data points
• Ensure targeted updates to specific fields

Supported Locations :

journals.creation.sidebar

Sample Code :

REQUEST DETAILS

window.onload = function () {
  ZFAPPS.extension.init().then(function(App) {
    ZFAPPS.set('journal.<custom_field_api_name>',<value>).then(function (data) {
     //response Handling
    }).catch(function (err) {
     //error Handling
    });
  });
}

Events

Events

ON_JOURNAL_PRE_SAVE

This event is triggered just before the journal record is saved in your organization. It allows your widget to validate data, modify field values, or perform custom checks before the save operation is completed.

Supported Locations :

journals.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_JOURNAL_PRE_SAVE').then(async function() {

    var record = await ZFAPPS.get('journal');
    record = record?.['custom_fields'];

    if (record.cf_approval_required && !record.cf_approval_notes) {

      await ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'error',
        message: 'Approval notes are required when Approval Required is selected.'
      });

      return {
        prevent_save: true
      };
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

JOURNAL_SAVED

This event is triggered after the journal record is successfully saved in your organization. You can use this event to perform post-save actions such as syncing data, triggering notifications, or updating external systems.

Supported Locations :

journals.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_JOURNAL_SAVED').then(function(data) {

    var recordId = data && data.record_id;

    ZFAPPS.invoke('SHOW_NOTIFICATION', {
      type: 'success',
      message: 'Record saved successfully. Record ID: ' + recordId
    });

    console.log('Saved record ID:', recordId);

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_JOURNAL_CHANGE

This event is triggered whenever a supported field value is changed within the journal form. The event is fired based on the configured supported keys, allowing your widget to react dynamically to user input.

Supported Locations :

journals.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_JOURNAL_CHANGE').then(async function() {

    var record = await ZFAPPS.get('journal');
    record = record?.['custom_fields'];

    if (record.cf_special_flag) {
      ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'success',
        message: 'Special option selected. Please review additional details before saving.'
      });
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_JOURNAL_PREVIEW

This event is triggered when the preview of a journal record is opened in your organization. It allows your widget to access record data and render contextual information during the preview phase.

Supported Locations :

journals.details.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_JOURNAL_PREVIEW').then(async function() {

    var record = await ZFAPPS.get('journal');
    record = record?.['custom_fields'];

    if (record.cf_priority_level === 'High') {
      ZFAPPS.invoke('SHOW_NOTIFICATION', {
        type: 'error',
        message: 'This record is marked as High Priority.'
      });
    }

  }).catch(function(err) {
    console.error('Error:', err);
  });
});

ON_JOURNAL_PAGE_LOAD

This event is triggered when the widget is loaded for the first time on the journal page. You can use this event to initialize data, fetch required resources, or set up the initial state of your widget.

Supported Locations :

journals.creation.sidebar

Sample Code :

REQUEST DETAILS

ZFAPPS.extension.init().then(function(App) {
  App.instance.on('ON_JOURNAL_PAGE_LOAD').then(async function() {
    // Set default value for a custom field
    await ZFAPPS.set('journal.cf_priority_level', 'Normal');

    ZFAPPS.invoke('SHOW_NOTIFICATION', {
      type: 'success',
      message: 'Default priority level has been set to Normal.'
    });
  }).catch(function(err) {
    console.error('Error:', err);
  });
});