japlscript / japlcontact

Java API for Apple's Contacts app (macOS)

Japlcontact

Japlcontact is a Java API for the Apple Contacts app (macOS) based on JaplScript.

Installation

Japlcontact is released via Maven. You can install it via the following dependency:

<dependency>
    <groupId>com.tagtraum</groupId>
    <artifactId>japlcontact</artifactId>
</dependency>

The Maven artifacts also contain sources and javadocs.

If you are using modules, its name is tagtraum.japlcontact.

Usage

To use the generated code, do something like this:

import com.tagtraum.macos.contacts.Application;

public class GetMyCard {

    public static void main(final String[] args) {
        // get application
        final Application application = Application.getInstance();
        final Person card = application.getMyCard();
        System.out.println("My Card: " + card.getFirstName() + " " + card.getLastName());
    }
}

API

You can find the complete API here.

AppleScript Sandbox

Since macOS 10.14 (Mojave), Apple imposed a sandbox on AppleScript. Therefore you may see dialog boxes requesting authorization to perform certain actions. After a while, these boxes simply disappear and there does not seem to be an easy way to authorize your app. In this case, you need to open the system preferences, navigate to Security & Privacy, Privacy, and then Automation, and make sure your app is allowed to remote control whatever app you are trying to remote control (see also this article).

If you are shipping a real app with a UI and not just a command line tool, you need to customize the sandbox permission dialog. You can do so by adding the key NSAppleEventsUsageDescription to your app bundle's /Contents/Info.plist file. For example:

[...]
<key>NSAppleEventsUsageDescription</key>
<string>SuperMusic uses AppleEvents to access your Music.app library,
        e.g., to set BPM values or create playlists.</string>
[...]

Apple's documentation for the keyword is here.

IMPORTANT Counterintuitively, the bundle id for the Contacts app is com.apple.AddressBook. Should you need to reset the sandbox using tccutil, you need to specify either com.apple.AddressBook or just AddressBook. Contacts or com.apple.Contacts won't work.