Skip to main content

Card Configurations

Overview​

This guide provides a step-by-step process for configuring a new card to display responses from an API on the Applications tab of the HyperVergeOne dashboard. It also covers modifying the layout or adjusting the displayed information for an existing API by updating its configurations.

You'll find detailed instructions on adding or modifying configurations, along with dedicated sub-sections containing documentation for each card type.

What this guide covers​

  • Adding a new card configuration to display API responses
  • Modifying existing card configurations to adjust layout or displayed information
  • Understanding the structure and documentation of different card types

Prerequisites​

  • Access to HV Central Config repository on GitLab
  • Basic understanding of version control
  • Basic understanding of JSON
  • Access to HV One Dashboard
  • Access to API response structure for which you are adding/modifying the configurations

Purpose & use case​

Who is this guide for? Module owners who intend to add new configurations or modify existing configurations for their modules to control the way information about their module is displayed on case management.

When should this be used? Use this guide when:

  • You want to add a new API and configure a card to display its responses
  • Updating the layout or amount of information shown in an existing API card
  • Understanding how different card types are structured and configured

Step-by-step guide​

1. Setting up​

To get started with adding or modifying configurations you should have access to the HV Central Config GitLab repository. Additionally, keep the API request and response for the API you plan to change or add configs for handy.

  1. Under the repository, find the module config file at:

    buckets/hv-central-config/audit-portal/prod/modules-config/modules.json

  2. This file contains configurations for all the cards displayed on the case management application details page. It is an array of JSON objects.

    • Each object is a configuration for an individual API endpoint.
    • This object defines how the card for this endpoint should look on case management.
    • If there is no configuration object present for an endpoint, a default card is displayed.
TODO

Screenshot: Default module card shown when no configuration exists. (Pending migration from Notion.)

2. How it works​

What is the structure of a card configuration object?​

{
  "moduleName": "Name of the module",
  "cardType": "Card type to be used",
  "endpoint": "Your endpoint",
  "parse": "no",
  "refreshSupportedS3URLs": "yes"
  // ...cardSpecificConfigurations
}

Each key explained:

  1. moduleName — Fallback name displayed as the title for the card on case management if no name is present in the workflow configuration. Workflow name takes precedence.
  2. cardType — Determines the card to be used for the endpoint. Supported types:
    • Multi-table Card: multiTableCard
    • Dynamic Card: dynamicCard
    • Generic Card v1: genericCardTypeV1
    • Generic Card v2: genericCardV2
  3. endpoint — The API endpoint URL for which these configs apply. Examples:
    • Read ID: /v1/readId
    • Check Liveness: /v1/checkLiveness
  4. parse — Specifies whether the response and request payload should be parsed by the BE and FE. no for most newer cards.
  5. refreshSupportedS3URLs — Used to determine whether the S3 URLs present inside the request or response body should be refreshed. Set it to yes if you want the URLs to be refreshed.
note

When refreshSupportedS3URLs is set to yes, it only supports refreshing S3 URLs that are valid Audit Portal Bucket URLs. This parameter cannot refresh URLs originating from other buckets. To identify whether a URL is an Audit Portal Bucket URL, verify if the URL starts with prod-audit-portal-<region_code>.

This limitation exists because our backend systems only have access to our bucket and we would not have the sufficient required permissions to refresh URLs from other buckets.

Example — Audit Portal Bucket URL
https://prod-audit-portal-ind.s3.ap-south-1.amazonaws.com/THOMAS/readCheque/2025-03-13/55a3a6/1741837273648-99ce71d9-5f6b-472c-acbc-4c38c583b56e/0.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&...
Example — Other Bucket URL (not refreshable)
https://hv-central-config.s3.ap-south-1.amazonaws.com/audit-portal/prod/frontend-config/homePageAssets/thumbnails/analytics.svg?...

Supported card types​

