Artifacts

Saving Data to Files

Compound query Artifacts are the files that the user generates and saves after the query executes. Using open() with any file in the current directory creates only temporary files. The server removes these files once the compound query completes. However, if the user writes files to the Artifact folder, the files will be preserved after execution, allowing the user to download later.

In order to do this, a file must be first opened by a specific code line: my_file = open("output.txt", "w+").

Likewise, if the file is opened, it must also be closed: my_file.close().

Below is an example of how one would write to a file. The Artifacts API allows the report to save information to the hard drive and retrieve that information later. The two main functions of the Artifacts API are the .open() function, which writes information out, and the .getURL(), which returns the URL which can be used to retrieve the information.

def save_report(fileName, fileContents, fileMode = 'w+'):
    with artifacts.open(fileName, fileMode) as f:
        f.write(fileContents)

#linkName is the text that will be shown to the user
def print_link_to_file(fileName, linkName):
    fileURL = artifacts.getURL('%s' % filename)
    print('' % (fileURL, linkName))

Artifact API Calls

artifacts.open(filepath, mode)

This is an alias to Python's built-in open() command, except for the fact that the file is opened inside of the artifact output directory (/output/) instead of in the current directory. The server will return a file handle.

artifacts.getURL(path)

The use of artifacts.getURL() provides the URL path to the file. Use the path to download or view the file inside of a web browser. This will return a string that can be used as a URL.

Example:

https://<ipaddress>/search/results/Result321/output/path/to/my.file

After the URL has been supplied, it is possible to either put it into a browser or to wrap it within a string and make it a link within a report.

Changing Artifact Files

In a manner, artifact files can be thought of as a variable: the files can be changed. To write additional items to the file, use either of the following methods:

Example:

#Method 1
file = artifacts.open("myfile.txt", "w+") # File is the variable here
file.write("File contents\n") # Write some data to the file
file.close() # We have to close it before we leave
#Method 2
with artifacts.open("myfile.txt", "a+") as f: # Open the file handle and store it in the "f" variable, this will clean up once we leave the with block
    f.write("Even more data!\n") # Write some more data to the file

The resulting file (/output/myfile.text) looks like this:

Response:

File contents
Even more data!

Specific Artifact Files

• .context.json: This is a JSON object which contains the information about the current user and options that are required for compound queries to run. For example, the report can access a user's username and can display it within the report.
  Example:

username=context['username']
print(username)
#Enter the rest of the query after this line

• result and /result/{result_id}/view: These calls have been deprecated for compound queries. Results is a backwards compatibility file for /results/{result_id}/view call. All new calls should refer to the Artifacts API to retrieve the result.log file.
• result.log: This is the file which generates the Hits table, it should be populated through show_hits
• script.py: This file contains the user's compound query script.
• stderr.log: This file contains the lines from Standard Error.
• stdout: This file contains the lines from Standard Out.
• summary.json: This contains the parameters that are used in parameterized queries.