Use the filelisteners resource to create, update, delete, run a file listener, and change the owner of a file listener association from one user to another. Informatica Intelligent Cloud Services can use file listeners to monitor specific folders. Informatica Intelligent Cloud Services are notified by using a call-back API when new files arrive at a monitored folder and when files in the folder are updated or deleted.
Consider the following when you use the filelisteners resource:
Note: If you use a tool such as Postman that automatically includes the HTTP version, do not enter the HTTP version in the URL. If the HTTP version appears twice in the URL, the request fails.
Complete the following tasks to run and monitor file listeners:
•Send a GET request to view details of a file listener. See View file listener.
Use the GET request to view file listeners details. You can view the details for a particular file listener or view details for all file listeners in your organization.
GET request
To view the details of a particular file listener, include the file listener ID in the following URI:
Get <serverUrl>/mftsaas/api/v1/filelisteners/<filelistener ID>
To view the details for all of the file listeners in the organization, omit the file listener ID.
GET response
A request for file listener details returns the following information:
Field
Type
Description
id
String
ID number associated with the file listener.
name
String
Name of the file listener.
description
String
Description of the file listener.
status
String
Status of the file listener.
- enabled. Listens to files on the designated folder.
disabled. Does not listen to files on the designated folder.
agentGroup
Numeric
Runtime environment that contains the Secure Agent used to run the file listener.
type
String
Type of the connection to which the file listener listens.
connection
String
Connection to which the file listener listens.
folderPath
String
Path to the folder on the connection to which the file listener listens.
filePattern
String
File name pattern to which the file listener listens.
Post Action
String
Determines the action the file listener must perform after the file listener listens to the events.
You can select the post action as Delete only if the file pattern is an indicator file. Default is None.
The following connection types support the Post Action option:
- Local folder
- Advanced FTP V2
- Advanced FTPS V2
- Advanced SFTP V2
- Azure Data Lake Store Gen2
patternType
String
The file pattern.
- wildcard. Use wildcard patterns of file name.
- regex. Use regular expression to match the file pattern. Consider the following examples:
- Use the following syntax to listen to all files except for files with a name that contains out, foo, and baz: ^(?!.*(?:out|baz|foo)).*$ à all except
- Use the following syntax to listen to all files with doc and docx, pdf extensions: ([a-zA-Z0-9\s_\\.\-\(\):])+(.doc|.docx|.pdf)$ à
- indicator file. Use the file name to which the file listener listens.
mandatory
String
Defines whether rule values are mandatory.
recursive
String
Defines whether rule values are recursive.
type
String
Frequency at which the file listener runs, daily, weekly, or monthly.
timezone
String
Time zone that refers to the start and end time.
startDate
Date/Time
Date on which the file listener starts running.
endDate
Date/Time
Date until which the file listener runs.
runIndefinitely
String
Whether the file listener runs without an end date.
startsAt
Date/Time
Time of day when the file listener starts running.
endsAt
Date/Time
Time of day when the file listener stops running.
frequency
Numeric
Frequency at which the file listener checks for files in the folder.
frequencyUnit
String
Unit of frequency to which file listener checks for files in the folder, by seconds, minutes, or hours.
listenerEvents
String
Determines when the file listener sends notifications to the services that are registered to it. Response to each event when the event is set to true is as follows:
- arrive. Send notifications when files arrive at the folder to which the file listener listens.
- update. Send notifications when files in the folder to which the file listener listens are updated.
- delete. Send notifications when files in the folder to which the file listener listens are deleted.
stopWhenRulesMet
String
Whether the file listener stops listening to the folder when the listener rules are met. Set to one of the following values:
- false. The file listener notifies the registered application on events and continues to listen for subsequent events.
- true. The file listener stops listening to the folder when the first event of file deletion occurs in the folder.
checkFileStability
String
Enter one of the following values.
- false.The file listener does not verify whether the entire file is copied to the folder before notifying the registered services.
- true. The file listener verifies whether the entire file is copied to the folder before notifying the registered services.
Default is true.
stabilityCheckInterval
Time
Time in seconds that a file listener waits to check for file stability.
You can specify a value in the stabilityCheckInterval field only if the checkFileStability option is set to true.
notifyExistingFiles
String
The first time the file listener runs, it sends a notification if files exist in the folder to which it listens, of the parameter is set to true.
excludeFileEventsWhenNotRunning
String
Determines if you want to exclude file events that occur when a file listener is not running.
continueOnError
String
Determines if you want the file listener to continue to retry and run in case of failures, such as temporary network disruption.
location
String
Location of the project folder that contains the file listener component.
createTime
Date/Time
Time when the component was created.
lastupdateTime
Date/Time
Time when the component was last updated.
GET response example for one file listener
If your request to view file listener details of the file listener with ID eX5qlosUfEHbwvNwGpRwQd is successful, you might receive a response similar to the following example:
If the request to view all file listeners is unsuccessful, you might receive a response similar to the following example:
File Listener not found (403 Forbidden) { "responseCode": "NOT_FOUND", "message": "File Listener with id 'eX5qlosUfEHbwvNwGpRwQd1' not found." }
Create a file listener
Use a POST request to create a file listener and an event listener.
POST request
Use the following URI to create a file listener and an event listener:
POST <serverUrl>/mftsaas/api/v1/filelisteners
Use the following fields in the POST request:
Field
Type
Required
Description
name
String
Yes
Name of the file listener.
description
String
-
Description of the file listener.
status
String
Yes
Status of the file listener.
- enabled. Listens to files on the designated folder.
- disabled. Does not listen to files on the designated folder.
agentGroup
Numeric
Yes
Runtime environment that contains the Secure Agent used to run the file listener.
connectionType
String
Yes
Type of the connection to which the file listener listens.
connection
String
Yes
Connection to which the file listener listens.
folderPath
String
Yes
Path to the folder on the connection to which the file listener listens.
filePattern
String
Yes
File name pattern to which the file listener listens.
Post Action
String
-
Determines the action the file listener must perform after the file listener listens to the events.
You can select the post action as Delete only if the file pattern is an indicator file. Default is None.
The following connection types support the Post Action option:
- Local folder
- Advanced FTP V2
- Advanced FTPS V2
- Advanced SFTP V2
- Azure Data Lake Store Gen2
patternType
String
Yes
The file pattern.
- wildcard. Use wildcard patterns of file name.
- regex. Use regular expression to match the file pattern. Consider the following examples:
- Use the following syntax to listen to all files except for files with a name that contains out, foo, and baz: ^(?!.*(?:out|baz|foo)).*$ à all except
- Use the following syntax to listen to all files with doc and docx, pdf extensions: ([a-zA-Z0-9\s_\\.\-\(\):])+(.doc|.docx|.pdf)$ à
- Indicator File. Use the file name to which the file listener listens.
mandatory
String
-
Defines whether rule values are mandatory.
recursive
String
-
Defines whether rule values are recursive.
scheduleDefinition
String
Yes
Defines the frequency in which the file listener must run.
type
String
Yes
Frequency at which the file listener runs, daily, weekly, or monthly.
timezone
String
Yes
Time zone that refers to the start and end time.
startDate
Date/Time
Yes
Date on which the file listener starts running.
endDate
Date/Time
Yes
Date until which the file listener runs.
runIndefinitely
String
-
The file listener runs without an end date.
startsAt
Date/Time
Yes
Time of day when the file listener starts running.
endsAt
Date/Time
Yes
Time of day when the file listener stops running.
frequency
Numeric
Yes
Frequency at which the file listener checks for files in the folder.
frequencyUnit
String
Yes
Unit of frequency to which file listener checks for files in the folder, by seconds, minutes, or hours.
listenerEvents
String
Yes
Determines when the file listener sends notifications to the services that are registered to it. Response to each event, when the event is set to true is as follows:
- arrive. Send notifications when files arrive at the folder to which the file listener listens.
- update. Send notifications when files in the folder to which the file listener listens are updated.
- delete. Send notifications when files in the folder to which the file listener listens are deleted.
stopWhenRulesMet
String
-
The file listener stops listening to the folder when the listener rules are met.
- false. The file listener notifies the registered application on events and continues to listen for subsequent events.
- true. The listener stops listening to the folder when the first event of file deletion occurs in the folder.
checkFileStability
String
-
The file listener verifies that the entire file is copied to the folder before notifying the registered services.
stabilityCheckInterval
Time
-
Time in seconds that a file listener waits to check for file stability.
You can specify a value in the stabilityCheckInterval field only if the checkFileStability option is set to true.
notifyExistingFiles
String
-
The first time the file listener runs, it sends a notification if files exist in the folder to which it listens.
excludeFileEventsWhenNotRunning
String
-
Determines if you want to exclude file events that occur when a file listener is not running.
continueOnError
String
-
Determines if you want the file listener to continue to retry and run in case of failures, such as temporary network disruption.
emailIds
String
-
List of email addresses to send notifications if the file listener fails.
Use commas to separate email addresses in the list.
location
String
-
Location of the project folder that contains the file listener component.
POST request example
Use this sample as a reference to create a file listener.
Use the following URI to update an existing file listener.
PUT <server URL>/mftsaas/api/v1/filelisteners/<filelistener ID>
Use the following fields in the PUT request:
Field
Type
Required
Description
id
String
Yes
ID number associated with the file listener.
name
String
Yes
Name of the file listener.
description
String
-
Description of the file listener.
status
String
Yes
Status of the file listener.
- enabled. Listens to files on the designated folder.
- disabled. Does not listen to files on the designated folder.
agentGroup
Numeric
Yes
Runtime environment that contains the Secure Agent used to run the file listener.
connectionType
String
Yes
Type of the connection to which the file listener listens.
connection
String
Yes
Connection to which the file listener listens.
folderPath
String
Yes
Path to the folder on the connection to which the file listener listens.
filePattern
String
Yes
File name pattern to which the file listener listens.
Post Action
String
-
Determines the action the file listener must perform after the file listener listens to the events.
You can select the post action as Delete only if the file pattern is an indicator file. Default is None.
The following connection types support the Post Action option:
- Local folder
- Advanced FTP V2
- Advanced FTPS V2
- Advanced SFTP V2
- Azure Data Lake Store Gen2
patternType
String
Yes
The file pattern.
- wildcard. Use wildcard patterns of file name.
- regex. Use regular expression to match the file pattern. Consider the following examples:
- Use the following syntax to listen to all files except for files with a name that contains out, foo, and baz: ^(?!.*(?:out|baz|foo)).*$ à all except
- Use the following syntax to listen to all files with doc and docx, pdf extensions: ([a-zA-Z0-9\s_\\.\-\(\):])+(.doc|.docx|.pdf)$ à
mandatory
String
-
Defines whether rule values are mandatory.
recursive
String
-
Defines whether rule values are recursive.
scheduleDefinition
String
Yes
Defines the frequency in which the file listener must run.
type
String
Yes
Frequency at which the file listener runs, daily, weekly, or monthly.
timezone
String
Yes
Time zone that refers to the start and end time.
startDate
Date/Time
Yes
Date on which the file listener starts running.
endDate
Date/Time
Yes
Date until which the file listener runs.
runIndefinitely
String
-
The file listener runs without an end date.
startsAt
Date/Time
Yes
Time of day when the file listener starts running.
endsAt
Date/Time
Yes
Time of day when the file listener stops running.
frequency
Numeric
Yes
Frequency at which the file listener checks for files in the folder.
frequencyUnit
String
Yes
Unit of frequency to which file listener checks for files in the folder, by seconds, minutes, or hours.
listenerEvents
String
Yes
Determines when the file listener sends notifications to the services that are registered to it. Response to each event, when the event is set to true is as follows:
- arrive. Send notifications when files arrive at the folder to which the file listener listens.
- update. Send notifications when files in the folder to which the file listener listens, are updated.
- delete. Send notifications when files in the folder to which the file listener listens are deleted.
stopWhenRulesMet
String
-
The file listener stops listening to the folder when the listener rules are met.
- false. The file listener notifies the registered application on events and continues to listen for subsequent events.
- true. The listener stops listening to the folder when the first event of file deletion occurs in the folder.
checkFileStability
String
-
The file listener verifies that the entire file is copied to the folder before notifying the registered services.
stabilityCheckInterval
Time
-
Time in seconds that a file listener waits to check for file stability.
You can specify a value in the stabilityCheckInterval field only if the checkFileStability option is set to true.
notifyExistingFiles
String
-
The first time the file listener runs, it sends a notification if files exist in the folder to which it listens.
excludeFileEventsWhenNotRunning
String
-
Determines if you want to exclude the file events that occur when a file listener is not running.
continueOnError
String
-
Determines if you want the file listener to continue to retry and run in case of a failure, such as temporary network disruption.
emailIds
String
-
List of email addresses to send notifications if the file listener fails.
Use commas to separate email addresses in the list.
location
String
-
Location of the project folder.
PUT request example
Use this sample as a reference to update the file listener.
The responses vary based on the file listener status.
Change owner of a file listener association
A file listener can be associated with a taskflow or with file ingestion tasks. You can use file listener as a source or schedule(trigger) for file ingestion tasks and as a trigger for a taskflow. A file listener association is the internal link between file listener and its associated file ingestion tasks or taskflows. The owner of a file listener association is the last person who selected the file listener as a source or schedule in a file ingestion task or the last person who published the taskflow with the file listener as a trigger. You might want to change or transfer the owner of a file listener association when a user who owns the file listener association leaves the organization. For example, if the user Alex creates a file ingestion task, the user Beth creates a file listener, and the user Clara selects the file listener as a source or schedule in a file ingestion task, Clara is the owner of the file listener association. If Clara leaves the organization, you must reassign her assigned file listener associations to another user before you can delete her user account.
POST request
Use a POST request to change the owner of a file listener association from one user to an another.
Use the following URI to change the owner of a file listener association:
POST <serverUrl>/mftsaas/api/v1/ChangeCallbackOwnership
Use the following fields in the POST request:
Field
Type
Required
Description
currentOwner
String
Yes
User ID of the current owner.
newOwner
String
Yes
User ID of the new owner.
POST request example
Use this sample as a reference to change the owner of a file listener association.