Tridion R5. Business Connector Guide 5.2 SP1

Transcription

1 Tridion R5 Business Connector Guide 5.2 SP1

2 Business Connector Guide 5.2 SP1 Revision CM_BC_52SP Tridion Development Lab BV NOTICE: The accompanying software package is confidential and proprietary to Tridion Development Lab BV or its respective licensors. No use or disclosure is permitted other than as set forth by written license with the authorized distributors of Tridion Development Lab BV. Trademarks Tridion and Tridion R5 are trademarks of Tridion Development Lab BV or its respective licensors. All other company or product names used herein are trademarks of its respective owners. Suggestions Your suggestions and comments about Tridion R5 functionality, documentation and course material are highly valued and may be used to further enhance our offerings available to you. We will be glad to receive your suggestions at: Tridion Development Lab BV Product Management P. O. Box DE Amsterdam The Netherlands fax: +31 (0) Additional Licenses Please contact your Tridion sales representative to order additional licenses of Tridion R5 software. offers you a complete overview of Tridion's sales offices and further contact details.

3 Table of contents Chapter 1 Introduction a Synchronize with external systems b Import content a Custom listener b Farm files c XML Responder Task... 4 Chapter 2 Configuring the Business Connector Configuring Web Services Farm files Configuring Business Connector Properties Maptables Configuring the WSDL file Accessing the Web Service from Visual Studio.NET... 9 Chapter 3 Defining Business Connector tasks Properties passed to pipeline.xml Example of an XML Responder task Mapping task Download tasks a FileDownloadTask b FtpDownloadTask c HttpDownloadTask Using the Base64 encoding utility Chapter 4 Requests and responses Request format Request and response examples a Getting a list of Publications b Getting the contents of a Publication c Getting the list of a Folder i

4 Business Connector Guide 5.2 SP1 4.2.d Creating an item e Updating an item f Deleting an item g Composite requests h Low-level API request examples i Sending properties ii Tridion R5

