Gentrack Support

Connecting a Core System

Linking your instance of Gentrack Velocity or Junifer to Gentrack Cloud Integration Services allows real time events to be published to your connectors and custom integrations. For self-hosted customers, connection to Gentrack Cloud Integration Services will be via a Data Gateway which will act as a communication broker for your instance of Velocity or Junifer.

Before you begin

Self-hosted customers should have a Data Gateway component installed and recommended security measures have been implemented to stop unauthorised access. Refer Installing the Data Gateway.

Connecting to Gentrack Cloud Integration Services

To connect your Velocity or Junifer system to Gentrack Cloud Integration Services, complete the following tasks:

Register a tenant

The process you follow depends on how your system is hosted.

Register a tenant in a Gentrack Cloud hosted environment

  1. Log into the Developer Portal as a user with administrator access.

  2. In the Developer Portal open the Tenants page from the Manage Access section.

  3. Click Add Tenant and enter a unique name such as Development or Production. This may take several seconds as the security keys are generated. A new Tenant Id is displayed.

  4. Click Connect tenant button and fill out the form with the following settings:

    • Product type - Junifer or Velocity
    • Core Product URL - Web service URL of the environment to connect to. For example, Junifer: http://[servername]:43002/, where [servername] is the hostname or IP address.
    • Use Gentrack Cloud identity authentication - GCIS will use internal app credentials instead of service user to connect to Core System. When this toggle is selected, Username and Password fields will be disabled. Junifer does not currently support this feature.
    • Username and Password - Used for API authentication and must match an existing API user of the Core System. Not all Junifer instances currently enforce API authentication but this will become mandatory in the future.
    • Tenant is hosted in Gentrack Cloud - Toggle should be selected.
  5. Click Connect Tenant.

The data you entered is validated by performing a complete trip between Gentrack Cloud and Core System. An error will be displayed if the connection was unsuccessful, resubmit the form once the information has been corrected.

Register a tenant in a self-hosted environment

  1. Log into the Developer Portal as a user with administrator access.

  2. In the Developer Portal open the Tenants page from the Manage Access section.

  3. Click Add Tenant and enter a unique name such as Development or Production. This may take several seconds as the security keys are generated. A new Tenant Id is displayed.

  4. Click Connect tenant button and fill out the form with the following settings:

    • Product type - Junifer or Velocity
    • Core Product URL - Web service URL of the environment to connect to. For example, Junifer: http://[servername]:43002/, where [servername] is the hostname or IP address.
    • Use Gentrack Cloud identity authentication - GCIS will use internal app credentials instead of service user to connect to Core System. When this toggle is selected, Username and Password fields will be disabled. Junifer does not currently support this feature.
    • Username and Password - Used for API authentication and must match an existing API user of the Core System. Not all Junifer instances currently enforce API authentication but this will become mandatory in the future.
    • Tenant is hosted in Gentrack Cloud - Toggle should be deselected for a self-hosted environment.
    • Data Gateway URL - Full URL of the Data Gateway web server e.g. https://gateway.integration.gentrack.cloud
  5. Click Connect Tenant.

  6. Copy the generated Event Subscriber URL.

The data you entered is validated by performing a complete trip between Gentrack Cloud, Data Gateway, and Core System. If successful, the form will display the Event Subscriber URL that you will need for the next section. Otherwise an error will be displayed, resubmit the form once the information has been corrected.

To link your instance of Junifer to Gentrack Cloud Integration Services, the Data Gateway must be added as an API event subscriber in Junifer.

  1. Add Data Gateway as an event subscriber. For instructions, see Creating a new subscriber in How to manage API event subscribers and subscriptions - Use the following settings:

    • Name
      • Hosted in Gentrack Cloud: Integration Services
      • Self-hosted: Integration Services - Data Gateway
    • Delivery URL
      • Hosted in Gentrack Cloud:
        • European region - https://api-uk.integration.gentrack.cloud
        • Asia Pacific region - https://api-au.integration.gentrack.cloud
      • Self-hosted: Event Subscriber URL (see step 6 in Register a tenant in a self-hosted environment)
    • Event subscriptions - Add event subscriptions for all relevant events including Bill Accepted, Payment Accepted, and so on.Ping Event is not required
  2. Test the Data Gateway subscriber to confirm that the test event is successfully delivered. For instructions, see Testing a subscriber in How to manage API event subscribers and subscriptions.

