bulkCleanupDigipass (Command)

Availability: OneSpan Authentication Server 3.27 and later
Scenario: Administration
Support: full-sdk

The bulkCleanupDigipass command searches for authenticators and/or authenticator instances based on a cleanup strategy (specified with the cleanupstrategy parameter) and applies a configurable action on them, for example, deleting them. Possible cleanup strategies are:

DigipassInstancesReusedPNID. Identifies all authenticator instances that have a reused DIGIPASS Push Notification Identifier (PNID) assigned. The PNID is considered reused if another authenticator instance for the same authenticator license exists, which uses the same PNID but has a higher sequence number.
DigipassInstancesWithoutPNID. Identifies all authenticator instances that have no DIGIPASS Push Notification Identifier (PNID) assigned and were never used (last authentication time is not set). The PNID is implicitly set when an authenticator instance is bound to a mobile app. The last authentication time is initially set when the authenticator instance is effectively activated. Having no PNID and no last authentication time set for an authenticator instance, indicates very likely that the activation of that particular instance was not completed.
DigipassNotAuthenticatedSince. Identifies all authenticators and authenticator instances that were not used at least once for a specified number of days (retention period). The usage is determined by the date and time the authenticator was used the last time for a successful authentication. It is only set and updated if the authenticator is assigned and used by the respective user.
DigipassDisabledSince. Identifies all authenticators and authenticator instances that have been disabled for a specified number of days (retention period). Authenticators and authenticator instances can be explicitly disabled by setting the authenticator status using the DIGIPASSCMD_UPDATE command.

Note that authenticator licenses are not processed or deleted by this command.

The command schedules a server task that processes the authenticators and authenticator instances in the specified search range. The search is done in blocks of 10,000 records. Unused authenticators and authenticator instances are disabled or deleted in blocks of 100 records per database transaction.

The server task generates a CSV report to provide a complete and detailed summary of the items that would be deleted or disabled. That report can be downloaded via reportfiledownloadmtom (Command) with the REPORTFILEFLD_REPORTFILE_ID attribute. To get that attribute value, use reportFileQuery (Command) with the task ID returned by bulkCleanupDigipass. If you set notify to Email, the CSV report is also attached to the notification mail.

Parameters

Table: bulkCleanupDigipass input parameters
Parameter name	Data type	Description
`sessionID`	String	Required. The session identifier of the current administrative session. The `logon` command returns this identifier after a successful logon (see logon (Command)).
`cleanupaction`	DigipassCleanupActionEnum	Optional. The action that should be applied to the items that were identified by the cleanup strategy (`cleanupstrategy`). An overview of the corresponding items is stored in the status information of the respective server task when completed. This parameter replaces `dryrun`. Possible values: deleteDP. All authenticators and authenticator instances that match the strategy will be deleted. disableDP. All authenticators and authenticator instances that match the strategy will be disabled. listDP. The command searches for authenticators and authenticator instances that match the strategy without modifying any data. Default value: listDP Availability: 3.29 and later
`cleanupstrategy`	DigipassCleanupStrategyEnum	Required. The strategy to determine the items that should be processed. Possible values: DigipassDisabledSince. DigipassInstancesReusedPNID. DigipassInstancesWithoutPNID. DigipassNotAuthenticatedSince.
`domain`	String	Optional. The domain to search for authenticators or authenticator instances to process. If omitted, all domains within the administrative scope of the session owner are searched.
`orgunit`	String	Optional. The organizational unit (OU) to search for authenticators or authenticator instances to process. If omitted, all organizational units within the administrative scope of the administrative session owner are searched.
`searchdownoupath`	Boolean	Optional. Specifies whether the specified organizational unit (OU) and all child OUs should be searched. If omitted and the search scope includes an OU, either implicitly because the administrative session owner is member of an OU or explicitly because `orgunit` is specified, this value is handled as true.
`age`	Unsigned Integer	Optional. The time period in days during which an authenticator must be used at least once to be considered active. Only applicable if `cleanupstrategy` is set to either DigipassDisabledSince or DigipassNotAuthenticatedSince. In these cases, the `age` attribute is mandatory. Possible values: 30–65536
`dryrun`	Boolean	Deprecated. Use `cleanupaction` instead. When set to true, the command behaves as if the `cleanupaction` parameter were set to listDP. When omitted or set to false, the command behaves as if the `cleanupaction` parameter were set to deleteDP. Availability: 3.28 and later (deprecated in 3.29)
`mode`	TaskModeEnum	Required. Specifies the server on which the task should run. Possible values: Specific. A specific server executes the task. Typically the server that is used to schedule the task. Any. Any server will execute the task, but only one server. For immediate non-scheduled tasks, this is typically the server that is used to schedule the task. For scheduled tasks a random server will run the task. All. All servers will execute the task, meaning the task will be run as many times as servers are available.
`schedule`	ScheduleChoice	Optional. Specifies the schedule that the task should run. You can also specify whether and how to notify the user when the task is completed with the `notify` parameter.
`notify`	TaskNotifyDeliveryMethodEnum	Optional. The notification delivery method to notify the user on completion of the task. The required contact information must be defined in the respective user account. This option is only effective if `schedule` is set. If omitted, the user will not be notified. Possible values: Email SMS

