ULM Entities
Content
- Overview
- Properties And Attributes
- User
- Group
- Account
- Subscription
- Feature
- Runtime
- Status
- REST Operations
Overview
This topic descries the the primary ULM entities that make up ULM Cloud.
The ULM data model includes 6 primary entities:
- User: The primary ULM entity. It represents an individual person.
- Group: A collection of entities (e.g., a group of users within a household)
- Account: Represents an operator's billing account for one or more services.
- Subscription: Represents an instance of a service. Cannot exist without a parent account entity
- Feature: A very specific functionality of a service. Cannot exist without a parent subscription entity.
- Runtime: Represents an individual device, physical (e.g., tablet) or virtual (e.g., web browser).
ULM entities are linked to each other by entity associations.
Properties And Attributes
ULM entities are composed of properties and attributes, or data field names and their respective values. Each entity includes a set of default properties, and an attributes property that contains additional entity-specific metadata.
In addition to this, any two entities are linked to each other by way of an association entity, which itself consists of of permission flags and attributes that define the relationship between those particular entities.
User
The user is the central entity in ULM. It represents and individual person.
Note About Semantics: User with an uppercase U refers to the ULM User entity, whereas user with a lowercase u refers to the end-user or human being. You might also think of the ULM User Entity as the back-end technical equivalent of the front-end "User ID" or "User Profile."
When a user onboards to get their own User ID or User Profile within your service, they are, in effect, creating that User entity within the ULM Cloud datastore via the Onboard User with Email and Mobile or Onboard User with Social Account Processes. When a user authenticates into a service, the client application can then invoke the GET /user API to retrieve that User's details.
Users can have different types in the context of an association with other entities. For example, a User in a ULM Group can be designated as either the Primary, and Admin, or Regular type. That type is defined on the actual User-to-Group Association. But on the actual User entity itself, in isolation, ULM Cloud currently only supports a single RegularUser type. Additional entity types may be added in the future.
User Entity Default Properties
A ULM User entity contains the following default properties:
| Property | Definition | Data Type | Example |
|---|---|---|---|
| id | Unique internal identifer for the ULM User. | integer | 123456789 |
| type | Type of User entity. Currently, only RegularUser is supported. | string | "com.uxpsystems.mint.user.RegularUser" |
| displayName | Optional display-friendly name that the client UI can render. | string | "Jane Smith" |
| status |
Entity status of the User. Possible User statuses include:
- activating: The User has onboarded, but they have yet to verify their authN ID and fully activate. - activated: The User has onboarded, has at least one verified authN ID. - suspended: The User is temporarily suspended, and can be reactivated. - deactivated: The User is permanently deactivated, and will be automatically deleted soon. |
string | "activated" |
| avatarUrl | URL where the User's avatar image is stored.
Useful for client applications that want to include an avatar for the user's authenticated view. |
string | "http://client.myavatar/janesmith" |
| createdDate | Date on which this entity was created, expressed in UNIX Epoch format. | integer | 1543833950000 |
| activatedDate | Date on which this entity was activated, expressed in UNIX Epoch format. | integer | 1527917430000 |
| updatedDate | Date on which this entity was last updated, expressed in UNIX Epoch format. | integer | 1538682581776 |
| suspendedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1621622651675 |
| deactivatedDate | Date on which this entity was deactivated, expressed in UNIX Epoch format. | integer | 1794095435804 |
| attributes | Additional metadata about the entity. | ||
User entities also contain attributes:
| Attribute | Definition | Data Type | Example | |
|---|---|---|---|---|
| familyName | User's family (or last) name. | string | smith | |
| givenName | User's given (or first) name. | string | jane | |
| language | User's preferred language, as per ISO 639-1:2002. | string | en | |
| emails | List that contains one more email addresses registered as this User's Authentication Identifiers (authN IDs). Each object includes: | array of email objects | ||
| id | Unique internal identifier for the email registered as an authN ID. | integer | 257 | |
| Actual email address value. | string | jane_smith@email.ca | ||
| status |
Current status of the authN ID. Possible statuses include:
- activated: authN ID is fully registered and verified. - activating: authN ID is registered, but needs to be verified. - pending: authN ID is registered to replace another authN ID, but needs to be verified. |
string | "activated" | |
| mfaOption | Whether or not this authN ID is registered as an MFA option. | boolean | false | |
| label | Optional label that the user can set. | string | "work email" | |
| mobiles | List that contains one or more mobile numbers registered as this User's Authentication Identifiers (authN IDs). Each object includes: | array of mobile objects | ||
| id | Unique internal identifier for the mobile registered as an authN ID. | integer | 834328 | |
| number | Actual mobile number value. | string | "1234567890" | |
| status | Current status of the authN ID. Possible statuses include:
- activated: authN ID is fully registered and verified. - activating: authN ID is registered, but needs to be verified. - pending: authN ID is registered to replace another authN ID, but needs to be verified. |
string | "activating" | |
| country | Country code, as per ISO 3166. | string | "CA" | |
| mfaOption | Whether or not this authN ID is registered as an MFA option. | boolean | true | |
| label | Optional label that the user can set. | string | "personal phone" | |
| aliases | Array of one or more aliases registered by the user. Each object includes: | array of alias objects | ||
| id | Unique internal identifier for the email registered as an authN ID. | string | 19743 | |
| alias | Actual alias value. | string | skippy | |
| preferredNotificationChannel |
User's preferred external channel to receive notifications (e.g. email or SMS), taken from one of the registered authN IDs. Value format is: {object}.{propertyName},{id}.
For example, "mobiles.number,723419" means that the UI should look inside the mobiles object, and inspect the number value where the corresponding id is 723419. |
string | "emails.email,02781" | |
| branding |
Indicator of branding to be used on a per-user level (e.g. differentiating between an operator's main brand and a discount brand).
Applicable to service providers with more than one brand, if they prefer to render a separate, distinct UI. |
string | "Maple" | |
| socialConnections | List of user's connections to social providers. Each object includes: | array of SocialConnection objects | ||
| id | Internal (ULM) unique identifer number for the connection between this User and the given social account. | integer | 597 | |
| socialId | External unique identifier of the social account profile. In other words, this is the user's profile ID with the social provider. This number is provided to ULM during the ULM-to-social account association. |
string | ||
| providerId | The name of the social provider in this connection. | string | "Facebook" | |
| Secret2faTotp | The shared secret between ULM Cloud for this User and an Authenticator App that the User has registered for Multi-factor Authentication. The value for is obfuscated. | string | ||
| domain | The domain which the user onboarded onto ULM Cloud from. Useful as an alternate form to determine appropriate branding. | string | int.m1amdocs.com | |
Group
A ULM Group entity is a connective entity. It represents the grouping of multiple users, as well each individual end user's access to different services and functionality under an account or subscription (which are themselves represented by the Account, Subscription and Feature entities associated to the Group entity). The typical group represents a "household" group of family members.
See the ULM Associate Billing Account Process for more information on how ULM Cloud leverages ULM Groups and associations on the back end to enable account and service sharing for users on the front end of a given application.
Note: Remember that every association between each entity is unique, and contains its own flags and attributes. The exception to this is the "association" between an Account and it's Subscriptions and Features.
A ULM Group entity contains the following default properties:
| Property | Definition | Data Type | Example |
|---|---|---|---|
| id | Unique internal identifier for this Group. | integer | 39846 |
| type | Specific type of Group entity. | string | "com.uxpsystems.mint.group.HouseholdUserGroup" |
| displayName | Optional display-friendly name that the client UI can render. | string | "The Smith Family" |
| status | ULM Entity status of the Group. The only possible status is activated. | string | "activated" |
| createdDate | Date on which this entity was created, expressed in UNIX Epoch format. | integer | 1543833950000 |
| activatedDate | Date on which this entity was activated, expressed in UNIX Epoch format. | integer | 1543833950000 |
| updatedDate | Date on which this entity was last updated, expressed in UNIX Epoch format. | integer | 1621622651675 |
| suspendedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1527917430000 |
| deactivatedDate | Date on which this entity was deactivated, expressed in UNIX Epoch format. | integer | 1794095435804 |
| attributes | Additional metadata about the entity. | ||
Group entities also contain attributes:
| Attribute | Definition | Data Type | Example |
|---|---|---|---|
| maximumNumberOfMembers | Maximum number of Users that can be associated to the Group. Attempts to exceed this number should be forbidden. | string | "5" |
Account
A ULM Account is created using the Associate Account Process, using billing records in the Business/Operations Support System (B/OSS) or other integration with a service provider. ULM maps records from the billing system into a ULM Account entity.
The Account entity can also contain ULM Subscriptions (and each individual Subscription may contain its own Subscription-specific ULM Features). The actual record-to-entity mapping depends on the type of services provided by the business, the type of service provider's records and bulling system, and the specific integration between the service provider and UL Cloud. The ULM data model is flexible enough to consume most any set of customer records and map them to an Account/Subscription/Feature hierarchy of associated entities.
A ULM Account entity contains the following default fields:
| Variable | Purpose | Data Type | Example |
|---|---|---|---|
| id | Unique internal identifier for this Account. | integer | "3298435" |
| type | Specific type of Account entity. | string | "com.uxpsystems.mint.account.BillingAccount" |
| displayName | A display-friendly name for this Account. | string | "Jane's Billing Account" |
| status | ULM Entity status of the Account. | string | "activated" |
| createdDate | Date on which this entity was created, expressed in UNIX Epoch format. | integer | 1543833950000 |
| activatedDate | Date on which this entity was activated, expressed in UNIX Epoch format. | integer | 1543833950000 |
| updatedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1621622651675 |
| suspendedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1527917430000 |
| deactivatedDate | Date on which this entity was deactivated, expressed in UNIX Epoch format. | integer | 1794095435804 |
| subscriptions | List of all ULM Subscriptions under the Account. | array of ULM Subscriptions (if any) | |
| Note: Each individual ULM Subscription may contain, among other properties, its own array of distinct ULM Features. | |||
| attributes | Additional metadata about the entity. | ||
Account entities also contain attributes:
| Attribute | Definition | Data Type | Example | ||
|---|---|---|---|---|---|
| accountNumber | Human-readable external account number as provided by an external B/OSS or other integration. | string
|
"123456" | ||
| maxUsers | The maximum number of users with which this account can be shared (i.e, associated). | integer
|
5 | ||
| paymentProviderAccountId | Account identifier as stored and/or provided by a payment provider. | string
|
"098765" | ||
| internalProviderAccountId | If the account is provided by a component internal to MarketONE (e.g. Subscribe), this attribute contains the internal reference within the appropriate component. | string
|
"509" | ||
| bssName | The name of the B/OSS (or other integration) that provides the account data. | string
|
"vindicia" | ||
| paymentDetail | List of available payment methods for this Account. Each object contains: | array of PaymentDetail objects | |||
| paymentMethodId | Unique identifier of the provider's payment method. | string
|
"97b0915f6e65614462fdee6ffbc8385f3308188f" | ||
| paymentMethodName | Name of the provider's payment method. | string
|
|||
| active | Whether or not the payment method is active. |
boolean
|
true | ||
| primary | Whether or not the payment method is the primary payment method for the account. | boolean
|
false | ||
| additionalFields | Additional metadata related to this payment method object. | string
|
|||
| bssAccounts | List of accounts as stored in (and provided by) one or more B/OSS (or other integration) that provides account data. Each object contains: | array of bssAccount objects | |||
| accountId | Unique identifier of the user's account in the B/OSS. |
string
|
"000123-45678" | ||
| externalId | Additional unique identifier specified by the B/OSS, if one exists. |
string
|
"123456" | ||
| Email address associated with the account in the B/OSS. | string
|
"jane.smith@email.ca" | |||
| language | User's preferred language, per ISO 639-1:2002, as specified in the B/OSS. |
string
|
"en-us" | ||
| name | Name of the person associated with the account as specified in the B/OSS. | string | "John Doe" | ||
| addresses | List of addresses associated with the account as specified in the B/OSS. Each bssAddress object includes: | array of bssAddress objects
|
|||
| name | Name of the person or contact associated with this address. | string | "Jane Smith" | ||
| street | Full street name of the address. | string | "1 Yonge Street, Suite 405" | ||
| city | City name of the address. | string | "Toronto" | ||
| county | County name of the address, if applicable. | string | "Orange County" | ||
| division | Region the address is domiciled, if applicable. | string | |||
| postalCode | Postal code of the address. | string | "M5E 1E5" | ||
| country | Country in which the address resides. | string | "Canada" | ||
| phone | Primary phone number associated with this address. | string | "4161234567" | ||
| fax | Primary fax number associated with this address, if applicable. | string | "4160987654" | ||
| latitude | Latitudinal coordinates of this address. | float | 38.8951 | ||
| longitude | Longitudinal coordinates of this address. | float | 77.0364 | ||
| paymentProviderId | The identifier of the payment provider for this account (e.g. Subscribe). | string | |||
Subscription
A ULM Subscription represents an instance of a service, the purchase type (one-time or recurring payments), and the entitlement to that service based on the both the entity status and its association to a ULM User.
For example, if a ULM User is associated to a ULM Subscription entity that represents a paid streaming TV service, then this association itself can define the entitlements that end user has to the service. If the service involves a variety of functional capabilities, those functions may be captured as ULM Features associated to (i.e., contained within) the ULM Subscription entity. For example:
- A customer's records in a billing system would be represented by a ULM Account.
- A Mobile Service Plan (MSP) under the billing account would be represented by a ULM Subscription.
- A special capability for the MSP (e.g., unlimited data) may be represented by a ULM Feature.
How the data from an external system maps to the Account/Subscription/Feature (A/S/F) hierarchy depends on the type of service, the type of service provider, the service provider's billing system, and the business needs defined during the initial integration between the service provider and ULM Cloud. The ULM data model is flexible enough to map most any external record data to the A/S/F hierarchy, but the needs may vary from tenant to tenant.
A ULM Subscription is "associated" with its parent Account at the moment the Subscription is created in ULM. A Subscription can not exist in ULM without a parent or container Account. Conversely, ULM Features cannot exist without a parent or container Subscription.
A ULM Subscription entity contains the following default fields:
| Variable | Purpose | Data Type | Example |
|---|---|---|---|
| id | Unique internal identifier for this Subscription. | integer | "3298435" |
| type | Specific type of Subscription entity. | string | No default or standard. The Subscription type is pulled from the service provider's external system, through the MarketONE SP API, and mapped within the Account/Subscription/Feature hierarchy according to a data mapping that is set during the initial onboarding and integration phase between ULM Cloud and a service provider. |
| displayName | A display-friendly name for this Subscription. | string | "My Streaming Account" |
| status | ULM Entity status of the Subscription. | string | "activated" |
| createdDate | Date on which this entity was created, expressed in UNIX Epoch format. | integer | 1543833950000 |
| activatedDate | Date on which this entity was activated, expressed in UNIX Epoch format. | integer | 1543833950000 |
| updatedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1621622651675 |
| suspendedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1527917430000 |
| deactivatedDate | Date on which this entity was deactivated, expressed in UNIX Epoch format. | integer | 1794095435804 |
| features | List of all ULM Features under the Subscription. | array of ULM Features (if any) | |
| attributes | Additional metadata about the entity. | ||
Subscription entities also contain attributes:
| Attribute | Definition | Data Type | Example | |
|---|---|---|---|---|
| subscriptionNumber | Identifier for the subscription as stored and/or provided by a downstream B/OSS (or other integration) that provides the subscription data. | string | ||
| maxUsers | The maximum number of users with which this subscription can be shared (i.e., associated). | int | ||
| paymentProviderSubscriptions | List of subscriptions as stored in (and provided by) one or more B/OSS (or other integration) that provides subscription data. Each object contains: | array of PaymentProviderSubscription objects | ||
| providerSubscriptionId | Subscription identifier as defined by the service provider. | string | ||
| internalProviderSubscriptionId | Unique reference subscription identifier generated by the payment provider client when the Subscription was created. Field is optional and only populated if Provider supports it. | string | ||
| productId | Product unique identifier as defined by the payment provider which was purchased. | string | ||
| subscriptionStartDate | Date when the subscription was first purchased and started, expressed in UNIX Epoch format. | integer | 1603481359 | |
| subscriptionEndDate | Date when the subscription ends if it is not renewed, expressed in UNIX Epoch format. | integer | 1603481359 | |
| maxUser: | Maximum number of users that can consume the subscription, as defined by the payment provider. | integer | 5 | |
| productDescription | Name of the product attached to the service. | string | ||
| billingState | Current financial state of the subscription. |
string (enum, one of: FREE_PERIOD, FREE, TRIAL, FREE_TRIAL, BILLING_COMPLETED, UNBILLED, GOOD_STANDING, OTHER) |
"UNBILLED" | |
| serviceStatus | Status of the subscription as defined by the payment provider. | string(enum, one of: ACTIVE, ACTIVATION, SUSPENDED, CANCELLED, DELETED, DRYRUN, EXPIRED, INCOMPLETE, LEGACY_SUSPENDED, TRIALING, UNPAID, PAST_DUE, UNKNOWN, PROCESSING, PENDING_ACTIVATION, PENDING_CANCEL, PENDING_PAUSE, PENDING_RESUME, PAUSED, UPGRADED, OTHER) | "PAUSED" | |
|
nextSubscriptionBillingDate |
Date when a recurring subscription will bill the customer for their next period of service, expressed in UNIX Epoch format. | integer | 1603481359 | |
| subscriptionPrice | Price that was charged to the customer when the subscription was last billed for the current period of service. | float | 7.99 | |
| nextSubscriptionPrice | Price that will be charged to the customer when their subscription is billed for their next period of service. | float | 9.99 | |
| subscriptionCurrency | Currency the customer was charged in for the current service cycle, as per ISO 4217. | string | "CAD" | |
| nextSubscriptionCurrency | Currency the customer will be charged in for the next service cycle, as per ISO 4217. | string | "CAD" | |
| purchaseSource | Source (or channel) of the subscription purchase. | string (enum, one of: OPERATOR, MARKETPLACE, PUSH_NOTIFICATION) |
"OPERATOR" | |
| serviceType | Type of service purchase (i.e., one time purchase, or recurring payments). | string (enum, one of: RECURRING, ONE_TIME) |
"ONE_TIME" | |
| additionalFields | Additional metadata accompanies this PaymentProviderSubscription (if any). | string | ||
| paymentMethod | Payment method used for this subscription. | PaymentDetail object (see the paymentDetail Account attribute above for list of properties) | ||
Feature
A ULM Feature represents a specific functionality offered, as part of a service, by a service provider. Alternatively, a service (Subscription) can be understood as simply a bundle of functional features, though there are no strict requirements for the relations between features and services. For example, if a user's streaming music service tier entitles them to download songs to a device, then the download capability could be represented by a Feature entity.
A Feature entity has the following default fields:
| Variable | Purpose | Data Type | Example |
|---|---|---|---|
| id | Unique internal identifier for this Feature. | integer | "3298435" |
| type | Specific type of Feature entity. | string | No default or standard. The Feature type is pulled from the service provider's external system, through the MarketONE SP API, and mapped within the Account/Subscription/Feature hierarchy according to a data mapping that is set during the initial onboarding and integration phase between ULM Cloud and a service provider. |
| displayName | A display-friendly name for this Feature. | string | "Commercial-free Streaming" |
| status | ULM Entity status of the Subscription. | string | "activated" |
| createdDate | Date on which this entity was created, expressed in UNIX Epoch format. | integer | 1543833950000 |
| activatedDate | Date on which this entity was activated, expressed in UNIX Epoch format. | integer | 1543833950000 |
| updatedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1621622651675 |
| suspendedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1527917430000 |
| deactivatedDate | Date on which this entity was deactivated, expressed in UNIX Epoch format. | integer | 1794095435804 |
| attributes | Additional metadata about the entity. | ||
Feature entities also contain attributes:
| Attribute | Definition | Data Type |
|---|---|---|
| featureNumber | An identifier for the feature, as stored and/or provided by a B/OSS (or other integration) that provides the Feature data. | string |
| maxUsers | The maximum number of users with which this Feature can be shared. | integer |
Runtime
A Runtime entity represents the software on which ULM is being accessed. Typical examples include web browsers on desktops, applications on mobile devices, or the firmware in embedded devices. In an example where a native mobile application on an iPhone is accessing ULM, ULM considers the application itself to be the runtime, not the underlying operating system (iOS) or the physical device itself (the iPhone).
The manipulation of Runtimes is restricted to creating them, deleting them, and editing their Attributes (if any). Runtimes and Users may have many-to-many relationships (associations).
A Runtime entity has the following default fields:
| Variable | Purpose | Data Type | Example |
|---|---|---|---|
| id | Unique internal identifier for this Subscription. | integer | "3298435" |
| type | The Runtime entity type. | string | |
| displayName | A display-friendly name for this Runtime. | string | "Jane's Android 4.1.1" |
| status | ULM Entity status of the Subscription. | string | "activated" |
| createdDate | Date on which this entity was created, expressed in UNIX Epoch format. | integer | 1543833950000 |
| activatedDate | Date on which this entity was activated, expressed in UNIX Epoch format. | integer | 1543833950000 |
| updatedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1621622651675 |
| suspendedDate | Date on which this entity was suspended, expressed in UNIX Epoch format. | integer | 1527917430000 |
| deactivatedDate | Date on which this entity was deactivated, expressed in UNIX Epoch format. | integer | 1794095435804 |
| guid | Unique identification string for the Runtime. | string | "DEF123" |
| version | The ULM client software's version. | string | "4.1.1" |
| buildType | The type of build for the ULM client software (Ex. "Development Build", "Production Build"). | string | "Production" |
| platformType | The OS that the client software is running on. | string | "android" |
| deviceType | The Device form factor that the software is running on (Ex. "tablet", "PC"). | string | "mobile" |
| customer | The Operator's name. | string | "Apple" |
| userAgent | The HTTP user agent for this Runtime. | string | "Mozilla/5.0 (Linux; U; Android 4.1.1; en-us; rk30sdk Build/JRO03H) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Safari/534.30" |
| features | List of all ULM Features under the Subscription. | array of ULM Features (if any) | |
| attributes | Additional metadata about the entity. | ||
Note: Currently, ULM Runtimes have no default attributes. However, Runtimes support attributes so that they can be easily provisioned in subsequent release versions of ULM Cloud.
Status
All ULM entities include a status property that represents the entity's status within the user lifecycle management.
| Status | Description | Examples |
|---|---|---|
| Activating | Provisioned but is not yet ready to be used or consumed. | User signed up with ULM with an email address or mobile number, but they have yet to verify it. |
| Activated | Activated and functionality its tied to is enabled. | User identity has been verified. The status was changed from "activating" or "pending" to "activated." |
| Pending | Similar to "Activating". | User updated an existing email address or mobile number, but they have yet to verify it. The old email or mobile remains active until the new one is verified. |
| Suspended | Temporarily deactivated but will likely be transitioned back to an activated state in the future. Its tied functionality is limited. | Suspected hacking or security risk on a user profile causes their status change to "suspended". |
| Deactivated | Permanently deactivated and optionally may be deleted from the system when necessary (e.g. after graceful period). | Soft delete a user ID before a scheduled batch job destroys it permanently. |
REST Operations
ULM REST APIs allow you to perform CRUD operations against ULM entities, to retrieve or update certain properties and attributes on each entity. However, you cannot update certain properties and attributes (e.g., a client application can read an entity's createdDate property, but it cannot update it). Consult the ULM APIs library in the MarketONE Developer Portal for the full list of APIs available to you. Each API lists the specific request parameter schema that the API will accept.
To perform actions against more protected entities and their properties/attributes, leverage ULM Processes instead.