diff --git a/bindings/java/doxygen/artifact_catalog.dox b/bindings/java/doxygen/artifact_catalog.dox
index 358bd2558b0a7e7eb33f026539ba79f93ee6ac3d..b208a111faf2695caa614a3bf3375fa4835c3fef 100644
--- a/bindings/java/doxygen/artifact_catalog.dox
+++ b/bindings/java/doxygen/artifact_catalog.dox
@@ -2,11 +2,19 @@
# Introduction
-This document reflects current standard usage of artifacts and attributes for posting analysis results to the case blackboard.
-
-Note that "TSK" is an abbreviation of "The SleuthKit." Artifact type names with a "TSK_" prefix indicate the names of standard or "built in" types. User-defined artifact and attribute types should not be given names with "TSK_" prefixes.
+This document reflects current standard usage of artifact and attribute types for posting analysis results to the case blackboard in Autopsy. Refer to \ref mod_bbpage for more background on the blackboard and how to make artifacts.
The catalog section below has one entry for each standard artifact type. Each entry lists the required and optional attributes of artifacts of the type.
+
+NOTE:
+- While we have listed some attributes as "Required", nothing will enforce that they exist. Modules that use artifacts from the blackboard should assume that some of the attributes may not actually exist.
+- You are not limited to the attributes listed below for each artifact. Attributes are listed below as "Optional" if at least one, but not all, Autopsy modules create them. If you want to store data that is not listed below, use an existing attribute type or make your own.
+
+For the full list of types, refer to:
+- org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE
+- org.sleuthkit.datamodel.BlackboardAttribute.ATTRIBUTE_TYPE
+
+
<h1>Artifacts Catalog</h1>
In alphabetical order.
@@ -26,6 +34,8 @@ TSK_CARD_NUMBER (Credit card number)
- TSK_SET_NAME (The keyword list name, i.e., "Credit Card Numbers", when the account is a credit card discovered by the Autopsy regular expression search for credit cards)
---
+
+
## TSK_ASSOCIATED_OBJECT
Provides a backwards link to an artifact that references the parent file of this artifact. Example usage is that a downloaded file will have this artifact and it will point back to the TSK_WEB_DOWNLOAD artifact that is associated with a browser's SQLite database. See \ref jni_bb_associated_object.
diff --git a/bindings/java/doxygen/blackboard.dox b/bindings/java/doxygen/blackboard.dox
index 7fb38c7571eb28933e11b11d847fe7278c95b0cf..c5c68add9aa3dc322a461354b573b8edd07e5763 100644
--- a/bindings/java/doxygen/blackboard.dox
+++ b/bindings/java/doxygen/blackboard.dox
@@ -8,11 +8,17 @@ The blackboard allows modules (in Autopsy or other frameworks) to communicate an
The blackboard is a collection of <em>artifacts</em>. Each artifact has a type, such as web browser history, EXIF, or GPS track points. The Sleuth Kit has many artifact types already defined (see org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE and the \ref artifact_catalog_page "artifact catalog") and you can also \ref jni_bb_artifact2 "create your own".
-Each artifact has a set of name-value pairs called <em>attributes</em>. Attributes also have types, such as URL, Created Date, or Device Make. The Sleuth Kit has many attribute types already defined (see org.sleuthkit.datamodel.BlackboardAttribute.ATTRIBUTE_TYPE) and you can also create your own. See the \ref artifact_catalog_page "artifact catalog" for a list of artifacts and the attributes that should be associated with each.
+Each artifact has a set of name-value pairs called <em>attributes</em>. Attributes also have types, such as URL, Created Date, or Device Make. The Sleuth Kit has many attribute types already defined (see org.sleuthkit.datamodel.BlackboardAttribute.ATTRIBUTE_TYPE) and you can also create your own.
+
+See the \ref artifact_catalog_page "artifact catalog" for a list of artifacts and the attributes that should be associated with each.
When a module wants to store its results in the blackboard, it makes an artifact of the correct type and then adds attributes to it. Other modules can then query the blackboard for artifacts of a given type or artifacts associated with a given file.
-There are two special types of artifacts that are used a bit differently than the rest. The first is the org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE.TSK_GEN_INFO artifact. A Content object should have only one artifact of this type and it is used to store single attributes that are not related to each other and that do not need their own artifact. There are special methods to access this artifact to ensure that only a single TSK_GEN_INFO artifact is created per Content object and that you get a cached version of the artifact. These methods will be given in the relevant sections below.
+\subsection jni_bb_specialart Special Artifact Types
+
+There are two special types of artifacts that are used a bit differently than the rest.
+
+The first is the org.sleuthkit.datamodel.BlackboardArtifact.ARTIFACT_TYPE.TSK_GEN_INFO artifact. A Content object should have only one artifact of this type and it is used to store a single, independent attribute that will not be displayed in the UI. Autopsy used to store the MD5 hash and MIME type in TSK_GEN_INFO, but they are now in the files table of the database. There are special methods to access this artifact to ensure that only a single TSK_GEN_INFO artifact is created per Content object and that you get a cached version of the artifact. These methods will be given in the relevant sections below.
The second special type of artifact is the TSK_ASSOCIATED_OBJECT. All artifacts are created as the child of a file or artifact. This TSK_ASSOCIATED_OBJECT is used to make additional relationships with files and artifacts apart from this parent-child relationship. See the \ref jni_bb_associated_object section below.
@@ -94,15 +100,21 @@ You can find artifacts using a variety of ways:
\section jni_bb_custom_types Custom Artifacts and Attributes
This section outlines how to create artifact and attribute types because the standard ones do not meet your needs. These custom artifacts will be displayed
-in the Autopsy UI alongside the built in artifacts and will also appear in the reports. However, before you make a custom type, you should consider the
+in the Autopsy UI alongside the built in artifacts and will also appear in the reports.
+
+However, before you make a custom type, you should consider the
TSK_INTERESTING_FILE_HIT artifact. It is very generic and we have used it
in the past when we did not want to make a new artifact type. You create the artifact, use the TSK_SET_NAME attribute to define the equivalent name of the custom artifact that you wanted to create, and then add whatever attributes you want.
\subsection jni_bb_custom_make Making Custom Artifacts and Attributes
+
+
org.sleuthkit.datamodel.SleuthkitCase.addBlackboardArtifactType() is used to create a custom artifact. Give it the display and unique name and it will return a org.sleuthkit.datamodel.BlackboardArtifact.Type object with a unique ID. You will need to call this once for each case to create the artifact ID. You can then use this ID to make an artifact of the given type. To check if the artifact type has already been added to the blackboard or to get the ID after it was created, use org.sleuthkit.datamodel.SleuthkitCase.getArtifactType().
To create custom attributes, use org.sleuthkit.datamodel.SleuthkitCase.addArtifactAttributeType() to create the type and get its ID. Like artifacts, you must create the type for each new case. To get a type after it has been created in the case, use org.sleuthkit.datamodel.SleuthkitCase.getAttributeType().
+Note that "TSK" is an abbreviation of "The Sleuth Kit." Artifact and attribute type names with a "TSK_" prefix indicate the names of standard or "built in" types. User-defined artifact and attribute types should not be given names with "TSK_" prefixes.
+
*/
diff --git a/bindings/java/src/org/sleuthkit/datamodel/BlackboardArtifact.java b/bindings/java/src/org/sleuthkit/datamodel/BlackboardArtifact.java
index 6197f4937ffc15ffa2902d02d9874087f2bcf057..e30a1c5e73723bc7bed357b04643e3a6a821295f 100644
--- a/bindings/java/src/org/sleuthkit/datamodel/BlackboardArtifact.java
+++ b/bindings/java/src/org/sleuthkit/datamodel/BlackboardArtifact.java
@@ -1232,6 +1232,12 @@ public enum ARTIFACT_TYPE implements SleuthkitVisitableItem {
TSK_GPS_TRACK(58, "TSK_GPS_TRACK",
bundle.getString("BlackboardArtifact.tskTrack.text"));
+ /* To developers: For each new artifact, ensure that:
+ * - The enum value has 1-line JavaDoc description
+ * - The artifact catalog (artifact_catalog.dox) is updated to reflect the attributes it uses
+ */
+
+
private final String label;
private final int typeId;