Models

Porta Models allow you to bring in data from external sources and display it in users’ profiles. They give you the option to create a full-fledged user profile where users can interact with the various information related to their profile such as their subscriptions to premium content, newsletters, comments they have placed on your site, their activities and more. Models are designed to offer a great degree of flexibility in defining what you would like to bring into the user profile and how you want to engage with your users while they interact with their account. 

The documentation below provides a detailed overview of how to use Models, including how to configure API calls, define data points, and set up 'Actions'. We are excited to see what models you come up with in your pursuit of providing a personalized user experience to their users.

Create a Model

To create your first model, navigate to the ‘User Profile’ section under the left navigation menu and click on ‘Models’. This will bring you to a list of all models you have created including the Name of the model, the Date when the model was created, and its status.

Please note that under the list you will also see three predefined ‘models’ including My Account, Data & Personalization, and Security. As these are essential to the functionality of the user profile they cannot be modified or deleted.

Under the ‘More’ action menu on the right you will find options to view a model’s details, configure data import, unpublish a model, or edit a model. You will find more information on each action further below.

To create a model click on the ‘New Model’ where you are free to define the properties and actions of a model.

Configuring a Model

To configure a model, you will first need to define the following parameters:

Name (required) - defines the name of the model. Please note that the text inserted in this field is displayed to end-users in their user profile. Therefore, it is advised that you pick a name that identifies what the model does and what users can expect to find under the menu.

Description (optional) - the description is only used for internal purposes for you and your team to be able to identify what the model is about.

Alias (required) - the alias serves to map with the appropriate web API connection to ensure that the appropriate authentication credentials are used when a RESTful web service is invoked from the business process.

Icon (required) - the icon is used as a design element that is displayed in the user’s profile to present a visual identifier of what the model does. This should be ‘visually descriptive’ for the end user to understand what the ‘menu’ is about.

Model Properties

The model properties define the different data points that you would like to display in the user’s profile depending on the mode’s purpose. Each model property has a name, a data type, a designation type, and a mode. 

The Property Name identifies the ‘data point’ that will be retrieved via the API call. For example, this could be ‘subscription_plan’ to identify the name of the subscription plan a user has purchased. All property names must be in lowercase letters.

The Data Type identifies the classification or categorization of a piece of data that specifies the values that it can have and the operations that can be performed on it. The following data types are supported in creating models:

• String: A sequence of characters, used to represent textual data.

• Long integer: A whole number with a larger range than a regular integer data type.

• Datetime: A data type used to represent a date and time value.

• Decimal: A data type used to represent decimal numbers with a high degree of precision.

• Boolean: A data type that can only have two possible values - true or false - used to represent logical values.

The Designation Type defines the purpose a property serves and thereby the ‘logical’ organization of the information that is rendered in the user’s profile. The following types of designations are supported:

• Title: A brief and descriptive name or heading given to a piece of content or information.

• Image: A visual representation of an object, concept, or idea.

• Description: A brief summary or explanation of the characteristics, features, or attributes of something.

• Email: A unique identifier that specifies the location of an email inbox, typically consisting of a username and a domain name separated by the "@" symbol.

The Mode defines whether a property value is required or only optional, thereby defining whether the model will always render the said field on the user’s profile or whether there can be a ‘null’ value instead. 

By default, in every model, the user id is a property that is always included, with a string data type, required mode and which cannot be edited. This is required because the model must know what information to display on which user’s profile. The same applies to the model id with the exception that the name of the property can be freely defined. Why?

With the ‘Add Property’ function, you will be able to add new properties and define the data points you would like to bring into the model and display in the user’s profile. For example, if we take a user’s subscription to premium content, we could add a few properties that define the ‘subscription name’, e.g. ‘Netflix Family Subscription’, and the datetime, defining when the subscription renews or expires. You are free to define the number of properties and the information you would like to display under each model.

Actions

Model actions allow you to define what actions an end user can take with specific functions offered by the model. For example, a user can ‘Cancel’ an active subscription, or ‘Resubscribe’. Some examples of call-to-actions that you want users to take include canceling a subscription, subscribing to a newsletter, or navigating to the external service or site when interacting with any data that has been brought in by an external system. These actions are dynamic and can be configured to account for various use cases. 

To create an action you must first define an Action Name. The Action Name identifies what the action is about. Please note that this name is used and displayed in the user’s profile under the call-to-action button. Models support two action types:

