Jitterbit Architecture and Best Practices

Recommendations for AppZen

1. Introduction

This document is prepared for AppZen to provide an overview regarding best practices to be
followed while developing projects in Jitterbit and provide architectural recommendations for
the Jitterbit operations to improve code reusability.

Since Jitterbit is a low-code development platform, it is important to develop operation chains

such that a maximal amount of operation building blocks are externalized (e.g. scripts, logging,
targets, sources). Along with this, to promote code reusability it is also important to design
operations such that they utilize a common input and output interface, as much as possible.

These recommendations are provided in the following sections.

2. Best Practice Recommendations

While creating Jitterbit operation chains it is recommended that the following suggestions be
followed, as much as possible:

a. Dot Notation Naming Scheme – Using a dot notation allows for easy organization
of operations, scripts, transformations, etc. into folders. This not only improves
readability but also ensures that operations can be easily found and reused.

As an example, consider that we work with two platforms, Oracle Fusion and
AppZen. Both these platforms are going to require different set of operations to
achieve the integration goals.

Let’s assume that for Oracle the following operations are made available:
i. Get all reports
ii. Get report details
iii. Get attachment

In this situation, it is recommended that the operations be named as below:

i. fusion.report.get.all
ii. fusion.report.get.details
iii. fusion.attachment.get

Similarly, in case of AppZen API the following operations are made available:
i. Check if report exists
ii. Upload report
iii. Upload image

In this case, it is recommended that the operations be named as below:

i. appzen.report.checkexists
 ii. appzen.report.upload
iii. appzen.image.upload

This notation is not only recommended to be used for operations, but also for
global and project variables, since it makes it easy to associate them to the
appropriate functionality and thereby increases maintainability of code.

For example, in case of Oracle Fusion there might be API endpoints to set, so it
would make sense to use a variable name like $fusion.http.url,
$fusion.http.headers and $fusion.http.operation to set the
target URL, the headers and the HTTP verb type (GET, PUT, POST, etc.).

A similar approach should be taken for the transformations and scripts as well.

b. Library Style Operations – It is important to design all operations with the idea that
they will be re-used, and as such architect your project to take the shape more of
a library than individual operation chains. It might take time in the beginning to
develop projects following this approach, but in the long run it makes code more
maintainable, allows for multiple developers to work on it at the same time and
makes it reusable.

Following the example of Oracle Fusion and AppZen, from the previous point, it is
recommended that the library operations be organized as below:

Creating a library of operations, transformations and other entities in this form

allows them to be readily reused in other components. Keeping them independent
from each other also allows for them to be chained together using controller
operations; this provides flexibility in terms of reusing same operations while
executing functionally different flows.

c. Controller Operations – an attempt should be made to create operations such that

they are chained together utilizing a controller operation. This is an operation that
basically calls library operations, along with any specialized operations that might
be needed in order to complete the flow logic.

The recommended way to set this up would lead to the operations being
connected as shown below:
 The simple script that would be used in this case, would look similar to this:

As you can see, following this approach makes your project into a simple step-by-
step chaining of operations. This also allows for the Oracle Fusion, AppZen and
CheckReportExists components to be developed individually, possibly even in
different projects so that multiple developers can focus on separate individual
tasks. Not only does this simplify project development, but also improves
maintainability and reusability.

d. Standardize Input/Output Mechanism – It is extremely beneficial to standardize

the input and output mechanism utilized for each operation. This helps make more
library style operations that can be reutilized.

It is recommended that instead of using Temporary Storage for passing data

between operations, the Global Variable source/target type be used. This avoids
issues with data encoding format (ASCII vs UTF-8, etc.). It also ensures that data is
always cleanly being operated upon, without there being traces of older data being
held in files. It also reduces the number of cycles needed due to the elimination of
the ReadFile() function.

Continuing the example presented above, you will notice that the input/output
global variables were standardized to the following names:
i. fusion.inout
ii. appzen.inout
iii. flows.inout

