3 Exporting Data

This chapter includes:

Understanding the Web Service Export Function
Using the exportData Web Service Operation

3.1 Understanding the Web Service Export Function

The following two export Web service operations are delivered as part of AIS:

exportData - A Web service operation that extracts data from an Agile PLM system in one of several data formats.
exportPartList - A Web service operation that takes a multilevel BOM and flattens it into a list of the manufacturer parts and their quantities in the BOM, and returns the data in aXML format.

3.2 Using the exportData Web Service Operation

The exportData Web service operation is capable of extracting Agile data in one of several structured formats. This operation can be used to provide integration functionality between your Agile PLM system and other, third-party systems.

This section illustrates how to format an XML request in order to use the exportData Web service operation. For more information on the XML schema that describes an exportData request, see the Export XML Schema documentation in"AIS Folders." To view the information, select documentation > schemas > export.htm.

The exportDataRequest XML element describes the XML format that you must use when submitting an exportData request to AIS. This enables you to specify the following types of data:

Queries - One or more queries that define what objects is exported.
Filters - One or more filters that define what data from the selected objects is exported.
Formats - The format that is used for the exported data.
Sites - Manufacturing sites for which data should be exported. By default, data for all sites is exported.
Export - Approval Matrix data is exported.
Import - Approval Matrix data is imported.

3.2.1 Working with Queries

Using the exportData Web service operation, you can specify parameters related to the object query:

The query itself (Required)
The type of object being queried (Required)
The site to apply to all objects matched by the query (Optional)
The revision to apply to all objects matched by the query (Optional)

You can specify multiple queries at once, returning multiple result sets. More information on query parameters can be found in the Agile API reference documentation. However, the following section provides a brief introduction to the criteria syntax.

3.2.1.1 Specifying Query Criteria

This section introduces the basics of Agile SDK query syntax. For complete information on how to construct complex search criteria, refer to Agile SDK Developer Guide - Using Agile APIs.

