Uploading macOS apps using REST APIs and Admin Assistant

Welcome to day 21 of Let’s Git Commit(ted) to </Dev> Resources! If you missed day 20, we discussed how to use the Workspace ONE UEM REST APIs to upload a Windows 10 application. Today’s discussion covers how to accomplish publishing macOS apps using two options:

1. Using the Workspace ONE UEM REST APIs
2. Using the Workspace ONE Admin Assistant CLI

Prerequisites for publishing macOS Apps

When publishing macOS apps, you need three items:

1. The application installer (.dmg, .pkg, .mpkg, .app)
2. The application metadata (.plist)
3. An optional application icon (.png, .jpg)

While you would have access to these files for applications you develop, what about applications you didn’t develop that you intend to publish? Never fear – the Workspace ONE Admin Assistant Tool is here!

What is the Workspace ONE Admin Assistant Tool?

The Workspace ONE Admin Assistant Tool is a macOS application that provides administrators with two features:

1. A graphical interface that accepts application installer files (.dmg, .pkg, .mpkg, .app) and outputs the application installer file, application metadata file, and application icon file to a subdirectory under the Workspace ONE Admin Assistant directory. This allows administrators to retrieve all the necessary files to publish macOS applications from third-party developers.
2. A Command Line Interface (CLI) that allows you to upload macOS applications, allowing you to script or automate the upload.

If you wish to upload a macOS application and you do not have access to the metadata file, you can use the Workspace ONE Admin Assistant Tool to extract it and continue publishing applications.

You can download the Workspace ONE Admin Assistant Tool using the instructions provided here.

Extracting macOS Application Metadata

Once you have installed the Workspace ONE Admin Assistant Tool, you can use either the drag-and-drop area or click to browse and supply the application installer to parse. See Figure 1.

Figure 1: Workspace ONE Admin Assistant Tool installed and ready to receive a third-party macOS application installer file.

Once the application installer file is provided, the Workspace ONE Admin Assistant Tool parses the contents and outputs the application installer (.dmg), application metadata (.plist) and application icon (.png) to the Documents/Workspace ONE Admin Assistant/ApplicationName-XX.YY.ZZ/ (where XX, YY, and ZZ change depending on the app version) directory. See Figures 2 and 3 with EverNote version 10.28.3 as an example.

Figure 2: Workspace ONE Admin Assistant Tool finished parsing macOS application installer file

Figure 3: The parsed application installer file, application metadata file, and application image file

You now have the prerequisite files (application installer, metadata, and icon) that can be used to upload the application to Workspace ONE UEM with either the REST APIs or the Admin Assistant Tool.

How Should I Publish macOS Apps? The REST APIs or the Admin Assistant Tool?

Good question! Let’s examine the primary differences.

The Workspace ONE UEM REST APIs are platform independent; you just need access to the application installer, application metadata, and optionally the application icon. The REST APIs use web requests to send and receive data, so any programming or scripting language or API application (such as Postman or Paw) that supports this process can be used.

The Workspace ONE Admin Assistant Tool is a macOS application and CLI, so if your team has more experience automating or scripting with CLIs, this may be an easier approach.

We review both options today so you can see the differences and decide for your use case.

Option 1: Workspace ONE UEM REST APIs

You use two REST APIs to accomplish the tasks of uploading the application files and publishing the application. Reference the API documentation for the following REST APIs:

1. MAM REST API V1 > API Reference > BlobsV1 > POST /blobs/uploadblob
2. MAM REST API V1 > API Reference > MacOsAppsV1 > POST /groups/{id}/macos/apps

You complete the following steps:

1. Extract the application metadata (.plist) and icon from the application installer file using the Workspace ONE Admin Assistant Tool.
2. Upload the application installer file as a blob to Workspace ONE UEM.
3. Upload the application metadata file as a blob to Workspace ONE UEM.
4. (Optional) Upload the application icon file as a blob to Workspace ONE UEM.
5. Publish the application by referencing the uploaded blob IDs of the application installer, metadata, and (if uploaded) icon files.

Requirements

