Use CX Industries Framework REST APIs to publish data from events to external applications. You publish event data to automatically notify external applications when specific events occur in your communications application. For example, when a customer purchases a product, your application sends the event data to your Customer Relationship Management (CRM) software. You can also use this data in your external analytics and reporting applications.

To do so, set the external applications as event listeners. You can also use the corresponding TMF API's hub instance to set up a listener.

For more information on TM Forum Open APIs and CX Industries Framework APIs, see Rest API for CX Industries Framework.

Here's how you can set up the event listeners in the respective TM Forum API's hub:

1. Create a payload for setting up the event listener with the details described in this table.

   Table 7-1 Payload for Setting Up Event Listeners

   Field	Description
   callback	The endpoint URL of the listener.
   query	The criteria used for determining the events that must be published to this listener. For setting the criteria, see the Gatekeeper Criteria topic in the Set Up Gatekeepers chapter.

   Here is the sample payload for setting up a custom tax engine as an event listener by using a TMF API's Hub:

   {
   "callback": "http://TAXATIONGW_IP:PORT",
   "query": "(/eventType eq "/event/TaxEvent3" or /eventType eq "/event/TaxEvent1" and "/event/TaxEvent3/ familyName" eq \"abc\")"
   }
   

   Here is the sample response payload with the listener ID:

   {
   "id": "listener-registration9tx8k", "callback": "http://TAXATIONGW_IP:PORT",
   "query": "(/eventType eq "/event/TaxEvent3" or /eventType eq "/event/TaxEvent1" and "/event/TaxEvent3/ familyName" eq \"abc\")"
   }
   

2. Call the corresponding TM Forum API by running this cURL command or by using a REST API client:

   curl -H Authorization: Bearer <accessToken> https://<hostName>/api/<pathParameter>/<apiName>/ <apiVersion>/hub -X POST -H "Content-Type: application/json" -d @lr-data.json

   where:

   • <accessToken> is the OAuth access token for your account or the HTTP basic authentication.
   • <hostName> is the URL for your API Gateway.
   • <pathParameter> is the path parameter for the production or test workspace, such as, 01 for the test workspace and 02 for the production workspace.
   • <apiName> is the name of the TMF Open API or the custom API that publishes the event data.
   • <apiVersion> is the version of the API.

   The API returns the response with the listener ID if the listener is added.

3. Specify the authentication credentials for authorizing access to the listener endpoint by doing the following:
   1. Create a payload with the OAuth or basic authentication credentials described in this table.

      Table 7-2 Creating a Payload with OAuth

      Field	Description
      User name	The user name for accessing the endpoint. Required for the HTTP basic authentication.
      Password	The password for accessing the endpoint. Required for the HTTP basic authentication.
      Identity URI	The URI from which your application retrieves an authorization token. Required for the OAuth authentication
      Client ID	The client ID your authorization server assigns to your application. Required for the OAuth authentication.
      Client Secret	The client secret assigned to your application and used to retrieve an authorization token. Required for the OAuth authentication.
      Scope	The OAuth scope that your application requests access to and that's granted with the token. Appears for the OAuth authentication.

   2. Call the listener Registrations API by using the cURL command or by using a REST API client:

      curl -H Authorization: Bearer <accessToken> https://<hostName>/admin/<pathParameter>/listenerRegistrations/<id> -X POST -H "Content-Type: application/json" -d @lr-data.json

      where:

      • <accessToken> is the OAuth access token for your account or the HTTP basic authentication.
      • <hostName> is the URL for your API Gateway.
      • <pathParameter> is the path parameter for the production or test workspace, such as, 01 for the test workspace and 02 for the production workspace. If you are calling the API using FA API Gateway, you can skip this parameter.
      • <id> is the unique identifier of the listener.

   Here is the sample payload with the OAuth credentials:

   [
   {
   "op": "replace",
   "path": "listenerRegistrations/listener-locality/external-listener/listener-auth", "value": {
   "oidc-client-credentials": {
   "identity-uri": "https://IDENTITY_URI", "client-id": "OIDC_CLIENT_ID",
   "client-secret": "OIDC_CLIENT_SECRET", "scope": "OIDC_SCOPE"
   }
   }
   }
   ]
   

   Here is the sample payload with the HTTP basic authentication credentials:

   [
   {
   "op": "replace",
   "path": "listenerRegistrations/listener-locality/external-listener/listener-auth", "value": {
   "basic": { "username": "admin", "password": "admin"
   }
   }
   }
   ]