# Saved Search Completed

Users can to subscribe to Saved Searches and receive an email of a report generated from the saved search. For example, a user can save a search query called "Identities with upcoming end dates" and create a subscription to receive a daily report showing identities with an end date within 10 days from the current date. This event trigger can also notify an external HTTP application that a report generated from a saved search subscription is available to be processed.

Flow

When an external application is notified that a report is available to be processed, the application can:

  • Perform Quality Control, such as continuously checking for Separation of Duties (SOD) violations
  • Respond to upcoming Joiner-Mover-Leaver scenarios, such as deprovisioning access before an employee's separation date.

This event trigger provides an extensible way to automatically process report results instead of through an emailed report that contains manual actionable items.


# Getting Started

# Prerequisites

  • Saved searches configured
  • Saved search subscriptions configured
  • To set up saved search subscriptios through the UI, see Compass (opens new window)
  • To set up through APIs, see Scheduled Search APIs
  • an oAuth Client to set up the trigger subscription
    • configured with Authority as ORG_ADMIN with the following options:
      • grant_type: Authorization Code
      • Personal Access Token

# In This Topic


# Event Context

Saved Search Completed events occur based on the schedules set for saved search subscriptions. For example, if you have a scheduled saved search for Monday, Tuesday, Wednesday, Thursday, Friday at 6:00 GMT, this is when your HTTP endpoint will also receive a notification. This can be set using the schedule object with v3/scheduled-search/scheduledsearchcreate

To receive this event when a saved search query does not have any results, set emailEmptyResults to TRUE.

Set the expiration date in the expiration field within the schedule object. Your HTTP endpoint will stop receiving these events when the Scheduled Search expires.

To view the idn:saved-search-complete trigger, call the /beta/triggers API.

curl --request GET --url 'https://{tenant}.api.identitynow.com/beta/triggers' --header 'authorization: Bearer {access_token}'

# Trigger Type

This event trigger type is a FIRE_AND_FORGET type. When you subscribe to this event trigger with your HTTP endpoint, a response is not expected to be returned.

# Input Schema

The input schema defines what you will receive from the trigger service. Here is input example provided by the trigger:

