Adding and Configuring Extensible Metadata for Users
This document provides information on a step-by-step use case for using Repository Client to add extensible user metadata to a tenant configuration in a specific use case.
API Platform Version: 8.4 and later
Table of Contents
- LM Asset Structure
- User Creation Scenario 1: Site Admin User Creation
- User Creation Scenario 2: User Self-Signup
- Adding Extensible User Metadata
In version 8.4, the Akana API Platform introduced support for extensible user metadata alongside the existing API and app capabilities introduced in version 8.3. This document provides a basic set of instructions for adding extensible user metadata to a tenant configuration in a specific use case. It is an example of using extensible user metadata; it is not a complete set of documentation for all scenarios.
LM Asset Structure
The LM Platform component deployed as part of the 8.4 API Platform comes with a default configuration that includes specification of an empty User asset type. This includes:
- Specification of two User capture templates:
- User - Initial
- User - Specified
- Declaration of the User asset type in the Lifecycle Repository Client user interface (LPC) with a default association of this type to the User - Initial capture template, as shown below.
- Specification of a User Submission process in the LPC which automatically transitions a User asset in the Initial state to the User - Specified capture template after initial publication, as shown below.
This default configuration is suitable as a baseline configuration for each of the two User creation scenarios supported by the API Platform. This document addresses configuration steps for both scenarios:
Scenario 1: User creation by the Site Admin
A Site Admin can create new users in the developer portal via the List of Users page: in the developer portal user interface, Admin > Users.
The default configuration assumes that the Site Admin is not responsible for populating any of the extensible User metadata fields specified for the tenant. Instead, it's expected that the user will populate these fields at first login.
To set this up, implement the User - Initial capture template as the default template to be used at the time of User asset creation. This template is empty except for an internal state classifier; this classifier is used to control template transition only, and should never be edited.
User Creation Scenario 2: User self-signup
An individual user can sign up to the developer portal, creating a local account, without Site Admin involvement. This process initiates the creation of a unique UserID which is assigned to the user and linked to the user's credentials and other information provided by the user and stored in the database.
When extensible metadata is in use, the developer portal user interface should present such users with the set of extensible User metadata fields at the time the user creates a profile. In order to enable this behavior, it's necessary to modify the User asset type entry in the LPC so that it references the User - Specified capture template in place of the default User - Initial capture template setting.
Adding Extensible User Metadata
Adding extensible metadata is a multi-step process.
The following metadata types are supported:
- Open String
- Enumerated String
- Multi-level taxonomy (in legacy Lifecycle Manager terminology, compound classifiers)
This document does not provide an exhaustive guide covering each type. Instead, it provides a single example (an enumerated String labeled User Type). You can apply the principles of this example to elements of other types.
The process steps are as follows:
- Step 0: Create a library connection and download the LM tenant library configuration
- Step 1: Declare a new metadata type in the GDT
- Step 2: Add the newly-declared metadata type to the User - Specified capture template
- Step 3: Configure the LPC to properly expose the new metadata element
- Step 4: Upload the configuration to the LM tenant library
Step 0: Create a library connection and download the LM tenant library configuration
If this is the first time that an LM tenant library is being edited within the LM Admin Client, the administrator must create a new library connection from the Repository Perspective of the client.
- From the Library Explorer view, choose the red New Library Connection action. This allows the Administrator to configure the connection, as shown below.
Note: By default, the developer portal Site Admin role includes the appropriate permission (LM roles) to edit library configurations. LM delegates user authentication to the Portal, so the same user credentials used to log into the Portal should be populated into the LM Library Connection.
- Once the connection is successfully created, switch to the Resource perspective and create a new Repository Project. To do this:
- In the Project Explorer, right-click and choose New Project.
- Expand the Repository folder
- Choose a configuration project and click Next.
- On the next panel of the wizard, choose the correct Connection and make sure that the other settings are set to Retrieve from.
This creates a new project, primed with the default LM tenant library configuration, in the Project Explorer.
Step 1: Declare a new metadata type in the GDT
All metadata types must be declared in the GDT (Global Definition Template) of the tenant library. This action makes them available for use within asset types.
The GDT is an XML file that can be opened in two ways:
- Using the graphical editor provided by the LM Admin Client.
- Within the schema-aware XML editor that comes as part of Eclipse.
Since the GDT is a declarative document, it can be very efficient to copy and paste existing elements as a starting point for new element declaration. However, many users prefer to use the graphical editor as a guide to populating the various attributes that control element behavior. The right-click context menu controls which editor is applied when opening a file.
When using the graphical editor, to add a new classifier, select the green plus icon on the Defined Classifiers list. A dialog box opens, and the administrator can specify the details of the newly declared classifier, as illustrated in the two images below.
In the example above, when the user clicks Finish, the editor generates the following underlying XML fragment:
<define-classifier display-name="User Type" help-text="How does this user interact with the API Platform?" name="user-type" type="string"> <add-value uuid="_FrMwIA4_Eeew5aMeFxkGxw" value="App Owner"/> <add-value uuid="_HI0ksA4_Eeew5aMeFxkGxw" value="App and API Owner"/> <add-value uuid="_DEi28A4_Eeew5aMeFxkGxw" value="API Owner"/> <add-value uuid="_IxnugA4_Eeew5aMeFxkGxw" value="Admin Only"/> </define-classifier>
You could also enter an equivalent XML fragment directly, using a schema-aware XML editor. In this case, you can omit the uuid attribute since the editor generates values on an as-needed basis based on other editing activities.
Step 2: Add the newly-declared metadata type to the User - Specified capture template
As discussed previously, the default LM configuration for User metadata is capable of supporting both user creation scenarios with minimal change.
In both cases, only the User - Specified capture template should be used as a basis for modification.
The User - Initial template should never have customer-specific metadata types. The only exception to this is if you want a hybrid Site Admin user creation scenario where the Site Admin fills in a subset of the extensible user fields and the user fills in the remainder.
When an element is added to a capture template, the administrator can control options that control presentation behavior and logic, such as:
- Cardinality (mandatory/optional
- Default values
- Editable vs. read-only
In this scenario, again the Lifecycle library administrator has the option of using either the graphical editor or the Eclipse-provided schema-aware XML editor.
When using the graphical editor, be aware that most options presented on the editor UI are not relevant for embedded LM within the API Platform. In most cases, the only section that should be edited is the Constraints section, shown below.
In the example above, the specific configuration settings enforce the following behavior on the newly-specified User property within the developer portal user interface:
- The User Type field is:
- Mandatory (Minimum occurrence = 1)
- Single-valued (Maximum occurrence = 1)
- The end-user can edit the value (this is the most common use case for integrated metadata).
- The metadata value is processed through submission governance (that is, the User submission process referenced earlier).
If you edit the User Type classifier as above, the following XML fragment is generated in the underlying capture template document:
<use-classifier min-occurs="1" max-occurs="1" name="user-type" />
To create an optional single-valued field, delete the Minimum occurrence value in the graphical UI. This is represented in the underlying XML as follows:
<use-classifier appear-on-edit="true" max-occurs="1" name="birthdate" />
You can define a field as read-only in a similar way. Read-only values are generally not needed for User metadata, but might be useful in more advanced scenarios, such as API state transition with metadata lockdown after final transition.
Step 3: Configure the LPC to properly expose the new metadata element
You must configure each metadata element into at least one LPC Group so that the element is accessible to the LM UI or developer portal UI.
By convention, the LM Platform default configuration defines two well-known LPC Groups:
- LM Internal Elements—This group is used to block exposure of an element to the Portal UI, so is used only for control metadata (such as the user-status field used in the User Submission Process to control template transition).
- Common Information—In general, all newly specified User metadata elements should be added to this group, in the order by which they are to be displayed in the developer portal user interface, as shown in the example below.
Step 4: Upload the configuration to the LM tenant library
To upload the modified configuration to the LM tenant library, right-click on the project folder and choose Upload to Library. In the dialog box, choose the correct connection and click OK.