platform sdk visitors

About visitors

In Security Center, a visitor is a temporary cardholder represented by a Visitor entity, which derives from Cardholder. The entity represents the visitor's current visit. After checkout, Security Center can retain an archived visit record according to the archived visitor retention configuration. Use Engine.VisitorManager to retrieve an archived visit and recreate a Visitor entity when the visitor returns:

VisitorManager manager = engine.VisitorManager;

Use the report manager to query active and archived visitors. Retrieve an archived visitor as an ArchivedVisitor snapshot through VisitorManager.

Querying visitors

Use VisitorQuery to search for active or archived visitors by state, name, contact information, or time range. Create the query through the report manager and execute it with BeginQuery/EndQuery:

VisitorQuery query = (VisitorQuery)engine.ReportManager
    .CreateReportQuery(ReportType.Visitor);
query.VisitorStates.Add(VisitorState.Archived);
query.LastName = "Smith";
query.LastNameSearchMode = StringSearchMode.StartsWith;
query.MaximumResultCount = 50;

QueryCompletedEventArgs result = await Task.Factory.FromAsync(
    query.BeginQuery,
    query.EndQuery,
    null);

foreach (DataRow row in result.Data.Rows)
{
    Guid visitorGuid = row.Field<Guid>("Guid");
    VisitorState state = row.Field<VisitorState>("VisitorState");

    Console.WriteLine($"{visitorGuid}: {state}");
}

VisitorQuery.VisitorStates is empty by default, which queries both active and archived visitors. Add VisitorState.Active or VisitorState.Archived to restrict the results to one state.

Note

VisitorQuery is not supported by ReportManager.QueryAsync. Use BeginQuery/EndQuery as shown above, or use the synchronous Query() method.

Filter properties on VisitorQuery:

• Name filters: FirstName, LastName, FullName, each paired with a matching *SearchMode of StringSearchMode.
• Contact filters: Email, MobilePhoneNumber, also paired with *SearchMode.
• Time-range filters: ActivationTimeRange, ArrivalTimeRange, DepartureTimeRange, ExpirationTimeRange. Mutate each through its SetTimeRange methods.
• EntityGuids to restrict the result to specific visitor identifiers.
• CustomFields to filter by visitor custom field values.
• LastConfiguration, which defaults to true, to return only the latest archived configuration and omit archived configurations for current visitor entities. Set it to false to include earlier archived configurations.
• MaximumResultCount to cap the result set.

The result table includes these columns, in order:

• Guid
• FirstName
• LastName
• Email
• CustomFields
• ActivationDate
• ExpirationDate
• Picture
• Thumbnail
• CheckinDate
• CheckoutDate
• Description
• Escort
• Escort2
• MandatoryEscort
• VisitDate
• MobilePhoneNumber
• VisitorState

Active and archived visitor rows use the same 18-column result schema. A column can contain DBNull or a default value when the visitor has no value for that field. For an active row, Guid identifies the current Visitor entity. Retrieve it with engine.GetEntity<Visitor>(visitorGuid) when you need entity members or operations such as Checkout.

Retrieving an archived visitor

VisitorManager exposes two lookup methods that return an ArchivedVisitor snapshot:

ArchivedVisitor archived = engine.VisitorManager
    .GetArchivedVisitor(visitorGuid);

ArchivedVisitor archivedByCardholder = engine.VisitorManager
    .GetArchivedVisitorByCardholderId(cardholderGuid);

Use GetArchivedVisitor with the Guid value from an archived VisitorQuery row. This identifier represents one archived visit. Use GetArchivedVisitorByCardholderId with the original Visitor entity identifier, which ArchivedVisitor.CardholderId exposes.

When you require a specific archived visit, query archived visitors and pass the row's Guid to GetArchivedVisitor. GetArchivedVisitor raises SdkException with SdkError.InvalidValue when no archived visit matches the identifier.

ArchivedVisitor is a snapshot of an archived visit. Guid and CardholderId are read-only. Before calling CreateVisitor, you can change the contact details, escort assignments, picture, and custom field values that the method copies. Changes to lifecycle properties on the snapshot do not affect the recreated visitor.

Recreating a visitor

CreateVisitor creates a new Visitor entity from an ArchivedVisitor and uses ArchivedVisitor.CardholderId as the new entity's Guid:

ArchivedVisitor archived = engine.VisitorManager
    .GetArchivedVisitor(visitorGuid);

Visitor recreated = engine.VisitorManager.CreateVisitor(archived);

The following fields are copied from the archived visitor onto the new entity:

• Name, used as the new entity's name
• FirstName, LastName, EmailAddress, Description, and MobilePhoneNumber
• Escort and Escort2
• MandatoryEscort
• Picture
• Archived values for visitor custom fields that still exist and contain a value

CreateVisitor does not copy ActivationDate, ExpirationDate, ExpirationMode, CheckinDate, CheckoutDate, VisitDate, or VisitState. Configure the new visit through supported Visitor members such as Arrival, Departure, and VisitDate. CheckinDate is read-only, and the archived checkout date and visit state remain historical information.

See also

• About access control: Access control entities and their relationships.
• About cardholders and credentials: Cardholder, group, and credential configuration and lifecycle.