1. You need a Workspace ONE UEM administrator account and an API Key. If you are not familiar with the Workspace ONE UEM REST APIs, see the Getting Started with the Workspace ONE UEM REST APIs.
2. The Workspace ONE Admin Assistant Tool is needed to extract the application metadata for a macOS application installer file.
3. A macOS application installer file. I use Evernote for this example, and have already followed the steps outlined in Extracting macOS Application Metadata to extract the application metadata (.plist) and icon from the downloaded installer (.dmg).
4. You need the organization group ID for the organization group where you intend to publish the macOS application. You can retrieve this value with one of the two following methods:
   
   1. In the Workspace ONE UEM administrator console, navigate to the organization group you wish to upload the application to. Then navigate to Groups & Settings > Groups > Organization Groups > Details. The URL of this page is in the following format: https://{host}/AirWatch/#/OrganizationGroup/Details/Index/###. The integer value at the end of the URL is your OrgGroupId.
   2. You can use the REST APIs to query the IDs of organization groups. The GET system/groups/search?name={orgGroupName} API returns a list of organization groups that contain the provided name value. The OrgGroupId for each result is listed in the Id object under the Value property.

Step 1: Upload the Application Installer Blob

Begin by using the uploadblob API mentioned in previous steps. Refer to the API documentation to see full details on using the uploadblob API and use the table below to format your API response.

Feel free to use Postman, Paw, or reference the UploadApp.ps1 sample to script the solution.

Request:

Response:

A successful request produces the following response:

The expected Status Code is 200 OK, and the body contains two values:

• uuid: A String formatted blob UUID. If an API requires a Blob UUID, you need to save this value and provide it to the corresponding API.
• Value: An integer value representing the Blob ID. If an API requires a blob ID, you need to save this value and provide it to the corresponding API.

The final API in the macOS application upload process is POST /mam/groups/{groupId}/macos/apps, which requires Blob IDs. Record the Blob ID (Value) received from the response.

Step 2: Upload the Application Metadata Blob

Use the same uploadblob API to upload the metadata (.plist) file that was extracted from the macOS application using the Workspace ONE Admin Assistant Tool.

Request:

Response:

A successful request produces the following response:

You need to save the returned Blob ID (Value) from the response for the metadata file as well. Be sure to keep this Blob ID separate from your first blob and label them appropriately, as you need to provide each Blob ID for the final API.

Step 3: (Optional) Upload the Application Icon Blob

Use the same uploadblob API to upload the application icon file that was extracted from the macOS application using the Workspace ONE Admin Assistant Tool. This step is optional, but recommended because the icon helps differentiate the application to your end users in the app catalog.

Request:

Response:

A successful request produces the following response:

As with the other requests, you need to save the returned Blob ID (Value) from the response for the application icon file.

Step 4: Publish the macOS Application

You should now have three different Blob IDs from the uploadblob API requests that were just submitted:

1. A Blob ID for the application installer (Evernote.dmg in this case). My Blob ID for the application installer was 100.
2. A Blob ID for the application metadata (Evernote.plist in this case). My Blob ID for the application metadata was 101.
3. A Blob ID for the application icon (Evernote.png). My Blob ID for the application icon was 102.

Your Blob IDs will differ from mine, but the important thing is to record which Blob ID was associate with which file.

Now you use the POST /mam/groups/{groupId}/macos/apps API to publish the Evernote macOS application. You need to substitute the {groupId} value in the URL with the organization group ID that you retrieved in previous steps.

Request:

Be sure to format your JSON post body correctly! You need to map the Blob IDs to the following properties:

• pkgInfoBlobId: The metadata (.plist) file. Blob ID 101 for my example.
• applicationBlobId: The application installer file. Blob ID 100 for my example.
• applicationIconId: The icon file. Blob ID 102 for my example. If you did not upload an icon to use for an application, remove this property from the body.

Response:

A successful request produces the following response:

If you receive a different status code, confirm that:

1. You uploaded the appropriate file with the appropriate filename and extension in your uploadblob APIs.
2. You provided the correct Blob ID to the correct property in the /macos/apps API.

Step 5: Confirm the App Was Published

The /macos/apps API publishes the application installer, metadata, and icon file to form an Internal app in Workspace ONE UEM. Once the API is finished, log in to the Workspace ONE UEM administration console, navigate to the Organization Group that matches the organization group ID you provided, and confirm the application exists under: Apps & Books > Applications > Native > Internal. See Figure 4.

Figure 4: The Evernote macOS application was successfully uploaded to the Apps & Books > Applications > Native > Internal tab.

Congratulations! Your macOS app is now published using the REST APIs and you can assign it to devices and users!

Option 2: Workspace ONE Admin Assistant CLI

The second option we discussed earlier to upload a macOS application is to use the Workspace ONE Admin Assistant CLI.  The CLI is installed alongside the application.  You can confirm that everything is setup by opening the Terminal app and running:

If you see output showing the version of the admin assistant (such as Version: 3.0.1), then you are ready to continue! If you do not see the above output, make sure that you installed the Workspace ONE Admin Assistant Tool as discussed at the beginning, and that your user account has sufficient privileges.

