Defining Software Library Metadata

Introduction to Software Library Framework

After defining and registering the new metadata, you can extend the Software Library framework to become aware of new types of software or scripts or configurations. You can use these entities in the existing or custom automation logic represented by a job type or deployment procedure.

As a plug-in developer, you will be able to define the following Software Library metadata:

Folder

Software Library allows you to organize the different user-defined or out-of-box entities into logical folders for efficient management.

For more information, see Defining Folders.
Type and Subtype

A type and subtype together define the common traits of the entities it represents in terms of common and searchable metadata/configuration properties, their default values, file association requirements, etc. All entities in Software Library have an associated type and a subtype.

For more information, see Defining Types and Defining Subtypes.
Entity

Entities are the primary artifacts stored in Software Library. They are identified by the type/subtype they have been created with and the folder they are present in.

For more information, see Defining Entities.

Defining Software Library Metadata

This section contains the following topics:

Note:

To view an example which describes how to use the Software Library artifacts, follow these steps:

In Cloud Control, from Setup menu, select Extensibility, and click Development Kit.
On the Extensibility Development Kit page, in the Getting Started section, five samples are listed in the samples directory. The Sample Host Plugin 2 (Sample II) is the plug-in sample that covers information about Software Library artifacts.

Once you have downloaded the EDK kit to your local system, select oracle.samples.xsh2 sample available in /samples/plugins/ directory. If you further drill down to /samples/plugins/oracle.samples.xsh2/plugin_dist/oms/metadata directory, the swlib folder is displayed which contains the necessary examples.

Note:

All the Software Library Metadata described in this section must be included in the XML file as described in Organizing Software Library Metadata Files. Following which, you must register them using the information available in Adding the Software Library Metadata to Enterprise Manager.

Defining Folders

The following example describes how you can create two top level folders called MPFolder1 and MPFolder2, with a subfolder named Subfolder under each of these folders:

<Folders>
      <Folder name="MPFolder1">
      </Folder>
      <Folder name="MPFolder2">
      </Folder>
      <Folder name="MPFolder1/subfolder">
      </Folder>
      <Folder name="MPFolder2/subfolder">
      </Folder>
</Folders>

After defining and registering the folders, when the plug-in is deployed, these folders will be displayed in Software Library console with a lock symbol, which means that the folders are Oracle-Owned, and can not be editted. You can customize them using the Create Like functionality available in Software Library. All the other folders that are created using Enterprise Manager console by users appear without the lock symbol, and can be editted by anyone who has been given the required accesses on the folder.

Defining Types

The following example describes how to create two Type artifacts called MPType1 and MPType2:

<Types>
<EntityType internalName="MPType1"/>
<EntityType internalName="MPType2"/>
</Types>

Defining Subtypes

The following example describes how you can create a subtype MPSubtype1 for the type MPType1:

<EntitySubtype internalName="MPSubtype1" type="MPType1">
      <EntityProperties filename="MPSubtype-entPropDict.xml"/>
       <GenericUISpecification>
         <Create>
           <ContentDescriptor>
             <DisplayName default="Describe"/>
             <Description default="Describe"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-describe-task-flow.xml#sdkcore-regions-swlib-describe-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
           <ContentDescriptor>
             <DisplayName default="Select Files"/>
             <Description default="Select Files"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-upload-task-flow.xml#sdkcore-regions-swlib-upload-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
           <ContentDescriptor>
             <DisplayName default="Review"/>
             <Description default="Review"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-review-task-flow.xml#sdkcore-regions-swlib-review-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
         </Create>
         <Edit>
           <ContentDescriptor>
             <DisplayName default="Describe"/>
             <Description default="Describe"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-describe-task-flow.xml#sdkcore-regions-swlib-describe-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
           <ContentDescriptor>
             <DisplayName default="Select Files"/>
             <Description default="Select Files"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-upload-task-flow.xml#sdkcore-regions-swlib-upload-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
         </Edit>
         <View>
           <ContentDescriptor>
             <DisplayName default="Describe"/>
             <Description default="Describe"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-describe-task-flow.xml#sdkcore-regions-swlib-describe-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
           <ContentDescriptor>
             <DisplayName default="Select Files"/>
             <Description default="Select Files"/>
             <Content contentId="/WEB-INF/sdk/core/regions/swlib/sdkcore-regions-swlib-upload-task-flow.xml#sdkcore-regions-swlib-upload-task-flow" contentType="ADFRegion"/>
           </ContentDescriptor>
         </View>
       </GenericUISpecification>
    </EntitySubtype>

