The event-listener feature allows you to listen and react to events originating from external services/apps.
To create a new event listener, you can click on the + next to the Event Listeners category in the resource tree. When you do, you'll be asked to select the app (service) you want to start listening for events from. After confirming which app you would like to work with, you're taken to a screen and asked for the following information:
- Event Type
You must select which event type you want to listen to. Event types are specific to the app you have selected.
- Linked Script
You'll get to either create a new script as part of the setup of the event listener by specifying a name for the new script, or link an existing one. We recommend creating a new script because the new script will be generated with the appropriate TypeScript event type you selected. If you link an existing script, then it's up to you to ensure that the TypeScript's event type is correct. If the type is incorrect, the editor will display incorrect suggestions.
(Global) connector to link with the event listener. Most of the time, this is not mandatory, but we recommend doing it anyway because then it logically relates the incoming event listener to a (global) connector, which can help you increase visibility of how connectors are being used. Most of the time, we'll provide a bit nicer setup instructions if the connector is linked.
After you save the event listener for the first time, most of the time you'll receive final setup instructions, which basically ask you to register a webhook in the external service/app.
You don't have to set up the event listener right away, but you can always come back to the event listener and click View setup instructions to finalize the setup.
You technically can configure more than one event listener to trigger the same script, but in this case, please be mindful that the script logic and the event type need to account for potentially having to process more than a single event type.
When you create a new environment, you'll be asked to link the connector again and go through the setup instructions again (if required) to register the event listener in the context of your new environment.
You cannot create a new deployment and have it deployed to the (new) environment until that environment has all the event listeners gone through a setup.
Test Event Payloads
Testing your script by triggering event listeners externally (from the external service/app) can be time-consuming. To increase productivity, you can register a dummy event to trigger your event listeners internally without ever leaving the ScriptRunner Connect app.
You have to save the event listener at least once to be able to configure the test event payload.
You can configure the dummy event by opening the event listener and then going to the Test Event Payloads tab. You'll get a dummy template that is already created for you. Modify it to suit your needs, and when you're ready, click the play button in the event listener node in the resource tree to trigger your event listener with the dummy event. You can create as many dummy events as you like.
- The event payload that remains selected in the Test Event Payloads tab will be the default event payload that will get triggered. To change the default selection, return to the Test Event Payloads tab, select a new event payload, and confirm the selection.
- If the default event payload that we provide is not accurate enough to start from, you can always trigger the event listener externally and have the event logged out into the console by your script, which you can then copy-paste into the payload window and use it as the dummy event.