SSI Interaction Page

An interaction is a set of actions, rules, and conditions that can be executed by the interaction's parties (participants) to achieve the intended result. Interactions can provide answers to questions such as "How" and "Why" credentials are issued or shared between parties.

Features

Description

Screenshots

Features

Description

Screenshots

Create new Interaction

To create a new Interaction, click on the “Interaction” tab of the main menu.

Click the “Add Interaction” button.

Name Interaction

Name the interaction in the “Name” field. This name will be shown as the title of this interaction’s button on the mobile application service screen.

We recommend following the naming rule of capitalizing the first letter of each word, e.g.: My Interaction Name.

After the interaction is saved, you can add localization for the interaction name and description. For more information about localization, see the platform documentation https://zaka.atlassian.net/wiki/pages/resumedraft.action?draftId=2077327369 section.

 

Describe Interaction

The “Description” field can be used to add a description of the interaction. This text will be displayed at the top of the interaction screen in the mobile application.

Add an icon for the Interaction

The icon that will be displayed for this interaction in the mobile application may be uploaded from an external source by clicking the “Upload” button and then selecting the desired file; or by selecting an icon from the “Select default” drop-down list. The selected icon will also be shown on the dashboard page of this interaction.

Interaction mode

Interactions can have two modes: “Active” and “Paused”. Paused interactions are not visible on the mobile application “Service interactions“ screen.

The status of existing interactions can be changed on the “Interactions” page.

Interaction ID

The interaction ID number will be assigned to the interaction automatically in the order in which the interactions are created. The interactions on the client's "Service Interactions" screen are arranged in ascending chronological order.

Select source for initiating Interaction

There are several ways to initiate an interaction.

If the “QR” checkbox is selected, the client will initiate the interaction by scanning a QR-code either from the interaction page or by clicking the scan button in the mobile app.

The QR code's timeout (in seconds) can be set. The QR code will be dynamically updated after the specified time period.

If the “Button” checkbox is selected, the client will initiate the interaction by clicking the “Proceed” button on the “Interaction” screen.

The “Incoming push from service” checkbox must be selected If the Interaction is to be initiated by a push notification from the service.

Note that with the selected initiation media “Incoming push from service”, the Issue Credentials template cannot be edited because these credentials are created before the interaction starts and the user shares his/her credentials.

If the “Call from app” checkbox is selected, the interaction will be initiated by a client by clicking on the “Call” button on the interaction screen.

 

Select Required credentials

 

 

Select the credentials that the client has to share to complete this interaction (optional).

Click the “Select” button next to the “Required credentials” field. The “Required credentials” pop-up window will appear.

Selecting Required credentials from the credential definitions list

The required credentials can be selected either from the list of “Credential Definitions” or from the list of “Schemas”.

 

If a credential is required, select the service that created this credential definition.

There will be a list of existing public credential definitions shown.

Select the credential definition required to complete this interaction.

The version of the schema that has been used to create this credential definition will appear. Select the checkbox next to the schema version number.

The selected credential's details will appear on the right side of the current pop-up window.

 

Selecting Required credentials from the schema list

Required credentials can also be chosen from the list of “All available schemas”.

Click the “Schemas” tab. On the left side of the “Required credentials”pop-up window, a list of “All available schemas” will appear. Select the desired schema then check the checkbox next to the schema’s version number.

On the right side of the current pop-up window, details about the selected schema will appear.

Notification ID required credential

 

The notification ID should be requested from the client on the initial interaction to enable push notifications from the service.

 

 

Saving a required credentials list

When all the required credentials have been added, click “OK” in the bottom right corner of the current pop-up window.

Configuring Required credentials

By clicking on the selected required credential from the list, the selective disclosure and zero-knowledge predicates can be specified.

Selecting attributes to be disclosed

The “Edit required credential” pop-up window will appear. Select the attributes you want to disclose from the “Attributes” list. If no attributes are selected, all attributes will be required.

Claim last credential

Check the “Claim last credential” checkbox to request the client’s most recent available credential.

 

Fill in an attribute by scaning QR code

Check the "Pre-filled from interaction QR code" for a client to scan a QR code to fill in the attributes of the self-attested credential definition.

The checkbox "Pre-filled from interaction QR code" is available for self-attested credentials set as required for the interactions with initiation media "QR".

This option is available for services with an activated "SSI OAuth" feature.

Add predicates

 

You can configure predicates only on not disclosed attributes with data types "Number "and "Date" of the service-attested credentials.

A predicate is a logical expression that uses one or more parameters and returns a boolean result.

In other words, a predicate is an expression that determines whether something is true or false.

The term "zero-knowledge" means that interaction may not necessarily require a client to reveal the actual value of a credential attribute, but rather to prove the predicate upon the attribute.

For example, you can demonstrate that your age is greater than 18 years without disclosing your real age or date of birth.

To set required proofs upon credential attributes, click on the "Predicates" tab.

Click the "+ Predicate" button to add the predicate. Select the attribute name from the drop-down list. Attributes used in predicates cannot be selected for disclosure. Set up the necessary preconditions.

 

Submit or cancel adding details of required credential

Click "Submit" to proceed, or "Cancel" to delete all the settings made on the current pop-up window.

Existing predicates can be deleted or edited later.

Select Issued credentials

Click the “Select” button next to the “Issued credentials” field if the intended result of the interaction is that a credential will be issued to the client.

 

The "Issued credentials" pop-up window will appear. The list of all available credentials will be displayed on the left side of the screen. Choose the credentials that will be issued to the client as a result of the current interaction.

A list of selected issued credentials will appear on the right side of the current pop-up window. Click "OK."

 

Edit issued credential template

 

 

 

 

Once the issued credentials have been selected, the credential project can be configured by setting the rules to pre-fill attributes in the issued credentials. Click on the chosen issued credential. The "Edit issued credential template" pop-up window will appear.

Pre-fill Rules for Attributes

Select the check box next to the issued credential's attribute name, the value of which should be automatically pre-filled and displayed in the issued credential.

Two additional fields will appear on the screen.

Selecting the source for the attribute’s pre-filled data

Select the source for the attribute’s pre-filled data from the drop-down list.

There are five different data sources to pre-fill the attribute:

 

If “Constant” is selected, the attribute will be pre-filled with the constant value specified in the adjacent field;

 

If "Parameter" is selected, an additional field will be added. Select the parameter as a value to pre-fill this attribute;

See more information in the “Parameters and instances“ section of this page.

 

If the "From existing credential” field option is selected, two additional fields will be added. Enter the data input source in the first of these fields and the name of the attribute from which the issued project attribute will get the pre-filled value in the second field; 

 

If “Unique autogenerated” is selected, the pre-filled attribute value will be a unique numerical value starting from 1.

 

 

If "Random" is selected, the pre-filled attribute value will be random (depending on the attribute data type).

 

Attributes without pre-filled data

If the checkbox next to the attribute name is not checked, the attribute will not get any pre-filled value.

The dashboard operator will be able to manually fill in the data for this attribute.

Manual issuance

If the “Manual” checkbox is not selected and pre-fill rules are set for all attributes, the credential will be issued automatically.

 

When all the details are added on this page, click the "Submit" button.

 

Flow notifications

The flow notifications for the mobile application client can be set in the "Flow notifications" section. Through the execution of the interaction, these messages will appear to the mobile application client in the form of pop-up windows.

If an interaction has instances, the name of the instance's parameter may be specified in the flow notifications. For example, if the instance parameter's name is "Room Number," the "Success" message can be "Welcome to Room {{Room Number}}!" The pop-up message for the client (a guest of room number 2) in the mobile application will be "Welcome to Room 2!"

If the interaction is completed successfully, the message from the "Success" area will appear as a pop-up in the mobile application.

The message "Pending" will appear in the mobile application as a pop-up when the required credentials have been successfully submitted by a client, but the interaction has not yet been completed.

The "Failure" message will appear in the mobile application as a pop-up window if the system fails to transfer or verify data, or if the current interaction cannot be performed for any reason.

 

Concurrency type

More interaction settingscan be added in the “Advanced Settings” section.

Choose a concurrency type.

Select the "Once" checkbox if the current interaction can be initiated and executed by the same client with the same DID one time only.

