bulkCleanupDigipass (Command)

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

The bulkCleanupDigipass command deletes authenticators and/or authenticator instances based on a cleanup strategy (specified with the cleanupstrategy parameters. Possible cleanup strategies are:

DigipassInstancesReusedPNID. Deletes 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. Deletes 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. Deletes 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.

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. The deletion of unused authenticators and authenticator instances is done in blocks of 100 records per database transaction.

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)).
cleanupstrategy	DigipassCleanupStrategyEnum	Required. The strategy to determine the items that should be deleted. Possible values: 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 DigipassNotAuthenticatedSince.
dryrun	Boolean	Optional. If set to true, the command is executed but only searches for authenticators and authenticator instances that match the strategy without deleting any data. An overview of the items that would be deleted is stored in the status information of the respective server task when completed. The server task generates a CSV report to provide a complete and detailed summary of the items that would be deleted. 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. If omitted or set to false, the command is executed regularly (deleting data). Availability: 3.28 and later
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.

Example

Schedule a task to run on the fifth of March and September at 9:00 UTC to delete unused authenticator instances 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>
      <domain>myDomain</domain>
      <orgunit>myOrgUnit<orgunit>
      <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
View DIGIPASS
View Domain
View Organizational Unit
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.