This standardization allows us to identify which library the input/output variable

belongs to. Furthermore, if you take a closer look you will find that we use the
same variable for input and output. This ensures that data does not linger from
operations that had errors or were not completed for some other reason.

e. Standardize Logging – While Jitterbit does a good job of logging events, there is no
mechanism to log payloads being sent to a target. Combining aforementioned
methods, with a standardized logging approach solves this problem.
 If you look at the image shown above, you will see that there is a logging script that
has been inserted before the source and after the target in each operation. The
script being used is exactly the same for each system, i.e. Oracle Fusion, AppZen
and the Jitterbit Flows being created in this project.

The contents of this script are as follows:

The only change as per the system of relevance is to use the appropriate prefix, i.e
$appzen or $flows and to use the appropriate logging enable/disable variable,
i.e. $appzen.logging.enabled or $flows.logging.enabled.

Using this approach lets you see the incoming and outgoing payloads while also
controlling whether you wish to see the log or not. You could potentially build a
log level functionality like this as well.

f. Separate Target Calls from Transformation – For easier insight into what the
payloads look like and to also make target operations more reusable it is
recommended that the transformation and submission operations be separated
when possible. An example of this would like the following:

If you notice here, the fusion.report.get.all operation uses the on-

success mechanism to perform a HTTP GET operation, via the
fusion.http.get operation. These two operations could have been combined
into a single transformation operation, but then we would not know the contents
of the outgoing and incoming payloads.

The fusion.http.get target has even been configured to take parameterized

versions of the URL, Content-Type and HTTP Headers so that these can be set on
the fly via the fusion.report.get.all operation. The configuration for the
target can be seen above, and advanced properties in the image below.
 You will notice that the following variables need to be set in order for the HTTP
GET operation to function:
i. $fusion.api.url – This needs to be set to the URL being operated on.
ii. $fusion.http.ContentType – This needs to have a default value of
text/plain and so it is recommended to use a project variable for this.
Alternates can be set by changing the contents of this global variable.
iii. $fusion.http.headers – This will contain headers to be sent (one
line per header). An empty project variable is recommended in case no
headers are to be sent.

Adding a new script, fusion.http.setParameters, that sets all HTTP

parameters to fusion.report.get.all, would then make the following
change to this operation:

The contents of fusion.http.setParameters would look like the

following:

Following this approach enables logging of incoming/outgoing payloads, while also

improving code reusability. Multiple developers can also independently now
develop the Jitterbit operations.

g. Common Error Handling – A common error handling mechanism is also highly

recommended. This not only allows catching of all errors within the project but
ideally also bubbles up the error to the top-level operation in the main calling
project.

This can be achieved by following the approach of creating an error handler for
each library independently, such as what is shown in the image below for Oracle
Fusion. Similar error handlers can be created for other libraries as well (AppZen
and Jitterbit Flows in this case).

The on-error mechanism is used to raise and capture errors. The contents of
fusion.error.handler are quite simplistic here:

This can easily be expanded to send email notification, take records in databses or
even create a log file.

This common error handling approach would easily capture errors for each library
(eventually its own project), but to bubble the error back to the top level calling
operation it is also important that Jitterbit scripts use the Eval() function when
calling other operations. In our controller example operation, this can be done so:

Here the Eval() function is used like a try-catch function. The on-error
mechanism of the controller will then send the error to an error handler, where
we can capture it the way we prefer. An overview of this is shown below.
3. Architecture Recommendations

Based on the best-practices above, there are several architectural improvements that could
be made to the existing AppZen codebase. This would start by separating the calls made to
each endpoint (Oracle Fusion, AppZen, Workday, etc.) into separate projects. This would make
these almost like library functions that can then be called by another project.

The main flows that implement the business logic can then sit in their own project(s). An
overview of this architecture is provided below:

These architecture recommendations will be implemented following the best practices

approach in order to provide AppZen with a maintainable codebase.