JMS v3.4.1 User’s Guide
JMS User’s Guide
INSTALLATION NOTES
1
SYSTEM RECOMMENDATIONS RECOMMENDED SERVER HARDWARE RECOMMENDED HARDWARE RECOMMENDED OPERATING SYSTEMS REQUIRED MIDDLEWARE REQUIRED DATABASE
1 1 1 1 1 1
APPLICATION OVERVIEW
2
JMS™ -‐ A COMMON PLATFORM FOR SYSTEM INTEGRATION
2
JMS™ ARCHITECTURE
3
BUSINESS MASHUPS -‐ THE BUILDING BLOCKS OF WORKFLOW AUTOMATION
4
INPUT SERVICES
5
FORM INPUT INPUT SERVICES HTML FORM A MASHUP IS AUTOMATICALLY CREATED INPUT SERVICE FIELDS URL STRING (GET) HTML FORM POST AJAX CALL
5 5 5 5 5 5 5 5
FORM INPUT SERVICE (TUTORIAL STEP ONE)
6
FIND THE ADDRESS OF JOB MANAGEMENT SYSTEM THINK UP A CLEVER NAME FOR YOUR FIRST SERVICE IDENTIFY THE FIELDS THE MASHUP NEEDS TO OPERATE THAT’S EVERYTHING -‐ LETS CREATE A MASHUP
6 6 6 6
DATABASE QUERIES
8
JDBC SQL FUNCTIONS JMS DATABASE CONNECTIONS ADDING A DATABASE BUILDING A SQL QUERY ADDING JOBCAST FOR THE QUERY
8 8 8 8 8
DATABASE QUERY SERVICE (TUTORIAL STEP TWO)
9
ADD THE DATABASE DEVICE ADD THE DATABASE QUERY
9 9
PRACTICAL EXAMPLES USING XML AND JDF DATA
10
SAMPLE XML FILE USED AS INPUT FORM SAMPLE JDF FILE USED AS INPUT FORM
10 10
SAMPLE JMS TOPOLOGY AT LARGE PACKAGING PRINTER
12
SAMPLE JMS PROCESS FLOW AT A LARGE LABEL PRINTER
13
JMS User’s Guide
APPENDIX A -‐ RESOURCES
14
RECOMMENDED SOFTWARE SOURCES SOFTWARE DOWNLOAD LOCATION NETWORK RECOMMENDATIONS TECHNICAL SUPPORT
14 14 14 14
APPENDIX B – APACHE TOMCAT INSTALLATION
15
MAC PC
15 16
JMS User’s Guide
INSTALLATION NOTES SYSTEM RECOMMENDATIONS RECOMMENDED SERVER HARDWARE
Processor 1.5 GHz or faster (2 GB preferred) 1024 MB (1 GB) of RAM or more RECOMMENDED HARDWARE
One Gigabit Ethernet adapter 750GB2 - 7200RPM, SATA 3.0Gb/s, 16MB Cache RECOMMENDED OPERATING SYSTEMS
One of these operating systems is recommended to run Tomcat: • Mac OSX 10.5 or later • Microsoft Windows 2000 or later REQUIRED MIDDLEWARE
All of these packages are required on the server with Hybrid Web Apps: Sun Microsystems Java Development Kit (JDK 1.6.x) Note: You MUST use one of the JDK 1.6 versions, not an earlier or a later version. Servlet container (Apache Tomcat 6.0+) REQUIRED DATABASE
Hybrid web applications typically install with PostgreSQL, however, other standard SQL databases (e.g. MySQL, Sybase, Microsoft SQL Server, DB2, etc.) are supported.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
1
JMS User’s Guide
APPLICATION OVERVIEW
JMS™ - A COMMON PLATFORM FOR SYSTEM INTEGRATION Hybrid Integration’s Job Management System (JMS™) is a middleware platform for the graphic arts industry. JMS has been designed to interface with different input sources, manipulate data, and produce a variety of desirable outputs. It is at the heart of all of Hybrid’s products and allows us to build very customizable products that are economical to purchase, install, and maintain because they can be configured through the JMS interface, rather than with custom coding and development work. JMS was designed for a technical user with some database and IT expertise, but it does not require programming knowledge. JMS features rules-based automation, which allows complex business logic to be developed while minimizing the need for custom programming. The purpose of this document is to give a brief overview of the architecture of JMS and the integration possibilities it can provide, as preparation for further technical discussions with the development team. It will also give a basic tutorial for setting up database connections and building mashups and services. All product screens are taken directly from a web browser, which serves as the user and admin interface for JMS and all Hybrid Integration software products.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
2
JMS User’s Guide
JMS™ ARCHITECTURE The Job Management System is written in Java for cross-platform compatibility. Supported platforms include Windows, Macintosh, Linux, and Unix. JMS includes an embedded SOAP (Simple Object Access Protocol) server for direct communication with web services and SOAPenabled software systems. JMS supports open standards and utilizes Apache Axis SOAP for web services. JMS includes a PostgreSQL or MySQL database, but it also includes drivers for a wide variety of databases, including SQL Server, Progress, Oracle, and any JDBC-compatible database. The core data format of JMS is XForms, a type of formatted XML data. XForms maintains the content and structure of an XML file while allowing data labels & types to be changed for ease of interfacing with other systems or databases. One key benefit of this approach is that both XML files and JDF (Job Definition Format) files are directly compatible with JMS. Examples of XML and JDF files are given in upcoming pages.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
3
JMS User’s Guide
BUSINESS MASHUPS - THE BUILDING BLOCKS OF WORKFLOW AUTOMATION Hybrid Integration’s Job Management System (JMS) is designed to take different input sources, manipulate data, and produce different outputs. The above diagram shows the tremendous variety of data sources that can be accessed by JMS as well as the ways in which data can be combined. 1. 2. 3. 4. 5.
These are the basic steps for process automation using JMS: Establish input data sources - forms, SOAP calls, database queries, etc. Build services that act on these data sources Combine services into “mashups” which provide reusable workflows for business data Use mashups to automate repetitive, time-consuming, or error-prone tasks.
Mashups can be very complex and can perform advanced automation tasks without human intervention, and even though you can run individual services without a mashup, there is a great advantage to placing even one service into a mashup. Any future modifications or additions don’t require you to start over; you can just build on the existing mashup. Let’s explore how to create mashups in JMS.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
4
JMS User’s Guide
INPUT SERVICES FORM INPUT JMS can be configured to start with a form as input. Since every service will usually require some input from the user, this is the place to “kickoff” your mashup. You can build the form in several different ways, but the main concept is to send in 3 pieces of data to begin. It is important that you include all of the input values you expect to use, so you can avoid replacing the input service each time. The main 3 methods are listed below; sending in either of these posts will prompt JMS to create: INPUT SERVICES A popular way to input to a mashup.
HTML FORM Posting an HTML form automatically creates an input service if it doesn’t exist. If the service exists, it will run each time.
A MASHUP IS AUTOMATICALLY CREATED The first time a form is posted to JMS, it will automatically insert the form fields as an input service to start off the mashup. Every subsequent post to that jobcast will run through the existing mashup.
1.
An Input service with the values which were passed in when it was created. It will be named with the Jobcast name + form ie., myserviceform
2.
A mashup with the input service as the first module. This is where you can combine multiple other services, and use rules to manipulate the data.
3.
A mashup service, which is an “instance” of the mashup. Each time you change the mashup, you need to remake the mashup service.
INPUT SERVICE FIELDS The fields posted to JMS are translated into service input fields, and usable in the rest of a mashup.
URL STRING (GET)
HTML FORM POST
AJAX CALL
Simply posting to /JobManagementSystem/formRequest?jobcastname =tutorial&id=1 will automatically create a mashup with a form input as the first module. Adding additional vars is possible by adding &name=george&other=something, etc.
To hide the vars from the url, or to include several variables, you can use a traditional HTML form to post to JMS. This is advisable when you are passing in several user defined fields.
Ajax calls are supported to eliminate the need for the page to navigate to JMS. Utilizing javascript, you can post to /JobManagementSystem/formRequest?jobcast name=tutorial&id=1 and achieve the same result as a GET or POST.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
5
JMS User’s Guide
FORM INPUT SERVICE (TUTORIAL STEP ONE) For the quick start tutorial, let’s do the following:
FIND THE ADDRESS OF JOB MANAGEMENT SYSTEM The URL of JMS will be needed first, and is probably something like http://localhost:8080/JobManagementSystem/ or http://75.146.223.217:8080/JobManagementSystem/.
THINK UP A CLEVER NAME FOR YOUR FIRST SERVICE Think about what the service is going to do, and make a name that will be easy to identify. Once you have 100 mashups, they all start to look the same. Here are a few examples. GetJobsById
InsertContactData
SearchCustomersByName
Once you have your “jobcastname” figured out, we can move to the next step.
IDENTIFY THE FIELDS THE MASHUP NEEDS TO OPERATE If you created a jobcast name like GetJobsById or InsertContactData, you will need the additional fields. For example, GetJobsById will need a JOBID, and InsertContactData might need &NAME=george&EMAIL=georgem@hybridintegration.com.
THAT’S EVERYTHING - LETS CREATE A MASHUP Type directly into the browser url: the address of JMS, and append the formRequest, jobcastname, and inputfields, like below. http://75.146.223.217:8080/JobManagementSystem/formRequest?jobcastname=GetJobsById&id=1 After you post that the first time, you can now log in to JMS, and look at the input service list. You will see your input service in the list on the left. If you select it, you will see your service requests to the right. Double click on the service request, and click on the input tab. You should find your id in there.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
6
JMS User’s Guide
Now go to the Manage menu, and select Mashups. You should see a mashup with your jobcastname. If you double click the mashup, you will see that the first module is your input service. Every time you run that URL, it will invoke a service request in your mashup service.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
7
JMS User’s Guide
DATABASE QUERIES JDBC SQL FUNCTIONS JMS DATABASE CONNECTIONS You can Insert, Update, Delete, and Select from any standard SQL database, using the queries in JMS. Caution: Please consult the manufacturer for the database when performing any write queries. You can damage a database with improper queries. Once you’ve established a database connection, it is possible to add multiple queries to different tables, and add, retrieve, or update data within a mashup. The rules for doing these functions will be covered under the rules topic, but for now, let’s see how we can add a database and a query. Special functionality: SQL Notations allow additional fieldnames to be added. select * from jobs where name=’${username=george}’will yield a query with an input named username, even though it doesn’t exist in the database. It also sets the default value to george
ADDING A DATABASE
BUILDING A SQL QUERY
ADDING JOBCAST FOR THE QUERY
The first step in performing a query is to add the Database connection. You will need the Database Type:Host Name:Database Name:User Name:Password:Port. You only need to add the database connection once. All subsequent queries fall under adding a database query.
Once you have a database connection, you can begin adding queries. Click on Manage/Queries, and select the plus button to add your first query. In order to add a query, it must be performed once with valid data. You should see the resulting fields.
Database queries can be run independently, or within a mashup. To add it to your mashup, you must first save your query as a Jobcast.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
8
JMS User’s Guide
DATABASE QUERY SERVICE (TUTORIAL STEP TWO) We will create a database connection, and a database query to add to our mashup.
ADD THE DATABASE DEVICE This step is required once for each database you plan to connect. Select Manage/Database Connections to access the database dialog. When it opens, click the plus button to add a new Database connection. Make sure to select the database type, and complete the Host, DB Name, Username, Password, and port.
ADD THE DATABASE QUERY Once you have a database, you can add queries. Select Manage/Queries to access the query dialog. When it opens, click the plus button to add a new query. You will want to be sure to name this with something that makes sense, since you might have several queries. example_insert is the query shown here. We then select a database from the “using database” dropdown, then the table name from the “search in” dropdown, and finally the column from the last dropdown. The criteria can be filled out in the edit box. You will notice that the dropdowns will build a SQL query in the SQL Statement box. You can edit the query to suit your needs. A simple “Select * from Table” will suffice for the demo. The query “MUST” have a result the first time it’s run. This is necessary for us to capture the DB schema. You can also use a special notation to add fields to the input side of the query, e.g. select * from table where name=’${inputname=george}’ This example will expect a field called inputname as input to the query. With practice, these database queries will become quite intuitive and easy to implement using JMS.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
9
JMS User’s Guide
PRACTICAL EXAMPLES USING XML AND JDF DATA SAMPLE XML FILE USED AS INPUT FORM Since posting an input form automatically creates the service if it doesn’t exist, JMS can easily use XML or JDF forms as templates to create mashups for automated processing. The sample XML file listed below was used to exchange information about a publication ad between JMS and the Dalim workflow system. Note that the XML schema is very descriptive and compact, and is defined by mutual agreement between both systems. It is also suitable for a 2-way exchange between JMS and the recipient.
<?xml version="1.0" encoding="UTF-8"?> <DalimJobInfo> <Product>newtest</Product> <Email>john.doe@host.com</Email> <JobID>17</JobID> <FirstName>John</FirstName> <LastName>Doe</LastName> <FileName>NYMagFall2007_0001BOHP000_0013AC.pdf</FileName> <Advertiser>TO BE ASSIGNED</Advertiser> <Bleed>false</Bleed> <ClientAdNo/> <CreatePhone>(267)555-1235</CreatePhone> <CreateBy>admin</CreateBy> <Headline>newtest</Headline> <Notes/> <SalesRep>TO BE ASSIGNED</SalesRep> <Status>UPLOADED</Status> <AdTrackingNumber/> <AdSize>7x5</AdSize> <Issue>Fall 2007</Issue> <PMSColors/> <Color>B&amp;W</Color> <UserType>admin</UserType> <NativeFile>false</NativeFile> <RenamedFile>false</RenamedFile> <OriginalFileName/> <Comments/> </DalimJobInfo>
SAMPLE JDF FILE USED AS INPUT FORM The sample JDF file listed below was used to exchange information about a print job between the EFI Hagen OA MIS system and a MAN Roland printing press. Note that the JDF schema is much more verbose than XML and can be more difficult to read and write. However, since JDF is just a strictly formatted form of XML, it is still fully compatible with JMS.
<?xml version='1.0' ?> Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
10
JMS User’s Guide
<JDF ID="r254480" Type="Product" JobID="254480" xmlns="http://www.CIP4.org/JDFSchema_1_1" Status="Ready" Version="1.2" xsi:type="Product" JobPartID="r254480" xmlns:xsi="http://www.w3.org/2001/XMLSchemainstance" Activation="Active" MaxVersion="1.2" ICSVersions="Base_L1-1.0 MIS_L3-1.0" DescriptiveName="Training doc Main Component "> <AuditPool> <Created Author="Joe Demo" AgentName="Hagen OA" TimeStamp="2007-0309T10:57:45-06:00" AgentVersion="Version 10.0.0.76 - March 8, 2007"/> </AuditPool> <NodeInfo LastEnd="2007-03-08T00:00:00-06:00" FirstStart="2007-03-08T00:00:00-06:00"> <Employee Roles="CSR" PersonalID="MJS"/> <JMF xmlns="http://www.CIP4.org/JDFSchema_1_1" Version="1.2" DeviceID="30" SenderID="HagenOA" TimeStamp="2007-03-09T10:57:45-06:00" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <Query ID="OASubscription850" Type="Status" xsi:type="QueryStatus"> <StatusQuParams JobID="254480" JobDetails="Brief" EmployeeInfo="true" DeviceDetails="Details"/> <Subscription URL="https://MSPDEVV10X:12443/jdfConnector/jdfConnector" RepeatTime="300"/> </Query> <Query ID="OASubscription851" Type="Status" xsi:type="QueryStatus"> <StatusQuParams JobID="254480" JobDetails="Full" EmployeeInfo="true" DeviceDetails="Details"/> <Subscription URL="https://MSPDEVV10X:12443/jdfConnector/jdfConnector" RepeatTime="3600"/> </Query> </JMF> </NodeInfo> <Comment Name="JobDescription">Training doc Main Component Training Doc 8-1/2 x 11 2 color</Comment> <CustomerInfo CustomerID="1001" CustomerOrderID="456789" DescriptiveName="Tree Top Airlines"> <ContactRef rRef="OARefID03678"/> </CustomerInfo> <ResourcePool> <Contact ID="OARefID03678" Class="Parameter" Locked="false" Status="Available" ContactTypes="Customer Administrator"> <ComChannel Locator="218-457-5455" ChannelType="Phone"/> <CompanyRef rRef="OARefID03677"/> <PersonRef rRef="OARefID03676"/> <AddressRef rRef="OARefID03675"/> </Contact> <Company ID="OARefID03677" Class="Parameter" Locked="false" Status="Available" OrganizationName="Tree Top Airlines"/> <Person ID="OARefID03676" Class="Parameter" Locked="false" Status="Available" The JDF file continues for several more pages.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
11
JMS User’s Guide
SAMPLE JMS TOPOLOGY AT LARGE PACKAGING PRINTER
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
12
JMS User’s Guide
SAMPLE JMS PROCESS FLOW AT A LARGE LABEL PRINTER (Note: PPMS is the acronym used for JMS and the Hybrid GoTicket system at this printer.)
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
13
JMS User’s Guide
APPENDIX A - RESOURCES RECOMMENDED SOFTWARE SOURCES SOFTWARE DOWNLOAD LOCATION
Sun Java JDK 1.6.x: http://java.sun.com/javase/downloads/index.jsp Tomcat 6.x: http://tomcat.apache.org/download-60.cgi PostgreSQL 1.8.x: http://www.postgresql.org/download/ NETWORK RECOMMENDATIONS A public IP Address will be necessary if external support is needed. TECHNICAL SUPPORT For GoPrint support, please use the support@hybridintegration.com mailing list.
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
14
JMS User’s Guide
APPENDIX B – APACHE TOMCAT INSTALLATION MAC
Installation Cheat Sheet
Update Java to the latest version:
Download the latest Tomcat:
Unpack the tar.gz file
Use Software Update
http://tomcat.apache.org/ download-60.cgi
Rename and place the apache-tomcat-6.0.x folder as /Library/Tomcat6/
Edit the /Tomcat6/bin/ catalina.sh to avoid memory errors Mac: Delete *.bat,*.exe files from the tomcat bin folder rm *.bat *.exe
Hybrid Integration Inc. 3.4.1 (1/2011)
Right After
#!/bin/sh set JAVA_OPTS=%JAVA_OPTS% -Xmx256M set JAVA_OPTS=%JAVA_OPTS% -Xms256m set JAVA_OPTS=%JAVA_OPTS% XX:PermSize=512m set JAVA_OPTS=%JAVA_OPTS% XX:MaxPermSize=512m
Edit /Tomcat6/conf/tomcat-users.xml file
Example - Next Block
<tomcat-users> <!-<roll rollname="tomcat"/> <roll rollname="role1"/> <user username="tomcat" password="tomcat" roles="tomcat" /> <user username="role1" password="tomcat" roles="role1" /> <user username="both" password="tomcat" roles="tomcat,role1" /> --> <user username="hybrid" password="!dirbyh!" roles="standard,manager,admin"/> </tomcat-users>
Start Tomcat in Terminal /Library/Tomcat6/bin/catalina.sh run
Stop Tomcat in Terminal /Library/Tomcat6/bin/catalina.sh stop
DRAFT
15
JMS User’s Guide
PC
Hybrid PC Installation Procedure 1
2
Download Latest Java JDK for Windows
Download Latest Tomcat
Run Installer to:
Run Installer to:
C:\Java\jdk_v_x.x.xx
2.5 copy the file msvcr71.dll from the bin dir of your java installation, to the bin dir of the tomcat installation.
3 Set Environment Variables in System:Environment Variables
C:\apache-tomcat-x.x.xx
Edit Startup.bat in Tomcat/bin
Add these lines after @echo o! @echo off set JAVA_OPTS=%JAVA_OPTS% -Xmx256M set JAVA_OPTS=%JAVA_OPTS% -Xms256m set JAVA_OPTS=%JAVA_OPTS% -XX:PermSize=512m set JAVA_OPTS=%JAVA_OPTS% -XX:MaxPermSize=512m 4
Hybrid Integration Inc. 3.4.1 (1/2011)
DRAFT
Create Shortcut to Startup.bat
16