2022
Introduction
This document explains the concept of ApiCode and how it can be used to build DBSync Adapters
The following step by step story board explains the following:
1: What is ApiCode ?
2: How to write an ApiCode project and create an ApiCode Service ?
3. How to write a test case for an ApiCode Service?
4: How to build and deploy an ApiCode project on dbsync2 ?
5: How to use it in dbsync profiles and execute a process flow?
Pre-Requisites
- JDK 7
- Eclipse IDE (Enterprise developers)
- Local DBSync setup
StoryBoard
- Create a new Java Project in Eclipse IDE
2.Now add the dbysnc-sdk.jar in the dependencies lib folder and other necessary jar files
3. Now add the jars to the project dependencies class path and configure the build path in eclipse by using "Add Jars" button and then adding the jars present in the lib folder
4. Now create your main ApiCode Implementation class.
Note : Each ApiCode implementation must implement com.appmashups.appcode.AppCode interface
5. Now implement the default methods exposed by the ApiCode interface
5.1 Open – Method called , from the JavaAdapter to initialize the adapter resources if any so that the latter can be used during the sync operation
5.2 Close – Method called by JavaAdapter to close the ApiCode service and release its resources if it is holding up any
5.3 setContext – Utility method exposed to allow Java Adapter to set the context with the necessary properties
6. Now see an example of how we have implemented app-code for MSNav.
7.Please note that before we start writing any reader or writer methods in the app code service we need to import the SOAP WSDL classes into the project for being able to access the necessary entities and their fields and mappings
For this we can make use of the build script "appcode-deploy,xml" which is checked in under msnav2013 module under dbsync2_1 project in the CVS repository. The same needs to be copied into the "appcode-build" folder under the project
8.Now change the relevant values in the apicode-deploy.xml file to point to the relevant locations and set the necessary properties
<!-- set global properties for this build --> <!-- Setup Deployment specific properties --> <property name="appcode.name" value="MyTestMsNavSvc" /> – The name of the appcode project — <property name="appcode" location="/AvankiaWS2/MyAppCodeSvc"/> — The location of the appcode project in your machine — <property name="environment" value="sandbox" /> — The environment under which the jars will be deployed in dbsync2 ( folder under the profile folder) — <property name="profile" value="profile_test" /> ---- Name of the profile ---- <property name="dbsync.server.url" value="http://localhost:8080/dbsync2"/> — DBSync2 server URL ----- <property name="dbsync.server.username" value="localhost@avankia.com"/> — DBSync2 UID ---- <property name="dbsync.server.password" value="avankia"/> ---- DBsync2 Password —
Note: The DBSync2 Properties are actually required to deploy the zip file in DBSync2 server location which the DBSync2 server is running
9. Assuming we are trying to do a a SOAP call in our AppCode Service implementation, we need to run a wsimport task to download the binding classes into our project and for future use for reading, writing and getmetadata operations
<!-- Additional properties to pass the wsdl filenames -->
<property name="customer_wsdl" value="Customer.wsdl"> </property>
<property name="salesinv_wsdl" value="SalesInvoice.wsdl"> </property>
<!-- added for running wsimport -->
<property name="java_home" value="/Library/Java/JavaVirtualMachines/jdk1.7.0_55.jdk/Contents/Home"/>
<target name="wsimport" depends="init">
<exec executable="$\{java_home\}/bin/wsimport">
<arg line="-keep -s $\{appcode\}/generated-src -d $\{appcode\}/generated-classes $\{appcode\}/$\{customer_wsdl\}"/>
</exec>
<exec executable="$\{java_home\}/bin/wsimport">
<arg line="-keep -s $\{appcode\}/generated-src -d $\{appcode\}/generated-classes $\{appcode\}/$\{salesinv_wsdl\}"/>
</exec>
<jar destfile="$\{appcode.lib\}/generatedwsdlclasses.jar" basedir="$\{appcode\}/generated-classes"/>
</target>
<target name="init">
<!-- Create the time stamp -->
<tstamp/>
<mkdir dir="$\{deploy.dir\}"/>
<mkdir dir="$\{compile.dir\}"/>
<mkdir dir="$\{deploy.dir\}/zip"/>
<!-- add src and target files -->
<delete dir="$\{appcode\}/generated-src"/>
<delete dir="$\{appcode\}/generated-classes"/>
<mkdir dir="$\{appcode\}/generated-src"/>
<mkdir dir="$\{appcode\}/generated-classes"/>
<delete file="$\{deploy.dir\}/$\{appcode.name\}.jar"></delete>
<delete file="$\{deploy.dir\}/zip/$\{appcode.name\}.zip"></delete>
<delete file="$\{appcode.lib\}/generatedwsdlclasses.jar"></delete>
</target>
Run the ant task with target as wsimport to generate the SOAP binding classes along with the classes and source code
You can see the sample output below:
10. Now you can start using the generated classes in your AppCode project
Note: Due to limitations in the existing DbSync mapping algorithm which cannot allow certain nested hierarchies, we need to create DBSync Compatible Wrapper classes to allow the metadata binding with the conversion processor
Please refer to msnav2013 project where we have created necessary wrapper classes to do the metadata binding
The main functions of the wrapper classes are to convert from the DBSync compatible type to the underlying SOAP type and Vice Versa
public class Customer {
<properties
and methods
public static Customer createCustomer(CustomerCard card) {
Customer newObject = new Customer();
newObject.setKey(card.getKey());
newObject.setNo(card.getNo());
////Set other attributes
return newObject;
}
public static CustomerCard createCustomerCard(Customer customer) throws DatatypeConfigurationException {
CustomerCard card = new CustomerCard();
card.setKey(customer.getKey());
card.setNo(customer.getNo());
//set other attributes
return card;
}
}
11. Build the filter classes to be used in the reader classes
They will be responsible for filtering the data in the read queries. Please refer to CustomerFilter and SalesInvoiceFilter in MsNav
public class CustomerFilter{
public CustomerFilter(){}
public String key;
public String No;
public String Name;
}
12. Open Method
This method is the place where all the authentication happens. Each AppCode can by default take the following three parameters as Adapter Properties
userName = ctx.getPropertyAsString("username"); //User name for accessing service
password = ctx.getPropertyAsString("password"); //Password for accessing the service
baseURL = ctx.getPropertyAsString("baseURL"); //BaseUrl for making the soap call
In this method the actual authentication happens which is more of a one time in the reader and writer call
Authenticator.setDefault(new MyAuthenticator());
try {
log.finer("Customer Service: INIT");
URL customerURL = new URL(baseURL + "/CustomerCard");
QName customerQName = new QName(
"urn:microsoft-dynamics-schemas/page/customercard",
"CustomerCard_Service");
CustomerCardService customerCardService = new CustomerCardService(customerURL, customerQName);
customerCardPort = customerCardService.getCustomerCardPort();
log.finer("SalesInvoice Service: INIT");
URL salesInvoiceURL = new URL(baseURL + "/SalesInvoice");
QName salesInvoiceQName = new QName("urn:microsoft-dynamics-schemas/page/salesinvoice","SalesInvoice_Service");
SalesInvoiceService sis = new SalesInvoiceService(salesInvoiceURL,salesInvoiceQName);
sip = sis.getSalesInvoicePort();
batchSize = Integer.parseInt(ctx.getPropertyAsString("batchSize"));
} catch (Exception e) {
log.log(Level.SEVERE,
"Customer/SalesInvoice Service Initialization Failed", e);
e.printStackTrace();
throw new RemoteException("Customer/SalesInvoice Service Initialization Failed", e);
}
13. Read and Write Methods
An AppCode implementation service can either have a read or write method exposed for reader and writer .The Reader Syntax is as follows:
/** Method to read a list of customers in MsNav Takes in a variable arguments* of CustomerFilter as input and returns a list of Customer objects */
public List<Customer> readCustomer(CustomerFilter filter) throws Exception {//Read operation}
Inside a reader method, data is fetched using a relevant SOAP call with the necessary filter applied and the data fetched from the SOAP call is wrapped into the dbsync compatible output wrapper class
try {
// Modified by Sambit to check for null for the filter object
if (null != filter) {
for (Field field : CustomerFilter.class.getFields()) {
CustomerCardFilter cusCardFilter = null;
Object value = getFieldValue(field, filter);
if (value != null
&& !((String) value).trim().equalsIgnoreCase("")) {
cusCardFilter = new CustomerCardFilter();
String fldName = field.getName().substring(
field.getName().lastIndexOf(".") + 1);
// CustomerCardFields.valueOf(CustomerCardFields.NO.toString());
//System.out.println(CustomerCardFields.NO.toString());
cusCardFilter.setField(CustomerCardFields.valueOf(fldName.toUpperCase()));
cusCardFilter.setCriteria((String) value);
custCardFilterList.add(cusCardFilter);
}
}//for}//if(null != filter)
// if there are more elements to read or it is the first read
if (repositionKey == null || hasMoreElements()) {
CustomerCardList cList = null;
if (repositionKey == null) {
cList = customerCardPort.readMultiple(custCardFilterList,"", batchSize);
} else {
cList = customerCardPort.readMultiple(custCardFilterList,repositionKey, batchSize);
}
int cCount = cList.getCustomerCard().size();
for (int i = 0; i < cCount; i++) {
CustomerCard cusCard = (CustomerCard) cList.getCustomerCard().get(i);
/** Customer cusw = new Customer();
* cusw.setCustomerCard(cusCard);*/
// Customer cusw =
// (Customer)ClassConverter.convertToClass(cusCard,// Customer.class);
Customer cusw = Customer.createCustomer(cusCard);
customers.add(cusw);
}
if (customers.size() == batchSize) {
// Get the last element in the list of customers to get the
// repositionkey
Customer cusw = customers.get(batchSize - 1);
repositionKey = cusw.getKey();
} else {
repositionKey = "-1";
}
}
} catch (Exception e) {
e.printStackTrace();
log.log(Level.SEVERE, "Error while reading customers from MSNAV", e);
throw e;
}
return customers;
14. Deployment Process
The AppCode is bundled into a zip file and is deployed as a zip file into the environment specified in the appcode-deploy.xml file. The environment name is specified in the “environment” attribute.
<property name = “environment” value = “sandbox” />
The details about the appcode-deployx.xml parameters has been mentioned previously
By default the target is deploy which does the following:
- init
- wsimport
- build
- zip
- deploy
For the deploy target to work, your dbsync location which you have specified in the appcode-deploy.xml file must be running
15. Viewing the Profile List
Select the profile which you have used to deploy the AppCode. In this case it is profile_test
16. Java Adapter Properties
Set the adapter properties for the Java Adapter
Classpath – same as environment
Username – SOAP Service username
Password – SOAP Service Password
BaseURL – SOAP Service BaseURL
17. View the Metadata
View the metadata of the service to select and map
Overview
Content Tools