The value for the criteria parameter for the exportData and exportPartlist is a single string consisting of one or more search conditions. Strings that appear within the search criteria should be enclosed in single quotes (').

3.2.2 Working with Sites

Companies that practice distributed manufacturing use several different sites to manufacture their products. The exportData Web service operation supports exporting data to all manufacturing sites, or to a specific site. Manufacturing sites affect how items and changes are exported. In the case of items, BOMs and AMLs can vary per site. For changes, the Affected Items table specifies which manufacturing sites are affected.

By default, the exportData Web service operation extracts information for all sites. If you specify a manufacturing site, only the data associated with that site is exported. All objects that are not associated with that manufacturing site are filtered out of the query results.

The following examples illustrate using exportData to extract all parts and documents in system and exportPartlist to extract only parts with AMLs.

Example: Using exportData to extract all parts and documents in the system

runner export.ExportData-h localhost -u admin -p agile -l 7001 -e Agile -c "[Title Block.Number] is not null " -F "Item.TitleBlock" -t Item -o outpart.pdx

Example: Using exportPartlist to extract only parts with AMLs

runner export.ExportPartlist -h localhost -u admin -p agile -l 7001 -e Agile -c "[Title Block.Number] is not null " -F "Item.TitleBlock" -o outpart.pdx

The following XML snippets illustrate different ways to specify a manufacturing site:

...
<site>
    <site-name>Taipei</site-name>
  </site>
  ...
  <site>
    <site-id>6</site-id>
  </site>
  ...
  <!--The following is optional since the default is all sites -->
  <site>
    <all/>
  </site>

...

3.2.3 Working with Filters

The exportData Web service operation enables you to define the information that you want to query from the selected objects. These parameters are captured by specifying one or more filters. Filters are either predefined in the Agile PLM system, or they are defined in an ad hoc fashion by the AIS client.

You can specify multiple filters and their effect is cumulative. The resulting filter is the combination of all specified filters. For example, if one filter includes an item's PageTwo information and a separate filter includes the item's History information, the effective filter includes both PageTwo and History information.

3.2.3.1 Predefined Filters

Agile provides several predefined filters to refine query results. You can specify a predefined filter in one of the following three different ways: --

By ID - Specify the numeric ID of a defined filter with the Agile administrative data. This information can be found using the Agile API to inspect the Agile administrative data. Use the ID of a defined filter to reduce the risk of a name change that can adversely affect your code.
By name - Specify the name of a defined filter found in the Agile administrative data. This is an easy way to reference previously defined filter definitions.
By object type -Specify different information sets for each type, from the set of available filters, one for each object type.

Note:

If you have administrator privileges to the Agile PLM system, you can define new filters. Log into Agile Java Client and choose Admin > System Settings > Agile Contents Service > Filters.

For more information on predefined filters, see the Export XML Schema documentation in AIS Folders. To view the information, select documentation > schemas > export.html.

3.2.3.2 Ad Hoc Filters

Ad hoc filters are defined for a particular purpose and are not stored in the Agile PLM system. The Export XML Schema defines several <filters> elements, such as ItemFilter, ChangeFilter, ManufacturerFilter, and ManufacturerPartFilter. The general usage for ad hoc filters is to specify the filter type, such as ItemFilter, and then supply boolean values for each table that you want included by the filter. For example, the following ad hoc filter includes the TitleBlock and PageTwo tables for items:

<filters>
<ItemFilter TitleBlock="true" PageTwo="true"/>
  </filters>

Most tables require simple boolean values. However, other tables support enumerated values that enable you to include the associated objects. For example, the BOM table supports the following enumerated values for filters: DoNotInclude (the default), TableOnly, SingleLevel, and Recurse.

Note:

The filter type that you specify depends on the output format. If you extract data to a PDX file, the filter type should be a superclass filter such as ItemFilter or ChangeFilter. If you extract data to an aXML file, the filter type should be a class filter such as PartFilter or ECOFilter.

3.2.3.3 An exportData Filter Example

The following code segment illustrates how to combine a predefined filter, "Default Part Filter," with an ad hoc filter that extracts all Item data, including attachments that may result from the query defined in the query example above.

...
<filters>
    <!--The following is a predefined filter specified by name-->
    <filter-name>Default Part Filter</filter-name>
    <!--The following is an ad hoc filter -->
    <ItemFilter TitleBlock="true" PageTwo="true"                
                     PageThree="true" History="true"                
             Attachments="TablesAndFiles"                
             BOM="Recurse" Changes="true"                
             WhereUsed="true"                 
             AML="TableOnly" Site="true"/>
 </filters>

...

3.2.4 Working with Formats

The exportData Web service operation can export data in either PDX or aXML format. For a description of these formats, see "Web Services Operations."

For more information on how to specify the supported formats, see the Export XML Schema documentation in "AIS Folders." To view the information, select documentation > schemas > export.htm.

3.2.4.1 An exportData Format Example

The following illustrates how to extract data in PDX format:

...
    <format>PDX</format>
  ...
A Sample exportData Web Service Operation
The following is a sample exportDataRequest, which demonstrates a complete exportData Web service operation request:

<exportDataRequest>
  <queries>    <query>      <criteria>[Title Block.Number] == '1000-02'</criteria>    <objectType>     <predefined>Item</predefined>    </objectType>   </query>  </queries> <site>    <site-name>Taipei</site-name> </site> <filters> <!--The following is a predefined filter specified by name--> <filter-name>Default Part Filter</filter-name> <!--The following is an ad hoc filter --> <ItemFilter TitleBlock="true" PageTwo="true"     PageThree="true" History="true"     Attachments="TablesAndFiles"     BOM="Recurse" Changes="true"     AML="TableOnly" Site="true"/>  </filters> <format>PDX</format>

</exportDataRequest>

The above XML sample is not a complete or valid SOAP request. Rather, this XML document represents the contents of a SOAP request body. In general, you do not need to manually generate the above XML document. Instead, the client-side stubs generated by a Web-Service-aware code library take care of creating an appropriately formatted XML document and placing it within a SOAP request, and this sample is an illustration of what the XML request generated by client-side stubs.

Note:

To generate the above XML in PDF format, the code that is submitted to the stubs must include at least one such parameter -c "[Title Block.Number] == '1000-02' " -f "Default Part Filter" -t Item -s Taipei.

3.2.5 Working with Tables in Export

With the exception of the PDX format, the Export operation supports exporting Job Function and Functional Team attributes as well as the Acknowledge workflow action. Also supports Functional Teams class tables in aXML, Text (csv), and Excel (xls).

Example 3-1 Using exportData to export tables supported by the Functional Teams class

runner export.ExportData -h server -l port -e virtualpath -u username -p password -c "[General Info.Name] equal to 'AIS_KFUNCTEAM1'" -t UserGroup -F "UserGroup.GeneralInfo" "UserGroup.FunctionalTeam" "UserGroup.JobFunction" "UserGroup.Discussions" "UserGroup.ActionItems" -o D:\UserGroups.axml -a aXML

3.3 Using the exportPartlist Web Service Operation

The exportPartlist Web service operation takes a multilevel BOM and "flattens" it into a list of the manufacturer parts in the BOM and their quantities and returns the data in aXML format. That is, it enables you to extract a rolled up set of parts, and the related Quantities Per Top Level Assembly (QPTLA). The value of the QPTLA is computed as the sum over recursive products starting from the top of the BOM tree. This Web service calculates the QPTLA for each unique item-revision pair, and returns the results in the Part Quantities element of the resulting aXML output.

Note:

The exportPartlist Web service exports data only for items with AMLs (approved manufacturer parts and their associated manufacturers). Items without AMLs are ignored.

3.3.1 Working with exportPartlist Queries

The exportPartlist Web service is similar to exportData in the way it accepts query definitions. The main difference is that you do not need to specify the object type against which the query is operating. This is because the queries related to a part list must always be queries against items.

3.3.2 Working with exportPartlist Filters

Filters are specified for the exportPartlist Web service operation similar to the exportData Web service operation. The only difference is which filters can be specified. Because exportData only operates over items, manufacturer parts (that is, AML) and manufacturers (AML's related manufacturers), the object-related filters are restricted to those three data types.

3.3.2.1 An exportPartlist Example

The following is an example of the exportPartlistRequest element. It is a simple adaptation of the previous exportData sample and demonstrates a complete exportPartlist Web service operation request.

Example 3-2 Using the exportPartlistRequest element

<exportPartlistRequest>
<queries><query><criteria>[Title Block.Number] == '1000-02'</criteria></query></queries><site><site-name>Taipei</site-name></site><filters><!--The following is a predefined filter specified by name--><filter-name>Default Part Filter</filter-name><!--The following is an ad hoc filter --><ItemFilter TitleBlock="true" PageTwo="true" PageThree="true" History="true" Attachments="TablesAndFiles" BOM="Recurse" Changes="true" WhereUsed="true" AML="TableOnly" Site="true"/></filters></exportDataRequest>

The following entries are removed from the previous exportData sample to make this adaptation:

The query element does not include an objectType element. This is because the exportPartlist Web service operation only queries against item objects.
The format element is not included in the exportPartlistRequest. This is because the exportPartlist Web service operation only exports data in the aXML format.

The preceding XML example is not a complete or valid SOAP request. Rather, this XML document represents the contents of a SOAP request body. Generally, you do not need to generate the above XML document manually. Instead, the client-side stubs generated by a Web-Service-aware code library create an appropriately formatted XML document and place it within a SOAP request. The above sample is an illustration of what the XML request generated by client-side stubs would resemble.

Note: