Metadata

Metadata is used to add specificity to an action. When you create a mission, you can add metadata as the name:value pair within the rule to collect information specific to the action the user needs to perform. Using metadata, you can use the same action to complete different tasks of the same type. For example:

You have the general action READ_ARTICLE. You have one mission that requires users to read any article (action=READ_ARTICLE), a second mission to read the September Press Release (action=READ_ARTICLE and metadata=ID:1234), and a third mission to read the October Press Release (action=READ_ARTICLE and metadata=ID:3456). Show me this example

You have a Bunchball Go program using the HUB_CLICK_THROUGH action to access external content. You have a mission that requires users to visit your intranet (action=HUB_CLICK_THROUGH and metadata=url:https://mycompany/intranet/internal.htm) and your training site (action=HUB_CLICK_THROUGH and metadata=url:https://mycompany/training/internal.htm). Show me this example

Metadata Rules

Nitro currently supports up to a total of 10 metadata pairs to be associated with actions logged. However, analytics can only support up to 5 metadata pairs.

If the metadata sent to Nitro does not exactly match what is defined in the rule, the action will not complete the mission. The metadata:

Name and Value are case-insensitive.
Name cannot contain a comma or a colon
Value cannot contain a comma
Value can contain spaces, but the Name should not
Must be UTF-8 encoded

Self-Reporting Rules Metadata

When using self-reporting rules, we recommend that:

You create actions only used for self-reporting rules. If a self-reporting rule uses an action that is also used in other missions, then completing a self-reporting rule may make progress on or complete other missions. For example, Mission A uses a self-reporting rule with the TRAINING action. Mission B uses a Number of Actions rule with the TRAINING action and no metadata. When a user marks the self-reporting rule as complete, it logs the TRAINING action which will complete Mission A and Mission B.
You MUST add metadata to all self-reporting rules. Metadata ensures that when a user marks a self-reporting task as complete, it will only complete that mission and not all missions that have a self-reporting rule using the same action. Nitro automatically adds metadata to the self-reporting rule when you save it, but you can add additional metadata if necessary.
You only edit self-reporting rule metadata during off-peak hours. If you edit the metadata at the same time a user is marking the task as complete, it will put the rule in a bad state. This happens because the user logs the rule with the old metadata, but the mission is looking for the new metadata. The rule will not complete for that user and it will remain in a "Submitted" status until manually remediated by an administrator.

Nitro Metadata

Nitro automatically logs metadata for quizzes, self-reporting rules, On The Spot card redemptions, and recognition events.

Action to Log	Action Name	Metadata Name	Metadata Value
Nitro Actions and Metadata
Completion of a quiz. The action is logged when a quiz is completed. In addition to the metadata, the percent correct is returned as the action value.	QUIZ_COMPLETED	passed	true or false
		quiz_id	the numeric quiz ID (available in the Quizzes view Quiz ID column)
		totalCorrect	the total number of questions the user answered correctly
		totalQuestions	the total number of questions in the quiz
		percentCorrect	the user's completion score for the quiz rounded to the nearest integer
Redemption of an On The Spot card using the OTS web component.	OTS_REDEMPTION	card_number	the 16-digit card number
	OTS_REDEMPTION	value	the point value redeemed
Completion of a self-reporting rule. The selfReporting and ruleUrl pairs are added/updated when you save the self-reporting rule in the mission builder. The rule URL is only added if a URL exists for the rule, it does not add metadata for subtask URLs.	Any action within your program	nitro-self-reporting	true
		selfReporting	{missionId_ruleId}
		ruleUrl	{ruleUrl}
Recognition given or received.	Name is configurable within your program	category	the category name (available in the Recognitions view Exchange Categories column)
Recognition given or received.	Name is configurable within your program	exchange	the recognition exchange name
Bunchball Go Actions and Metadata
Successful login	HUB_LOGIN
Successful logout	HUB_LOGOUT
Successful confirmation of a registration via the registration process or automatically via single-sign-on.	HUB_REGISTER
Click-through from content in the links section. This section's name is custom to your program (e.g. Resources, Information, Learning, etc.).	HUB_CONTENT_REFERRAL	url	[URL path] For example, url:https://www.bunchball.com/
Click-through from content in the Missions web component. Content can be accessed from a link within the Tasks list.	HUB_CLICK_THROUGH	url	[URL path]
Page view, excluding the Home page. Note: Nitro does not log an action for the home page.	HUB_VIEW	view	missions, community, achievements, or recognition Note: The metadata Value must match the page's href value to log the action for that specific page. If you add additional pages to your program or change the name of the default page, use the href value to find the correct metadata.
User subscribes to push notifications.	HUB_PUSH_ENABLE
User subscribes to a channel. You can specify the type of channel and channel name in the metadata.	HUB_SUBSCRIBE_TO	type	push_notification
	HUB_SUBSCRIBE_TO	channel	recognition_received

View Action Metadata

You can view the metadata sent with an action in the User Management view or with GET /users/{userId}/actions. Use this to verify that the information sent to Nitro matches the metadata defined in the mission.

Metadata Example

Mission = Read any article	Mission = Read the September Press Release	Mission = Read the October Press Release