Jitterbit Documentation Image Processor¶

Introduction¶

The Jitterbit Documentation Image Processor assists in the creation of the images used in the documentation that Jitterbit publishes on each of its connectors. The Image Processor is a tool used to modify PNG screenshot images of the configuration of a connector’s connection and its activities. This utility crops and renames images in a manner consistent with the standard formats used by Jitterbit in its documentation.

Download¶

The Image Processor is available for the macOS and Windows operating systems. Download an appropriate installer package from these links:

• macOS

• Windows

See the release notes for details of changes in the application.

Installation¶

The application is packaged using an installer appropriate for the operating system. Open the installer and follow its prompts to install the application.

If you are installing on macOS, you may receive a warning message about the installer and be required to approve the installation in the Security & Privacy panel of the macOS System Preferences, as shown in this example for the Project Reporter tool:

For both the macOS and Windows operating systems, the default scaling and color settings should be used to produce images that are consistent with the other images used in Jitterbit documentation.

Calibration¶

As images can be generated with different resolutions, the Image Processor requires calibration to adjust for a resolution other than the standard resolution. By making a screenshot of the page that contains the online calibration image, which is 100 x 100 pixels in size, the program can read this image and adjust accordingly for images created on higher resolution monitors.

• You can confirm the required calibration by making a screenshot of the page at that URL, and then using the menu command Load a Calibration Image… to import the image. The image will be read and the appropriate calibration set.
• Calibration settings are saved when you exit the application. A previous setting can be reused by using the Calibrate menu item Select an Existing Calibration Setting….
• Use the Calibrate menu item Enter a Calibration Setting… to enter a custom calibration value.

Intent of the Tool¶

The intent of the tool is two functions: image cropping and image renaming. Image cropping crops images to match conventions used at Jitterbit when documenting connectors. Image renaming names images following similar conventions that make it possible to generate and manage connector documentation in an automated and consistent fashion.

Image Cropping¶

There are two types of images that are commonly used in Jitterbit connector documentation:

• Operation images
• Connection or activity images

When an image is cropped, a border is often added. It can be explicitly added (by setting a type of B) or is implicitly used when finding and detecting objects and then adding a border in the background color around the bounding box described by the objects of the image.

Operation Images¶

An operation image is characterized as being an image of a complete Jitterbit Harmony Cloud Studio operation, and a screenshot of an operation is white in all four corners. In the Jitterbit documentation, these are named following the pattern of <connector-name>-<activity-name>-operation.png and cropped tight. These are referred as type O images:

Before cropping:

After cropping:

Connection or Activity Images¶

A connection or activity image is characterized as being an image of a Jitterbit Harmony Cloud Studio connection or a step of an activity configuration. A screenshot image is “Cloud Studio beige” in all four corners, with a large X in the upper right-hand corner.

In the Jitterbit documentation, for connection configuration images these are named following the pattern of <connector-name>-configuration.png.

For activity steps, these are named following the pattern of <connector-name>-<activity-name>-activity-<step-number>.png and cropped with specific margins around the image elements. As they all have a common element of an upper right-hand corner “X”, these are referred as type X images:

Before cropping:

After cropping:

Image Renaming¶

With connectors with a large number of activities and a large number of steps, the number of images can be numerous. And once created and named, updating the images can be tedious, time-consuming, and error-prone. To help with that, the Image Processor is designed to take advantage of an existing set of named images and use those names to help in the renaming of new screenshots.

An existing set of names is referred to as Generated Images. (The reason for that name is that an initial set of names can be generated from the adaptor.json of a connector using the Documentation Generator.)

As seen in the image at the top of the page, the generated names are loaded into the left panel of the Image Processor using the Browse for Images button below that panel. In this example, the names are loaded by browsing for a directory that has existing images used in documenting the Coupa connector.

By selecting an image in the middle panel and then double-clicking the appropriate name in the left panel, the name will be copied into the Revised Filename column of the middle panel for the selected image. When the image is processed, it will be renamed to that name.

Image Types¶

The Image Processor uses simple patterns to determine where there is a change in the colors of an image and from there sets the cropping. This means that simple adjustments in the Cloud Studio UI can easily break the processor. Don’t be surprised when issues arise. Always check all images after processing for correct cropping.

Images will be cropped with a 20-pixel margin as an outer border outside of all elements.

The following image types are supported for processing. They are ordered by the X-type first (as it is the most common) with the others following alphabetically:

• X: An image with a large “X” in the upper right corner. Marking an image as an “X” type tells the processor to ignore that “X” when calculating the location of the right-hand side. It uses the bottom of the “X” to determine where the base line of the top-most text is and from there determines where to crop.

  However, if the calculation of the location of the right side of the “X” is in the bottom half of the image (has a y component greater than 50% of the height), then that means that the “X” is actually in line with the other elements. In that case, use that location as the right-hand side rather than attempting to crop off the “X”.

• A: A component palette image of an existing endpoint, showing its activities.

• B: An image cropped “tight” with a 20 pixel border (scaled based on the assumed DPI) added using its background color.

• C: A component palette image of a connector or an endpoint, but not to show any activities. If any activities show, they will be cropped off.

