14 Importing and Exporting Data with SDK

This chapter includes the following:

About Importing and Exporting Data
Validating Import Data and Importing Data
Exporting Data from the SDK
Importing and Exporting Microsoft Project 2010 Files

14.1 About Importing and Exporting Data

You can use the SDK to import and export data from external databases into the PLM system. The source can be an Agile database, a third party Product Data Management (PDM) system, or an Enterprise Resource Planning (ERP) system. The following paragraphs provide background information, procedures, and examples to perform these tasks using the agile SDK.

14.2 Validating Import Data and Importing Data

When you import data, you have the option to validate the data, or ignore this step. The purpose of import validation is to check the data for compliance with applicable server rules such as length tolerances, allowable values, and other constraints. The validation process informs you of the data that will fail to import before initiating the process.

The SDK exposes two methods to programmatically perform the following import-related tasks:

The IImportManager.validateData(byte[], String, byte[], byte[], String[], List) method to validate the imported data for compliance with server business rules. This action is performed before importing the data to identify the invalid items in the input source data.
The IImportManager.importData(byte[], String, byte[], byte[], String[], List) method supports importing data into the PLM databases. This action is performed after running the IImportManager.validateData() method to select the data that meets the server business rules and is importable into the PLM system.

For more information about importing data, refer to Agile Integration Services Developer Guide and Agile Import and Export Guide.

The following example uses these methods to validate the imported data for compliance and import it into the PLM system upon validation.

Example 14-1 Validating and Importing Data into PLM

import com.agile.api.*;import java.util.*;import java.io.ByteArrayInputStream;import java.io.ByteArrayOutputStream;import java.io.FileInputStream;import java.io.FileOutputStream;import java.io.IOException;import java.io.InputStream;import java.util.ArrayList;import java.util.List;public class ImportClient {   public static IAgileSession session = null;   public static AgileSessionFactory factory;   public static void main(String[] args) {try {   String _url="http://localhost/Agile";   String _user="admin";   String _pwd="agile";   String srcFilePath="bom.txt";/* Supported file types: aXML,IPC2571, ExcelFile, DelimitedTextFile* The value of "-f" parameter is the same* in Import AIS sample command*/   String srcFileType="DelimitedTextFile";// Null implies loading the default mapping   String mappingPath="NewMapFile.xml";// Null implies do not transform   String transformPath=null;/* The value used by operations and options are the same as the value of  "-t"    parameter in the import AIS sample command. 
*/   String [] operations=new String[]{"items", "items.bom","items.aml"};*/   List options=new ArrayList();   options.add("BusinessRuleOptions|ChangeMode=Authoring");   options.add("BusinessRuleOptions|BehaviorUponNonExistingObjects=Accept");   String _output="log.xml";   FileOutputStream fop=new FileOutputStream(_output);// Create an instance of IAgileSession   session = connect(_url,_user,_pwd);   IImportManager imgr = (IImportManager)          session.getManager(IImportManager.class);   byte[] logData=null;
// Insert Code to import and validate data. See sample in Example 14-2.
   int n=0;   InputStream logStream=byte2stream(logData);   while((n=logStream.read(buf))!=-1){   fop.write(buf, 0, n);      }       fop.close();      }       catch (Exception e) {e.printStackTrace();      }      finally {session.close();      }   }/*   * <p> Create an IAgileSession instance </p>   * @return IAgileSession   * @throws APIException*/   private static IAgileSession connect(      String _url,String _user,String _pwd) throws APIException {   factory = AgileSessionFactory.getInstance(_url);   HashMap params = new HashMap();   params.put(AgileSessionFactory.USERNAME, _user);   params.put(AgileSessionFactory.PASSWORD, _pwd);   session = factory.createSession(params);   return session;   }   private static byte[] stream2byte(InputStream stream)       throws IOException {   ByteArrayOutputStream outStream=new ByteArrayOutputStream();   byte buf[]=new byte[1024*4];   int n=0;   while((n=stream.read(buf))!=-1){      outStream.write(buf, 0, n);      }   byte[] data=outStream.toByteArray();   outStream.close();   return data;   }   private static InputStream byte2stream(byte[] data) throws IOException{   ByteArrayInputStream stream=new ByteArrayInputStream(data);   return stream;   }   private static byte[] convertFiletoStream(String path) throws IOException{   if(path==null || path.equals(""))      return null;      return stream2byte(new FileInputStream(path));      }   }