5 Preface About this guide This guide is written for XML and XSLT developers. The following knowledge is assumed: Tridion R5 Content Manager XML and XSLT SOAP How to use this guide Visual Basic (or any other COM compliant programming language) Apache Ant 1.5 ( The purpose of this guide is to describe how to configure and use the Tridion Business Connector, the Tridion XML content-exchange engine. Read this guide to use the Business Connector according to your organization s requirements. The information in this guide is organized as follows: Chapter 1 Introduction Describes Business Connector functionality and architecture. Chapter 2 Configuring the Business Connector Describes the configuration of the Business Connector. Chapter 3 Defining Business Connector tasks Describes how to create tasks. Chapter 4 Requests and responses Describes how to create requests and interpret the responses and provides request and response examples. iii

6 Business Connector Guide 5.2 SP1 Related documents Version history This guide is one document from the documentation set for Tridion R5. The full documentation set consists of the following documents: The Tridion Installation Guide explains how to get Tridion R5 modules up and running. The Tridion Upgrade Guide explains how to upgrade and configure Tridion R5 modules included in this release. It is intended for system administrators that want to upgrade their system from older versions of R5. Platforms and Requirements lists the prerequisites for Tridion R5, as well as the software and hardware it supports. The Administration Guide explains how to perform general administrative tasks for the Content Manager. It is intended for system administrators. The Content Manager User Manual explains which tasks an end user can perform using this product, and what it means to perform those tasks. The Content Manager Publication Management Guide explains how to manage Publications within the Content Manager. The Content Manager Programmer s Reference Guide explains how to configure the product in detail and how to extend its functionality through scripting and programming. It is intended for software developers. The WebDAV Connector User Manual explains which tasks an end user can perform using the Tridion WebDAV Connector. The Business Connector Guide explains how to use the Tridion Business Connector. The Content Delivery Guide explains how to configure and use the Content Delivery modules. For information about this specific release or Tridion R5, see the Tridion Release Notes document. This version history list outlines the changes to this guide since it was last released. Product version Changes 5.1 Main release. 5.1 SP1 Inclusion of an index. 5.1 SP2 Tomcat is removed as a prerequisite for this product. New configuration settings are described. 5.1 SP3 Information added about use of JRE files. See "Sun Java Runtime Environment (JRE)" on page SP4 No changes. 5.2 No changes. 5.2 SP1 No changes. iv Tridion R5

7 Chapter 1 Introduction The Business Connector uses XML instruction sets to exchange content between third-party systems and the Tridion Content Manager. The Business Connector supports the following: XSLT or other transformation services XSLT can be used to transform content from the Tridion format to the format of the external system, and vice versa. Mapping internal and external IDs You can use mapping to establish a correlation between IDs used in the external system and the corresponding item in the Content Manager. The Business Connector stores these mappings in its own maptable database. Composite action API One Business Connector message can contain multiple requests. For example, a single message can be used to update content, check-in content, and publish content. Stateless programming model The Business Connector provides a stateless programming model. Platform independent API The Business Connector API is accessible using the Simple Object Access Protocol (SOAP). Therefore, the Business Connector can be accessed from any platform that supports SOAP. The Business Connector uses SOAP as a Web service (WSDL), to communicate with external systems. The Business Connector can be installed using the Tridion Content Manager installer. This chapter describes: Using the Business Connector Business Connector architecture Apache software used by the Business Connector 1

8 1.1 Using the Business Connector The following examples illustrate the ways in which you can use the Business Connector: Synchronize with external systems Synchronize with external content from an e-commerce application. Import content Receive incoming content and transform this content to a Tridion-compatible format that can be published. 1.1.a Synchronize with external systems The Business Connector can synchronize Content Manager content (Components) with products defined in an external system, such as a cataloging application. For example, a product item in an external system may map to a specific Component in the Content Manager. As a result, the administrator of the external system can update product quantities or create new product lines in that external system. The Business Connector can update this content in the Content Manager automatically or on a pre-defined schedule. The Business Connector defines the relationship between an external item and the Content Manager item by mapping the identifiers in the two systems. The Business Connector s MapTable allows you to identify this relationship. As a result, an external system can export content to the Content Manager. The request uses the MapTable to identify the corresponding items in both systems. 1.1.b Import content The Business Connector works with a small application called a listener. The listener polls specific locations (using FTP, HTTP, and so on) for new content. You create these listeners specifically for your organization s requirements. For example, a newspaper Web site, The Tridion Times, has a breaking-news ticker running along the main page. This content comes from authors working anywhere in the world. These authors may not be able to access to the Content Manager to enter their content directly. However, they can write up their story with a predefined structure and it to an SMTP server, newsfeed@tridiontimes.com. The listener polls the SMTP server for content sent to newsfeed@tridiontimes.com, detects the new content, and automatically imports it to the Business Connector. The Business Connector then transforms the content into a format that the Content Manager can use in the ticker using a predefined XSLT. Note You can use other transformation methods, you are not limited to XSLT. However, this document describes XSLT only. Depending on the instructions specified in the request, this method can also enter the new content into a Workflow process or a Blueprinting hierarchy in the Content Manager. 2 Tridion R5

9 Business Connector Guide 5.2 SP1 1.2 Business Connector architecture The Business Connector uses a cartridge architecture, which allows you to develop individual solutions and then slot these solutions into the Business Connector. A cartridge is a conceptual object that contains the following components: A configuration Farm that details specific XSLTs and configuration options A listener application The Business Connector has the following components: Business Connector Service Implemented in.net, this service exposes a SOAP API. Business Connector Implemented as a Java class, the Business Connector processes the incoming request and generates the request s XML file. Configuration files Farm files that are implementation-specific and configuration files that specify which config.xml and pipeline.xml to use for that implementation. XSLTs (optional) Transforms the incoming content into a format that the Content Manager can use. XML Responder Task Passes the formatted request to the Content Manager s XML Responder and receives the response after the Content Manager has finished processing the request. Figure 1-1 Business Connector architecture See also "Custom listener" on page 3 "Farm files" on page 4 "XML Responder Task" on page a Custom listener You must create and define your own custom listener for the client application. The Business Connector exposes itself as a SOAP interface, therefore the listener must support SOAP. The listener can be remote or local and can use either COM or Java. 3

10 1.2.b Farm files A Farm is a collection of files and folders that specify how the Business Connector should handle incoming requests and outgoing responses. Each implementation of the Business Connector uses a separate Farm. With each request, the listener specifies which Farm the Business Connector should use. The Farm is configured in XML files: Configuration (config.xml) Defines the properties of the Business Connector implementation. Pipeline (pipeline.xml) Describes the tasks the Business Connector must perform. The client can decide if transformation should be skipped if it uses the Business Connector s native XML format, for example. 1.2.c XML Responder Task The XML Responder task is one of the tasks specified in the Farm's pipeline. This task calls the Content Manager XML Responder. After the Content Manager processes the request, it returns a response to the Business Connector. The Business Connector continues with the tasks specified in the pipeline.xml and returns it via the SOAP API to the listener. 1.3 Apache software used by the Business Connector This module includes software developed by the Apache Software Foundation ( The Business Connector uses the following Apache technologies: Ant 1.5 Build tool used to run Business Connector tasks Digester 1.2 XML configuration reader used to read the config.xml file Portions of the Apache documentation for Ant 1.5 are reproduced in Chapter 3 "Defining Business Connector tasks" on page 11, as the Business Connector s pipeline.xml is the Tridion counterpart to Ant s build.xml. pipeline.xml specifies all the tasks performed by your implementation of the Business Connector, and uses the same formatting and syntax as the Ant build.xml file. Ant is a very extensible tool, but not all of its functionality is used in a standard implementation of the Business Connector. As such, the properties and attributes described in this document pertain directly to using the Business Connector for the types of implementation described in this document. If you want to extend the Business Connector s functionality further, consult the Ant 1.5 task documentation on the jakarta.apache.org site. 4 Tridion R5

11 Chapter 2 Configuring the Business Connector Every Business Connector implementation requires the following: Farm files that contains the references for your implementation. These files describe the location of required XSLTs, config.xml and pipeline.xml files. config.xml Describes the Business Connector properties. pipeline.xml Describes the Business Connector tasks for a specific implementation. businessconnector.properties This file is created during the installation of the Business Connector and describes the locations of all the relevant files for the Business Connector, such as the conf, and working directories. A functional.net installation A maptable database This database contains the mappings between the external content source and the corresponding Content Manager values. This chapter describes: Configuring Web Services Farm files Configuring Business Connector Properties Maptables Configuring the WSDL file 5

12 Chapter 2 Configuring the Business Connector 2.1 Configuring Web Services The Business Connector uses the.net Web Service and the Business Connector COM Win32 Service. The Content Manager installer installs the Web Service Component. However, you must ensure that the targeted system is correctly configured with.net Runtime 1.1. Ensure that the following items have the correct configuration: A Virtual Directory named BCListener under the Tridion Web Site exists The Virtual Directory points to the location of the Business Connector Web Service The web.config file points to the attachment directory used by the BusinessConnector.Properties file Important: If you make any changes to the Business Connector, you must restart the Business Connector Win32 Service to ensure that the configuration changes take effect. Security requirements The role of the Business Connector impersonation user (who impersonates a Tridion user) is performed by the ASP.NET user. By default, the ASP.NET user is: On Windows 2000 MACHINE_NAME\ASPNET On Windows 2003 NT AUTHORITY\NETWORK SERVICE Because they are used as impersonation users, these ASP.NET user accounts require the following basic permissions: Table 2-1 Rights for ASP.NET user (Business Connector impersonation user) Folder (under Tridion root folder) Read Write Execute Modify bc bc\work bc\attachments bin Authentication You can use both Basic Authentication and Integrated Windows Authentication with the Business Connector. 6 Tridion R5

13 Business Connector Guide 5.2 SP1 In general, unless you are using LDAP, use Integrated Windows Authentication and do not configure Basic authentication. Important: To ensure access to the Content Manager, you must run the Business Connector COM Service (BCCOM) under a valid impersonation user. Sun Java Runtime Environment (JRE) The Business Connector uses JRE xml libraries to process xml constructs. The jar files incorporated in the JRE are of a lower version than those used by the Business Connector. As a result, you must modify some of your JRE root files to ensure that the newest jars are used. To ensure that the Business Connector uses the correct files: 1 Locate the correct JRE root by checking the following registry key: HKEY_LOCAL_MACHINE\Software\JavaSoft\Java Runtime Environment\ [java_version_nr]\javahome 2 In the %JRE_ROOT%\lib directory, create a directory called endorsed 3 Copy the following files from the %TRIDION_ROOT%\bc\lib directory: xalan.jar xercesimpl.jar xml-apis.jar Chapter 2 Configuring the Business Connector 4 Paste these files into the %JRE_ROOT%\lib\endorsed directory. 2.2 Farm files The Farm is a collection of files and folders that specify how the Business Connector should handle incoming requests and outgoing responses. Each implementation of the Business Connector uses a separate Farm. The Farms are stored in C:\Program Files\Tridion\BC\conf\default. To create a new Farm, create a folder in the C:\Program Files\Tridion\BC\conf\ directory. The name of the folder is the name of the Farm. This Farm must contain the config.xml and pipeline.xml files for that Farm. The folders and files included in the Business Connector installation are as follows: attachments Storage for attachments conf contains the Business Connector s property files, including the logging property file the configuration files for each implementation which uses the Business Connector. Each implementation uses a separate directory in the conf directory. lib Java class storage 7

14 Chapter 2 Configuring the Business Connector work Storage for requests and responses, which are created in folders named after the farm responsible for the individual requests, and responses xsd Storage for your validation schemas This businessconnector.properties file describes the locations of all the relevant files for the Business Connector, such as the conf, and working directories. 2.3 Configuring Business Connector Properties config.xml defines the following Business Connector properties: bc.in.file the name of the request file, such as XMLResponderIn.xml. bc.out.file the name of the response file, such as XMLResponderOut.xml. The following is an example of the config.xml: <?xml version="1.0" encoding="utf-8"?> <properties> <property name="bc.in.file" value="xmlresponderin.xml"/> <property name="bc.out.file" value="xmlresponderout.xml"/> </properties> 2.4 Maptables The Business Connector uses maptables to map an external ID to an internal ID. This map table is called 'bcmap' and can be in any type of database that has a JDBC driver and contains three columns: Internal ID External ID Sessions ID The pipeline.xml file specifies the connection string and name of the columns. If the pipeline.xml file uses a password, it is encrypted in Base64. See also For more information on the encoding used in the Business Connector, see "Using the Base64 encoding utility" on page 19. pipeline.xml describes which of the following actions the Map Task should perform: LookupInternalId AddMapping DeleteMapping 8 Tridion R5

15 Business Connector Guide 5.2 SP1 2.5 Configuring the WSDL file To use the Business Connector as a Web Service, Tridion provides a Web Services Description Language (WSDL) file. The WSDL file tells the client application how to access the Web Service. The WSDL file can be requested from the Business Connector with the following URL: " The WSDL file can be used with several Web Service clients like Microsoft SOAP Toolkit and Apache AXIS for Java. 2.6 Accessing the Web Service from Visual Studio.NET Once the Business Connector is installed, you can access the Business Connector from Microsoft Visual Studio.NET. To access Business Connector from Microsoft Visual Studio.NET: 1 In Visual Studio, select Project>Add Web Reference from the menu bar. 2 Type the WSDL URL in the address bar and press enter on your keyboard. 3 After the Web Service files are downloaded, click Add Reference. Chapter 2 Configuring the Business Connector Results The Business Connector can now be accessed as Web Service in Visual Studio. Figure 2-1 Business Connector as a Web Service Example of requesting Business Connector in C#.NET The Network credentials should be supplied by the.net application for authentication. You should add a web reference to the Business Connector by binding it to the new end point: Consult the Microsoft.NET documentation for more information. 9

16 Chapter 2 Configuring the Business Connector To request the Business Connector in C#.NET: //Create a new BusinessConnector object. In this case we already made //a Web Reference to the Server hosting the BusinessConnector and gave it //the BusinessConnectorService alias. BusinessConnectorService.BusinessConnector bcservice = new BusinessConnectorService.BusinessConnector(); //In the example we use an XMLWriter object to create the requestxml //but any other //source can be used to generate the string. //This example makes a tcmapi:getlist request of type ListPublications StringWriter stringwriter = new StringWriter(); XmlTextWriter writer = new XmlTextWriter(stringWriter); writer.writestartdocument(); writer.writestartelement("tcmapi","message"," ntmanager/5.0/tcmapi"); writer.writeattributestring("version","5.0"); writer.writeattributestring("from","bcclient"); writer.writeattributestring("failonerror","false"); writer.writestartelement("tcmapi","request"," ntmanager/5.0/tcmapi"); writer.writeattributestring("id","anything"); writer.writeattributestring("preserve","false"); writer.writestartelement("tcmapi","getlist"," ntmanager/5.0/tcmapi"); writer.writeattributestring("itemuri","tcm:0-0-0"); writer.writeattributestring("listtype","listpublications"); writer.writeendelement(); writer.writeendelement(); writer.writeendelement(); writer.close(); stringwriter.close(); //obtain the default credentials used. bcservice.credentials = System.Net.CredentialCache.DefaultCredentials; //call the BC WebService. Note that we pass null for farmprops but if we desire //we can also send cutom properties. string response = bcservice.execute("default",stringwriter.tostring(),null); MessageBox.Show(response); //This example is the same request as above except that it will send //a custom property via the farmprop parameter. BusinessConnectorService.Map map = new BusinessConnectorService.Map(); //Initialize the Map array to 1, can be bigger if needed. map.item = new BusinessConnectorService.itemType[1]; //Array contains itemtype objects so we need to create one. map.item[0] = new BusinessConnectorService.itemType(); map.item[0].key = "custom Property"; map.item[0].value = "custom Value"; //call the BC WebService. response = bcservice.execute("default",stringwriter.tostring(),map); MessageBox.Show(response); 10 Tridion R5

17 Chapter 3 Defining Business Connector tasks This chapter describes the tasks you can define in the pipeline.xml task file. This task file is used to describes the Business Connector tasks for a specific implementation. pipeline.xml is the Tridion equivalent of the Apache Ant 1.5 build.xml file. Tridion uses Ant 1.5 as an XML serializer. The Business Connector implementation reads the XML as an event-driven instruction set and performs tasks on the Request and Response files. Ant does not perform actions on the Content Manager. It passes the Request file to the Content Manager and passes the Response back to the client. Ant uses the Tridion XML Responder task to perform actions on the Content Manager. You can define the following types of tasks: Sending updates or notifications Copying the request and/or response to another location for project tracking Performing XSLT transformations on the request and/or response Downloading content using FTP or HTTP(S) This chapter describes: Properties passed to pipeline.xml Example of an XML Responder task Mapping task Download tasks Using the Base64 encoding utility 11

18 Chapter 3 Defining Business Connector tasks 3.1 Properties passed to pipeline.xml The following properties are passed to the pipeline.xml file: bc.lib.dir directory in which libraries are located bc.in.file name of the file in which the request is stored. Must be defined in config.xml file bc.out.file name of the file in which the response is stored. Must be defined in config.xml file username username that is issuing the request. If the username is defined in config.xml, then the user defined in the config.xml file is used. Normally the user name is the same user as authenticated by IIS. basedir even though the project element has its own basedir attribute, this value is overwritten by the Business Connector upon calling Ant. bc.xsd.dir directory in which schemas used for validation are stored. bc.conf.dir directory in which the configuration for the farm is specified, that is, the directory where the config.xml and pipeline.xml are located; it is also the directory in which property files are located. All these properties, with the exception of bc.in.file and bc.out.file, are specified by the Business Connector. 3.2 Example of an XML Responder task In the following example the XML Responder task is called. Notice the use of the properties used in pipeline.xml and the properties set in config.xml. The path definition in indicated in bold must be added to the project. Without this path definition, the Business Connector fails. Always include this path definition exactly as defined below: <?xml version="1.0"?><project name="test_xmlresponder_task" default="xml_responder" basedir="."> <path id="classpath"> <fileset dir="${bc.lib.dir}"> <include name="**/*.jar"/> </fileset> <pathelement location="${bc.classes.dir}"/> </path> <taskdef name="xmlrespondertest" classname="com.tridion.integrations.bc.tasks.xmlrespondertask"> <classpath refid="classpath"/> </taskdef> <target name="xml_responder"> <xmlresponder infile="${bc.in.file}" outfile="${bc.out.file}" username="${username}" </xmlresponder> </target> </project> 12 Tridion R5

19 Business Connector Guide 5.2 SP1 Before using the XMLResponderTask, it must be defined using the taskdef element, common in Ant when using external tasks, such as the XMLResponderTask. Other tasks can be used for customized actions, like XSLT transformation on the request and/or response file. The example below uses the Ant XSLT task: <?xml version="1.0"?> <project name="test_bc_tasks" default="responsetransform" basedir="."> <path id="classpath"> <fileset dir="${bc.lib.dir}"> <include name="**/*.jar"/> </fileset> <pathelement location="${bc.classes.dir}"/> </path> <taskdef name="xmlrespondertest" classname="com.tridion.integrations.bc.tasks.xmlrespondertask"> <classpath refid="classpath"/> </taskdef> <target name="requesttransform"> <xslt in="${bc.in.file}" out="requesttransformed.xml" extension=".xml" style="${bc.conf.dir}/requesttemplate.xslt"> </xslt> </target> <target name="xmlresponder_test" depends="requesttransform"> <XmlResponderTest infile="requesttransformed.xml" outfile="responseoriginal.xml" username="${username}"> </XmlResponderTest> <echo message="${myproperty}"/> </target> <target name="responsetransform" depends="responsetransform"> <xslt in="responseoriginal.xml" out="${bc.out.file}" extension=".xml" style="${bc.conf.dir}/responsetemplate.xslt"> </xslt> </target> </project> Chapter 3 Defining Business Connector tasks In the example above, the bc.in.file property is used as input file for the XSLT task, transformed using the RequestTemplate.xslt file in the directory specified by the bc.conf.dir (the directory where pipeline.xml and config.xml are located) and the output is written to a file called RequestTransformed.xml. This transformed file is used as the input file for the XMLResponderTask, and the output file of this task is again transformed by the ResponseTemplate.xslt stylesheet. The output of the last transformation is written down to the file specified in bc.out.file (see the config.xml for the name of this file), and returned to the client as the SOAP response. Table 3-1 describes the attributes used in the XMLResponderTask. Table 3-1 XMLResponderTask attributes Attribute infile outfile username Description Name of the XML input file that contains the request. Name of the XML output file that will contain the response. Name of the user that has been authenticated. This value can be overwritten by setting a username property in the config.xml file. 13

20 Chapter 3 Defining Business Connector tasks 3.3 Mapping task To map external IDs to internal IDs, the Business Connector uses a map table called 'bcmap'. This map table can be stored in any type of database that uses JDBC driver (or ODBC via a JDBC-ODBC bridge). It contains three columns: Internal ID External ID Session ID The MapTask defines: The names of the columns (intcol, extcol and sescol). The connection string If require a password, you must enter the password encrypted using BASE64. See "Using the Base64 encoding utility" on page 19 for more information. The MapTask can perform three actions: LookupInternalId Look up the external ID and session ID specified in the input file and return the internal ID in the output file. If the IDs are not found, the value NULLURI is returned. AddMapping Add a record with the IDs specified in the input file. DeleteMapping Delete the record with the IDs specified in the input file Table 3-2 describes the attributes used in a Map task. Table 3-2 Maptask attributes Attribute infile outfile intxpath extxpath sesxpath driver url username password intcol extcol sescol Description Name and location of the XML input file that contains the original IDs. Name and location of the XML output file that contains the mapped IDs. The XPath expression used to get the textnode with the internal IDs from the input file. The XPath expression used to get the textnode with the external IDs from the input file. The XPath expression used to get the textnode with the session IDs from the input file. The driver JDBC uses to make the database connection. The URL of the maptable database. Username for connection to the data source. Password for connection to the data source. The password must be specified using Base64 encoding. See "Using the Base64 encoding utility" on page 19. Name of the column where the internal ID is stored in the database. Name of the column where the external ID is stored in the database. Name of the column where the session ID is stored in the database. 14 Tridion R5

21 Business Connector Guide 5.2 SP1 Table 3-2 Maptask attributes (Continued) Attribute action failonerror Namespaces Description The action the Task performs. The following are the possible actions: LookupInternalId Look up the ID and session ID specified in the input file and return the internal ID in the output file. If the ID's are not found, internal ID NULLURI is returned. AddMapping Add a record with the IDs specified in the input file. DeleteMapping Delete the record with the IDs specified in the input file The string value of the action argument is case insensitive. Applicable only if the action is LookupInternalId or DeleteMapping. If the value is "true", then the task fails, if the value is "false" the task continues processing. If the XML in-file uses namespaces, this attribute allows you to set the namespaces used to search through the XML file. If no namespaces are used, declare the attribute, but leave the value empty (namespaces=""). The following example shows a MapTask: <taskdef name="maptask" classname="com.tridion.integrations.bc.tasks.maptask"> <classpath refid="classpath"/> </taskdef> <target name="mapper"> <maptask infile="lookupmaptasksrc.xml" outfile="temp\lookupmaptaskdest.xml" intxpath="/myprefix:doc/secondprefix:internal/secondprefix:id/text()" extxpath="/myprefix:doc/secondprefix:external/secondprefix:id/text()" sesxpath="/myprefix:doc/myprefix:session/myprefix:id/text()" driver="sun.jdbc.odbc.jdbcodbcdriver" url="jdbc:odbc:;dbq=busconmap.mdb;defaultdir=maptasktest; DRIVER={Microsoft Access Driver (*.mdb)}" username="" password="" intcol="internal" extcol="external" sescol ="sessionid"action="lookupinternalid" failonerror="false" namespaces="xmlns:myprefix=' xmlns:secondprefix=' </target> Chapter 3 Defining Business Connector tasks To update existing mappings, use the deletemapping task before the addmapping task. You have two options for using the deletemapping task to update mappings: Option one Use the deletemapping task with failonerror set to false 15

22 Chapter 3 Defining Business Connector tasks Use the addmapping task Setting failonerror to false will make sure if the entry already exists, it will be updated with the new value by removing the previous mapping. If the mapping did not exist, deletemapping will not fail and addmapping will add the mapping to the table. Option two Use deletemapping with failonerror set to true Use the addmapping task Setting failonerror to true will make sure if the entry already exists, it will be updated with the new value by removing the previous mapping. If the mapping did not exist, the deletemapping task will return an error. 3.4 Download tasks You can use three tasks to download files from a client to the server on which the Business Connector is running: FileDownloadTask FtpDownloadTask HttpDownloadTask 3.4.a FileDownloadTask The FileDownloadTask task allows the Business Connector to download a file from a network location. The classname for this task is com.tridion.integrations.bc.tasks.filedownloadtask. You define this task in the pipeline.xml file. Table 3-3 lists the attributes used in the FileDownloadTask. Table 3-3 FileDownloadTask attributes Attribute infile outfile Xpath DestDir Namespaces Description Name and location of the XML input file that describes the file to download. Name and location of the XML output file that describes the destination where the class has downloaded the file to. The value of this attribute can have the same value as the infile attribute (the file is then updated with the new location for the downloaded file). The XPath expression used to get the textnode with the file description from the input file and output file. The destination for the downloaded file. If the XML file to be processed uses namespaces, then this attribute allows setting the namespaces that are used to search through the XML file. If no namespaces are used, declare the attribute, but leave the value empty (namespaces="") The following example shows a FileDownloadTask:. 16 Tridion R5

23 Business Connector Guide 5.2 SP1 <path id="classpath"> <fileset dir="${tlib.dir}"> <include name="**/*.jar"/> </fileset> <fileset dir="${tdist.dir}"> <include name="**/*.jar"/> </fileset> <pathelement location="${tbuild.dir}"/> </path> <taskdef name="download" classname="com.tridion.integrations.bc.tasks.filedownloadtask"> <classpath refid="classpath"/> </taskdef> <target name="test_download"> <download infile="testfiledownloadsrc.xml" outfile="testfiledownloaddest.xml" xpath="/myprefix:doc/binary_loc/text()" destdir="c:\temp" namespaces="xmlns:myprefix=' </target> 3.4.b FtpDownloadTask This FtpDownloadTask allows the Business Connector to download a file from an FTP server. Chapter 3 Defining Business Connector tasks The classname for this task is com.tridion.integrations.bc.tasks.ftpdownloadtask. You define this task in the pipeline.xml file. Table 3-4 describes the attributes used in the FTPDownload task. Table 3-4 FtpDownload Task attributes Attributes infile outfile Xpath DestDir username password Namespaces Description Name and location of the XML input file that describes the to be downloaded file. Name and location of the XML output file that describes the destination where the class has downloaded the file to. The value of this attribute can have the same value as the infile attribute (the file is then updated with the new location for the downloaded file). The XPath expression that should be used to get the textnode with the file description from the input file and output file. The location where the downloaded file should be stored. Name of user to be used in the FTP file transfer. The value of this attribute must be set. The password of the user used in the FTP file transfer. The value of this attribute must be set using Base64 encoding. See "Using the Base64 encoding utility" on page 19. If the XML file to be processed uses namespaces, then this attribute allows setting the namespaces that are used to search through the XML file. If no namespaces are used, declare the attribute, but leave the value empty (namespaces="") 17

24 Chapter 3 Defining Business Connector tasks The following example shows an FtpDownloadTask:. <path id="classpath"> <fileset dir="${tlib.dir}"> <include name="**/*.jar"/> </fileset> <fileset dir="${tdist.dir}"> <include name="**/*.jar"/> </fileset> <pathelement location="${tbuild.dir}"/> </path> <taskdef name="download" classname="com.tridion.integrations.bc.tasks.ftpdownloadtask"> <classpath refid="classpath"/> </taskdef> <target name="test_download"> <download infile="testftpdownloadsrc.xml" outfile="testftpdownloaddest.xml" xpath="/myprefix:doc/binary_loc/text()" destdir="c:\temp" username="anonymous" password="bm90qgzyb20ubwu=" namespaces="xmlns:myprefix=' </target> 3.4.c HttpDownloadTask This task allows the Business Connector to download a file from a HTTP server. The classname for this task is com.tridion.integrations.bc.tasks.httpdownloadtask. You define this task in the pipeline.xml file. Table 3-5 lists the attributes used in the Map task. Table 3-5 HttpDownload task attributes (Sheet 1 of 2) Attribute infile outfile Xpath DestDir username Description Name and location of the XML input file that describes the file to be downloaded. Name and location of the XML output file that describes the destination where the class has downloaded the file to. The value of this attribute can have the same value as the infile attribute (the file is then updated with the new location for the downloaded file). The XPath expression that should be used to get the textnode with the file description from the input file and output file. The location in which the downloaded file should be stored. Name of user to be used in the HTTP file transfer. If this argument is not provided, the session is started as anonymous login. 18 Tridion R5

25 Business Connector Guide 5.2 SP1 Table 3-5 HttpDownload task attributes (Sheet 2 of 2) Attribute password https Namespaces Description The password of the user used in the HTTP file transfer. If this argument is not provided, the session is started as anonymous login. The value of this attribute must be set using Base64 encoding. See "Using the Base64 encoding utility" on page 19. If this argument is set to 'true', the transfer will be performed with the secured HTTPS protocol. Default value of this argument is 'false'. If the XML file to be processed uses namespaces, then this attribute allows setting the namespaces that are used to search through the XML file. If no namespaces are used, declare the attribute, but leave the value empty (namespaces="").. <path id="classpath"> <fileset dir="${tlib.dir}"> <include name="**/*.jar"/> </fileset> <fileset dir="${tdist.dir}"> <include name="**/*.jar"/> </fileset> <pathelement location="${tbuild.dir}"/> </path> <taskdef name="download" classname="com.tridion.integrations.bc.tasks.httpdownloadtask"> <classpath refid="classpath"/> </taskdef> <target name="test_download"> <download infile="testhttpdownloadsrc.xml" outfile="testhttpdownloaddest.xml" xpath="/myprefix:doc/binary_loc/text()" destdir="c:\temp" username="anonymous" password="bm90qgzyb20ubwu=" namespaces="xmlns:myprefix=' </target> Chapter 3 Defining Business Connector tasks 3.5 Using the Base64 encoding utility You can use a Business Connector utility to encode text using Base64. The Business Connector uses Base64 encoding as input for passwords defined in the tasks. To use this utility, you must set the BusinessConnector.jar file in the system CLASSPATH environment, or use the example below, where the location of the BusinessConnector.jar file is specified. C:\ java -classpath BusinessConnector.jar;log4j-core.jar com/tridion/integrations/bc/utils/passwordencrypter passwordtoencode 19

26 Chapter 3 Defining Business Connector tasks 20 Tridion R5

27 Chapter 4 Requests and responses The Business Connector uses Apache Ant 1.5 to pass the Request file to the Content Manager and pass the Response back to the client. The config.xml file holds Business Connector properties. This file requires at least two of the following properties: the name of the request file the name of the response file This chapter describes the format of Business Connector requests and provides examples of requests and responses. 4.1 Request format The Request is formatted in the following way: <?xml version='1.0'?> <tcmapi:message xmlns:tcmapi=" version="5.0" from="mdvc" failonerror="false"> <tcmapi:request ID="ResponderRequest" preserve="false"> <tcmapi:action="itemuri"/> </tcmapi:request> <tcmapi:request ID="ResponderRequest" preserve="false"> <tcmapi:action="itemuri"/> </tcmapi:request> </tcmapi:message> Where: The Request root element is always <tcmapi:message>, and this element contains one or more <tcmapi:request> elements The <tcmapi:request> elements contains one or more <tcmapi> elements, which contain the Tridion Content Manager action and request data. The ItemURI is a Tridion Content Manager URI. These are unique identifiers for each item in the Content Manager. The URI tcmuri:0-0-0 is the root of the system. 21

28 Chapter 4 Requests and responses For more information about allowable actions and attributes, refer to the tcmapi.xsd schema. 4.2 Request and response examples This section contains the following request examples: Getting a list of Publications Getting the contents of a Publication Getting the list of a Folder Creating an item Updating an item Deleting an item Composite requests 4.2.a Getting a list of Publications Request This request asks the Content Manager for a list of all Publications, using tcm:0-0-0 as the root of the system: <?xml version='1.0'?> <tcmapi:message xmlns:tcmapi=" version="5.0" from="testtool" failonerror="false"> <tcmapi:request ID="Request1" preserve="false"> <tcmapi:getlist itemuri="tcm:0-0-0" listtype="listpublications"/> </tcmapi:request> </tcmapi:message> Response The response returns the list of Publications A, B, and C, with the URIs tcm:0-3-1, tcm:0-4-1, and tcm:0-5-1, respectively. These publications are used in the subsequent examples. <?xml version="1.0"?><tcmapi:message version="5.0" from="mdvc" xmlns:tcmapi=" <tcmapi:response ID="Request1" success="true" xmlns:tcmapi=" <tcmapi:result> <tcm:listpublications xmlns:tcm=" Managed="1"> <tcm:item ID="tcm:0-3-1" Title="Publication A" Allow=" " Deny=" " Managed="516"/><tcm:Item ID="tcm:0-4-1" Title="Publication B" Allow=" " Deny=" " Managed="516"/> <tcm:item ID="tcm:0-5-1" Title="Publication C" Allow=" " Deny=" " Managed="516"/> </tcm:listpublications></tcmapi:result> </tcmapi:response> </tcmapi:message> 22 Tridion R5

29 Business Connector Guide 5.2 SP1 Request Response 4.2.b Getting the contents of a Publication This request asks the Content Manager for the contents of Publication A, with the URI tcm: <?xml version='1.0'?><tcmapi:message xmlns:tcmapi=" version="5.0" from="testtool" failonerror="false"> <tcmapi:request ID="Request1" preserve="false"> <tcmapi:getlist itemuri="tcm:0-3-1" listtype="listitems"/> </tcmapi:request> </tcmapi:message> The response is successful, and lists the Publication as empty except for the Building Blocks system folder. <?xml version="1.0"?><tcmapi:message version="5.0" from="mdvc" xmlns:tcmapi=" <tcmapi:response ID="ResponderRequest" success="true" xmlns:tcmapi=" <tcmapi:result> <tcm:listitems xmlns:tcm=" Managed="4"> <tcm:item ID="tcm:3-9-2" Title="Building Blocks" Type="2" Modified=" T11:22:25" Size="0" Allow="650240" Deny="96" Managed="2490" Icon="T2L0P0"/> </tcm:listitems> </tcmapi:result> </tcmapi:response> </tcmapi:message> Chapter 4 Requests and responses 4.2.c Getting the list of a Folder Request This request asks the Content Manager for the contents of the Building Blocks Folder identified by the URI tcm: <?xml version='1.0'?><tcmapi:message xmlns:tcmapi=" version="5.0" from="testtool" failonerror="false"> <tcmapi:request ID="Request1" preserve="false"> <tcmapi:getlist itemuri="tcm:3-9-2" listtype="listitems"/> </tcmapi:request> </tcmapi:message> Response The response returns the contents as the Default Multimedia Schema, Default Component Template, Default Page Template, and Default Template Building Block. <?xml version="1.0"?><tcmapi:message version="5.0" from="mdvc" xmlns:tcmapi=" <tcmapi:response ID="ResponderRequest" success="true" xmlns:tcmapi=" <tcmapi:result> <tcm:listitems xmlns:tcm=" Managed="2490"> <tcm:item ID="tcm:3-50-8" Title="Default Multimedia Schema" Type="8" Modified=" T11:22:26" Size="0" Allow=" " Deny="118" Icon="T8L0P0S1"/> 23

30 Chapter 4 Requests and responses <tcm:item ID="tcm: " Title="Default Component Template" Type="32" Modified=" T11:22:26" Size="0" Allow="125321" Deny="630" Icon="T32L0P0S1"/> <tcm:item ID="tcm: " Title="Default Page Template" Type="128" Modified=" T11:22:26" Size="0" Allow="125321" Deny="630" Icon="T128L0P0S1"/> <tcm:item ID="tcm: " Title="Default Template Building Block" Type="2048" Modified=" T11:22:26" Size="0" Allow="124937" Deny="118" Icon="T2048L0P0S1"/> </tcm:listitems></tcmapi:result> </tcmapi:response> </tcmapi:message> 4.2.d Creating an item Request The following request creates a Component called Component. <?xml version="1.0"?><tcmapi:message xmlns:tcmapi=" version="5.0" failonerror="true"> <tcmapi:request ID="REQ1" preserve="false"> <tcmapi:saveitem itemuri="tcm:0-0-0" contexturi="tcm:3-9-2" doneediting="true" itemtype="component"> <tcm:component xmlns:tcm=" xmlns:xlink=" <tcm:data> <tcm:title>component</tcm:title> <tcm:content> <Content xmlns="uuid:bf747b17-386a-41a d2286fe48945"> <author>pasikniks</author> </Content> </tcm:content> <tcm:schema xlink:href="tcm:3-52-8"/> </tcm:data> </tcm:component> </tcmapi:saveitem> </tcmapi:request> </tcmapi:message> Note The itemuri attribute of the tcm:saveitem element is set to tcm: If this itemuri is specified, a new item is created. The response contains the itemuri for the newly created item (see response below, where itemuri is tcm:2-53). Response The response returns that the Component creation was successful, and the Component is created in the system. <?xml version="1.0"?><tcmapi:message version="5.0" xmlns:tcmapi=" <tcmapi:response ID="REQ1" success="true" xmlns:tcmapi=" actionwf="true"> <tcmapi:result> <tcm:component ID="tcm:2-53" IsEditable="false" xmlns:tcm=" xmlns:xlink=" <tcm:context> 24 Tridion R5

31 Business Connector Guide 5.2 SP1 <<STRIPPED OUT>> </tcm:context> <tcm:info> <<STRIPPED OUT>> </tcm:info> <tcm:data> <tcm:title>wfcomp5</tcm:title> <tcm:schema xlink:type="simple" xlink:title="testschema" xlink:href="tcm:3-52-8"/> <tcm:content> <Content xmlns="uuid:bf747b17-386a-41a d2286fe48945"> <author>test me please</author> </Content> </tcm:content> <tcm:metadata/> <tcm:approvalstatus xlink:type="simple" xlink:title="unapproved" xlink:href="tcm: "/> <tcm:isbasedontridionwebschema>true</tcm:isbasedontridionwebschema> <tcm:multimediatype xlink:href="tcm:0-0-0" xlink:title=""/> </tcm:data> </tcm:component> </tcmapi:result> </tcmapi:response> </tcmapi:message> Chapter 4 Requests and responses 4.2.e Updating an item Request The following request and response examples update an existing item, with the itemuri tcm:2-53, in TCM 5.0. <?xml version="1.0"?> <tcmapi:message xmlns:tcmapi=" version="5.0" failonerror="true"> <tcmapi:request ID="REQ1" preserve="false"> <tcmapi:saveitem itemuri="tcm:2-53" contexturi="tcm:3-9-2" doneediting="true" itemtype="component"> <tcm:component xmlns:tcm=" xmlns:xlink=" <tcm:data> <tcm:title>component</tcm:title> <tcm:content> <Content xmlns="uuid:bf747b17-386a-41a d2286fe48945"> <author>test me please. I want to update this item</author> </Content> </tcm:content> <tcm:schema xlink:href="tcm:3-52-8"/> </tcm:data> </tcm:component> </tcmapi:saveitem> </tcmapi:request> </tcmapi:message> Note The main difference between creating and updating an item is that the itemuri attribute of the tcm:saveitem element has the value of an existing item in the Content Manager. 25

32 Chapter 4 Requests and responses In this case, we update the item with itemuri tcm:2-53. Response <?xml version="1.0"?> <tcmapi:message version="5.0" xmlns:tcmapi=" <tcmapi:response ID="REQ1" success="true" xmlns:tcmapi=" actionwf="true"> <tcmapi:result> <tcm:component ID="tcm:2-53" IsEditable="false" xmlns:tcm=" xmlns:xlink=" <tcm:context> <<STRIPPED OUT>> </tcm:context> <tcm:info> <<STRIPPED OUT>> </tcm:info> <tcm:data> <tcm:title>wfcomp5</tcm:title> <tcm:schema xlink:type="simple" xlink:title="testschema" xlink:href="tcm:3-52-8"/> <tcm:content> <Content xmlns="uuid:bf747b17-386a-41a d2286fe48945"> <author>test me please. I want to update this item</author> </Content> </tcm:content> <tcm:metadata/> <tcm:approvalstatus xlink:type="simple" xlink:title="unapproved" xlink:href="tcm: "/> <tcm:isbasedontridionwebschema>true</tcm:isbasedontridionwebschema> <tcm:multimediatype xlink:href="tcm:0-0-0" xlink:title=""/> </tcm:data> </tcm:component> </tcmapi:result> </tcmapi:response> </tcmapi:message> 4.2.f Deleting an item Request This example deletes an item with the URI tcm:2-53. <?xml version='1.0'?> <tcmapi:message xmlns:tcmapi=" version="5.0" from="mdvc" failonerror="false"> <tcmapi:request ID="ResponderRequest" preserve="false"> <tcmapi:delete itemuri="tcm:2-53"/> </tcmapi:request></tcmapi:message> Response <?xml version="1.0"?><tcmapi:message version="5.0" from="mdvc" xmlns:tcmapi=" <tcmapi:response ID="ResponderRequest" success="true" xmlns:tcmapi=" </tcmapi:message> 26 Tridion R5