Jitterbit Documentation Image Processor¶
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.
The tool available from this page is supplied without warranty or support, and is used under license from Jitterbit, Inc. See the tool installer for the license for the tool.
The Image Processor is available for either the macOS or Windows operating systems. Download an appropriate installer package from either of these links:
The application is packaged using an installer appropriate for the operating system. Open the installer and follow its prompts to install the application.
When running on Windows, before creating screenshots, the Display Settings need to be a Scale and layout of 100%. 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.
As images can be generated with different resolutions, the Image Processor can be calibrated 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. If the images were created on standard resolution monitors, no adjustment is required.
- 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.
There are two types of images that are commonly used in Jitterbit connector documentation:
- Operation images
- Connection or activity 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:
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
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:
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 another Jitterbit tool called the Documentation Generator. That tool will be made available on this site in the future.)
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.
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 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”.
A: A component palette image of an existing endpoint, showing its activities
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.
M: A modal dialog image, a white rectangle with an orange bottom border on gray overlay background
O: An image of an operation example
S: An activity step image without an “X” in the upper-right corner
A hints can be added for these file attributes:
- F: A full-page image includes the entire contents of the browser tab or window with the current Cloud Studio display.
It can be applied for all image types except operation examples (“O” type). For component palette images (types “A” and “C”), as image edges can be found, the setting of full-page is ignored. Generate a full-page image using a browser plugin or another screenshot application. For example:
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.
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.
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.
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.
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
sRGBcolor profile. Colors are then matched using the
sRGBprofile, 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
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 (
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.
_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.
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.
- 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”.
- 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.
- 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.
- 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.
- 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 firstname.lastname@example.org.