Example 14-2 Sample code to import and validate data

/* Sample code for Example 14-1, "Validating and Importing Data into PLM"    * Remove comments to run the importData example.   * byte[]logData=imgr.importData(stream2byte   * (new FileInputStream(srcFilePath)),   * srcFileType, convertFiletoStream(mappingPath),   * convertFiletoStream(transformPath),   * operations, options);   * Sample code to validate data   * Remove comments to run the validateData example   * logData=imgr.validateData(stream2byte   * (new FileInputStream(srcFilePath)),   * srcFileType, convertFiletoStream(mappingPath),   * convertFiletoStream(transformPath), * operations, options);   * byte buf[]=new byte[1024*4];
   * }

14.3 Exporting Data from the SDK

The SDK exposes the exportData()method to programmatically export data from PLM databases. This method is designed to overcome performance and memory issues that are encountered when loading large BOMs into the SDK programs. To overcome this issue, you can invoke the export functionality to load the BOM. The SDK programs are then able to read and export the data from extracted XML files.

For more information about exporting data, refer to the Agile Integration Services Developer Guide and Agile Import and Export Guide.

14.3.1 Invoking SDK's Export Function

Use the following call to invoke the export function of the SDK.

public byte[] exportData (Object[], Integer, String[])

In this call,

exportData - Is the method that returns the exported data in an array of bytes. The byte array represents a ZIP file that contains the export XML file in aXML or PDX formats and any file attachments that are included in the exported package.
Object[]- Is the array of objects that are exported from PLM to the external system. These objects are passed as IDataObject objects.
Integer - Is the indicator (constants that are provided in ExportConstants.java) to identify whether the output export format should be aXML or PDX. These are the two formats that the SDK supports.
String[] - Is the array of ACS filter names that are used for the export. The filter names are not case sensitive and must match the names of filters defined by the Admin tool for ACS.

The conditions that causes the exportData method to throw an exception and the respective exceptions are:

Invalid Data Format - The method was called with an unrecognized value for the export data format. Only aXML (provide constant label) and PDX (provide constant label) values are valid.
No Filter Specified - The method was called but no filters were specified. At least one valid filter must be provided.
Specified Filter Not Found - The method was called with specified filter which was not found in the system

Example 14-3 Exporting data from PLM using the SDK

   ... //

   IItem item = (IItem) session.getObject(IItem.OBJECT_TYPE, "P0001");   if (item == null) {   ... // throw an error, the part wasn't found   }

   IDataObject[] expObjs = {item};   String[] filters = {"Default Item Filter"};

   ...

   IExportManager eMgr = (IExportManager)       session.getManager(IExportManager.class);      try {      byte[] exportData = 
      eMgr.exportData(expObjs, ExportConstants.EXPORT_FORMAT_PDX, filters);   if (exportData != null) {      String fileName = createOutputFileName();      FileOutputStream outputFile = new FileOutputStream(fileName);      outputFile.write(exportData);      outputFile.close();......System.out.println("Data exported to file: " + fileName);      }   } catch (Throwable t) {       // error handling   }

14.4 Importing and Exporting Microsoft Project 2010 Files

Microsoft Project 2010 (MSP) integration with PPM is based on the XML format used by MSP. Project data between MSP and PPM is transferred in XML format. The XML format used for this integration is the same as the one used by MSP. This integration is carried out with the aid of the following three operations:

Validate - All MSP data is validated before importationImport - Imports project data by synchronizing the data from MSP to the corresponding PPM project tree. In the event a PPM Project tree is not available, this operation will create a new project tree.Export - Exports project data by synchronizing the data from PPM to MSP

You can perform these operations programmatically using APIs listed in the following paragraphs.

14.4.1 Validating MSP Import Data

This API validates MSP data in XML format. In this process, it takes the document object as the parameter and returns a Boolean True if the validation is successful. If there are any validation errors, it throws an API exception to the client

Object validateXML(Object documentObject) throws APIException

Validate API is exposed in IAgileSession.This API enables validating the XML data that was newly created in MSP.Validate API is also exposed in IProgram. This API enables validating the data in the document that was retrieved from an existing Program in PPM.

Validate APIs of session and program uses the validateMSPXML API of the Activity to validate do the XML data. It returns the MspSyncActivityVO object which provides the validation results. The MspSyncActivityVO object is passed to the validateXML method of PCUtil which processes the validation information. The validateXML method returns true if the validation is successful and there were no errors. In case of any validation errors, the exceptions are added to a batch exception file that is thrown.

Example 14-4 Validate the data prior to publication

// Create an IAgileSession instance - Login to Agile server.   session = connect();//Validate the document before publication   session.validateXML(document)

14.4.1.1 Importing MSP Data

This Import operation reads the MSP project data sent in the XML format and synchronizes it with project data in the PPM. The File Manager (DFM) is used as an intermediary tool to transfer the MSP XML file from the Client machine to the Server.

The Import operation is performed in one of the two following modes:

Create Mode - A new PPM project tree is created for the imported MSP project XML file.Update Mode - Updates the existing PPM project tree with the MSP project data.

This API imports the data from MSP to PPM and returns the IProgram to the Client upon successful completion of the Import operation.

14.4.1.1.1 Create Mode

For Create mode, the Import API is exposed in IAgileSession and enables publishing the data which was newly created in the XML format from MSP to PPM.

API Signature

Object publishXML(Object documentObject, Object resNameToUserIdObject, Object resNameToRolesObject, Integer templateType, boolean setScheduleEditorToPPM) throws APIException

API Parameters
- documentObject - This parameter is a Document Object retrieved from the MSP XML.resNameToUserIdObject - This parameter is a Map<String, Long/IUser> of User Name to Agile User ID. User ID can be passed as a Long object or an IUser object.resNameToRolesObject - This parameter is a Map<String, String/IRole[]> of User Name to array of Roles. Roles can be a String array of Role IDs or an array of IRole Objects.templateType - This parameter specifies the template type for the new project. Values of template type are defined in ProgramConstants.java as ACTIVE_STATE, TEMPLATE_STATE and PROPOSED_STATE.setScheduleEditorToPPM - This parameter determine whether the Schedule Editor for the new Program is set to PPM or not.
  
  IProgram program = (IProgram)session.publishXML(document, resNameToUserId, resNameToRoles, ProgramConstants.ACTIVE_STATE, false)

14.4.1.1.2 Update Mode

The import API for Update mode is exposed in IProgram and enables users to publish the data that was retrieved from PPM and modified in MSP

API Signature - This API takes only three parameters explained above.

Object publishXML(Object xmlDocument, Object resNameToUserIdObject,Object resNameToRolesObject) throws APIException

Code sample

IProgram program = (IProgram)program.publishXML(document, resNameToUserId, resNameToRoles);

The Import API for session and program publishes the XML data to PPM only if data validation is successful. It will then call the validate API to ensure the data designated for publication is correct. Once validation is successful without any errors, SyncMspToPE API of Activity is used to publish the XML data to PPM. Data in resNameToUserIdObject and resNameToRolesObject is prepared by prepareUsersForMSP of PCUtil in the required format for SyncMspToPE.

14.4.1.2 Exporting MSP Data

The Export operation is invoked on a particular PPM project to generate the PPM project data in MSP XML format.The export operation is performed in one of the two following modes

Create Mode - A new XML file in MSP XML format is generated with the selected PPM project data. This XML file will contain a limited subset of the XML tags.Update Mode - It there are any previously imported MSP XML files for the PPM project that are stored in DFM, the XML file is sent to the Client once it is updated with the latest PPM project data such as task name,% complete, description, and so on.

14.4.1.2.1 API Signature

Object saveAsXML(Integer saveAsXMLMode) throws APIException;

The saveAsXMLMode is the only parameter that is supplied to the API. It defines the mode in which the data is exported. The values of saveAsXMLMode are defined in ProgramConstants.java as SAVE_AS_XML_READ and SAVE_AS_XML_EDIT. If the mode type is Read, then the data exported to MSP is available for read-only purposes and cannot be published back to PPM. If the mode type is Edit, then the exported data can be modified in MSP and can be published back to PPM.

   document =        (org.jdom.Document)program.saveAsXML(ProgramConstants.SAVE_AS_XML_EDIT);

The export API uses the SyncPEToMSP API of Activity to return the program data in the form of org.jdom.Document object.