Publishing the Bixby Device Graph (BHS Metadata Submission)

This guide assumes familiarity with:

In this guide, you'll learn about the following:

  • How to create a Bixby Home Studio (BHS) Metadata Submission
  • Submission States
  • Submission History

You can add or edit voice actions for devices with metadata submissions. Once you create a new metadata file or update an existing one, you can submit your metadata file for publishing and release approval, and track its progress.

Note

On-device testing and submissions of metadata for voice commands are only available to device manufacturer developers who have registered their device with SmartThings. For more information, see the Start Developing guide on the SmartThings Developers website.

Submitting BHS Metadata

BHS enables you to create new metadata or update existing metadata with the icons in the Metadata Sidebar.

  • New Metadata New Metadata Icon: used to create new metadata for a device.
  • Load Metadata Load Metadata Icon: used to update existing metadata of a device.

Once you load a new or existing metadata file, this file will have a list of voice intents, as shown below. In this example, the editor shows the metadata file generic-dimmer with three voice intents.

Add or update Voice Intent

Editing Voice Intent Options

You have three options for editing voice intents. Once you've done at least one of the following, you can submit your metadata for approval:

Adding a New Voice Intent

To add a voice intent, click the Add Voice Intent icon Add Voice Intent Icon to the right of Voice Intents in the Metadata profile section.

A pop-up appears, as seen below. Select a category from the drop-down menu, and then select a voice intent from the list that appears. Click ADD.

Add a Voice Intent

The added voice intent appears in the list under Metadata profile in the Metadata Sidebar.

Added Voice Intent

After adding the new voice intent, you can update the graph for this voice intent and then proceed to submitting it. For more information on adding to this graph, see Creating an Action Flow in the Bixby Home Studio Basics guide.

Updating an Existing Voice Intent

To update an existing voice intent, click a voice intent under Metadata profile to open its metadata information.

To make changes to the capability information for a device, click Property under the selected voice intent.

Change Voice Intent Property

To make changes to a graph directly, click Graph under a voice intent.

Change Voice Intent Graph

To make changes to the JSON for a graph, click RAW in the top right corner.

Click RAW button

In the pop-up, make changes to the raw JSON and click ADD.

Update Raw JSON

Deleting an Existing Voice Intent

To delete an existing voice intent, right click the voice intent. Then, click Delete "%voice intent%". The below example deletes the "powerSwitch-turnOn" intent.

Delete a Voice Intent

Preparing Metadata Submissions

Now that you've created new metadata or updated existing metadata, you can submit your metadata for approval for publishing and release:

  1. Click Metadata profile in the Metadata Sidebar. You can view the current version (the version before you applied updates) on the left of the upload button. In this example, it's 0.0.1. The Metadata profile tab opens, and you can view the Meta Profile (Name, Version, MNID, VID). The Meta Profile version number shows the current version. Metadata profile

  2. Update the version to the next version number. In this example, you can use 0.0.2. Confirm that the updated version number shows in the Metadata Sidebar, as shown below. Metadata profile version update

    Alternatively, you can click the Upload button in the Metadata Sidebar. In the Metadata Submission Message pop-up, you can update the metadata version. Submit Metadata

  3. Use the Metadata Submission Message pop-up to add a Submission Message that states the changes you've made to the metadata. Click SUBMIT.

  4. The Submission Tab opens. As shown below, your metadata moves from the Local submission state to the Private submission state. Click SUBMIT. Click Submit on Submission Tab

Next, you'll decide whether to test your metadata or skip this step before submitting.

Testing Submissions

A pop up appears that shows the steps to submit your metadata. You have two options:

Steps to Submit Metadata

Note

Testing before submission allows developers to discover and fix errors. It also helps the Bixby Home Platform team verify that the metadata will not affect platform stability.

Skipping Testing Before Submission

To submit metadata without testing it, click SKIP TESTING AND SUBMIT.

Click Submit on Submission Tab

A Metadata Submission Message pop up appears. Add a message about the submission that explains what has changed since the last transition in submission state. Click SUBMIT.

Metadata Submission Message Pop Up Appears

A confirmation screen appears, stating that you successfully submitted your metadata.

Metadata Submission Message Pop Up Appears

The metadata will be forwarded to the release manager. If your metadata submission gets approved, the release manager releases it to the public per the deployment schedule.

Note

While you can skip testing if you've tested it thoroughly on your own, it's still recommended to perform testing here as well.

Testing Metadata Before Submission

You can verify the metadata before submission:

  1. Select the location and device to test the metadata. Click NEXT. Metadata test device selection
  2. Click the TEST buttons against the action flows to test the metadata. Metadata testing
  3. You can review the test results, as shown below. Click DONE. Metadata testing results
    • The Execution Ratio shows how many voice intents were successfully executed.
    • The Success Ratio shows how many of those voice intents successfully reached their goal.
    • The Time Average shows how quickly each action flow completed, and if it completed in a reasonable amount of time.
  4. A Metadata Submission Message pop up appears. Add a message about the submission that explains what has changed since the last transition in submission state. Click SUBMIT. Metadata Submission Message Pop Up Appears

A confirmation screen appears, stating that you successfully submitted your metadata.

Metadata Submission Message Pop Up Appears

The metadata will be forwarded to the release manager. If your metadata submission gets approved, the release manager releases it to the public per the deployment schedule.

Submitting Messages

Whenever a user changes the submission state of the metadata, a message (log) prompt appears. When you're changing the status of your submission, the message you submit should give information on what has changed in the metadata.

The recipients of your message will also differ depending on the transition state:

  • Local to Private: members of the device manufacturer's team
  • Private to Submitted: the release manager

The release manager writes a message to the members of the device manufacturer's team for the following transition states:

  • Submitted to Private - This message should explain why the submission was rejected.
  • Published to Released - This message lets the device manufacturer's team know that their submission was approved.

Submission States

Note

If updating existing metadata, your version number must be higher than that of the original file before submitting. Also, you cannot have multiple versions of the same metadata file in the Submitted state at the same time.

There are five submission states:

  • Local: The metadata file is stored locally but hasn't been uploaded.

  • Private: Your metadata file has been uploaded. However, it hasn't been submitted to the release manager.

  • Submitted: Your metadata file has been submitted. The release manager reviews the metadata for any issues. Reviews usually take about 2 to 3 days. When they've completed the review, the status can have two outcomes:

    • If the release manager doesn't find any issues with the metadata, it moves to Published status.
    • If the release manager rejects the file, the submission reverts to Private status.
  • Published: Your metadata submission has been submitted and published on the Bixby Home Platform (BHP) server. However, it hasn't been released publicly to end users.

  • Released: Your metadata submission has been publicly released to end users, and other BHP developers can view and use it.

Submission History

To view metadata submission history and state transition details, click the Submission icon in the Activity Bar on the left, which opens the Submission sidebar. Click on a device from the list to open its Submission history. Then click a version to view its history.

Metadata submission history

To view submissions in specific states, select one or more states at the top of the Submission sidebar. You'll see a check mark on the selected states.

Metadata submission history

In the next guide, you'll learn how to perform Data Conversion Using a JSON Query Node.