Hyperlink: a hyperlink type action can be used to help the user navigate from the user profile to an external site where they can view data related to the properties defined in the model. When selected you will be asked to enter the URL where users will be redirected to with an option to configure whether the URL should be opened in a new tab or within the same tab.

Button: a button type action can be used to configure various call-to-actions that a user can undertake relating to the properties defined in the model. Similarly to the hyperlink type, you will be asked to enter a URL. This URL should typically point to the endpoint that must be notified when the user clicks on the ‘button’ in order to perform the necessary operations related to the action. For instance, this could be a URL that when users click on ‘Cancel Subscription’ notifies the subscription management system that this user has canceled their subscription and their access should be gated depending on the logic set under the subscription management system. 

Visibility Settings: these settings are used to define what call to action is displayed to end-users depending on the state of the property defined in the model. When enabled, the visibility settings will display the property name, an operator dropdown list which includes the  ‘is’, ‘is not’, ‘contains’, and ‘does not contain’ operators, and a Value input, with all being required fields. To configure the visibility setting of an action, you can select a property defined in the model, select the operator, and enter the value the action button should take. For example, you can select a property named ‘subscriptionstatus’ that defines the status of a subscription which for illustrative purposes we can say can take one of two values: active or canceled. The visibility setting can be configured in the following way: given the property name ‘subscriptionstatus’ is ‘Active’, display the ‘Action Name’ which for this example is a ‘Cancel’ button. Doing this configuration entails that only users with an ‘Active’ subscription status will see and be able to take the action of canceling their subscription. You can also define an ‘Action Output’ to change the value of the action button depending on the events users are taking under their profile. Continuing with the example above, when the user ‘undertakes’ this action of ‘Canceling’ their subscription, the Action Output can be configured such that a given property, in this case, subscription state, once the user clicks on Cancel, change the value of the Action button to ‘Renew’. A second action can be configured to determine the necessary API calls that must be made when a user clicks on Renew subscription. 

Configure Request Headers: are used to provide additional information about a client's request to a web server. A request or response message is made up of a header and a body. The header contains metadata that provides additional information about the message, while the body contains the actual data being transmitted.8*7

The header is made up of one or more header fields, each of which consists of a header name and a header value. The header name identifies the specific information being conveyed in the header field, while the header value provides the value of that information.

For example, in a request message, the "User-Agent" header field might have a header name of "User-Agent" and a header value of "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.93 Safari/537.36". This indicates that the client making the request is using the Chrome web browser on a Windows 10 operating system.

In a response message, the "Content-Type" header field might have a header name of "Content-Type" and a header value of "text/html". This indicates that the body of the response message contains HTML-formatted text.

The request methods supported include:

• POST: used to submit an entity to the specified resource, often causing a change in state or side effects on the server.

• PUT: replaces all current representations of the target resource with the uploaded content, or creates the resource if it does not already exist.

• PATCH: partially updates the target resource with the specified changes, allowing for more fine-grained updates without replacing the entire resource.

• DELETE: removes the specified resource from the server.

Expected HTTP Status Code: refers to the status code that the model should expect to receive from a server in response to a specific HTTP request. In this field you can enter the numerical value of the status code that the model anticipates to receive as a response. The possible values for HTTP status codes are:

• 1xx (Informational): Indicates that the request was received and is being processed.

• 2xx (Success): Indicates that the request was successfully received, understood, and accepted.

• 3xx (Redirection): Indicates that further action is needed to complete the request.

• 4xx (Client Error): Indicates that the request contains bad syntax or cannot be fulfilled by the server.

• 5xx (Server Error): Indicates that the server encountered an error while attempting to fulfill the request.

Please note that you can enter ‘xx’ after the first numerical digit specified to indicate that the model can expect to receive one of the possible status codes. E.g. for 2xx, it can expect to receive one of the following: 200, 201, 202, 203, 204, 205, 206, 207, 208, or 226.

This is then used by the model to determine whether to display an error message as specified in the optional error message field.

Error Message: is an optional input that is displayed to end-users in case of an error occurrence during the communication, otherwise there is a default error message.

Please note that you are free to add multiple actions to the same model to dynamically change the values and function of Action buttons depending on the state of a property.

Upon completing the configurations, you can ‘Save’ the model. Please note that merely saving the model does not display it or the associated data retrieved in the user’s profile. A model must be published in order for it to be made visible in the users’ profiles. 

Publish a Model