{
   "fileName":"Modified.zip",
   "ownerEmail":"test@sailpoint.com",
   "ownerName":"Cloud Support",
   "query":"modified:[now-7y/d TO now]",
   "searchName":"Modified Activity",
   "searchResults":{
      "Identity":{
         "count":"2",
         "noun":"identities",
         "preview":[
            [
               "Display Name",
               "First Name",
               "Last Name",
               "Work Email",
               "Created",
               "Lifecycle State"
            ],
            [
               "Carol Shelby",
               "Carol",
               "Shelby",
               "carol.shelby@sailpoint.com",
               "2019-11-14T15:56:00.862Z",
               ""
            ],
            [
               "Jack Roush",
               "Jack",
               "Roush",
               "jack.rousha@sailpoint.com",
               "2019-11-14T15:56:00.862Z",
               ""
            ]
         ]
      },
      "Entitlement":{
         "count":"2",
         "noun":"entitlements",
         "preview":[
            [
               "Display Name",
               "Name",
               "Description",
               "Source ID",
               "Source Name",
               "Attribute",
               "Value",
               "Privileged",
               "Tags"
            ],
            [
               "Administrator",
               "Administrator",
               "Full administrative access to IdentityNow",
               "2c91808a6e236e33016e6a91f61e3b32",
               "IdentityNow",
               "assignedGroups",
               "ORG_ADMIN",
               "false",
               ""
            ],
            [
               "Auditor",
               "Auditor",
               "Auditor access to IdentityNow",
               "2c91808a6e236e33016e6a91f61e3b32",
               "IdentityNow",
               "assignedGroups",
               "AUDITOR",
               "false",
               ""
            ]
         ]
      },
      "Account":{
         "count":"3",
         "noun":"accounts",
         "preview":[
            [
               "Account Name",
               "Native Account ID",
               "Source Name",
               "Identity Name",
               "Extended Attributes",
               "Tags"
            ],
            [
               "Stacy.Warner",
               "Stacy.Warner",
               "House Staff",
               "Stacy.Warner",
               "mail\u003dstacy@house.com,teletexTerminalIdentifier\u003dteletexTerminalIdentifier,postalCode\u003d78726,carLicense\u003d[carLicense],telexNumber\u003dtelexNumber,employeeNumber\u003d681497,postOfficeBox\u003dpostOfficeBox,registeredAddress\u003dregisteredAddress,pager\u003dpager,msRTCSIP-UserEnabled\u003dfalse,mailNickname\u003dmailNickname,LyncPinSet\u003dLyncPinSet,physicalDeliveryOfficeName\u003dabc,sAMAccountName\u003dStacy.Warner,initials\u003dHH,msNPAllowDialin\u003dmsNPAllowDialin,givenName\u003dStacy,homePhone\u003d512-942-7578,objectClass\u003d[objectClass],destinationIndicator\u003ddestinationIndicator,postalAddress\u003dpostalAddress,internationaliSDNNumber\u003dinternationaliSDNNumber,departmentNumber\u003dLegal,objectSid\u003dobjectSid,LyncPinLockedOut\u003dLyncPinLockedOut,pwdLastSet\u003dpwdLastSet,msNPCallingStationID\u003d[msNPCallingStationID],msRADIUSFramedIPAddress\u003dmsRADIUSFramedIPAddress,preferredLanguage\u003dpreferredLanguage,roomNumber\u003droomNumber,telephoneNumber\u003d512-942-7578,displayName\u003dStacy Warner,distinguishedName\u003dDN\u003dStacy Warner,title\u003dtitle,seeAlso\u003dseeAlso,uid\u003duid,secretary\u003dsecretary,street\u003dstreet,objectguid\u003d125,memberOf\u003d[Diagnostics],msExchHideFromAddressLists\u003dfalse,sn\u003dWarner,department\u003ddepartment,userPrincipalName\u003duserPrincipalName,idNowDescription\u003d391ff9c367aa90a0e1a0c6c174aa1d3dec1d3071148e0e62827858a562397224,st\u003dst,manager\u003dCN\u003dLisa.Cuddy,ou\u003d[ou],mobile\u003d512-942-7578,primaryGroupDN\u003dprimaryGroupDN,cn\u003dStacy.Warner,facsimileTelephoneNumber\u003d[512-942-7578],l\u003dl,homeMDB\u003dhomeMDB,homePostalAddress\u003d11305 Four Points Blvd,SipAddress\u003dSipAddress,o\u003do,accountFlags\u003d[accountFlags],employeeType\u003dFull Time,preferredDeliveryMethod\u003dpreferredDeliveryMethod,primaryGroupID\u003dprimaryGroupID,businessCategory\u003dLegal,RegistrarPool\u003dRegistrarPool,msDS-PrincipalName\u003dmsDS-PrincipalName,msRADIUSFramedRoute\u003d[msRADIUSFramedRoute],msRADIUSCallbackNumber\u003dmsRADIUSCallbackNumber",
               ""
            ],
            [
               "Lisa.Cuddy",
               "Lisa.Cuddy",
               "House Staff",
               "Lisa.Cuddy",
               "mail\u003djames@house.com,teletexTerminalIdentifier\u003dteletexTerminalIdentifier,postalCode\u003d78726,carLicense\u003d[carLicense],telexNumber\u003dtelexNumber,employeeNumber\u003d681497,postOfficeBox\u003dpostOfficeBox,registeredAddress\u003dregisteredAddress,pager\u003dpager,msRTCSIP-UserEnabled\u003dfalse,mailNickname\u003dmailNickname,LyncPinSet\u003dLyncPinSet,physicalDeliveryOfficeName\u003dabc,sAMAccountName\u003dLisa.Cuddy,initials\u003dHH,msNPAllowDialin\u003dmsNPAllowDialin,givenName\u003dLisa,homePhone\u003d512-942-7578,objectClass\u003d[objectClass],destinationIndicator\u003ddestinationIndicator,postalAddress\u003dpostalAddress,internationaliSDNNumber\u003dinternationaliSDNNumber,departmentNumber\u003dAdministration,objectSid\u003dobjectSid,LyncPinLockedOut\u003dLyncPinLockedOut,pwdLastSet\u003dpwdLastSet,msNPCallingStationID\u003d[msNPCallingStationID],msRADIUSFramedIPAddress\u003dmsRADIUSFramedIPAddress,preferredLanguage\u003dpreferredLanguage,roomNumber\u003droomNumber,telephoneNumber\u003d512-942-7578,displayName\u003dLisa Cuddy,distinguishedName\u003dDN\u003dLisa Cuddy,title\u003dtitle,seeAlso\u003dseeAlso,uid\u003duid,secretary\u003dsecretary,street\u003dstreet,objectguid\u003d125,memberOf\u003d[Administration],msExchHideFromAddressLists\u003dfalse,sn\u003dCuddy,department\u003ddepartment,userPrincipalName\u003duserPrincipalName,idNowDescription\u003d0fb7bb4cb6c086640ef098f5dd36c5c42500e3a60a116ea936f284a4f70cf45b,st\u003dst,manager\u003dCN\u003dLisa.Cuddy,ou\u003d[ou],mobile\u003d512-942-7578,primaryGroupDN\u003dprimaryGroupDN,cn\u003dLisa.Cuddy,facsimileTelephoneNumber\u003d[512-942-7578],l\u003dl,homeMDB\u003dhomeMDB,homePostalAddress\u003d11305 Four Points Blvd,SipAddress\u003dSipAddress,o\u003do,accountFlags\u003d[accountFlags],employeeType\u003dFull Time,preferredDeliveryMethod\u003dpreferredDeliveryMethod,primaryGroupID\u003dprimaryGroupID,businessCategory\u003dAdministration,RegistrarPool\u003dRegistrarPool,msDS-PrincipalName\u003dmsDS-PrincipalName,msRADIUSFramedRoute\u003d[msRADIUSFramedRoute],msRADIUSCallbackNumber\u003dmsRADIUSCallbackNumber",
               ""
            ],
            [
               "Robert.Chase",
               "Robert.Chase",
               "House Staff",
               "Robert.Chase",
               "mail\u003drobert@house.com,teletexTerminalIdentifier\u003dteletexTerminalIdentifier,postalCode\u003d78726,carLicense\u003d[carLicense],telexNumber\u003dtelexNumber,employeeNumber\u003d681497,postOfficeBox\u003dpostOfficeBox,registeredAddress\u003dregisteredAddress,pager\u003dpager,msRTCSIP-UserEnabled\u003dfalse,mailNickname\u003dmailNickname,LyncPinSet\u003dLyncPinSet,physicalDeliveryOfficeName\u003dabc,sAMAccountName\u003dRobert.Chase,initials\u003dHH,msNPAllowDialin\u003dmsNPAllowDialin,givenName\u003dRobert,homePhone\u003d512-942-7578,objectClass\u003d[objectClass],destinationIndicator\u003ddestinationIndicator,postalAddress\u003dpostalAddress,internationaliSDNNumber\u003dinternationaliSDNNumber,departmentNumber\u003dDiagnostics,objectSid\u003dobjectSid,LyncPinLockedOut\u003dLyncPinLockedOut,pwdLastSet\u003dpwdLastSet,msNPCallingStationID\u003d[msNPCallingStationID],msRADIUSFramedIPAddress\u003dmsRADIUSFramedIPAddress,preferredLanguage\u003dpreferredLanguage,roomNumber\u003droomNumber,telephoneNumber\u003d512-942-7578,displayName\u003dRobert Chase,distinguishedName\u003dDN\u003dRobert Chase,title\u003dtitle,seeAlso\u003dseeAlso,uid\u003duid,secretary\u003dsecretary,street\u003dstreet,objectguid\u003d125,memberOf\u003d[Diagnostics],msExchHideFromAddressLists\u003dfalse,sn\u003dChase,department\u003ddepartment,userPrincipalName\u003duserPrincipalName,idNowDescription\u003d820ff29573b916d9630205e4cae9a21061284a2866981433c9ef012f644ea326,st\u003dst,manager\u003dCN\u003dGreg.House,ou\u003d[ou],mobile\u003d512-942-7578,primaryGroupDN\u003dprimaryGroupDN,cn\u003dRobert.Chase,facsimileTelephoneNumber\u003d[512-942-7578],l\u003dl,homeMDB\u003dhomeMDB,homePostalAddress\u003d11305 Four Points Blvd,SipAddress\u003dSipAddress,o\u003do,accountFlags\u003d[accountFlags],employeeType\u003dFull Time,preferredDeliveryMethod\u003dpreferredDeliveryMethod,primaryGroupID\u003dprimaryGroupID,businessCategory\u003dDiagnostics,RegistrarPool\u003dRegistrarPool,msDS-PrincipalName\u003dmsDS-PrincipalName,msRADIUSFramedRoute\u003d[msRADIUSFramedRoute],msRADIUSCallbackNumber\u003dmsRADIUSCallbackNumber",
               ""
            ]
         ]
      }
   },
   "signedS3Url":"https://sptcbu-org-data-useast1.s3.amazonaws.com/arsenal-john/reports/Events%20Export.2020-05-06%2018%2759%20GMT.3e580592-86e4-4953-8aea-49e6ef20a086.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200506T185919Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=AKIAV5E54XOGTS4Q4L7A%2F20200506%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=2e732bb97a12a1fd8a215613e3b90fcdae8ba1fb6a25916843ab5b51d2ddefbc"
}
  • searchName - The name of the saved search which completed.
  • query - The query that was executed.
  • ownerName - The name of the identity for the saved search's owner.
  • ownerEmail - The email of the identity for the saved search's owner.
  • fileName - A file name for the downloaded report to be downloaded from.
  • signedS3Url - A signed URL where the saved search results can be downloaded from.
  • searchResults - A preview of the search results for each object type. This includes a count as well as headers, and the first several rows of data, per object type.