Once a subtype defined is registered, entities of this subtype can be created (if creation is not blocked) using the Software Library console. To do so, from Enterprise menu, select Provisioning and Patching , then click Software Library. From the Software Libray page, select a user-owned folder. From Actions menu, select Create, and then select Type and then the SubType. All the sub-types that belong to the type selected are displayed. For more information, see the following graphic file.

Ideally, you must see the subtypes you created as a part of this list, if not, there is an issue with registration. For more information on registerting the sub-type, see Adding the Software Library Metadata to Enterprise Manager.

Entity Properties File

Following is the entity properties file MPSubtype-entPropDict.xml:

<?xml version="1.0"?>
<Dictionary xmlns="http://www.oracle.com/sysman/emgc/Properties">
   <TypeDefinitions>
      <DictionaryItem refID="MPAttr1" purpose="PURPOSE_TopLevel">
         <PropType typeCode="TYPE_String">
            <SimpleType className="java.lang.String" uiHintReadOnly="false" uiHintHidden="false" secret="false" guid="false">
               <Constraints/>
            </SimpleType>
         </PropType>
      </DictionaryItem>
 
      <DictionaryItem refID="MPAttr2" purpose="PURPOSE_TopLevel">
         <PropType typeCode="TYPE_String">
            <SimpleType className="java.lang.String" uiHintReadOnly="false" uiHintHidden="false" secret="false" guid="false">
               <Constraints/>
            </SimpleType>
         </PropType>
      </DictionaryItem>
 
      <DictionaryItem refID="MPAttr3" purpose="PURPOSE_TopLevel">
         <PropType typeCode="TYPE_String">
            <SimpleType className="java.lang.String" uiHintReadOnly="false" uiHintHidden="false" secret="false" guid="false">
               <Constraints/>
            </SimpleType>
         </PropType>
      </DictionaryItem>
   </TypeDefinitions>
   <DynamicTypes/>
</Dictionary>

To use the file, ensure that you make the following changes:

MPAttr1, MPAttr2, and MPAttr3 are the names of the entity properties, remove the properties that are not required, and change the names of the properties that you retain appropriately.

Copy the DictionaryItem section from the above sample to create more entity properties. Note that, you can only update the name, you cannot change other aspects of the entity property.
The entity properties for this sub-type are displayed as Other Attributes in Sotware Library console. Only, after the subtype metadata with entity property definitions are registered, while creating or editing entities, you can specify values for the entity properties. However, note that you can not define new entity properties.

Defining Entities

The following example describes how you can create an entity of the type MPType and subtype MPSubtype in the folder MPFolder1:

    <Entity name="MPTSEntity">
      <Type>MPType</Type>
      <Directory>/MPFolder1</Directory>
      <Subtype>MPSubtype</Subtype>
      <Fileset>
        <FileEntry>
          <path>payload.zip</path>
          <sourcePath>payloadSrc.zip</sourcePath>
        </FileEntry>
      </Fileset>
      <ExternalID>0.1</ExternalID>
    </Entity>

FileSet: A file payloadSrc.zip should be present in the same directory as of this XML. The entity will have a file entry payload.zip.

ExternalID : A decimal floating point number of the form xxxxxxxx.x, which means, a maximum 8 digits before decimal point, and one digit after decimal point is allowed. For example, 0.6, 23.9, an so on. When registering metadata again, the external IDs of the entities are compared. Entities whose ExternalID matches the ExternalID of the latest revision currently registered will not get registered again.

For example:

If the entity MPTSEntity in MPFolder1 is registered with ExternalID 0.1, the an entity with revision 0.1 is created. If ExternalID is not specified, then the default value is 0.1.
If XML is updated and registered again without changing ExternalID, then his entity will not be registered, and a warning will be logged. Entity will continue to have 0.1 revision.
If the ExternalID is changed to 0.2, and registered again, then the registration will be applied, and a revision 0.2 is created in addition to the earlier registered 0.1 revision. Consequently, multiple increments might need to be performed to ExternalID for it to be registered during the development and testing phase. However, before the release, ensure that you reset it back to the correct value and track it correctly.