To publish a model, go to the Models List view and under the ‘More’ action menu click on Publish. You will be asked to verify that you want to publish this model live where it will become visible to all users under their user profile. 

Please note, before publishing a model live we advise that you go to the ‘Branding’ section of your Porta Admin and preview or configure the HTML or Custom CSS to determine how the model will be rendered to end-users. 

To unpublish a model, you can go to the Models List view and under the ‘More’ action menu click on Unpublish. Similarly, you will be asked to verify that you want to unpublish a model.

Edit a Model

To edit a model, go to the Models List view and under the ‘More’ action menu click on Edit. Please note that once a model has been created you will only be able to edit a few fields such as the name, description, and icon used in the model. You will not be able to edit the alias of the model and the properties that have already been added as this will break the structure of the data that is saved under the Model. However, you will still be able to add new properties to an existing model to bring in additional data from the external source. Both published and unpublished models can be edited in this manner. 

Please note that you will still be able to edit actions freely, with the exception of the name and type of the action.

Delete a Model

To delete a model, go to the Models List view and under the ‘More’ action menu click on Delete. Please note that this action is not reversible and all configurations and changes made to the model will be lost upon deletion. Please note that it is possible to only delete models that are unpublished in order not to disrupt the user experience abruptly. 

View Model Details

To view the model details, from the Models List view, click on the ‘More’ action menu on the right and you will be redirected to a page that shows all the configurations done for the model. The view details page also includes two tabs including the ‘Swagger’ and ‘Data Import’ tabs.

Swagger

Models include a Swagger interface for developers to test and explore APIs, which can speed up the configuration process and reduce the likelihood of errors.

Data Import

Data import serves to bring in existing data from external sources into the models. Once a model is set up as new data is generated, they will be added to the model and to the user's profile. However, to import existing data, it is necessary to create a data import so that all historical data, e.g. all previous purchases, are also inserted in the model and displayed to end users.

To create a data import, from the Models list view, under the ‘more’ action menu, click on ‘Create Data Import’. This will redirect you to a page where you can configure the data import. You will be asked to specify the following:

Url: is a required input prompting you to specify the source from which to import the data.

Response Type: selecting the response type is required when importing data from a specific source so that the model can recognize which response format it can expect to receive in order to properly parse and process the data. For example, if a file contains data in CSV, JSON, or XML formats, an importer would need to specify which format the file uses in order to properly parse the data. If the importer tries to parse the file as the wrong format, it may fail to import the data correctly or it may generate errors.Selecting the appropriate response type is important for ensuring that data is imported accurately and efficiently. It can also help prevent errors or unexpected behavior that can arise when data is imported using the wrong format. Models support the following three formats: CSV, JSON, and XML.

Property Accessor (optional): the property accessor allows the model to access the properties of an object, which are the characteristics or attributes that define the object, such as their name. It provides a way to read or modify the values of these properties from within Models.

The syntax for accessing an object property can vary depending on the specific implementation, but it typically involves using a dot notation or a bracket notation to reference the property name. For example, in JavaScript, one can access the "length" property of a string object using the dot notation, like this:

  let myString = "Hello, world!";

let length = myString.length; // accessing the "length" property of the "myString" object

Alternatively, one can use the bracket notation to access the property, like this:

  let myString = "Hello, world!";

let length = myString["length"]; // accessing the "length" property of the "myString" object using the bracket notation

Request Headers (optional): are used to provide additional information about a client's request to a web server. A request or response message is made up of a header and a body. The header contains metadata that provides additional information about the message, while the body contains the actual data being transmitted.

The header is made up of one or more header fields, each of which consists of a header name and a header value. The header name identifies the specific information being conveyed in the header field, while the header value provides the value of that information.

Schedule: under the schedule you will be asked to specify the frequency with which the data import function should be run. This can take one of the following values: Once, Hourly, Daily, Weekly, and Monthly.

Once the data import has been created, when viewing the details of the model you will see a tab ‘Data Import’. The tab will display the specified schedule of the data import and the import executions. The import executions will display the message of the action executed and the duration of the import. 

Entries

Under Model Entries, you will be able to view all the data that is brought into the model for all of your users. Depending on the configuration of the data properties under the model, you will be able to view all the data points. Entries serve for you to review the data that has been brought into the model and to be able to diagnose any potential issues users may face when interacting with their user profile. You can search for data of specific users using the Search function. Please note that you must use the full email address when searching for a user as the function uses exact match rules.