Data Gateway or Gentrack Cloud will now receive the events you have subscribed to.

You must add the Data Gateway as a messaging service in Velocity.

  1. Log in to Velocity as a system administrator.

  2. Go to Gentrack Launch Pad > Configuration Search. The Search for a Configuration Option screen displays.

  3. In Search Term, type interface.

  4. In the Configuration Options list, click FILEMANAGER.MESSAGESERVICE

  5. Click Finish. The Interface Message Service screen displays.

  6. Click the Create Message Service action. The Create Message Service screen displays.

  7. Fill out the fields with the following values:

    • Service ID - GCIS
    • Service Name
      • Hosted in Gentrack Cloud: Integration Services
      • Self-hosted: Integration Services - Data Gateway
    • Notify Contact - If you want to receive notifications of connection failures, enter your email address
    • Send URL
      • Hosted in Gentrack Cloud:
        • European region - https://api-uk.integration.gentrack.cloud
        • Asia Pacific region - https://api-au.integration.gentrack.cloud
      • Self-hosted: Event Subscriber URL (see step 6 in Register a tenant in a self-hosted environment)
    • Send Procedure - Integration Services - Data Gateway
    • Send Retry Interval - 2 minutes
    • Send Logging Enabled - Leave disabled unless there are errors that require troubleshooting.
  8. Click Finish.

For customers hosted in Gentrack Cloud, your Customer Success Team will work with you to save the required Gentrack Cloud credentials in your Velocity instance to allow it to publish events directly to Gentrack Cloud.

For self-hosted customers, your Velocity instance will now begin to publish events which will be received by the Data Gateway.

Test Connection to Core Billing System

You can validate that connection between Gentrack Cloud Integration Services and your Core System has been successfully established by using Test connection functionality. The check includes:

  • Test the network connectivity from GCIS to the Core System. For customers hosted in Gentrack Cloud, GCIS will connect to the Core System directly. For self-hosted customers, GCIS will connect to the Core System via your Data Gateway. The test does not cover the network connectivity from the Core System to GCIS.

  • Test API call to the Core System using the API credentials supplied when you Connect Tenant.

To perform the connection test:

  1. Log into the Developer Portal as a user with administrator access.

  2. In the Developer Portal open the Tenants page from the Manage Access section.

  3. Find the tenant from the tenant list.

  4. Click Test connection to core system icon.

  5. In a few seconds, you will see whether the connection test was successful or has failed. If the latter, click on the Connect tenant icon and make sure the information are correct.

Monitor Connection Status

Self-hosted customers

To monitor health of your Data Gateway, navigate to the Tenants page. The Connection Method column includes:

  • Version: The current version of the Data Gateway the tenant is connected to
  • Heart beat: The last time the Data Gateway successfully sent the heartbeat message to GCIS. Such a message is being sent every 30 minutes. If the heartbeat message have not been received within the last 30 minutes, a warning icon will be displayed.

Customers hosted in Gentrack Cloud

Tenants hosted in Gentrack Cloud will show a Connection Method of Direct on the Tenants page.

Disconnect Tenant

In the cases where you want to temporarily disable the connection to you core billing system or when you want to switch to a different GCIS data gateway, you can choose to disconnect a tenant:

  1. Log into the Developer Portal as a user with administrator access.

  2. In the Developer Portal open the Tenants page from the Manage Access section.

  3. Find the tenant from the tenant list.

  4. Click Disconnect tenant icon.

  5. Confirm by clicking Disconnect tenant.

Last updated on 16 Nov 2020