Adding and Configuring Extensible Metadata for apps and APIs

This document provides information on a step-by-step use case for using Repository Client for configuring and implementing custom app and API properties used by the extended properties and workflow feature on the API Platform.

Promotion User's Guide Using Custom Metadata on the Developer Portal Installing the Extended Properties Feature

API Platform Version: 8.4 and later

Table of Contents

  1. Overview
  2. 1 Enable Feature
  3. 2 Establish Admin Connection to Repository Client
  4. Create Configuration Project
  5. Define New Metadata Elements
  6. Populate Defined Elements into API and/or App Types
  7. Upload the Configuration

Overview

At a high level, the steps are:

Back to top

1 Enable Feature

In the developer portal, enable the Extended Properties and Workflow setting, as shown below.

Navigation: In the developer portal, Admin > Site. For details, see How do I configure site settings? (developer portal help).

Enabling the feature in CM

Back to top

2 Establish Admin Connection to Repository Client

To establish the admin connection to the Repository Client, complete the following steps, illustrated below:

Start the LM Administrative Client (Repository Client)

Start up the Repository Client user interface, shown below.

Note: If you don't have the Repository Client installed, contact your Akana representative.

Create New Connection

  1. In the Library Explorer view, left-click on the red Connection icon to launch the New Library Connection wizard.
  2. In the Library Name field, use your tenant name from the developer portal, as shown below.

    You can use the Site Admin credentials from any developer portal tenant as the credentials for the library connection.

    Any tenant Site Administrator credentials can be used as LM admin credentials

  3. The Connection name field defaults to the library (tenant) name, as shown below. Click Finish.

    Initial connection to the instance triggers certificate installation and restart.

  4. When the connection is established, the Admin Client automatically opens the connection, as shown below.

Note: It's not necessary to keep the connection open. To close it, in Library Explorer, right-click on the Connection name and choose Disconnect.

Back to top

Create Configuration Project

To create the configuration project, complete the following steps, illustrated below:

Switch Admin Client to Resource Perspective

Create New Configuration Project

To create a new project, follow the steps below.

  1. Right-click in Project Explorer to launch the New Project wizard.

  2. Open the Repository folder, select Configuration Project, and then click Next.
  3. Select the tenant library connection that you created in the earlier step, and make sure that the two Retrieve from the connected library options and selected. Click Next.

  4. The project name defaults to the tenant library connection name. Click Finish.

  5. The Configuration Project creation and population process runs.

When this process is complete, a new Configuration Project appears in the Project Explorer, and the Library Process Configuration (LPC) document editor opens in the editor view. An example is shown below.

Back to top

Define New Metadata Elements

To define metadata elements, complete the following steps, illustrated below:

Open GDT Editor

Close the LPC editor. In the configuration project, double-click the gdt.xml file. The Global Definition Template (GDT) Editor opens in the editor view.

Define New Metadata Element

To define a simple metadata element, left-click the + icon on the Classifiers section of the editor. Simple metadata elements include:

  • String (open or enum)
  • Boolean
  • Date
  • Decimal

The convention is to use lower-case with connecting hyphens for the classifier name.

when you click Finish, the new classifier is added to the GDT, as shown below. This example is a Boolean classifier.

Further editing of the newly defined classifier is typically not required.

You can define additional classifiers in the same way, as shown below.

Date classifier:

Decimal classifier:

String classifier (string classifier types can be specified as open or enumerated).

Enumerated string classifier: To specify a string as enumerated, define the enumeration values by selecting the + action on the Values Constraints section of the Define Classifier Type dialog. Fill in the value field with the desired enumerated value, leave the other fields blank, and click Finish.

The enumerated values are presented by the developer portal UI in the order in which they are specified. If necessary, you can reorder individual values by selecting the value and clicking the up or down arrow.

To specify taxonomic classifiers (for example, business domain/subdomain) expand the Compound Classifiers section of the editor.

When specifying a compound classifier, specify the fields of the classifier first, and then specify the allowed values.

The ordering of fields in the editor dialog controls the definition of the taxonomy levels. Use the up and down arrow actions as needed to establish the correct ordering.

You must specify all valid value combinations for the taxonomy in the Values section of the dialog. To separate field values, use the pipe character (|).

You can specify URL-based fields by defining by-reference artifact types.

Note that you must clear the Textual description and File upload containment options as these are currently not supported by the API Platform UI.

Once all new elements are defined, save and close the GDT editor.

Back to top

Populate Defined Elements into API and/or App Types

Expand the Capture-Templates folder of the configuration project. Also expand the Common Asset.ctxml template to view its child templates.

Capture Templates are used to associate elements defined in the Global Definition Template with specific asset type/state combinations. For this release, the only asset types supporting extensible metadata in the API Platform are API, app, and User. There are two sets of templates:

  • The API - Initial and App - Initial templates are used to specify create-time extensible metadata elements and constraints.
  • The API - Specified and App - Specified templates are used to specify edit-time metadata elements and constraints (for example, to lock down a value entered at create time to become read-only, or to introduce an additional element that is applicable only after initial creation).

Double-click the desired template to open the template editor. Start with the Initial template prior to editing the Specified template, as all changes made to the Initial template will be automatically inherited by the Specified template.

Collapse the General section of the Editor, and expand the Classifiers section to add Boolean, date, decimal, string (open or enum) and taxonomy types previously specified in the GDT.

Select the + action to add a classifier to the template. It's only necessary to specify a name.

Click Finish, and then expand the Constraints subsection of the Properties section of the newly added classifier to add cardinality or read-only constraints. Read only, Minimum occurrences and Maximum occurrences are the only constraints currently supported by the API Platform UI. In addition, you can specify a default value, in the General Appearance Properties section of the editor.

Expand the Artifacts section of the editor to add a previously-defined URL element to the template.

Back to top

Upload the Configuration

After saving all the edited template files, right-click on the top-level configuration project folder in the Project Explorer view and select Upload to Library to access the upload dialog. If this is the first time this configuration has been uploaded, select the correct tenant connection and check the set as the default for this project option. Click OK to initiate the upload.

A progress dialog appears until the upload is complete.

Back to top