• I: An inline image trimmed to the first pixels different than the background with a 2 pixel border (scaled based on the assumed DPI) added using its background color.

• M: A modal dialog image, a white rectangle, possibly with an orange bottom border, on a gray overlay background. Rounded corners on the rectangle are acceptable and are cleaned up when cropped.

• O: An image of an operation example, trimmed to eliminate the outer border.

• S: An activity step image without an “X” in the upper-right corner.

• T: A “tight” image, trimmed to all outer pixels.

The inline and tight images detect their backgrounds by calculating the color distance of a pixel from the background (the background being the color of the corner pixels) and using a threshold of 20 units. (The maximum distance in the RGB color space is from white to black and is approximately 765 units.) Any pixel under the threshold is considered part of the background and not considered when detecting edges.

A hint can be added for this file attribute:

• F: A full-page image includes the entire contents of the browser tab or window with the current Cloud Studio display.

  A full-page image includes the entire contents of the browser tab or window with the current Cloud Studio display. It can be applied to these image types:

  • Image with an “X” in the upper-right corner (“X” type)
  • Modal dialog image (“M” type)
  • Activity step image (“S” type)

  For other image types, a setting of full-page is ignored.

  Generate a full-page image using a browser plugin or another screenshot application. For example:

  

• R: A resized image is resized using a LANCZOS filter based on the current image calibration.

Borders and margins are scaled based on a combination of an assumed image resolution of 72 DPI and the current image calibration. The current calibration is a percentage determined by the relative monitor DPI where the screenshot was taken.

Files without a type are not processed unless they are given a name, in which case they are renamed without further processing.

Selecting multiple screenshot images to set them all to the same type is supported. You can also select multiple images and use your keyboard to enter the appropriate type (either lowercase or uppercase keys). The deletion and space character keys (such as the macOS delete, forward-delete, and space keys or the Windows Backspace, DEL, and Spacebar keys) all remove the current type.

Double-clicking the F or R columns of an image’s row will toggle that setting.

See Jitterbit Image Processor Examples for “before” and “after” image examples for each of the above types.

Help Window¶

A help window with a summary of image types can be displayed either by selecting it from the Help menu or using the F1 key shortcut.

Operating the Tool¶

Start the tool as you would any other application. The tool runs in a single window. Help in the tool links to this documentation. Menus are not used in the application except for an “About” dialog, help link, and exiting the tool. Everything is done by clicking the buttons as shown in the introductory illustration.

Tool Components¶

The tool consists of these panels, with relevant buttons underneath:

• The top panel lists the current directory used for the Generated Image Names, the current directory for the Screenshot Images, and the screenshot calibration. The calibration is set as described above.

• The left panel lists Generated Image Filenames, and is filled by browsing for a directory with existing images that have the correct names, following the pattern described above.

• The middle panel lists the images that are to be processed. For each image, its current name (Screenshot Image Filename), a Type, Full-page, and a Revised Filename are listed.

• The right panel shows a display of the image currently selected in the middle panel. Its button Process Screenshot Images is used to process the specified images.

Typical Workflow¶

The typical workflow is to load a set of screenshots in the middle panel of the tool, configure each image as to its type and revised filename, and then process all images, cropping and renaming based on the settings.

• If a Revised Filename is not specified, the file is not renamed. Instead, the original name is reused.

• If a Type is not specified for an image file, the file is ignored for processing. (If a revised filename is specified but no type, the image file is renamed without processing.)

• If Full-page is specified, the image is expected to be one that includes the entirety of the Cloud Studio interface, including the Harmony Portal header. This allows for integration with a workflow involving screen capture software that grabs an entire page of contents. Example of such an image:

  

  See the section below on Recommended Practices for how to incorporate using this setting in a workflow.

• Clicking an image name (Screenshot Image) displays the image in the right panel, with size information displayed immediately below the image.

• Double-clicking an image name will allow you to open the image with the default operating system application. If the image has been processed, you will be given the option of opening either the original image (from the _originals directory) or the revised image.

• High-resolution images (those when calibration is set greater than 100%) are reduced in size to 72 dpi using a high-quality Lanczos filter when they are processed. They are also displayed before processing so that all edges can be seen.

• Any embedded CMS (color management system) profiles are converted to the sRGB color profile. Colors are then matched using the sRGB profile, using a “fuzzy” match, typically a margin of ± 2 RGB values.

• You can load a set of generated names in the left panel. Double-clicking a Generated Image name copies that name to the currently selected image in middle panel. If the revised name matches a known pattern, the Type is set automatically. Otherwise, you can use the Toggle Type button to change the type by stepping through all of the types until you set the correct type or enter the type using your keyboard.

• Multiple selections are allowed in the middle panel by pressing Shift, Command (macOS), or Control (Windows) while clicking. This allows you to set the Type of multiple images at the same time. If multiple images are selected, no image is displayed in the right panel, nor can an image name be copied from the generated names (as all images must have different names).

• You can use the keyboard to set the image type. The Delete key will remove a type. Multiple selections are supported and can be set to the same type using the standard key combinations (Control+, Command+, or Shift+click).

