Using the AddMetadata Method

To create a metadata object with the AddMetadata method, you must provide the following information:

This information is passed as AddMetadata parameters. The parameters are displayed here as XML elements that can be submitted to the SAS Metadata Server in the INMETADATA parameter of the DoRequest method:

<AddMetadata>
  
<Metadata>metadata_property_string</Metadata>
  
<Reposid>repository_identifier</Reposid>
   <Ns>namespace</Ns>
   <Flags>268435456</Flags>
   <Options/>
</AddMetadata>
  

To create a metadata object describing an application element, you specify the following information:

The input metadata property string must be formatted in XML. For instructions to code an XML metadata property string, see Constructing a Metadata Property String. At a minimum, the metadata property string must specify one metadata type and any required attributes and associations for the object to be created. Most metadata types have required attributes. Some metadata types also have required associations. For information about required and optional properties of the metadata types describing application elements, see the metadata type descriptions in “Alphabetical Listing of SAS Namespace Metadata Types” in the SAS Metadata Model: Reference.

Although it is not required, it is recommended that you provide values for all of an object's attributes, and define as many associations as possible in the metadata property string. This makes your metadata more meaningful. Before creating objects, see Selecting Metadata Types to Represent Application Elements.

The metadata property string that defines a SAS Metadata Model object can also define associations to related SAS Metadata Model objects. The related objects can already exist in the SAS Metadata Repository, or they can be created new along with the main object in the property string.

As discussed in Constructing a Metadata Property String, an association is defined by including XML subelements that specify an association name and an associated metadata type in the property string that defines a SAS Metadata Model object.

The following is an example of a metadata property string that includes XML subelements that define an association:

<MetadataType Name="Name-of-primary-object" Desc="New object created using AddMetadata">
     <AssociationName>
        <AssociatedMetadataType Name="Name-of-associated-object" 
          Desc="New associated object that is created by AddMetadata" />
     </AssociationName>
   </MetadataType>
 

The AddMetadata method creates a new object for every property string that is submitted in the <METADATA> element, unless the ObjRef attribute is included in the property string. ObjRef is supported only in a nested property string. It specifies that the object instance is an existing metadata object. It instructs the SAS Metadata Server to create an object reference to the specified object without modifying the specified object's other properties.

The SAS Metadata Server creates a new associated object in all of the following cases:

The default behavior of the AddMetadata method is to create the main metadata object and all references to new and existing objects in the repository specified in the <REPOSID> element. You can also create associations that reference new and existing objects in other repositories. Associations between objects that exist in different repositories are referred to as cross-repository references. A cross-repository reference is created by including the appropriate repository identifier in the associated object definition.

The objects and associations that make up an application entity’s logical metadata definition should be created in the same metadata repository as the main object. Cross-repository references should be reserved for associations between application entities.

A symbolic name is an alias that is preceded by a dollar sign ($). You assign a symbolic name to a metadata object to reference it before it is created. Symbolic names are used to create associations and new associated objects in other repositories. They also enable you to create references between multiple, unrelated metadata objects in a single XML request. For more information about this type of usage, see Example of an AddMetadata Request That Creates Multiple, Unrelated Metadata Objects.

When used to create an association and a new associated object in another repository, the symbolic name has the form Reposid.$Alias. It is specified in the Id attribute of the XML subelement that defines the associated object.

When used to create multiple, unrelated metadata objects in the same repository, the simple form $Alias is used.

Alias can be any name, as long as it is preceded by a dollar sign ($). After the successful completion of AddMetadata or UpdateMetadata processing, the alias and any references to it are automatically replaced with a real object identifier.

The following is an example of a metadata property string that creates a SAS Metadata Model object and an association to an existing SAS Metadata Model object in another repository:

<MetadataType Name="Name-of-primary-object" Desc="New object created using AddMetadata">
   <AssociationName>
     <AssociatedMetadataType Objref="Reposid.Objectid"/>
   </AssociationName>
</MetadataType>

Note the use of the ObjRef attribute and the fact that no other attributes are specified. When ObjRef is used, the SAS Metadata Server ignores any additional attributes that might be specified. The object identifier in the ObjRef attribute includes both the repository identifier and the object instance identifier of the target object.

The following is an example of a metadata property string that creates a SAS Metadata Model object, an association, and a new associated SAS Metadata Model object in another repository:

<MetadataType Name="Name-of-primary-object"  Desc="New object created using AddMetadata">
   <AssociationName>
     <AssociatedMetadataType Id="Reposid.$SymbolicName" Name="Name-of-associated-object" 
     Desc="Associated object that is created by AddMetadata"/>
   </AssociationName>
</MetadataType>

The portion of the property string that identifies the associated object specifies the Id attribute with the repository identifier and a symbolic name for the new object. (You can determine the available repositories and their unique identifiers by issuing the GetRepositories method. For more information, see Using GetRepositories to Get the Registered Repositories.) Because a new object is created, you must specify at least a Name value for the associated object and you should include values for other attributes.

To define multiple associations for an object, stack the associated object definitions within the primary object definition as follows:

<Metadata>
   <MetadataType Name="String" Desc="String">
     <AssociationName1>
        <AssociatedMetadataType Name="String" Desc="String"/>
     </AssociationName1>
     <AssociationName2>
        <AssociatedMetadataType Name="String" Desc="String"/>
     </AssociationName2>
  </MetadataType>
</Metadata>

To create multiple, unrelated SAS Metadata Model metadata objects in an AddMetadata request, stack the metadata property strings that define the metadata objects in the <METADATA> element as follows:

<Metadata>
  <MetadataType1 Name="String" Desc="String">
   <AssociationName>
     <AssociatedMetadataType Name="String" Desc="String"/>
   </AssociationName>
 </MetadataType1>
 <MetadataType2 Name="String" Desc="String">
   <AssociationName>
     <AssociatedMetadataType Name="String" Desc="String"/>
   </AssociationName>
 </MetadataType2>
</Metadata>