The preview only shows up to 20 objects per type, such as Identity or Entitlement.

To retrieve the search results, the link to the report is under signedS3Url. This link will expire 1 hour after receiving the notification.

The report is in .csv format and compressed into .zip.

An example of the report looks like this:

Display Name,First Name,Last Name,Work Email,Created,Lifecycle State
Cloud Support,Cloud,Support,support@testmail.identitysoon.com,2019-11-14T15:39:43.513Z,
Cloud Supportone,Cloud,Supportone,support.one@testmail.identitysoon.com,2019-11-14T15:39:43.541Z,

# Subscribe to the Trigger

To subscribe to the Saved Search Event Trigger, make a POST call to /beta/trigger-subscriptions with the following headers and body:

Headers:

  • Authorization: Bearer <access_token>

Body:

{ 
   "triggerId":"idn:saved-search-complete",
   "type":"HTTP",
   "httpConfig":{ 
      "url":"https://urlOfTheExternalService.com",
   }
}

By default, your subscription will receive all Saved Searches. To only subscribe to certain Save Searches, consider using a filter:

$[?($.searchName == "Modified Activity")]

Filters follow the Goessner JSON Path (opens new window).

# Testing Tools

  • webhook.site (opens new window) - This tool creates a temporary HTTP endpoint for you to verify that you are able to successfully subscribe to the Event Trigger. You can receive the event after an access request has been submitted. Copy the "unique URL" from webhook.site and use it in the url field of the POST body to /beta/trigger-subscriptions.
  • localhost.run - This tool creates an endpoint for a HTTP server running on your local machine.