Gentrack Integration Resources

Connecting a Core System

On this page

Linking your instance of Gentrack Velocity or Junifer to GCIS allows real time events to be published to your connectors and custom integrations.

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 to Installing the Data Gateway for details.

Register a tenant

Note: The process you follow depends on whether a Data Gateway is used for the integration.

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

  2. In the Integration 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 - Full URL of the API server of Junifer or Velocity. This URL needs to be accessible by GCIS or Data Gateway if a Data Gateway is used for the integration.
    • Use Gentrack Cloud identity authentication - Only supported by Velocity. When turned ON, a service user will NOT be required to connect to the Core System, and Username and Password fields will be disabled. Check with your CSM whether this feature is supported.
    • Username and Password - The API user credential of the Core System. Leave empty if API authentication is not enforced in Junifer. For Velocity, the API user’s role must have permission to the class PUS:USER and to all the classes to be called via Soap API or Rest API in your application. For either Junifer or Velocity, you must first verify that you can use the provided user credentials to call the Core system API directly. When selecting a role for the API user, the principle of least privilege must be applied, i.e., the user should only be given the access to the business area of the core system required by the application.
    • Tenant is hosted in Gentrack Cloud - OFF when a Data Gateway is used for the integration.
    • Data Gateway URL - Full URL of the Data Gateway. Only applicable when a Data Gateway is used for the integration.
    • Verify SSL certificate - When turned ON, GCIS will verify that a Data Gateway’s SSL certificate is issued by a CA when connecting to the Data Gateway. Only applicable when a Data Gateway is used for the integration. It is recommended to install a valid CA signed SSL certificate on your Data Gateway and turn on this option to ensure security of the communication between GCIS and your Data Gateway.

  5. Click Connect Tenant.

  6. Copy the generated Event Subscriber URL. Only applicable when a Data Gateway is used for the integration.

  7. Enable Billing under Services. Copy Client ID and Client Secret for later GCIAM configuration in the Core System.

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

  1. Add an event subscriber. For instructions, see Creating a new subscriber and use the following settings:

    • Name - Integration Services
    • GCIAM Authentication - Select if Junifer is configured to use GCIAM for authentication. The following configuration properties are required for Junifer to use GCIAM for authentication.
      • gciam_endpoint - https://uk.id.gentrackcloud.com/v1/token or https://au.id.gentrackcloud.com/v1/token depending on the Sovereignty Regions. Refer to Issue machine token for details.
      • gciam_tenantid - Tenant Id that is created in step 3 in Register a tenant in the Integration Portal.
      • gciam_username - Client ID of the Billing service that is created for the tenant in step 7 in Register a tenant in the Integration Portal.
      • gciam_password - Client Secret of the Billing service that is created for the tenant in step 7 in Register a tenant in the Integration Portal.
    • Delivery URL
      • If GCIAM Authentication is enabled: https://api-uk.integration.gentrack.cloud/v1/events or https://api-au.integration.gentrack.cloud/v1/events depending on the Sovereignty Regions.
      • Otherwise, use the Data Gateway Event Subscriber URL from step 6 in Register a tenant.
    • Event Subscriptions - Add event subscriptions for all relevant events including Bill Accepted, Payment Accepted, and so on.

  2. Test the event subscriber to confirm that the test event is successfully delivered. For instructions, see Testing a subscriber.

  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 - Integration Services
    • Notify Contact - If you want to receive notifications of connection failures, enter your email address
    • Send URL
      • If Gentrack Cloud Credentials is configured: https://api-uk.integration.gentrack.cloud or https://api-au.integration.gentrack.cloud depending on the Sovereignty Regions.
      • Otherwise, use the Data Gateway Event Subscriber URL from step 6 in Register a tenant.
    • Send Procedure - Select the one that contains Integration Platform or Integration Services.
    • Send Retry Interval - 2 minutes
    • Send Logging Enabled - Leave disabled unless there are errors that require troubleshooting.

  8. Click Finish.

Configure Gentrack Cloud Credentials

Note: This is NOT required if a Data Gateway is used for the integration.

  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 Gentrack Cloud Credentials.

  4. In the Configuration Options list, click CLOUD.CREDENTIALS

  5. Click Finish. The Gentrack Cloud Credentials screen displays.

  6. Click the Maintain Gentrack Cloud Credentials and fill the following fields:

    • Token URL - https://uk.id.gentrackcloud.com/v1/token or https://au.id.gentrackcloud.com/v1/token depending on the Sovereignty Regions. Refer to Issue machine token for details.
    • Client Id - Client ID of the Billing service that is created for the tenant in step 7 in Register a tenant in the Integration Portal.
    • Client Secret - Client Secret of the Billing service that is created for the tenant in step 7 in Register a tenant in the Integration Portal.
    • Tenant Id - Tenant Id of the Tenant in GCIS that was created in step 3 in Register a tenant in the Integration Portal.

  7. Click Finish.

Test Connection to Core System

You can validate the connection between GCIS and your Core System by using Test Connection functionality. The check includes:

  • Test the network connectivity from GCIS to the Core System. 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 Integration Portal as a user with administrator access.

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

  3. Click the tenant to open tenant details page.

  4. Click the Test Connection button in the Connection Details section.

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

Heartbeat of Data Gateway

To monitor health of your Data Gateway, navigate to the Tenant details page. The Connection Details section includes:

  • Version - The current version of the Data Gateway.
  • Last Heartbeat - The last time the Data Gateway successfully sent a heartbeat message to GCIS. Data Gateway sends heartbeat messages every 30 minutes. A warning icon will be displayed if no heartbeat message is received by GCIS in more than 30 minutes.

Disconnect Tenant

In the cases where you want to temporarily disable the connection to your Core System or when you want to switch to a different GCIS Data Gateway, you can choose to Disconnect a tenant:

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

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

  3. Click the tenant to open tenant details page.

  4. Click the Disconnect button in the Connection Details section.

  5. Confirm by clicking Disconnect.

Last updated on 7 May 2024