listRecords Documentation

Purpose

The listRecords logic component is designed to facilitate the retrieval of all records from the contacts application within the Vantage analytics & data platform. By leveraging the functionality provided by a data adapter, it retrieves structured data relevant to the application's records. The primary output is a structured response containing the data of the retrieved records, making it essential for any applications that require the listing or manipulation of contact information.

Settings

The listRecords component operates with a set of configuration parameters. Below are the details of each setting.

Input Parameters

1. inputs

   • Type: Object
   • Description: This parameter serves as a way to pass in specific input values that may be needed for the execution of the logic. Although it is defined, no specific keys are required for this logic to execute properly.
   • Default Value: {} (an empty object, implying no default inputs)

2. config

   • Type: Object
   • Description: The configuration object contains settings necessary for establishing the context of the operation, including specifications about the application type. The appType is key to directing which application's records should be retrieved.
   • Default Value: { appType: 'contacts' }

3. context

   • Type: Object
   • Description: This context object holds critical information required for the execution of the logic, including the user and client identifiers. The nodeType attribute specifies the type of node being executed and can influence operation behavior.
   • Default Value: {} (an empty object)

Execution Variables

• clientId

  • Type: String
  • Description: This identifier uniquely represents the client making the request. The absence of a clientId will halt execution and return an error, emphasizing its necessity.
  • Default Value: None (must be provided in the execution context)

• userId

  • Type: String
  • Description: This parameter identifies the user performing the action. It helps in determining permissions and ensuring that the retrieval aligns with user access rights.
  • Default Value: None (must be provided in the execution context)

• appType

  • Type: String
  • Description: This dictates the type of records being listed, defaulting to 'contacts'. Changing this parameter allows the user to specify different data categorizations if the logic were extended to support more application types in future iterations.
  • Default Value: 'contacts' (if not provided explicitly)

How It Works

1. Execution Context Validation: The function starts by checking if the clientId is present in the execution context. If absent, it immediately returns an error message indicating the missing identifier.

2. Configuration Retrieval: Upon validating the context, the function calls getAppConfig to retrieve the configuration settings relevant to the app type, utilizing the provided clientId.

3. Data Adapter Initialization: A data adapter is then created with the storage provider specified in the application’s configuration, which is crucial for interfacing with the data source.

4. Records Listing: The core functionality resides in calling the listRecords method of the adapter, which fetches and returns the records from the specified application type.

5. Output Handling: The resulting records are then formatted into a structured output object. If any error occurs at any point in this process, it captures the error and returns a formatted error message instead.

Expected Data

The listRecords component expects the following inputs:

• A valid clientId: A string identifier specific to the client requesting the data.
• An optional userId: A string that identifies the user and is contextually relevant.
• An optional appType: A string describing the type of records (defaults to 'contacts' if not specified).

Use Cases & Examples

Use Cases

1. Contact Management System Integration: A business using Vantage may want to list all contact records associated with a particular client, enabling them to analyze customer relationships and engagement efforts.

2. Data Migration Projects: During a migration to a new platform, the existing contact data needs to be pulled from the contacts application to facilitate smooth transitioning and validation of records.

3. Dynamic Reporting: Organizations may utilize this logic in generating reports dynamically by pulling current contact records in response to specific reporting parameters set by the users.

Example

Use Case: A marketing team requires a list of all contact records to perform an email campaign targeting existing customers.

Configuration:

{
  "inputs": {},
  "config": {},
  "context": {
    "clientId": "unique-client-123",
    "userId": "user-456",
    "nodeType": "contacts/listRecords"
  }
}

In this configuration:

• The clientId specifically identifies the client's account.
• The userId can be used in auditing who accessed the data.
• The appType defaults to 'contacts', retrieving all records from the contacts application.

This structured approach simplifies data retrieval for application interfacing and enhances the overall user experience when utilizing the Vantage platform.