Select the "Sequenced" checkbox if the interaction may be executed multiple times by the same client with the same DID, but only after the current interaction has been executed and has "Complete" status on the dashboard.

Select the "Concurrent" checkbox if the current interaction may be initiated by the same client with the same DID simultaneously.

 

External verification hook

In the case of any required credential containing an "External verification hook," additional external verification can be activated by checking the "External verification hook" checkbox.

If external verification is activated, verification will be attainable if in addition to successful verification of the requested verifiable credentials the third-party service verification result is "true."

Web hook URL

If you want a third-party system (such as CRM) to receive the required credentials when the interaction is initiated by a client, the URL for the webhook request, key, and authorization type can be specified here.

Before selecting a key type, create a key in the "Keys" tab.

Click on the “Web hook“ field. The “Edit web hook“ pop-up window will appear. Specify an URL for the webhook, select key and authentication type for the output webhook request.

If no key type is specified, the key that was generated automatically when the service was setup will be used (Default).

Click “Submit.“

For more information, visit the key page of this overview and https://proofspace.atlassian.net/wiki/spaces/PSM/pages/2133786630.

Parameters and instances

Parameters can be included in the interaction. The interaction instances are defined by the values of the parameters. As a result, a single interaction can have multiple instances, and a client can choose the correct instance from the interaction screen (initiation media: Button) or by scanning the QR code of one of the instances (initiation media: QR). For example, the "Open Door" interaction could have three instances with the values "Room 1," "Room 2," and "Room 3."

 

Add parameter

To set parameters and instances, an interaction has to be saved first.

To add parameters, click the “Parameters“ area in the “Advanced Settings” section of the "Edit interaction" page.

 

 

The "Add Parameters & Instances" pop-up window will appear.

Click on the "Parameters" tab. Click the "+ Parameter" button. The box with the "Name" and "Value" areas will appear. In the relevant fields, give the parameter a name and a default value (optional). A single interaction might have several parameters.

Create, edit or hide an interaction instance

 

Click the "Instances" tab.

Add or edit instances if needed.

Click the "Create" button to add a new instance. A new box will appear on the right side of the current window. In this box, click the “Edit“ icon. Set an instance parameter value in the field of the proper parameter name. Click “Done“ in the instance box OR click “Save“ on the bottom left corner of this window.

If the interaction initiation media is a button, the selection of a specific instance of the interaction will be available on the mobile application interaction page.

If the interaction's initiation media is QR, the user will select a particular instance by scanning the instance's relevant QR.

For example, as a result of the interaction a hotel guest can open the room by scanning the QR code. In this case, the interaction initiation media should be set as "QR". The instance parameter name will be "Room" and the instance parameter values will be "1", "2", and "3"—so the instances of this interaction will be "Room 1," "Room 2," and "Room 3."

In order for a hotel guest to be able to open only one particular room, it is necessary to set the predicate upon the attribute of the required (from a tourist) credential.

In this case, it could be the predicate: "The attribute name "Room" {number} of the required credential ‘Key’ = The parameter name ‘Room’ {value}" is "True" (Room 1 = Room 1 is True).

More information about predicates can be found in the “Add predicates“ section of this page.

 

 

 

Set the instance's active time interval (optional). The client will be unable to interact with this instance once this period has passed.

Edit an interaction instance

By clicking on the “Edit“ button, instances can be edited.

 

Saved instances can not be deleted.

 

Hide an interaction instance

By clicking on the “Hide“ button (icon) instances can be hidden from the mobile application interaction screen.

 

Once all the details have been added, click the "Submit" button. The parameters and instances have been defined and added.

 

Once all the details have been added, click "Done" to save the interaction.

Edit interaction

Previously saved interactions can be edited.

To edit the interaction, click on the "Interactions" tab of the main menu. Click the “Edit” button next to the chosen interaction. Edit the interaction. Click "Done."

Once an interaction has been saved, it cannot be deleted.

Interactions can have two modes: "Active" and "Paused". Paused interactions are not visible on the mobile application’s "Service" screen.

QR Codes

The list of QR codes for interaction instances with initiation media "QR" can be found on the "Interactions" page by clicking the "QR codes" button.