Once all images are configured with a Type and Revised Filename, click Process Screenshot Images to crop and rename the files. There will be a delay while the application completes the task. Text information with the progress of the application and which file was last processed are written to the UI as it processes the files.

An _originals directory is created in the screenshot images directory, and any image files that are being revised are copied there first as a backup. If all changes are to your liking, the directory can be discarded when complete.

Recommended Practices¶

We recommend using a utility in a Chromium-based browser such as Brave to take full-page screenshots.

When full-page screenshots are taken and then hinted as such in the Image Processor, the application will use that information to determine where the edges of the components are and properly trim the image.

Release Notes¶

1.8.0

• Updated the application icons to use the new Jitterbit logo and to correct an issue with the macOS icons being too large.

1.7.0

• Changed the calculations to always use the calibration setting and never use intrinsic resolution as the latter can often be inaccurate.
• Double-clicking the R column of an image will now toggle the resize setting, similar to the F column.
• Double-clicking the filename column will bring up dialog that depends on whether the image has been processed and if there is a revised image. If so, a choice will be presented between the original and the revised images.
• The original DPI is now rounded to two decimal places when displayed.
• The internal DPI is still displayed even though it is ignored for calculation purposes.
• Updated the documentation, both here and in the application.

1.6.1

• Removed the R image type and replaced with a “resizing” setting that can be applied to all image types.
• Improved the modal type (M) to handle images without an orange bottom border (such as those in App Builder) and images with rounded corners.
• Added calibration settings in the menu for 100% through to 200% in 25% increments.
• Added an “Enable Image Resizing by Default” item in the Calibration menu that if checked sets all images to being resized.
• Improved the output of all images by reducing the number of copies being made and fixing errors in calculations.
• Changed the calculation of the threshold to use a lower value against the background.
• Improved the dialog for error messages by removing a button and by changing the logic to not use a hack of overloading a cancel button.

1.6.0

• Fixed an issue with O and T images messaging about not supporting full page images when that was not specified.
• Fixed an issue with O images not working with images that did not contain a border.
• Added a new “B” type that crops tight and then adds a border in the background image color.
• Added a new “R” type that resizes without cropping.
• Added text in the window showing the default border being added.
• Updated the text of the HTML help window.

1.5.1

• Fixed an issue with X images (images with a close X in the upper right corner) being unable to find the correct right hand edge of the objects below the X in the image.

1.5.0

• The inline type (I) has been improved when detecting edges in images with low contrast. It converts the image to grayscale and uses that converted image to detect the edges with a threshold scaled to the difference between the maxima values of the image.

1.4.0

• Added two new images types: inline (I) and tight (T). See the documentation above for details.
• The operation type (O) has been adjusted for the current (Jitterbit Harmony version 10.40) Cloud Studio UI changes and removes the border that was added as it interferes with a border added when the images are displayed.

1.3.0

• Fixed an error when handling images with embedded ICC profiles. They are now handled with perceptual intent rather than absolute colorimetric, resulting in conversions that more closely match the perceived colors.
• Fixed errors that occurred when messages were returned in a dialog and buttons were not correctly updated when the dialog was dismissed.
• Adjusted the colors used for testing to accommodate the changes in the Cloud Studio UI as of Harmony 10.38.

1.2.1

• Changed the algorithm used with an “X” type image to assume that if the calculation of the right side of the “X” is in the bottom half of the image, then the “X” is actually in line with the rest of the elements. In that case, use that as the right-hand side rather than attempting to crop off the “X”.

1.2.0

• Replaces the H (High Resolution) hint with a calibration setting that is saved and can be set by explicitly entering a value, selecting from an existing value, or by scanning a screen shot of a calibration page. The calibration is the size of a 100 pixel-wide element as displayed in the screenshot of the uncalibrated system.
• Renamed a button to Browse for Image Names to better reflect what it is used for.

1.1.1

• Increases the margin used when examining images from 10 pixels to 12 pixels, as the newest macOS (Big Sur) is creating curved “corners” on certain images that are 10 pixels across. These corners interfere when attempting to detect components of an image.
• Fixes the keys recognized for deletion in the list view of screenshots to include forward and backward deletion, in addition to the current space key. Recognizes usage of key modifiers when in the list, so “C” is recognized but “Control-C” is ignored.
• If no errors are detected but there are messages, the “error message” footer is no longer appended to the message displayed.
• Fixes an issue with “C” type images not correctly finding the bottom of the icon text if there is not a gray horizontal rule.
• Corrects the DPI setting of cropped images that are converted from high resolution (144 dpi or higher) to 72 dpi.

1.1.0

• New image types supported (modal dialog and full-page images).
• Fixes and improvements to the resizing of high resolution (144 dpi and higher) images.
• All images are now resized down to 72 dpi and alpha (transparency) layers removed before saving.
• Files without a type are not processed unless they are given a name, in which case they are renamed without further processing.
• A help page, in addition to this document, is available in the application from the Help menu.

1.0.9

• Initial public release of the application.

For More Information¶

Though this tool is unsupported, we are happy to receive any feedback, questions, or concerns. You can reach the Jitterbit Documentation Team at documentation@jitterbit.com.