Organizing Software Library Metadata Files

To organize the Software Library Metadata files, follow these steps:

Once you have the XMLs to define types, subtypes, folders, and entities ready, navigate to the following location:
```
$OMS_PLUGIN/metadata/swlib
```
Create a directory for your functional area (for example, functionalArea), in the following location:
```
$OMS_PLUGIN/metadata/swlib/functionalArea
```
Create a driving file (swlib.xml)
Edit order.xml file available at the following location: $OMS_PLUGIN/meadata, to add an entry for the newly created functionalArea/swlib.xml file:

Here is a sample example of how your directory structure should look:

swlib/
    order.xml 
    functionalArea/swlib.xml
    functionalArea1/swlib.xml

Here is a sample example of the contents of order.xml file:

<order>
  <name>functionalArea/swlib.xml</name>
  <name>functionalArea1/swlib.xml</name>
</order>

Note:

For each functional area in the plug-in, you must add an entry in the order.xml file as described in the example.

Adding the Software Library Metadata to Enterprise Manager

Adding the Software Library Metadata to Enterprise Manager is a two-step process as described in this section:

Step 1: Validating Metadata XML

For the purpose of testing, use emctl to register the metadata as follows:

emctl register oms metadata -service swlib -file <Metadata Instance file> -pluginId <Plugin Id> [-sysman_pwd "sysman password"]
Where:
Metadata Instance file is the path to the folder containing order.xml. For example, $OMS_PLUGIN/metadata/swlib.

Note:

If you have not added a Software Library location, then the emctl register command will not work, instead, you will see an error message as follows:

EM-04040: Metadata operation is skipped. Reason: Software Library OMS shared storage is not configured, skipping metadata registration. Check /u01/inst/em/EMGC_OMS1/sysman/log/emctl.log for more details.

Also, if the metadata XML file is repeatedly registered for entities, then you must ensure that the external ID element is incremented each time. For example, if there are 11 entities defined in XML, four of which have same ExternalID, and seven have updated ExternalID, then you will see the following message:

Total 0 errors, 4 warnings. 7 entities imported.
Metadata registration successful

Note:

OMS must be restarted for the registration to take effect, when a metadata registered using emctl contains types or subtypes. However, OMS need not be restarted for the registration of types and subtypes, when the Software Library metadata defined in a plug-in contains types or subtype, and is deployed.

Oracle recommends that you check the logs even if the registration is successful, as there may be some warnings. These warnings are mainly caused when the external ID is not modified, inturn causing entity registration to fail. To view the logs, navigate to the following location:

$INSTANCE_HOME/sysman/log/emctl.log

Step 2: Adding Metadata XML to OPAR

When a plug-in OPAR is deployed containing Software Library metadata organized in the way described above, Software Library metadata will be registered if Software Library is configured on the system. Software Library metadata XMLs are to be included in the OPAR like any other metadata. See Chapter 13, "Validating, Packaging, and Deploying the Plug-in" for more information.

Note 1: If Software Library is not configured at plug-in deployment time, the plug-in's Software Library metadata will get registered whenever Software Library is configured for the first time after the plugin deployment.

Using Software Library Entities

Software Library entities created by the plug-in may represent a patch/script/configuration or any other software relevant to the plug-in. To use these entities after they have been created using the options described in previous sections, consider one of the following approaches:

Note:

For information about how plug-in Graphical User Interface uses the Software Library search service, see Software Library Search Service.

For information about how to use the Component step and Directive Step available in User Defined Deployment Procedure to automate a custom deployment activity, see Oracle Enterprise Manager Lifecycle Management Administrator's Guide

Using Job Types

Software Library makes use of the following job types:

SwlibStageEntities - Transfers files associated with a Software Library Entity to a destination host target.
SwlibUploadFiles - Uploads files to be associated with a Software Library Entity to the appropriate Software Library storage location specified.

You can create your own job types, which inturn contain these jobtypes. For example, you can create a jobtype XML that containsthe SwlibStageEntities jobtype as follows:

<?xml version="1.0"?>
<jobType name="StageWrap" version="1.0" singleTarget="true" targetTypes="host" editable="true">
     <credentials>
     <credential usage="destHostCreds" authTargetType="host" defaultCredentialSet="HostCredsNormal">
     </credential>
     <credential usage="destNfsHostCreds" authTargetType="host" defaultCredentialSet="HostCredsPriv">
     </credential>
    </credentials>
    <paramInfo>
        <paramSource sourceType="user" paramNames="stageLocation, entityURN" 
                     required="true" evaluateAtSubmission="true" />
        <paramSource sourceType="user" paramNames="stageFileEntryPaths, operMode, autoRetry" required="false"/>
        <paramSource sourceType="inline" paramNames="operMode">
           <sourceParam name="paramValues" value="mount"/>
           <sourceParam name="overwriteExistingFiles" value="yes"/>
        </paramSource>
    </paramInfo>
    <stepset ID="main" type="serial">
      <step ID="preStage" command="remoteOp">
        <credList>
          <cred usage="defaultHostCred" reference="destHostCreds"/>
        </credList>
       <paramList>
        <param name="remoteCommand">%job_default_shell%</param>
        <param name="args">ls, -R, %stageLocation%</param>
        <param name="targetName">%job_target_names%[1]</param>
        <param name="targetType">%job_target_types%[1]</param>
      </paramList>
      </step>
      <job ID="stage" type="SwlibStageEntities">
        <credList>
          <cred usage="destHostCreds" reference="destHostCreds"/>
          <cred usage="destNfsHostCreds" reference="destNfsHostCreds"/>
        </credList>
        <paramList>
          <param name="entityURN">%entityURN%</param>
          <param name="stageFileEntryPaths" valueOf="stageFileEntryPaths"/>
          <param name="stageLocation">%stageLocation%</param>
          <param name="operMode">%operMode%</param>
          <param name="autoRetry">%autoRetry%</param>
          <param name="overwriteExistingFiles">%overwriteExistingFiles%</param>
        </paramList>
        <targetList allTargets="true" />
      </job>
      <step ID="postStage" command="remoteOp">
        <credList>
          <cred usage="defaultHostCred" reference="destHostCreds"/>
        </credList>
       <paramList>
        <param name="remoteCommand">%job_default_shell%</param>
        <param name="args">ls, -R, %stageLocation%</param>
        <param name="targetName">%job_target_names%[1]</param>
        <param name="targetType">%job_target_types%[1]</param>
      </paramList>
      </step>
    </stepset>
  <displayInfo 
               useDefaultCreateUI="true"
               showParams="true"> 
 
  <jobTypeDisplayInfo>
    <nlsValue>Stage Wrap</nlsValue>
  </jobTypeDisplayInfo>
    <parameterDisplayInfo name="stageLocation" showInResults="true" showInCreate="true">
         <parameterLabel>
             <nlsValue>Stage Location</nlsValue>
         </parameterLabel>
         <parameterHint>
            <nlsValue>Directory location on target where the files from the entity will be transferred.</nlsValue>             </parameterHint>
          <parameterTextBox lines="1" />
    </parameterDisplayInfo>
    <parameterDisplayInfo name="entityURN" showInResults="true" showInCreate="true">
         <parameterLabel>
             <nlsValue>Entity URN</nlsValue>
         </parameterLabel>
         <parameterHint>
            <nlsValue>Internal identifier of the entity</nlsValue>             
        </parameterHint>
          <parameterTextBox lines="1" />
    </parameterDisplayInfo>
  </displayInfo>
</jobType>

Jobs of jobtype SwlibStageEntities expect the following inputs:

Stage Location: The directory path where the file of the entity will be transferred.
Entity URN: This is the internal identifier of the entity, which can be obtained any one of the following methods:
- In Enterprise Manager Cloud Control, from the Enterprise menu, select Provisioning and Patching, then click Software Library. On the Software Library home page, from View menu, select Internal ID to enable it. Copy and supply the Internal ID value available to the job as the value of this parameter.
- You can use the emcli verb list_swlib_entities with the parameter-show_entity_rev_id to obtain the Internal ID. Copy and supply the Internal ID value available to the job as the value of this parameter.

Using EMCLI Verbs

You can use the EMCLI verbs provided by Software Library to add Software Library storage location, create folders, create entities, upload files for entities, modify entities, and so on. For more information about EMCLI verbs, see Oracle Enterprise Manager Command Line Interface and the Oracle Enterprise Manager Lifecycle Management documentation available in the Oracle Help Center:

https://docs.oracle.com/en/enterprise-manager/