For detailed configuration of each card type, see:

  • Generic Card V2
  • Multi-table Card (pending migration)
  • Dynamic Card (pending migration)
  • Generic Card v1 (pending migration)
warning

There are certain old card types like type1, type2, etc. that are being deprecated and are not actively maintained. We discourage their use and encourage migration to the newer cards. For most use cases, Generic Card V2 is sufficient. It has most of the features available, provides flexibility to design your own layout, supports a lot of components other cards lack, and is being actively maintained and enhanced.

Update: From April 2026 onwards, only Generic Card v1, v2, and Multi-table Card will be supported for further development/features. All older cards will not be receiving any additional development support.

How to add or modify configurations for an endpoint​

  1. Go to the HV Central Config GitLab repository.
    • If cloned locally:
      1. Go to the master branch: git checkout master
      2. Pull the latest commit: git pull
      3. Create a new branch: git checkout -b <your-branch-name>
    • If not cloned:
      1. Go to the GitLab repository page.
      2. Open the project in GitLab Web IDE by clicking on the Edit dropdown on the repository home page.
      3. Click on master at the bottom-left corner.
      4. Enter your branch name and press Enter to create your new branch.
TODO

Screenshots: GitLab Web IDE "Edit" dropdown, branch switcher, and branch-creation dialog. (Pending migration from Notion.)

  1. Find the modules config file:

    buckets/hv-central-config/audit-portal/prod/modules-config/modules.json

  2. To modify an existing card configuration: Locate the configuration object for the endpoint by searching for the endpoint URL, then make the changes per the card type and requirements.

TODO

Screenshot: Searching the modules.json file for an endpoint URL. (Pending migration from Notion.)

  1. To add a new card configuration: Add a new configuration object for the endpoint at the bottom of the array. Choose the card type that best suits your requirements.
    • If you are not sure what the endpoint URL is, the default card will show the URL.
    • Make an API call for your endpoint and view it on the dashboard to get the URL.
  2. Raise an MR for the change on GitLab.
  3. A validator job runs on MR creation and performs basic validations on the configuration added.
  4. Get the MR reviewed, approved, and merged.
    • Review requests can be raised in the #config-mr-approval channel.
    • If changing configs for a module and you're not the module owner, the module owner should review the MR.
    • If changing configs for a module you own, other module owners can review.
    • Approval can be granted by anyone with maintainer access to HV Central Config repository.
  5. Once the MR is merged, a sync pipeline is triggered.
  6. Once the sync pipeline passes, it takes a maximum of 15 minutes for your changes to be reflected.

How do I test my changes?​

  1. Once the sync pipeline passes, wait 15 minutes for changes to take effect.
  2. Then:
    • If there are existing API calls for this endpoint, view any transaction which has this API call and the changes should reflect there.
    • If there are no existing API calls, make a request for an internal App ID and view the card in case management.

3. Common issues & fixes​

  1. Configuration changes take 15 minutes to reflect from the time the sync pipeline passes, not from when the MR is merged.
  2. Configuration for an endpoint is global — changes apply to all clients, not a specific one.
  3. If the API response contains an S3 URL and the media is not being displayed, the URL may have expired (each S3 URL is only valid for 15 minutes from generation). Enable refreshSupportedS3URLs to refresh these.

FAQs​

Q: How long does it take for the changes to come into effect? A: Maximum of 15 minutes from the time the pipeline passes.

Q: How do I test my changes before pushing them to production? A: Currently, there is no way to test changes before pushing to production.

Q: I set refreshSupportedS3URLs to yes but the URLs are not being refreshed. Is this a bug? A: We only support refreshing URLs from the Audit Portal bucket. Verify the URLs are from prod-audit-portal-<region>. Also check the environment — prod backend refreshes prod bucket URLs, dev backend refreshes dev bucket URLs. If everything checks out, reach out to the audit portal team for further debugging.

Was this helpful?
Ask AI

Ask anything about the internal documentation

AI answers are based on internal documentation. Verify critical information.