Step 1: Configure the Workspace ONE Admin Assistant CLI

Use the config subcommand to configure your Workspace ONE administrator credentials, API key, UEM API hostname, and the target organization group ID.

Don’t forget that you can see a list of flags to include by using:

Provide the following flags to sign in:

IMPORTANT: The Organization Group ID requested here is the Group ID string field, not the integer field as we have used previously. You can find this value in two ways:

1. In the Workspace ONE UEM administrator console, navigate to the organization group you wish to upload the application to. Then navigate to Groups & Settings > Groups > Organization Groups > Details. The Group ID field under the name field is the string-based Organization Group ID you need.
2. You can use the REST APIs to query the IDs of organization groups. The GET system/groups/search?name={orgGroupName} API returns a list of organization groups that contain the provided name value. The Organization Group ID for each result is listed in the GroupId string property.

You can now setup your adminassistantcli config command. Refer the following as an example:

If the provided credentials are correct, you receive a confirmation output stating you have been successfully signed in.

Step 2: Upload an App with the Workspace ONE Admin Assistant CLI

With the adminassistantcli configured, you can now use the upload subcommand and provide the necessary file paths to the application installer, metadata, and icon files – just as we did with the REST APIs.

Don’t forget that you can see a list of flags for the upload command using:

Since we configured the adminassistantcli with a group id already using the -g flag and we have an app icon file, we use the following flags with the upload command:

Since I need to provide file paths, I change directory (cd) into the Workspace ONE Admin Assistant folder where the Evernote files were extracted to. My commands are as follows:

If everything is configured and formatted properly, you see the following success messages:

Step 3. Confirm the App Was Published

Once the adminassistantcli upload has completed, you can confirm the upload was successful by logging in to the Workspace ONE UEM administration console and navigating to the Organization Group that matches the organization group ID you provided. Then, confirm the application exists under: Apps & Books > Applications > Native > Internal.

Conclusion and Next Steps

We provided two methods for uploading macOS applications:

1. Using the REST APIs to upload the application installer, metadata file, and icon file as blobs, then to publish the macOS application by referencing the returned Blob IDs.
2. Using the Workspace ONE Admin Assistant CLI to configure API access, and then using the upload subcommand to publish the application installer, metadata file, and icon file.

For next steps, check out the following ideas:

1. Use the API documentation and check out the MAM REST API V1 /apps/internal/{applicationId}/assignments API to check out how you can create (POST), modify (PUT), or delete (DELETE) assignments so that your intended users and groups get access to the newly installed internal application.
2. Use the API documentation and check out the System V1.

If you enjoyed this API overview and want to see more examples or a deeper dive – let us know!

Agenda

Make sure to check out the other blog posts in our 28-day series:

• Day 1: Let's Git Commit(ted) to Dev Resources
• Day 2: Getting Started with the Workspace ONE UEM REST APIs
• Day 3: Getting Started with the Workspace ONE Access APIs
• Day 4: Getting Started with the VMware Workspace ONE Intelligence APIs
• Day 5: Getting Started with the VMware Horizon REST APIs and VMware PowerCLI
• Day 6: Getting Started with Automating the Unified Access Gateway Deployment
• Day 7: Podcast: Day 0 Onboarding Automation with Scot Curry
• Day 8: Video: Anatomy of the Workspace ONE UEM API
• Day 9: Introduction to using Postman - Part 1
• Day 10: Introduction to using Postman - Part 2
• Day 11: Pro Tips and Tricks - How to be an API Boss
• Day 12: What is OAuth - Learning the Basics
• Day 13: Getting Started with Intelligent Hub Notifications
• Day 14: Git Basics: Getting Git Going
• Day 15: Podcast: Git Commit(ted) to Resources: Customer Spotlight with The Home Depot
• Day 16: Git VMware {code} Samples and Flings
• Day 17: Using paginated requests with Workspace ONE UEM REST APIs
• Day 18: Event Notifications
• Day 19: Overview of Script Samples using PowerCLI for Horizon
• Day 20: Uploading Windows apps using REST APIs 
• Day 21: Uploading macOS apps using REST APIs and Admin Assistant 
• Day 22: API-based user lifecycle and SCIM 
• Day 23: Video: Community Expert Roundtable on Leveraging APIs and Scripting
• Day 24: Video: Exploring the Workspace ONE GitHub Samples Repository 
• Day 25: Featured Fling: Forklift for Workspace ONE UEM
• Day 26: Featured VMware {code} Samples for Horizon
• Day 27: Featured Flings for VMware Horizon
• Day 28: Continuing to Focus on </Dev> Resources Page