Table: bulkCleanupDigipass output parameters
Parameter name	Data type	Description
`status`	CommandStatusResponse	Required. The error stack, if applicable, which indicates that the command has not completed successfully. This also includes the result and status codes returned by the command.
`result`	BulkCleanupDigipassResult	Required. The output field for this command.

ScheduleChoice (Data type)

The ScheduleChoice data type contains of choice elements that define how the task should be scheduled. Only one of the choice elements can be specified.

Table: ScheduleChoice (Data type)
Element name	Data type	Description
`once`	ScheduleOnce	Required. A choice element that defines if and how the task should be scheduled to run once.
`daily`	ScheduleRecurrenceDaily	Required. A choice element that defines if and how the task should be scheduled to run on a daily basis.
`monthly`	ScheduleRecurrenceMonthly	Required. A choice element that defines if and how the task should be scheduled to run on a monthly basis.

ScheduleOnce (Data type)

Table: ScheduleOnce (Data type)
Element name	Data type	Description
`time`	DateTime	Required. The date and time to schedule the task to run once.

ScheduleRecurrenceDaily (Data type)

Table: ScheduleRecurrenceDaily (Data type)
Element name	Data type	Description
`time`	Time	Required. The time of the day to run the task.
`weekdays`	ScheduleRecurrenceWeekdays	Required. The days of the week to run the task. Each day is a boolean value.

ScheduleRecurrenceMonthly (Data type)

Table: ScheduleRecurrenceMonthly (Data type)
Element name	Data type	Description
`time`	Time	Required. The time of the day to run the task.
`day`	Unsigned Integer	Required. The day of the month to run the task. Possible values: 1–31
`months`	ScheduleRecurrenceMonths	Required. The months of the year to run the task. Each month is a boolean value.

BulkCleanupDigipassResult (Data type)

Table: BulkCleanupDigipassResult (Data type)
Element name	Data type	Description
`taskID`	String	Required. The ID of the scheduled server task.

Examples

Run the command immediately to search for authenticators in the myDomain domain that are disabled for over 90 days and list them.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
  <soapenv:Header/>
  <soapenv:Body>
    <adm:bulkCleanupDigipass>
      <sessionID>wo]to7L]ChB^?iH1Bmi3jXUu#-ORG^Mh</sessionID>
      <cleanupstrategy>DigipassDisabledSince</cleanupstrategy>
      <cleanupaction>listDP</cleanupaction>    
      <domain>myDomain</domain>
      <orgunit>myOrgUnit<orgunit>
      <age>90</age>
      <mode>Any</mode>
    </adm:bulkCleanupDigipass>
  </soapenv:Body>
</soapenv:Envelope>

Schedule a task to run on the fifth of March and September at 9:00 UTC to delete authenticator instances that haven't been used for 120 days in the myDomain domain and notify by email.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:adm="http://www.vasco.com/IdentikeyServer/IdentikeyTypes/Administration">
  <soapenv:Header/>
  <soapenv:Body>
    <adm:bulkCleanupDigipass>
      <sessionID>wo]to7L]ChB^?iH1Bmi3jXUu#-ORG^Mh</sessionID>
      <cleanupstrategy>DigipassNotAuthenticatedSince</cleanupstrategy>
      <cleanupaction>deleteDP</cleanupaction>
      <domain>myDomain</domain>
      <orgunit>myOrgUnit<orgunit>
      <age>120</age>
      <mode>Any</mode>
      <schedule>
        <monthly>
          <time>09:00:00Z</time>
          <day>5</day>
          <months>
            <March>true</March>
            <September>true</September>
          </months>
        </monthly>
      </schedule>
      <notify>Email</notify>
    </adm:bulkCleanupDigipass>
  </soapenv:Body>
</soapenv:Envelope>

Requirements

Required administrative privileges:

Administrative Logon
Bulk Cleanup DIGIPASS Data
Delete DIGIPASS
Download Report File
Update DIGIPASS
View DIGIPASS
View Domain
View Organizational Unit
View Report File
View Task

Additional considerations

You can configure the database chunk size for the search and the delete operations by setting the values of Task-Manager_TaskProcessing_BatchRecordCount and Task-Manager_TaskProcessing_TransactionRecordCount in the vdsConfiguration table, respectively.